Django 6 ModelForm 教程

ModelForm 是 Django 中一个强大的工具，它基于模型（Model）自动生成表单，简化了表单创建和数据处理的流程。本教程将带你从零开始，详细学习 ModelForm 的定义、字段映射、验证自定义以及保存操作。

1. 模型表单定义与字段映射

什么是 ModelForm？

ModelForm 是 Django 的一个表单类，它通过关联数据库模型来自动生成表单字段。这样，开发者无需手动定义每个字段，可以节省时间并减少错误。

如何定义 ModelForm

首先，你需要有一个 Django 模型。假设我们有一个 Book 模型，定义如下：

# models.py
from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.CharField(max_length=100)
    publication_date = models.DateField()
    price = models.DecimalField(max_digits=6, decimal_places=2)

然后，可以创建一个 ModelForm 来生成对应这个模型的表单。在 forms.py 中定义：

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

class BookForm(forms.ModelForm):
    class Meta:
        model = Book  # 指定关联的模型
        fields = ['title', 'author', 'publication_date', 'price']  # 指定表单包含的字段
        # 也可以使用 fields = '__all__' 来包含所有字段

字段映射

当 ModelForm 定义好后，Django 会自动根据模型字段类型生成对应的表单字段类型。例如：

• CharField 映射到 forms.CharField
• DateField 映射到 forms.DateField
• DecimalField 映射到 forms.DecimalField

你可以在模板中使用这个表单来渲染 HTML。示例：

<!-- template.html -->
<form method="post">
  {% csrf_token %}
  {{ form.as_p }}  <!-- 将表单渲染为段落形式 -->
  <button type="submit">提交</button>
</form>

2. 模型表单验证与自定义

内置验证

ModelForm 会自动根据模型定义的约束进行验证。例如，如果模型字段有 max_length 或 null=False，表单会相应验证数据长度和必填项。

在视图中处理表单时，可以通过 is_valid() 方法验证数据：

# views.py
from django.shortcuts import render
from .forms import BookForm

def create_book(request):
    if request.method == 'POST':
        form = BookForm(request.POST)
        if form.is_valid():  # 验证表单数据
            # 数据有效，准备保存
            pass
        else:
            # 数据无效，显示错误
            pass
    else:
        form = BookForm()
    return render(request, 'template.html', {'form': form})

自定义验证

你可以为 ModelForm 添加自定义验证逻辑。有两种主要方式：

1. 覆盖 clean 方法：对整个表单进行验证。
2. 为特定字段添加验证方法：格式为 clean_<field_name>。

示例：添加自定义验证，确保价格不为负数。

# forms.py
class BookForm(forms.ModelForm):
    class Meta:
        model = Book
        fields = '__all__'

    def clean_price(self):
        price = self.cleaned_data.get('price')
        if price < 0:
            raise forms.ValidationError("价格不能为负数")
        return price

    def clean(self):  # 整体验证示例
        cleaned_data = super().clean()
        title = cleaned_data.get('title')
        author = cleaned_data.get('author')
        if title == author:
            raise forms.ValidationError("书名和作者不能相同")
        return cleaned_data

3. 模型表单保存（save 方法）与关联数据处理

save 方法的使用

当表单验证通过后，可以使用 save() 方法将数据保存到数据库。save() 方法会创建或更新模型实例。

# views.py
def create_book(request):
    if request.method == 'POST':
        form = BookForm(request.POST)
        if form.is_valid():
            book = form.save()  # 保存数据到数据库
            # book 现在是 Book 模型的一个实例
            return redirect('book_detail', pk=book.pk)  # 假设重定向到详情页
    else:
        form = BookForm()
    return render(request, 'template.html', {'form': form})

• 如果表单绑定了一个现有实例（例如通过 instance 参数），save() 会更新该实例。
• 如果不绑定实例，save() 会创建一个新实例。

关联数据处理

当模型有外键（ForeignKey）或多对多（ManyToManyField）关系时，ModelForm 也能处理关联数据。

示例：假设我们扩展模型，添加一个 Category 模型和关联。

# models.py
class Category(models.Model):
    name = models.CharField(max_length=100)

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.CharField(max_length=100)
    categories = models.ManyToManyField(Category)  # 多对多关联

在 ModelForm 中，Django 会自动生成一个字段来处理多对多关系，例如一个多选框。在表单定义中：

# forms.py
from .models import Book, Category

class BookForm(forms.ModelForm):
    class Meta:
        model = Book
        fields = ['title', 'author', 'categories']  # 包含关联字段

在视图中，save() 方法会自动保存关联数据。对于 ManyToManyField，需要先保存主实例，然后处理关联。但在 ModelForm 中，这可以简化：

# views.py
def create_book(request):
    if request.method == 'POST':
        form = BookForm(request.POST)
        if form.is_valid():
            book = form.save()  # 这会自动保存 Book 实例和关联的 categories
            # 注意：对于 ManyToManyField，需要在保存后处理，但 ModelForm 的 save 方法会处理
            # 如果需要额外逻辑，可以使用 form.save(commit=False)
            pass
    else:
        form = BookForm()
    return render(request, 'template.html', {'form': form})

• 使用 save(commit=False) 可以延迟保存，以便在保存前添加额外操作。
• 示例：手动添加关联数据。

# views.py
if form.is_valid():
    book = form.save(commit=False)  # 不立即保存到数据库
    book.publication_date = timezone.now()  # 添加额外数据
    book.save()  # 保存 Book 实例
    form.save_m2m()  # 保存多对多关联数据，如果使用 commit=False
    # 或者，可以直接在 form.save() 中处理，但使用 commit=False 提供更多控制

总结

ModelForm 是 Django 开发中处理表单的强大工具，它能自动映射模型字段、简化验证和保存流程。通过本教程，你应该已经掌握了 ModelForm 的定义、字段映射、验证自定义以及如何保存数据和处理关联。在实践中多加练习，可以快速提升 Django 开发效率。

进阶提示

• 使用 widgets 属性自定义表单字段的 HTML 表现。
• 利用 exclude 属性排除不需要的字段。
• 在 ModelForm 中覆盖字段以添加额外属性，如 widgets 或 labels。

示例：自定义字段标签和帮助文本。

class BookForm(forms.ModelForm):
    class Meta:
        model = Book
        fields = '__all__'
        labels = {
            'title': '书籍标题',
            'author': '作者'
        }
        help_texts = {
            'price': '请输入正数价格'
        }

希望这个教程能帮助你更好地理解和使用 Django 6 的 ModelForm！