Django Crispy Forms 技术文档

1. 安装指南

环境要求

• Python 3.8 及以上版本
• Django 4.2 及以上版本

安装步骤

1. 使用 pip 安装 django-crispy-forms：

   pip install django-crispy-forms
   

2. 在 Django 项目的 settings.py 文件中添加 crispy_forms 到 INSTALLED_APPS：

   INSTALLED_APPS = [
       ...
       'crispy_forms',
       ...
   ]
   

3. 配置模板包（可选）： 默认情况下，django-crispy-forms 使用 Bootstrap 4 模板包。你可以通过设置 CRISPY_TEMPLATE_PACK 来选择其他模板包，例如 Bootstrap 5：

   CRISPY_TEMPLATE_PACK = 'bootstrap5'
   

2. 项目的使用说明

基本使用

django-crispy-forms 提供了两种主要方式来渲染表单：

1. |crispy 过滤器： 在模板中使用 |crispy 过滤器来渲染表单，类似于 Django 内置的 as_table、as_ul 和 as_p 方法。这种方式简单易用，但无法自定义输出。

   {% load crispy_forms_tags %}
   {{ form|crispy }}
   

2. {% crispy %} 标签： 使用 {% crispy %} 标签可以根据配置和布局设置渲染表单。这种方式提供了更大的灵活性和控制力。

   {% load crispy_forms_tags %}
   {% crispy form %}
   

自定义布局

你可以通过创建自定义布局来控制表单的渲染方式。例如：

from crispy_forms.helper import FormHelper
from crispy_forms.layout import Layout, Submit

class MyForm(forms.Form):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.helper = FormHelper()
        self.helper.layout = Layout(
            'field1',
            'field2',
            Submit('submit', 'Submit')
        )

3. 项目API使用文档

FormHelper 类

FormHelper 类用于配置表单的渲染行为。常用方法包括：

• FormHelper.layout: 设置表单的布局。
• FormHelper.form_method: 设置表单的提交方法（如 POST 或 GET）。
• FormHelper.form_action: 设置表单的提交地址。
• FormHelper.add_input: 添加按钮或输入元素。

Layout 类

Layout 类用于定义表单的布局结构。你可以使用以下组件：

• Field: 渲染单个字段。
• Div: 创建一个包含多个字段的容器。
• Submit: 创建提交按钮。
• Button: 创建自定义按钮。

示例

from crispy_forms.helper import FormHelper
from crispy_forms.layout import Layout, Field, Submit

class MyForm(forms.Form):
    field1 = forms.CharField()
    field2 = forms.CharField()

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.helper = FormHelper()
        self.helper.layout = Layout(
            Field('field1'),
            Field('field2'),
            Submit('submit', 'Submit')
        )

4. 项目安装方式

通过 pip 安装

pip install django-crispy-forms

从源码安装

1. 克隆仓库：

   git clone https://github.com/django-crispy-forms/django-crispy-forms.git
   

2. 进入项目目录并安装：

   cd django-crispy-forms
   pip install .
   

通过以上步骤，你可以成功安装并使用 django-crispy-forms 来优化你的 Django 表单渲染体验。