如何用Crispy Forms实现Django ForeignKey字段的自动补全？

问题背景 #

Category表存有约4000条分类数据，Search模型的category1字段是关联该表的ForeignKey，当前使用下拉选择框时滚动耗时过长，需要改为文本输入自动补全形式：用户输入关键词时显示包含该关键词的分类选项，且仅能选择列表内选项，不允许随意输入。

原实现代码如下：

Models.py #

class Category(models.Model):
    details = models.CharField(max_length=250, blank=True, null=True)

    def __str__(self):
        return self.details

class Search(models.Model):
    name = models.CharField(max_length=200)
    email = models.CharField(max_length=200)
    category1 = models.ForeignKey('Category', blank=True, null=True, on_delete=models.CASCADE, related_name='category')

Forms.py #

class NewSearch(forms.ModelForm):
    class Meta:
        model = Search
        fields = ['name', 'email', 'category1']

    def __init__(self, *args, **kwargs):
        super(NewSearch, self).__init__(*args, **kwargs)
        self.fields['category1'] = forms.ModelChoiceField(queryset=Category.objects.all().order_by('details'))
        self.helper = FormHelper()
        self.helper.form_show_labels = False

Views.py #

@csrf_exempt
def search(request):
    my_form = NewSearch()
    if request.method == 'POST':
        my_form = NewSearch(request.POST)
        if my_form.is_valid():
            my_form.save()
            return redirect('frontpage-results')
    context = {
        'my_form': my_form,
    }
    return render(request, 'frontpage/search.html', context)

Search.html #

<form method="POST" class="page-section" enctype="multipart/form-data">
    <div>
        {% csrf_token %}
        <fieldset class="form-group">
             <div class="form-row">
                <div class="form-group col-md-5 mb=0">
                    Your Full Name:
                    {{ my_form.name|as_crispy_field }}
                </div>
                <div class="form-group col-md-7 mb=0">
                    Your E-mail Address:
                    {{ my_form.email|as_crispy_field }}
                </div>
                <div class="form-group col-md-4 mb=0">
                    Category you are looking for:
                    {{ my_form.category1|as_crispy_field }}
                </div>
             </div>
             {{ my_form.media }}        {# Form required JS and CSS #}
        </fieldset>
        <div class="form-group">
            <button class="btn btn-secondary" type="submit" name="first">SEARCH NOW</button>
        </div>
   </div>
</form>

Urls.py #

urlpatterns = [
    path('', views.home, name='frontpage-home'),
    path('search/', views.search, name='frontpage-search'),
]

尝试使用django-autocomplete_light实现自动补全时，出现错误：AttributeError: module 'autocomplete_light' has no attribute 'register'，配置代码如下：

SETTINGS.PY

INSTALLED_APPS = [
    'autocomplete_light',
    # 其他app...
]

URLS.PY

path('autocomplete/', include('autocomplete_light.urls')),

FORMS.PY

import autocomplete_light

autocomplete_light.register(Search, name='CatAutocomplete', choices=Category.objects.all())

class NewSearch(forms.ModelForm):
    class Meta:
        model = Search
        fields = ['name', 'email', 'category1']
        autocomplete_fields = {'category1': 'CatAutocomplete'}

    def __init__(self, *args, **kwargs):
        super(NewSearch, self).__init__(*args, **kwargs)
        self.helper = FormHelper()
        self.helper.form_show_labels = False

错误原因 #

1. 版本适配问题：django-autocomplete-light 3.x及以上版本已废弃autocomplete_light.register()的旧写法，改用ModelAutocomplete类定义自动补全器。
2. 注册对象错误：应该注册关联的Category模型，而非Search模型。

正确实现步骤 #

1. 安装/更新django-autocomplete-light #

确保安装最新版本：

pip install --upgrade django-autocomplete-light

2. 配置settings.py #

将autocomplete_light添加到INSTALLED_APPS，且放在django.contrib.admin之前：

INSTALLED_APPS = [
    'autocomplete_light',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # 你的其他app...
]

3. 定义分类自动补全器（Forms.py） #

替换原错误的注册代码，创建CategoryAutocomplete类并注册：

import autocomplete_light
from .models import Category, Search
from crispy_forms.helper import FormHelper

# 定义Category的自动补全器
class CategoryAutocomplete(autocomplete_light.ModelAutocomplete):
    model = Category
    # 按details字段模糊匹配，支持大小写不敏感
    search_fields = ['details__icontains']
    # 配置前端属性
    attrs = {
        'placeholder': '输入分类关键词...',
        # 输入1个字符就触发搜索
        'data-autocomplete-minimum-characters': 1,
        # 限制最多显示20条结果，避免加载过慢
        'data-autocomplete-limit': 20,
    }

# 注册自动补全器
autocomplete_light.register(CategoryAutocomplete)

class NewSearch(forms.ModelForm):
    category1 = forms.ModelChoiceField(
        queryset=Category.objects.all().order_by('details'),
        # 指定使用自定义的自动补全组件
        widget=autocomplete_light.ChoiceWidget('CategoryAutocomplete')
    )

    class Meta:
        model = Search
        fields = ['name', 'email', 'category1']

    def __init__(self, *args, **kwargs):
        super(NewSearch, self).__init__(*args, **kwargs)
        self.helper = FormHelper()
        self.helper.form_show_labels = False

4. 确认URL配置 #

保留自动补全的URL路由：

urlpatterns = [
    path('', views.home, name='frontpage-home'),
    path('search/', views.search, name='frontpage-search'),
    path('autocomplete/', include('autocomplete_light.urls')),
]

5. 确保模板加载媒体资源 #

模板中已有的{{ my_form.media }}必须保留，它会自动加载自动补全所需的JS和CSS文件。

额外优化建议 #

• 给Category的details字段添加数据库索引，提升搜索查询速度：

  class Category(models.Model):
      details = models.CharField(max_length=250, blank=True, null=True, db_index=True)
  
      def __str__(self):
          return self.details
  

• 如果分类数据持续增长，可以考虑在自动补全器中添加分页逻辑，进一步优化前端加载性能。

内容的提问来源于stack exchange，提问作者Steve