如何让Django Model Choice Field支持多条件匹配？

问题背景 #

现有如下定义的Product模型：

class Product(models.Model):
    code = models.CharField(max_length=20, unique=True)
    name = models.CharField(max_length=100) # 故意设为非唯一

需求：可通过产品的code或name字段选择产品，例如产品1的code为SUS304、name为Stainless Steel 304时，输入两者任一值都应选中该产品。

尝试使用union查询集作为数据源，但Django提示不支持在.union后调用.filter方法，尝试代码如下：

class OrderForm(forms.ModelForm):
    codes = Product.objects.annotate(full=F('code'))
    names = Product.objects.annotate(full=F('name'))
    product = forms.ModelChoiceField(codes.union(names), to_field_name='full')
    class Meta:
        # Order是另一个拥有指向Product外键的模型
        model = Order
        fields = ['product']

补充说明：

• 可能存在多个产品重名，或某产品名称是另一产品编码的情况，此时需抛出ValidationError。
• 无法通过长度等规则有效区分输入字符串是编码还是名称，例如SUS304也可能是产品名称。

解决方案 #

通过自定义ModelChoiceField子类，在字段验证阶段处理输入值的匹配逻辑，是Django的标准实现方式，具体步骤如下：

1. 自定义产品选择字段 #

from django import forms
from django.core.exceptions import ValidationError
from django.db.models import Q

class ProductChoiceField(forms.ModelChoiceField):
    def label_from_instance(self, obj):
        # 下拉选项同时显示编码和名称，方便用户直观选择
        return f"{obj.code} - {obj.name}"

    def clean(self, value):
        # 处理下拉选择的场景（value为产品ID）
        if value and value.isdigit():
            return super().clean(value)
        
        # 处理手动输入的编码/名称
        if not value:
            raise ValidationError("请输入产品编码或名称")
        
        # 查询匹配编码或名称的产品
        matches = self.queryset.filter(Q(code=value) | Q(name=value))
        
        if not matches.exists():
            raise ValidationError("找不到匹配的产品")
        
        if matches.count() > 1:
            raise ValidationError("输入值匹配到多个产品，请输入更精确的内容")
        
        return matches.first()

2. 在表单中使用自定义字段 #

class OrderForm(forms.ModelForm):
    product = ProductChoiceField(
        queryset=Product.objects.all(),
        # 使用文本输入框，允许用户手动输入内容
        widget=forms.TextInput(attrs={'placeholder': '输入产品编码或名称'})
    )

    class Meta:
        model = Order
        fields = ['product']

方案说明 #

• label_from_instance方法：自定义下拉选项的展示内容，同时显示编码和名称，避免用户混淆同名产品。
• clean方法：
  • 区分下拉选择（产品ID）和手动输入两种场景，兼容不同的交互方式。
  • 通过Q构造查询条件，同时匹配编码和名称字段。
  • 严格处理三种异常场景：无匹配结果、多个匹配结果、空输入，确保数据有效性。
• 文本输入组件：替换默认的下拉组件，支持用户自由输入编码或名称，满足需求场景。

可选优化：模糊匹配 #

如果需要支持部分字符串匹配（比如输入"304"就能找到相关产品），可以修改查询条件为：

matches = self.queryset.filter(
    Q(code__icontains=value) | Q(name__icontains=value)
)

注意：模糊匹配可能返回更多结果，需要调整验证提示，引导用户输入更精确的内容。

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