如何在Django Admin默认自动完成字段中启用标签功能

问题场景 #

现有模型结构如下：Task通过外键关联仅含一个TextField的Instructions模型，且Task可能以inline形式嵌套在其他模型（如Project）的Admin页面中：

class Task(models.Model):
    instructions = models.ForeignKey(
        "Instructions", on_delete=models.SET_NULL, null=True, blank=True
    )

class Instructions(models.Model):
    content = models.TextField(blank=False, null=False, max_length=500)

已尝试在ModelForm中给AutocompleteSelect设置data-tags="true"启用Select2的标签功能：

from django.contrib.admin.widgets import AutocompleteSelect

class TaskInlineModelForm(forms.ModelForm):
    class Meta:
        model = Task
        widgets = {
            "instructions": AutocompleteSelect(
                Task.instructions.field,
                admin_site=admin.site,
                attrs={"data-tags": "true"},    # 启用标签功能
            ),
            ...
        }

但提交表单时，若在instructions字段输入未存在的内容，会触发报错：

Field 'id' expected a number but got "This is a brand new instructions that has never been seen".

解决方案 #

方案一：保留外键关联，动态创建Instructions对象 #

核心思路是重写表单字段的clean方法，识别输入的新内容并自动创建关联对象：

from django import forms
from django.contrib.admin.widgets import AutocompleteSelect
from .models import Task, Instructions

class TaskInlineModelForm(forms.ModelForm):
    # 重新定义instructions字段，使用ModelChoiceField
    instructions = forms.ModelChoiceField(
        queryset=Instructions.objects.all(),
        required=False,
        widget=AutocompleteSelect(
            Task.instructions.field,
            admin_site=admin.site,
            attrs={"data-tags": "true"},
        )
    )

    def clean_instructions(self):
        value = self.cleaned_data.get('instructions')
        # 若输入的是字符串（而非已选中的模型对象），说明是新标签
        if isinstance(value, str):
            # 使用get_or_create避免重复创建
            new_instructions, _ = Instructions.objects.get_or_create(content=value.strip())
            return new_instructions
        return value

    class Meta:
        model = Task
        fields = '__all__'

这个逻辑对inline表单同样生效，表单验证时会自动处理新输入的内容，创建对应的Instructions对象并关联到Task。

方案二：改为TextField，实现轻量化自动完成+标签 #

如果不需要复用Instructions内容，直接把Task的instructions字段改为TextField，再通过自定义Widget实现功能：

1. 修改模型

class Task(models.Model):
    instructions = models.TextField(blank=True, null=True, max_length=500)

2. 配置表单与Widget

from django import forms
from django.contrib.admin import ModelAdmin
from .models import Task

class TaskAdminForm(forms.ModelForm):
    instructions = forms.CharField(
        widget=forms.TextInput(attrs={
            'data-toggle': 'select2',
            'data-tags': 'true',
            # 可选：从现有Instructions拉取自动完成提示
            'data-ajax--url': '/admin/yourapp/instructions/autocomplete/',
            'data-placeholder': '输入或选择说明'
        })
    )

    class Meta:
        model = Task
        fields = '__all__'

# 绑定到Admin类
class TaskAdmin(ModelAdmin):
    form = TaskAdminForm

3. （可选）添加自动完成提示接口

如果需要从现有Instructions中获取提示，创建一个自动完成视图：

from django.contrib.auth.mixins import LoginRequiredMixin
from django.http import JsonResponse
from django.views.generic import View
from .models import Instructions

class InstructionsAutocompleteView(LoginRequiredMixin, View):
    def get(self, request):
        query = request.GET.get('term', '')
        # 匹配包含关键词的内容，返回前10条
        matches = Instructions.objects.filter(content__icontains=query)[:10]
        results = [{'id': item.content, 'text': item.content} for item in matches]
        return JsonResponse({'results': results})

在urls.py中注册该视图：

from django.urls import path
from .views import InstructionsAutocompleteView

urlpatterns = [
    # ... 其他路由
    path('admin/yourapp/instructions/autocomplete/', InstructionsAutocompleteView.as_view(), name='instructions-autocomplete'),
]

方案选择 #

• 保留外键：适合需要复用说明内容、统计使用场景的需求，数据结构更规范。
• 改为TextField：适合轻量化需求，实现更简单，无需维护关联模型。

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