Django ModelForm

1. 概述

1.1 什么是 ModelForm？

ModelForm 是 Django 表单 (forms.Form) 的高级封装，专门用于简化基于数据库模型创建表单的过程。它能够自动从指定的 Django 模型生成表单字段，并处理数据的验证、保存等操作。

1.2 核心价值

• 自动化字段生成：根据 Model 字段定义自动生成对应表单字段
• 内置验证：自动使用 Model 字段的约束作为表单验证规则
• 快速保存数据 ：提供 save() 方法直接操作数据库
• 高维护性 ：模型变化时只需更新 Meta 类，无需重写表单逻辑

2. ModelForm 基础用法

2.1 定义模型

# models.py
from django.db import models

class Article(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    published_date = models.DateField(blank=True, null=True)
    is_published = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

2.2 创建 ModelForm

# forms.py
from django import forms
from .models import Article

class ArticleForm(forms.ModelForm):
    # 额外添加的字段（不会保存到模型中）
    confirm = forms.BooleanField(
        label="我确认内容正确", 
        required=True,
        help_text="请确认文章内容无误"
    )

    class Meta:
        model = Article  # 指定关联的模型
        fields = ['title', 'content', 'published_date', 'is_published']  # 包含的字段
        # fields = '__all__'  # 包含所有字段
        # exclude = ['created_at']  # 排除某些字段

        # 自定义配置
        labels = {
            'title': '文章标题',
            'is_published': '立即发布',
        }
        help_texts = {
            'title': '请输入一个吸引人的标题（最多200字）',
        }
        widgets = {
            'content': forms.Textarea(attrs={
                'rows': 6, 
                'cols': 50,
                'placeholder': '请输入文章内容...'
            }),
            'published_date': forms.SelectDateWidget(
                years=range(2020, 2030)
            ),
        }
        error_messages = {
            'title': {
                'max_length': "标题太长了，请不要超过200个字符",
                'required': "标题不能为空",
            },
        }

3. is_valid() 方法详解

3.1 核心功能

is_valid() 是表单的核心验证方法，触发完整的验证流程并返回布尔值表示数据是否有效。

3.2 验证流程

1. 字段清理 (Field Cleaning)

   • 转换数据到合适的 Python 类型
   • 失败示例：IntegerField 中输入 "abc"

2. 字段验证 (Field Validation)

   • 检查字段特定规则：max_length, min_length, 格式等

3. 自定义字段级验证

   • 调用 clean_<fieldname>() 方法

4. 表单级验证

   • 调用 clean() 方法检查多字段关系

5. 返回结果

   • 所有步骤通过 → 返回 True
   • 任何步骤失败 → 返回 False

3.3 重要属性

• cleaned_data ：清理后的有效数据字典（仅在 is_valid() 返回 True 时可用）
• errors ：包含所有验证错误信息的对象（仅在 is_valid() 返回 False 时包含数据）

4. 在视图中使用 ModelForm

4.1 创建新对象

# views.py
from django.shortcuts import render, redirect
from django.contrib import messages
from .forms import ArticleForm

def article_create_view(request):
    if request.method == 'POST':
        form = ArticleForm(request.POST)
        if form.is_valid():
            article = form.save()  # 自动创建并保存新对象
            messages.success(request, f'文章 "{article.title}" 创建成功！')
            return redirect('article_detail', pk=article.pk)
        else:
            messages.error(request, '请修正下面的错误')
    else:
        form = ArticleForm()

    return render(request, 'articles/article_form.html', {'form': form})

4.2 编辑现有对象

# views.py
from django.shortcuts import render, redirect, get_object_or_404
from .models import Article
from .forms import ArticleForm

def article_update_view(request, pk):
    article = get_object_or_404(Article, pk=pk)
    
    if request.method == 'POST':
        form = ArticleForm(request.POST, instance=article)
        if form.is_valid():
            updated_article = form.save()  # 更新现有对象
            return redirect('article_detail', pk=updated_article.pk)
    else:
        form = ArticleForm(instance=article)  # 用实例数据预填充表单

    return render(request, 'articles/article_form.html', {
        'form': form, 
        'article': article
    })

4.3 使用类视图（推荐）

# views.py
from django.views.generic.edit import CreateView, UpdateView
from django.urls import reverse_lazy
from .models import Article
from .forms import ArticleForm

class ArticleCreateView(CreateView):
    model = Article
    form_class = ArticleForm  # 使用自定义 ModelForm
    template_name = 'articles/article_form.html'
    success_url = reverse_lazy('article_list')

class ArticleUpdateView(UpdateView):
    model = Article
    form_class = ArticleForm
    template_name = 'articles/article_form.html'
    
    def get_success_url(self):
        return reverse_lazy('article_detail', kwargs={'pk': self.object.pk})

5. 高级功能

5.1 自定义验证方法

class ArticleForm(forms.ModelForm):
    # ... Meta 配置 ...
    
    # 字段级自定义验证
    def clean_title(self):
        title = self.cleaned_data.get('title')
        if len(title.strip()) < 5:
            raise forms.ValidationError("标题至少需要5个字符")
        if "test" in title.lower():
            raise forms.ValidationError("标题不能包含'test'字样")
        return title

    # 表单级自定义验证（多字段检查）
    def clean(self):
        cleaned_data = super().clean()
        title = cleaned_data.get('title')
        content = cleaned_data.get('content')
        is_published = cleaned_data.get('is_published')

        if is_published and not content:
            raise forms.ValidationError("发布文章前必须填写内容")
            
        if title and content and title in content:
            raise forms.ValidationError("标题不应重复出现在内容中")
            
        return cleaned_data

5.2 自定义 save() 方法

class ArticleForm(forms.ModelForm):
    # ... Meta 配置 ...
    
    def save(self, commit=True):
        # 获取实例但不立即保存
        instance = super().save(commit=False)
        
        # 对实例进行额外操作
        if instance.is_published and not instance.published_date:
            from django.utils import timezone
            instance.published_date = timezone.now().date()
        
        # 根据 commit 参数决定是否保存
        if commit:
            instance.save()
            # 如果有 ManyToMany 字段，需要额外保存
            self.save_m2m()
        
        return instance

6. 模板中的表单渲染

6.1 自动渲染

<!-- article_form.html -->
<form method="post" novalidate>
    {% csrf_token %}
    
    <!-- 自动以段落形式渲染所有字段 -->
    {{ form.as_p }}
    
    <button type="submit" class="btn btn-primary">保存</button>
    <a href="{% url 'article_list' %}" class="btn btn-secondary">取消</a>
</form>

6.2 手动渲染（推荐）

<form method="post" novalidate>
    {% csrf_token %}
    
    {% if form.non_field_errors %}
        <div class="alert alert-danger">
            {{ form.non_field_errors }}
        </div>
    {% endif %}
    
    <div class="mb-3">
        {{ form.title.label_tag }}
        {{ form.title }}
        {% if form.title.errors %}
            <div class="text-danger">
                {{ form.title.errors }}
            </div>
        {% endif %}
        {% if form.title.help_text %}
            <div class="form-text">{{ form.title.help_text }}</div>
        {% endif %}
    </div>
    
    <div class="mb-3">
        {{ form.content.label_tag }}
        {{ form.content }}
        {% if form.content.errors %}
            <div class="text-danger">
                {{ form.content.errors }}
            </div>
        {% endif %}
    </div>
    
    <div class="mb-3">
        {{ form.published_date.label_tag }}
        {{ form.published_date }}
    </div>
    
    <div class="mb-3 form-check">
        {{ form.is_published }}
        {{ form.is_published.label_tag }}
    </div>
    
    <div class="mb-3 form-check">
        {{ form.confirm }}
        {{ form.confirm.label_tag }}
        <div class="form-text">{{ form.confirm.help_text }}</div>
    </div>
    
    <button type="submit" class="btn btn-primary">保存</button>
</form>

7. Meta 类配置选项

选项	说明	示例
model	必需。指定关联的模型	model = Article
fields	指定包含的字段	fields = ['title', 'content']
exclude	指定排除的字段	exclude = ['created_at']
widgets	覆盖字段默认小部件	widgets = {'content': forms.Textarea}
labels	自定义字段标签	labels = {'title': '文章标题'}
help_texts	自定义帮助文本	help_texts = {'title': '输入标题'}
error_messages	覆盖错误信息	error_messages = {'title': {'required': '必填'}}
localized_fields	指定本地化字段	localized_fields = '__all__'

8. 最佳实践

8.1 安全建议

• 始终使用 is_valid() 验证用户输入
• 不要直接使用 request.POST 数据
• 使用 csrf_token 防止跨站请求伪造

8.2 性能建议

• 在 Meta 中明确指定 fields 而不是使用 '__all__'
• 对于大型表单，考虑使用 fieldsets 或分步表单
• 合理使用 SelectDateWidget 等小部件减少数据库查询

8.3 代码组织建议

• 为复杂的表单逻辑创建自定义表单类
• 使用类视图减少重复代码
• 将表单模板标签提取为可重用组件

9. 常见问题解答

Q: 什么时候使用 ModelForm vs 普通 Form？

A: 当表单直接对应一个模型时使用 ModelForm，否则使用普通 Form。

Q: is_valid() 返回 False 时怎么办？

A: 重新渲染表单，Django 会自动显示错误信息。

Q: 如何修改某个字段的默认小部件？

A: 在 Meta.widgets 中指定或直接在表单类中重新定义字段。

Q: commit=False 有什么用？

A: 允许你在保存到数据库前对模型实例进行额外操作。

10. 总结

ModelForm 是 Django 开发中极其强大的工具，它：

• 遵循 DRY（Don't Repeat Yourself）原则
• 自动化常见任务，提高开发效率
• 提供强大的数据验证机制
• 与 Django 的模型系统无缝集成