使用CheckboxSelectMultiple与Crispy Forms时.controls div重复表单属性问题

问题根源 #

Crispy Forms 1.13.0在渲染CheckboxSelectMultiple组件时，会将<form>标签上的全局属性（包括HTMX的hx-*属性）意外继承到存放复选框的<div class="controls">容器上。这就导致点击复选框时，form和div上的HTMX触发逻辑同时生效，发起两次请求，且第一次请求因为没有正确携带表单数据而出错。

解决方案 #

1. 用FormTag组件手动控制表单属性（推荐）

不要直接给FormHelper.attrs添加HTMX属性，而是通过FormTag布局组件单独给<form>标签设置属性，避免属性被传递到子组件：

from django import forms
from crispy_forms.helper import FormHelper
from crispy_forms.layout import Layout, FormTag, Fieldset, Field

YOUR_CHOICES = (
    ('opt1', '选项1'),
    ('opt2', '选项2'),
    ('opt3', '选项3'),
)

class FilterForm(forms.Form):
    multiple_options = forms.MultipleChoiceField(
        choices=YOUR_CHOICES,
        widget=forms.CheckboxSelectMultiple,
        required=False
    )

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.helper = FormHelper()
        self.helper.form_method = 'get'
        
        # 用FormTag单独定义form标签的HTMX属性
        self.helper.layout = Layout(
            FormTag(attrs={
                'hx-get': '.',
                'hx-target': '#results-container',
                'hx-trigger': 'change'
            }),
            Fieldset(
                '筛选条件',
                Field('multiple_options')
            )
        )
        # 注意：不要设置 self.helper.attrs = {...}，避免属性扩散

2. 自定义CheckboxSelectMultiple模板

如果上面的方法不适用，可以自定义widget模板，强制不继承父元素的属性：

1. 在项目templates/widgets/目录下创建checkbox_select_multiple.html：

{% load crispy_forms_field %}
<div class="controls">
    {% for choice in field.field.choices %}
        <div class="checkbox">
            <label for="{{ field.id_for_label }}_{{ forloop.counter }}">
                <input 
                    type="checkbox"
                    {% if choice.0 in field.value or choice.0|stringformat:"s" in field.value %} checked{% endif %}
                    name="{{ field.html_name }}"
                    id="{{ field.id_for_label }}_{{ forloop.counter }}"
                    value="{{ choice.0|stringformat:"s" }}"
                >
                {{ choice.1 }}
            </label>
        </div>
    {% endfor %}
</div>

2. 在表单中使用自定义widget：

class CustomCheckboxSelectMultiple(forms.CheckboxSelectMultiple):
    template_name = 'widgets/checkbox_select_multiple.html'

# 表单字段中替换widget
multiple_options = forms.MultipleChoiceField(
    choices=YOUR_CHOICES,
    widget=CustomCheckboxSelectMultiple,
    required=False
)

3. 前端临时修复（备选）

如果不想修改后端代码，也可以用JS阻止事件冒泡，避免触发两次请求：

document.querySelector('#your-form-id').addEventListener('change', function(e) {
    if (e.target.tagName === 'INPUT' && e.target.type === 'checkbox') {
        e.stopPropagation();
    }
});

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