什么是 ModelForm

Model 在 Django 对应数据库模型
- 一个 Model 拥有多个 Model.Field
Form 在 Django 对应表单
- 一个 Form 拥有多个 Form.Field

ModelForm 即基于 Model 的 Form，把 Model 中的 Field 根据下图中的映射关系自动转化为 Form 中的 Field。

为什么使用 ModelForm

利用 Model 生成 Form，提高 Model 复用性

如何使用 ModelForm

定义 ModelForm

举一个书籍管理例子

# Model

class Article(models.Model):
    title = models.CharField(max_length=20, unique=True)
    author = models.ForeignKey('Author')

这个 Model 中定义了两个字段

title
- 储存书籍标题
- 数据类型是 char
- 最大长度 20
- 数据库唯一值限制，即不能储存两本相同标题的书
author
- 储存书籍的作者
- 数据类型是外键，指向 Model Author

下面我们用 ModelForm 构建表单

# ModelForm

class ArticleForm(forms.ModelForm):
    class Meta:
        model = Article

和下面手动构建表单的代码等效

class ArticleForm(forms.Form):
    title = forms.CharField(max_length=20)
    author = forms.ModelChoiceField(queryset=Author.objects.all())

定制 ModelForm

很多情况下自动生成的 ModelForm 并不能满足设计要求，下面我们来讲一下如何定制

定制有两种方式

Meta
- 使用 Model 转化的时候自定义转化规则
自定义字段
- 定义额外的 Field，会覆盖 Model 自动生成的 Field

在 Form 中另外定义 Field

这是 Form 中定义 Field 的通用方法，在 ModelForm 中它有两个作用

补充 Model 没有的 Field 到 Form
覆盖 Model 中的同名 Field 定义

且看下面的例子，Article 中已经包含了 title 字段，我们在 ModelForm 中重新定义了它，把 CharField 改为了 ChoiceField，并且自定义了 validators。

覆盖 title 的时候，把 title 从 Meta 中 exclude 掉是可选的，去不去掉的区别在于，你是否需要它为你校验 unique=True 这个数据库级限制。
在这里我们需要校验，因为 ModelForm 校验通过后我需要把它存入数据库，如果这里没有校验的话，碰到同标题的书数据库就会在储存时报错，我们希望把这步校验放在 ModelForm 的校验中，而不是在通过校验后再用 try... catch... 来捕获它。

class ArticleForm(forms.ModelForm):
    title = forms.ChoiceFied(choices=((1, 'alice'), (2, 'bob'),), validators=MaxValueValidator(2))

    class Meta:
        model = Article

值得一提的一些 Field 转化

AutoField

该 Field 不会出现在 ModelForm 表单中。

所有 editable=False 的 Field 都不会出现在 ModelForm 中。

BooleanField

由于表单提交时统一识别为 string，而 BooleanField 是用 python 中的 bool 来判断的，所以只要传了任意非空值，BooleanField 都会当做 True 来处理，而如果传了空值，由于 forms.Field 默认属性是 required=True，会校验失败，所以如果你需要一个可以填 False 的 Field，那么你需要在 Form 中手动设置这个 Field 的 required=False。

ForeignKey

ForeignKey 自动转化为 ModelChoiceField，用下拉选项菜单渲染，默认渲染出来的选项显示为对应 Field 的 __str__，提交的值为对应 Field 的 id，这些都可以定制。

在后端接收提交的时候会自动在对应的 Model 中用 id 去找，如果没找到则抛出 ValidationError。

ManyToManyField

ManyToManyField 自动转化为 ModelMultipleChoiceField，用多选框渲染，同样默认渲染出来的选项显示为对应 Field 的 __str__，提交的值为对应 Field 的 id 值。

比如有个叫 group 的 ManyToManyField，选中了 'finance' 'develop' 这两个选项，他们的 id 分别为 1 和 2，那么世界上提交的表单 QueryString 就是 group=1&group=2

初始化 ModelForm

form = ArticleForm(request.POST)

article = Article.objects.get(pk=1)
author = Author.objects.first()

form = ArticleForm(request.POST, instance=article, initial={'author': author})
# form 绑定到 article 实例了 
# 初始化表单的时候，author 字段的初始值为 author

if form.is_valid():
    form.save()

instance
- 给 ModelForm 初始化 Model 实例，后续的操作都作用在这个实例上
initial
- 给 ModelForm 初始值
- 如果和 instance 同时被定义，同名 field 的值覆盖 instance 中的值

数据加载的先后顺序为 instance, initial, request.POST

校验 ModelForm

Form 只会检查内部定义过的 Field，request.POST 中其余 keyword 都会被无视和过滤掉，即不会出现在返回的 cleaned_data 中。

form = ArticleForm(request.POST)

# 校验表单 
if form.is_valid():
    # 保存到数据库 
    article = form.save()

is_valid() 会调用 full_clean() 来对表单进行全面校验，它又分成三步（定义在基类 Form 中）

根据每个 Field 注册的 validators 做单个 Field 的校验 (比如 title 字段就会校验是否超出最大允许长度 20) 其中在 Field.clean() 执行过后提供了钩子 clean_[field_name]，可以自定义该 function 来注册自己的校验方法。
根据 Form 定义的 Field 之间的依赖关系做整个表单的校验，钩子为 clean()，默认为空。
自定义校验通过后的表单处理，钩子为 _post_clean()
- 这一步中，ModelForm 做了一些额外的检验：如果定义在 Meta 中的 Field 有 unique=True这个限制，那么 ModelForm 会按照现有数据库中的数据对其校验，看这个 Field 的值是否已存在，如果已存在，则抛出一个 IntegrityError。实际操作中如果强制不校验 unique 的话，可以把该字段从 Meta 中移除，在 ModelForm 中重新定义该字段。

储存 ModelForm 对象

调用 save() 的时候可以传入 commit=False 来避免立即储存，从而通过后续的修改或补充来得到完整的 Model 实例后再储存到数据库。

如果初始化的时候传入了 instance，那么调用 save() 的时候会用 ModelForm 中定义过的字段值覆盖绑定实例的相应字段，并写入数据库。

save() 同样会帮你储存 ManyToManyField，如果 save 时使用了 commit=False，那么 ManyToManyField 的储存需要等该条目存入数据库之后手动调用 ModelForm 的 save_m2m() 方法。

定义一个 Form 来新建、更新实例

通常的步骤分为如下几步

检测该对象是否已在数据库
- 如果已存在，那么手动获取该实例，然后更改相关 field 内容，最后使用 update() 方法保存到数据库
- 如果不存在，新建一个 Model 实例并修改至完整的 Model，调用 save() 方法保存到数据库

写成代码的话是这样子

f = AuthorForm(request.POST)

if f.is_valid():
    try:
        # Save the new instance.
        new_author = f.save(commit=False)
        new_author.some_field = f.cleaned_data['some_field']
        new_author.save()
    except IntegrityError:
        # 已存在 
        # 若要这样使用 update 的话需要在 cleaned_data 中加入上述 some_field 的改动 
        # 因为 some_field 的改动只在 new_author 中使用，并不能更新到数据库 
        Author.objects.filter(pk=f.cleaned_data['pk']).update(f.cleaned_data)

太麻烦了！！其实 Django 中已经有 update_or_create 方法已经实现了上述所有功能，可以避免这个 try ... except ... 判断实例是否已存在，我们来看这个例子

# forms.py

class AuthorAddForm(forms.ModelForm):
    # 确保 pk 不是必须字段 
    # 如果不传，自动识别为 None
    pk = forms.IntegerField(required=False)

    class Meta:
        model = Author
        fields = ['name', 'address']

    def _post_clean(self):
        super(forms.ModelForm, self)._post_clean()
        # 不传 pk 的话表示需要新建一个条目 
        if not self.cleaned_data['pk']:
            # 添加需要的 Field
            self.cleaned_data['Origin'] = City.objects.get(Province='北京', City='北京')

# views.py

class AuthorsView(LoginRequiredMixin, TemplateView):
    template_name = 'authors.html'

    def post(self, request):
        form = AuthorAddForm(request.POST)
        result = {}

        if not form.is_valid():
            return form.errors

        # 如果 pk 不存在，为 None，那么 update_or_create 匹配失败，从而进入 create 流程 
        # 否则 pk 存在表单中，那么尝试匹配数据库，如果命中，进行 update 操作，否则进行 create 操作 
        Author, created = Author.objects.update_or_create(pk=form.cleaned_data['pk'], defaults=form.cleaned_data)

        return Author.pk

其中 update_or_create 通过检测所有非 defaults 的字段，在上述例子中就是 id=form.cleaned_data['id'] 一项是否已存在于数据库而判断是用 update() 还是 create()，而不论是 update() 还是 create()，都会使用 cleaned_data 作为数据源来写入数据库。

floodwater

Django 中 ModelForm 的使用