第四章：Django表单 - 5：模型表单ModelForm

如果你正在构建一个数据库驱动的应用，那么你可能会有与Django的模型紧密映射的表单。比如，你有个BlogComment模型，并且你还想创建一个表单让大家提交评论到这个模型中。在这种情况下，写一个forms.Form类，然后在表单类中定义字段，这种一般创建表单的做法是冗余的，因为你已经在ORM模型model中定义了字段的属性和功能，完全没必要重新写一遍字段。

一、核心用法

基于这个原因，Django提供一个辅助类帮助我们利用Django的ORM模型model创建Form。

像下面这样：

>>> from django.forms import ModelForm

>>> from myapp.models import Article

# 创建表单类

>>> class ArticleForm(ModelForm):

...     class Meta:

...         model = Article

...         fields = ['pub_date', 'headline', 'content', 'reporter']

# 创建一个表单，用于添加文章

>>> form = ArticleForm()

# 创建表单修改已有的文章

>>> article = Article.objects.get(pk=1)

>>> form = ArticleForm(instance=article)

用法的核心是：

首先从django.forms导入ModelForm；
编写一个自己的类，继承ModelForm；
在新类里，设置元类Meta；
在Meta中，设置model属性为你要关联的ORM模型，这里是Article；
在Meta中，设置fields属性为你要在表单中使用的字段列表；
列表里的值，应该是ORM模型model中的字段名。

上面的例子中，因为model和form比较简单，字段数量少，看不出这么做的威力和效率。但如果是那种大型项目，每个模型的字段数量几十上百，这么做的收益将非常巨大，而且后面还有一招提高效率的大杀器，也就是一步保存数据的操作。

二、字段类型

生成的Form类中将具有和指定的模型字段对应的表单字段，顺序为fields属性列表中指定的顺序。

每个模型字段有一个对应的默认表单字段。比如，模型中的CharField表现成表单中的CharField。模型中的ManyToManyField字段会表现成MultipleChoiceField字段。下面是完整的映射列表：

模型字段	表单字段
AutoField	在Form类中无法使用
BigAutoField	在Form类中无法使用
BigIntegerField	IntegerField，最小-9223372036854775808，最大9223372036854775807.
BooleanField	BooleanField
CharField	CharField，同样的最大长度限制。如果model设置了null=True，Form将使用empty_value
CommaSeparatedIntegerField	CharField
DateField	DateField
DateTimeField	DateTimeField
DecimalField	DecimalField
EmailField	EmailField
FileField	FileField
FilePathField	FilePathField
FloatField	FloatField
ForeignKey	ModelChoiceField
ImageField	ImageField
IntegerField	IntegerField
IPAddressField	IPAddressField
GenericIPAddressField	GenericIPAddressField
ManyToManyField	ModelMultipleChoiceField
NullBooleanField	NullBooleanField
PositiveIntegerField	IntegerField
PositiveSmallIntegerField	IntegerField
SlugField	SlugField
SmallIntegerField	IntegerField
TextField	CharField，并带有widget=forms.Textarea参数
TimeField	TimeField
URLField	URLField

可以看出，Django在设计model字段和表单字段时存在大量的相似和重复之处。

ManyToManyField和 ForeignKey字段类型属于特殊情况：

ForeignKey被映射成为表单类的django.forms.ModelChoiceField，它的选项是一个模型的QuerySet，也就是可以选择的对象的列表，但是只能选择一个。
ManyToManyField被映射成为表单类的django.forms.ModelMultipleChoiceField，它的选项也是一个模型的QuerySet，也就是可以选择的对象的列表，但是可以同时选择多个，多对多嘛。

同时，在表单属性设置上，还有下面的映射关系：

如果模型字段设置blank=True，那么表单字段的required设置为False。否则，required=True。
表单字段的label属性根据模型字段的verbose_name属性设置，并将第一个字母大写。
如果模型的某个字段设置了editable=False属性，那么它表单类中将不会出现该字段。道理很简单，都不能编辑了，还放在表单里提交什么？
表单字段的help_text设置为模型字段的help_text。
如果模型字段设置了choices参数，那么表单字段的widget属性将设置成Select框，其选项来自模型字段的choices。选单中通常会包含一个空选项，并且作为默认选择。如果该字段是必选的，它会强制用户选择一个选项。如果模型字段具有default参数，则不会添加空选项到选单中。

三、完整示例

模型：

from django.db import models

from django.forms import ModelForm

TITLE_CHOICES = (

    ('MR', 'Mr.'),

    ('MRS', 'Mrs.'),

    ('MS', 'Ms.'),

)

class Author(models.Model):

    name = models.CharField(max_length=100)

    title = models.CharField(max_length=3, choices=TITLE_CHOICES)

    birth_date = models.DateField(blank=True, null=True)

    def __str__(self):              # __unicode__ on Python 2

        return self.name

class Book(models.Model):

    name = models.CharField(max_length=100)

    authors = models.ManyToManyField(Author)

class AuthorForm(ModelForm):

    class Meta:

        model = Author

        fields = ['name', 'title', 'birth_date']

class BookForm(ModelForm):

    class Meta:

        model = Book

        fields = ['name', 'authors']

上面的ModelForm子类基本等同于下面的定义方式（唯一的区别是save()方法）：

from django import forms

class AuthorForm(forms.Form):

    name = forms.CharField(max_length=100)

    title = forms.CharField(

        max_length=3,

        widget=forms.Select(choices=TITLE_CHOICES),

    )

    birth_date = forms.DateField(required=False)

class BookForm(forms.Form):

    name = forms.CharField(max_length=100)

    authors = forms.ModelMultipleChoiceField(queryset=Author.objects.all())

四、ModelForm的验证

验证ModelForm主要分两步：

验证表单
验证模型实例

与普通的表单验证类似，模型表单的验证也是调用is_valid()方法或访问errors属性。模型的验证（Model.full_clean()）紧跟在表单的clean()方法调用之后。通常情况下，我们使用Django内置的验证器就好了。如果需要，可以重写模型表单的clean()来提供额外的验证，方法和普通的表单一样。

五、ModelForm的字段选择

强烈建议使用ModelForm的fields属性，在赋值的列表内，一个一个将要使用的字段添加进去。这样做的好处是，安全可靠。

然而，有时候，字段太多，或者我们想偷懒，不愿意一个一个输入，也有简单的方法：

all:

将fields属性的值设为__all__，表示将映射的模型中的全部字段都添加到表单类中来。

from django.forms import ModelForm

class AuthorForm(ModelForm):

    class Meta:

        model = Author

        fields = '__all__'

exclude属性:

表示将model中，除了exclude属性中列出的字段之外的所有字段，添加到表单类中作为表单字段。

class PartialAuthorForm(ModelForm):

    class Meta:

        model = Author

        exclude = ['title']

因为Author模型有3个字段name、birth_date和title，上面的例子会让birth_date和name出现在表单中。

六、自定义ModelForm字段

在前面，我们有个表格，展示了从模型到模型表单在字段上的映射关系。通常，这是没有什么问题，直接使用，按默认的来就行了。但是，有时候可能这种默认映射关系不是我们想要的，或者想进行一些更加灵活的定制，那怎么办呢？

使用Meta类内部的widgets属性！

widgets属性接收一个数据字典。其中每个元素的键必须是模型中的字段名之一，键值就是我们要自定义的内容了，具体格式和写法，参考下面的例子。

例如，如果你想要让Author模型中的name字段的类型从CharField更改为<textarea>，而不是默认的<input type="text">，可以如下重写字段的Widget：

from django.forms import ModelForm, Textarea

from myapp.models import Author

class AuthorForm(ModelForm):

    class Meta:

        model = Author

        fields = ('name', 'title', 'birth_date')

        widgets = {

            'name': Textarea(attrs={'cols': 80, 'rows': 20}), # 关键是这一行

        }

上面还展示了添加样式参数的格式。

如果你希望进一步自定义字段，还可以指定Meta类内部的error_messages、help_texts和labels属性，比如：

from django.utils.translation import ugettext_lazy as _

class AuthorForm(ModelForm):

    class Meta:

        model = Author

        fields = ('name', 'title', 'birth_date')

        labels = {

            'name': _('Writer'),

        }

        help_texts = {

            'name': _('Some useful help text.'),

        }

        error_messages = {

            'name': {

                'max_length': _("This writer's name is too long."),

            },

        }

还可以指定field_classes属性将字段类型设置为你自己写的表单字段类型。

例如，如果你想为slug字段使用MySlugFormField，可以像下面这样：

from django.forms import ModelForm

from myapp.models import Article

class ArticleForm(ModelForm):

    class Meta:

        model = Article

        fields = ['pub_date', 'headline', 'content', 'reporter', 'slug']

        field_classes = {

            'slug': MySlugFormField,

        }

最后，如果你想完全控制一个字段,包括它的类型，验证器，是否必填等等。可以显式地声明或指定这些性质，就像在普通表单中一样。比如，如果想要指定某个字段的验证器，可以显式定义字段并设置它的validators参数：

from django.forms import ModelForm, CharField

from myapp.models import Article

class ArticleForm(ModelForm):

    slug = CharField(validators=[validate_slug])

    class Meta:

        model = Article

        fields = ['pub_date', 'headline', 'content', 'reporter', 'slug']

七、启用字段本地化

默认情况下，ModelForm中的字段不会本地化它们的数据。可以使用Meta类的localized_fields属性来启用字段的本地化功能。

>>> from django.forms import ModelForm

>>> from myapp.models import Author

>>> class AuthorForm(ModelForm):

...     class Meta:

...         model = Author

...         localized_fields = ('birth_date',)

如果localized_fields设置为__all__这个特殊的值，所有的字段都将本地化。

八、表单的继承

ModelForms是可以被继承的。子模型表单可以添加额外的方法和属性，比如下面的例子：

>>> class EnhancedArticleForm(ArticleForm):

...     def clean_pub_date(self):

...         ...

以上创建了一个ArticleForm的子类EnhancedArticleForm，并增加了一个clean_pub_date方法。

还可以修改Meta.fields或Meta.exclude列表，只要继承父类的Meta类，如下所示：

>>> class RestrictedArticleForm(EnhancedArticleForm):

...     class Meta(ArticleForm.Meta):

...         exclude = ('body',)

九、提供初始值

可以在实例化一个表单时通过指定initial参数来提供表单中数据的初始值。

>>> article = Article.objects.get(pk=1)

>>> article.headline

'My headline'

>>> form = ArticleForm(initial={'headline': 'Initial headline'}, instance=article)

>>> form['headline'].value()

'Initial headline'