Effective Django 项目中的表单基础教程

2025-07-06 15:07:28作者：傅爽业Veleda

什么是 Django 表单

Django 表单是处理用户输入的核心组件，它主要完成三个关键任务：

验证用户输入数据的合法性
将原始输入数据转换为 Python 对象
提供便捷的 HTML 渲染方式

表单与模型(Model)类似，都是由字段(Field)组成的，但它们的用途不同：模型字段用于数据库映射，而表单字段用于输入验证和转换。

定义表单

创建一个基本的表单类非常简单，下面是一个联系人表单的示例：

from django import forms
from django.utils.translation import gettext_lazy as _

class ContactForm(forms.Form):
    name = forms.CharField(
        label=_("Your Name"),
        max_length=255,
        widget=forms.TextInput,
    )
    email = forms.EmailField(label=_("Email address"))

每个表单字段都可以配置：

label：字段的显示标签
max_length：最大长度限制
widget：指定如何渲染该字段的HTML元素
以及其他字段特定的参数

表单实例化与绑定

Django 表单有两种状态：

未绑定表单：没有关联任何数据
```
form = ContactForm()  # 未绑定
```

已绑定表单：关联了用户提交的数据

form = ContactForm(data=request.POST, files=request.FILES)  # 已绑定

只有已绑定表单才能进行数据验证。

表单验证机制

Django 表单验证分为两个阶段：

1. 字段级验证

每个字段独立进行验证，包括：

to_python()：将原始输入转换为Python对象
执行字段验证器(validators)
clean_<fieldname>()：字段特定的清理方法

验证流程如下：

原始输入 → to_python() → 验证器 → clean_<fieldname>() → 最终值

2. 表单级验证

在所有字段验证通过后执行：

可以访问所有已验证的字段值
适合需要跨字段比较的逻辑
通过实现 clean() 方法实现

def clean(self):
    cleaned_data = super().clean()
    email = cleaned_data.get('email')
    confirm_email = cleaned_data.get('confirm_email')
    
    if email != confirm_email:
        raise forms.ValidationError("Email addresses must match.")
    
    return cleaned_data

表单渲染控制

Django 提供了多种表单渲染方式：

快速渲染方法：

form.as_p()    # 渲染为<p>标签
form.as_ul()   # 渲染为<ul>列表
form.as_table() # 渲染为<table>表格

自定义渲染（推荐）：

{% for field in form %}
<div class="field-wrapper">
    {{ field.label_tag }}
    {{ field }}
    {% if field.errors %}
    <div class="error">{{ field.errors }}</div>
    {% endif %}
    {% if field.help_text %}
    <p class="help">{{ field.help_text }}</p>
    {% endif %}
</div>
{% endfor %}

可用的字段渲染属性：

field.label：字段标签文本
field.label_tag：包含完整HTML的标签
field.errors：字段错误信息
field.help_text：字段帮助文本
field.is_hidden：是否为隐藏字段

模型表单(ModelForm)

当表单与模型紧密关联时，可以使用 ModelForm 自动生成表单字段：

from django import forms
from .models import Contact

class ContactForm(forms.ModelForm):
    confirm_email = forms.EmailField(
        label="Confirm email",
        required=True,
    )
    
    class Meta:
        model = Contact
        fields = ['first_name', 'last_name', 'email']

ModelForm 会根据模型定义自动创建对应的表单字段，同时允许添加额外的字段。

表单测试

测试表单验证逻辑非常重要，可以使用单元测试来验证：

from django.test import TestCase
from rebar.testing import flatten_to_dict
from .forms import ContactForm

class ContactFormTests(TestCase):
    def test_email_matching(self):
        # 测试邮箱匹配情况
        form_data = flatten_to_dict(ContactForm())
        form_data.update({
            'first_name': 'Test',
            'last_name': 'User',
            'email': 'test@example.com',
            'confirm_email': 'test@example.com',
        })
        
        form = ContactForm(data=form_data)
        self.assertTrue(form.is_valid())
        
    def test_email_mismatch(self):
        # 测试邮箱不匹配情况
        form_data = flatten_to_dict(ContactForm())
        form_data.update({
            'first_name': 'Test',
            'last_name': 'User',
            'email': 'test@example.com',
            'confirm_email': 'wrong@example.com',
        })
        
        form = ContactForm(data=form_data)
        self.assertFalse(form.is_valid())
        self.assertIn('email', form.errors)