Django ModelForm 组件配置与高级用法详解

苏见山

发布时间：2026-10-16 | 2人浏览过

原创

本文详细介绍 Django 中 ModelForm 组件的配置与使用。涵盖从创建模型类、生成迁移文件，到定义表单类、配置字段校验与样式。深入讲解如何自定义添加模型中不存在的字段（如确认密码）、控制显示字段、自定义错误提示信息及输入控件参数，并对比 Form 与 ModelForm 的适用场景，帮助开发者高效构建数据录入功能。

前言

大家好，今天我们来总结 ModelForm 组件的学习内容。这样做主要有三个目的：一是防止自己遗忘，二是巩固所学知识，三是希望能为正在学习 Django 的初学者提供一点参考。接下来直接进入正题。

基础配置步骤

在 Django 项目创建完成后，首先需要在对应的 app 目录下的 models.py 文件中定义模型类。这里以“添加学生”功能为例，定义好模型后，执行数据库迁移命令：python manage.py makemigrations 和 python manage.py migrate。

from django.db import models
 
# Create your models here.
 
class Student(models.Model):
    name = models.CharField(max_length=6, verbose_name="学生姓名")
    age = models.IntegerField(max_length=3, verbose_name="学生年龄")
    birthday = models.DateField(verbose_name="学生生日")
    emil = models.EmailField(verbose_name="学生邮箱")
    create_time = models.DateField(auto_now_add=True, verbose_name="创建时间")
 
    class Meta:
        db_table = "db_student"
 
    def __str__(self):
        return self.name

接着，在 app 目录下新建一个表单文件（如 myforms.py，名称可自定义但需避免冲突）。在该文件中导入 ModelForm 并创建继承自 ModelForm 的类。指定 model 属性关联数据模型，并通过 fields 属性指定需要校验的字段。若设置为 "__all__"，则表示校验所有字段；也可以明确列出需要校验或排除的字段。

from django.forms import ModelForm
from django.forms import widgets
from appo1.models import Student
from django.core.exceptions import ValidationError
 
class StudentModelForm(ModelForm):
    class Meta:
        model = Student
        fields = "__all__"
        # fields = ["name", "age"]  # 只校验名字和年龄
        # exclude = ["create_time"]  # 除了建立时间其他的都要校验
        labels = {"name": "名字", "age": "年龄", "birthday": "生日", "emil": "邮箱"}
        widgets = {
            # 不同类型的字段要用不同的属性输出，不然表单的格式验证失效
            # 给不同字段添加class属性，改变样式
            "name": widgets.TextInput({"class": "form-control"}),
            "age": widgets.NumberInput({"class": "form-control"}),
            "birthday": widgets.DateInput({"class": "form-control", "type": "date"}),  # 自己给type属性让前端模板有date样式
            "emil": widgets.EmailInput({"class": "form-control"}),
        }
        error_messages = {"emil": {"invalid": "请填写正确的邮箱格式"}}  # 给错误改中文

完成上述步骤，基础配置即告完成。需要注意的是，在设置 widgets 时，必须确保不同类型的字段使用对应的属性，否则可能导致前端格式验证失效。

模板文件创建与 ModelForm 集成

在根目录下的 templates 文件夹中创建 add_student.html 文件。在 HTML 中添加 form 标签，并利用模板语法渲染从视图传来的 form 对象数据。此处示例中同时引入了 Bootstrap 组件以优化界面效果。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <!-- 最新版本的 Bootstrap 核心 CSS 文件 -->
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css" rel="external nofollow" 
          integrity="sha384-HSMxcRTRxnN+Bdg0JdbxYKrThecOKuH5zCYotlSAcp1+c8xmyTe9GYg1l9a69psu" crossorigin="anonymous">
</head>
<style>
    form p span {
        color: red;
        font-size: 15px;
        margin: 5px;
        float: right;
    }
</style>
<body>
<div class="container">
    <div class="row">
        <div class="col-md-8  col-md-offset-2">
            <h1>添加学生1</h1>
            <form action="" method="post">
                {% csrf_token %}
                <p class="form-group">姓名：{{ modelform.name }}<span>{{ modelform.name.errors.0 }}</span></p>
                <p>年龄：{{ modelform.age }}</p>
                <p>生日：{{ modelform.birthday }}</p>
                <p>邮箱：{{ modelform.emil }}</p>
                <p>&nbsp</p>
                <p><input type="submit" class="btn btn-info" style="float: right"></p>
            </form>
        </div>
    </div>
</div>
 
 
</body>
</html>

随后，在 urls.py 文件中配置相应的路由规则，指向处理该页面的视图函数。

from django.contrib import admin
from django.urls import path
frpm app01.views import add_stu
 
urlpatterns = [
    path('admin/', admin.site.urls),
    path('add/', add_stu),
]

在视图函数中定义 add_stu(request) 来处理逻辑。具体实现代码如下：

from django.shortcuts import render, HttpResponse, redirect
from appo1.my_model_form import StudentModelForm
 
def add_stu(request):
    if request.method == "GET":
        modelform = StudentModelForm()
        return render(request, "add_student.html", {"modelform": modelform})
    else:
        modelform = StudentModelForm(data=request.POST)
        if modelform.is_valid():
            print(modelform.cleaned_data)
            return redirect("/")
        else:
            return render(request, "add_student.html", {"modelform": modelform})

运行项目后，访问对应路由即可看到如下页面效果：

至此，ModelForm 组件的基本应用已成功实现。

补充：Django ModelForm 快速上手指南

ModelForm 自定义添加字段

在常见的注册表单中，通常需要提供“确认密码”的输入框，但该字段并不存在于用户数据模型中。ModelForm 支持在表单中自定义添加模型中不存在的字段，以处理此类需求。

# app01/forms.py
 
from django import forms
from app01 import models
 
class RegisterModelForm(forms.ModelForm):
    
    # 自定义添加字段
    confirm_password = forms.CharField(label='确认密码', widget=forms.PasswordInput)
 
    class Meta:
        model = models.UserInfo # 基于的model表名
        fields = '__all__' # 表示自动渲染所有字段

ModelForm 自定义显示部分字段

fields = '__all__'：表示自动渲染模型中的所有字段。
fields = ['user', 'password', 'email']：表示仅渲染列表中指定的字段。
exclude = ['phone']：表示排除列表中的字段，其余字段将被渲染，效果与指定 fields 类似。

# app01/forms.py
 
from django import forms
from app01 import models
 
class RegisterModelForm(forms.ModelForm):
    
    class Meta:
        model = models.UserInfo # 基于的model表名
        fields = ['user‘,'password‘,'email‘] # 表示仅渲染列表中的字段
        # exclude = ['phone‘] # 表示排除列表中的字段，效果同上

ModelForm 自定义错误信息

ModelForm 具备自动校验并返回错误信息的功能。若需修改默认的错误提示，可通过 error_messages 属性进行自定义设置。

class RegisterModelForm(forms.ModelForm):
    class Meta:
        ...
        error_messages = { # 自定义错误信息
            'user':{
                'required': ('角色名称不能为空'),
            
            },
            '字段名':{
                ‘错误情况1':('错误信息1‘),
                ...
            },
            ...
        }

ModelForm 自定义参数（样式）

例如，若希望 password 字段在输入框中以密文形式显示，可以通过自定义参数实现。

class RegisterModelForm(forms.ModelForm):
    
    # 自定义添加字段参数(方式一)
    confirm_password = forms.CharField(label='确认密码', widget=forms.PasswordInput)
    
    class Meta:
        ...
        widgets = { # 自定义标签参数（方式二）
            'password': forms.PasswordInput(attrs={'class': 'form-control'})
        }