FormType 字段

action

类型：string 默认值：空字符串

此选项指定提交表单数据的位置（通常是 URI）。它的值呈现为 form 元素的 action 属性。空值被视为同文档引用，即表单将提交到呈现表单的同一 URI。

allow_extra_fields

类型：boolean 默认值：false

通常，如果您提交了未在表单中配置的额外字段，您将收到“此表单不应包含额外字段。”验证错误。

您可以通过在表单上启用 allow_extra_fields 选项来消除此验证错误。

by_reference

类型：boolean 默认值：true

在大多数情况下，如果您有一个 author 字段，那么您希望在底层对象上调用 setAuthor()。但是，在某些情况下，可能不会调用 setAuthor()。将 by_reference 设置为 false 可确保在所有情况下都调用 setter。

为了进一步解释这一点，这里有一个简单的例子

1
2
3
4
5
6
7
8
9
10
11
12
13

use Symfony\Component\Form\Extension\Core\Type\EmailType;
use Symfony\Component\Form\Extension\Core\Type\FormType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
// ...

$builder = $this->createFormBuilder($article);
$builder
    ->add('title', TextType::class)
    ->add(
        $builder->create('author', FormType::class, ['by_reference' => ?])
            ->add('name', TextType::class)
            ->add('email', EmailType::class)
    )

如果 by_reference 为 true，当您在表单上调用 submit() （或 handleRequest()）时，幕后会发生以下情况

1
2
3

$article->setTitle('...');
$article->getAuthor()->setName('...');
$article->getAuthor()->setEmail('...');

请注意，没有调用 setAuthor()。作者是通过引用修改的。

如果您将 by_reference 设置为 false，则提交看起来像这样

1
2
3
4
5

$article->setTitle('...');
$author = clone $article->getAuthor();
$author->setName('...');
$author->setEmail('...');
$article->setAuthor($author);

因此，by_reference=false 真正做的就是克隆对象，这强制框架在父对象上调用 setter。

同样，如果您正在使用 CollectionType 字段，其中您的底层集合数据是一个对象（例如使用 Doctrine 的 ArrayCollection），那么如果您需要调用 adder 和 remover（例如 addAuthor() 和 removeAuthor()），则必须将 by_reference 设置为 false。

compound

类型：boolean 默认值：true

复合表单可以是整个 <form> 元素或一组表单字段（例如在 <div> 或 <tr> 容器元素内呈现）。复合表单使用 DataMapperInterface 来初始化它们的子项或写回它们提交的数据。

一个简单（非复合）表单呈现为以下任何 HTML 元素：<input> (TextType, FileType, HiddenType), <textarea> (TextareaType) 或 <select> (ChoiceType)。

某些核心类型（如日期相关类型或 ChoiceType）根据其他选项（如 expanded 或 widget）是简单还是复合的。它们将表现为简单的文本字段或一组文本或选择字段。

constraints

类型：array 或 Constraint 默认值：[]

允许您将一个或多个验证约束附加到特定字段。有关更多信息，请参见添加验证。此选项在FormTypeValidatorExtension表单扩展中添加。

data

类型：mixed 默认值：默认为底层结构的字段。

当您创建表单时，每个字段最初显示表单域数据的相应属性值（例如，如果您将对象绑定到表单）。如果您想覆盖表单或单个字段的此初始值，您可以在 data 选项中设置它

1
2
3
4
5
6

use Symfony\Component\Form\Extension\Core\Type\HiddenType;
// ...

$builder->add('token', HiddenType::class, [
    'data' => 'abcdef',
]);

data_class

类型：string

此选项用于设置表单要使用的适当数据映射器，因此您可以将其用于任何需要对象的表单字段类型

1
2
3
4
5
6
7

use App\Entity\Media;
use App\Form\MediaType;
// ...

$builder->add('media', MediaType::class, [
    'data_class' => Media::class,
]);

empty_data

类型：mixed

此选项的实际默认值取决于其他字段选项

• 如果设置了 data_class 且 required 为 true，则为 new $data_class()；
• 如果设置了 data_class 且 required 为 false，则为 null；
• 如果未设置 data_class 且 compound 为 true，则为 []（空数组）；
• 如果未设置 data_class 且 compound 为 false，则为 ''（空字符串）。

此选项确定当提交的值为空（或丢失）时，字段将返回的值。如果呈现表单时未提供初始值，则它不会设置初始值。

这意味着它可以帮助您处理带有空白字段的表单提交。例如，如果您希望在未选择任何值时将 name 字段显式设置为 John Doe，您可以这样做

1
2
3
4

$builder->add('name', null, [
    'required'   => false,
    'empty_data' => 'John Doe',
]);

这仍然会呈现一个空文本框，但在提交后，将设置 John Doe 值。使用 data 或 placeholder 选项在呈现的表单中显示此初始值。

is_empty_callback

类型：callable 默认值：null

此可调用对象获取表单数据并返回该值是否被视为空。

error_bubbling

类型：boolean 默认值：false，除非表单是 compound

如果为 true，则此字段的任何错误都将传递给父字段或表单。例如，如果在普通字段上设置为 true，则该字段的任何错误都将附加到主表单，而不是附加到特定字段。

error_mapping

类型：array 默认值：[]

此选项允许您修改验证错误的目标。

假设您有一个名为 matchingCityAndZipCode() 的自定义方法，该方法验证城市和邮政编码是否匹配。不幸的是，您的表单中没有 matchingCityAndZipCode 字段，因此 Symfony 所能做的只是在表单顶部显示错误。

通过自定义错误映射，您可以做得更好：将错误映射到城市字段，以便它显示在其上方

1
2
3
4
5
6
7
8

public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'error_mapping' => [
            'matchingCityAndZipCode' => 'city',
        ],
    ]);
}

以下是映射左侧和右侧的规则

• 左侧包含属性路径；
• 如果违规是在类的属性或方法上生成的，则其路径为 propertyName；
• 如果违规是在 array 或 ArrayAccess 对象的条目上生成的，则属性路径为 [indexName]；
• 您可以通过连接属性路径来构造嵌套属性路径，并用点分隔属性。例如：addresses[work].matchingCityAndZipCode；
• 右侧包含表单中字段的名称。

默认情况下，任何未映射属性的错误都将冒泡到父表单。您可以使用点（.）在左侧将所有未映射属性的错误映射到特定字段。例如，要将所有这些错误映射到 city 字段，请使用

1
2
3
4
5

$resolver->setDefaults([
    'error_mapping' => [
        '.' => 'city',
    ],
]);

extra_fields_message

类型：string 默认值：This form should not contain extra fields.

如果提交的表单数据包含一个或多个不属于表单定义的字段，则会使用此验证错误消息。占位符 {{ extra_fields }} 可用于显示提交的额外字段名称的逗号分隔列表。

此消息可以复数化，有关详细信息，请参见格式化复数消息。

form_attr

类型：boolean 或 string 默认值：false

当 true 且在表单元素上使用时，它会将其 HTML 字段表示形式的 “form”属性添加到其 HTML 表单 ID。通过这样做，表单元素可以在 HTML 表单之外呈现，同时仍然按预期工作

1
2
3

$builder->add('body', TextareaType::class, [
    'form_attr' => true,
]);

当您需要解决嵌套表单问题时，这可能很有用。您也可以在根表单上将其设置为 true，以在所有子项上自动设置“form”属性。

getter

类型：callable 默认值：null

如果提供，将调用此可调用对象以从底层对象读取值，该值将用于填充表单字段。

更多详细信息，请参见关于何时以及如何使用数据映射器的部分。

help

类型：string 或 TranslatableInterface 默认值：null

允许您为表单字段定义帮助消息，默认情况下该消息呈现字段下方

1
2
3
4
5
6
7
8
9
10
11
12
13

use Symfony\Component\Translation\TranslatableMessage;

$builder
    ->add('zipCode', null, [
        'help' => 'The ZIP/Postal code for your credit card\'s billing address.',
    ])

    // ...

    ->add('status', null, [
        'help' => new TranslatableMessage('order.status', ['%order_id%' => $order->getId()], 'store'),
    ])
;

help_attr

类型：array 默认值：[]

设置用于显示表单字段帮助消息的元素的 HTML 属性。它的值是一个关联数组，其中 HTML 属性名称作为键。这些属性也可以在模板中设置

1
2
3

{{ form_help(form.name, 'Your name', {
    'help_attr': {'class': 'CUSTOM_LABEL_CLASS'}
}) }}

help_html

类型：boolean 默认值：false

默认情况下，help 选项的内容在模板中呈现之前会被转义。将此选项设置为 true 以不转义它们，这在帮助包含 HTML 元素时很有用。

help_translation_parameters

类型：array 默认值：[]

help 选项的内容在显示之前会进行翻译，因此它可以包含翻译占位符。此选项定义用于替换这些占位符的值。

给定此翻译消息

1
2

# translations/messages.en.yaml
form.order.id.help: 'This will be the reference in communications with %company%'

您可以按如下方式指定占位符值

1
2
3
4
5
6

$builder->add('id', null, [
    'help' => 'form.order.id.help',
    'help_translation_parameters' => [
        '%company%' => 'ACME Inc.',
    ],
]);

子字段的 help_translation_parameters 选项与其父级的相同选项合并，因此子项可以重用和/或覆盖任何父占位符。

inherit_data

类型：boolean 默认值：false

此选项确定表单是否将从其父表单继承数据。如果您有一组在多个表单中重复的字段，这将很有用。请参见如何使用“inherit_data”减少代码重复。

invalid_message

类型：string 默认值：This value is not valid

如果在此字段中输入的数据没有意义（即验证失败），则会使用此验证错误消息。

例如，如果用户在无法转换为实际时间的 TimeType 字段中输入了无意义的字符串，或者用户在数字字段中输入了字符串（例如 apple），则可能会发生这种情况。

正常的（业务逻辑）验证（例如，当设置字段的最小长度时）应使用带有验证规则的验证消息进行设置（参考）。

invalid_message_parameters

类型：array 默认值：[]

当设置 invalid_message 选项时，您可能需要在字符串中包含一些变量。这可以通过向该选项添加占位符并将变量包含在此选项中来完成

1
2
3
4
5

$builder->add('someField', SomeFormType::class, [
    // ...
    'invalid_message' => 'You entered an invalid value, it should include %num% letters',
    'invalid_message_parameters' => ['%num%' => 6],
]);

label_attr

类型：array 默认值：[]

设置 <label> 元素的 HTML 属性，该属性将在呈现字段标签时使用。它是一个关联数组，其中 HTML 属性作为键。此属性也可以直接在模板中设置

1
2
3

{{ form_label(form.name, 'Your name', {
    'label_attr': {'class': 'CUSTOM_LABEL_CLASS'}
}) }}

1
2
3
4
5

echo $view['form']->label(
    $form['name'],
    'Your name',
    ['label_attr' => ['class' => 'CUSTOM_LABEL_CLASS']]
);

label_format

类型：string 默认值：null

配置用作字段标签的字符串，以防未设置 label 选项。当使用关键字翻译消息时，这非常有用。

如果您使用关键字翻译消息作为标签，则通常最终会为同一标签拥有多个关键字消息（例如，profile_address_street，invoice_address_street）。这是因为标签是为字段的每个“路径”构建的。为了避免重复的关键字消息，您可以将标签格式配置为静态值，例如

1
2
3
4
5
6
7
8

// ...
$profileFormBuilder->add('address', AddressType::class, [
    'label_format' => 'form.address.%name%',
]);

$invoiceFormBuilder->add('invoice', AddressType::class, [
    'label_format' => 'form.address.%name%',
]);

此选项由子类型继承。使用上面的代码，两个表单的 street 字段的标签都将使用 form.address.street 关键字消息。

标签格式中有两个变量可用

%id%

字段的唯一标识符，由字段的完整路径和字段名称组成 (例如 profile_address_street)；

%name%

字段名称 (例如 street)。

默认值 (null) 会生成字段名称的 “人性化”版本。

mapped

类型：boolean 默认值：true

如果您希望在读取或写入对象时忽略该字段，则可以将 mapped 选项设置为 false。

method

类型: string 默认值: POST

此选项指定用于提交表单数据的 HTTP 方法。它的值呈现为 form 元素的 method 属性，并用于决定是否在提交后在 handleRequest() 方法中处理表单提交。可能的值包括

• POST
• GET
• PUT
• DELETE
• PATCH

post_max_size_message

类型: string 默认值: 上传的文件太大。请尝试上传较小的文件。

如果提交的 POST 表单数据超过 php.ini 的 post_max_size 指令，则会使用此验证错误消息。{{ max }} 占位符可用于显示允许的大小。

property_path

类型: PropertyPathInterface|string|null 默认值: null

默认情况下（当此选项的值为 null 时），表单字段从表单域对象中具有相同名称的属性读取和写入。 property_path 选项允许您定义字段从哪个属性读取和写入。此选项的值可以是任何有效的 PropertyAccess 语法。

required

类型：boolean 默认值：true

如果为 true，将呈现 HTML5 required 属性。相应的 label 也将使用 required 类呈现。

这是表面的，并且独立于验证。在最好的情况下，如果您让 Symfony 猜测您的字段类型，那么此选项的值将从您的验证信息中猜测出来。

setter

类型：callable 默认值：null

提供后，将调用此可调用对象以将表单值映射回底层对象。

更多详细信息，请参见关于何时以及如何使用数据映射器的部分。

trim

类型：boolean 默认值：true

如果为 true，则当数据绑定时，提交的字符串值的空格将通过 trim 函数去除。这保证了如果提交的值带有额外的空格，则会在该值合并回底层对象之前将其删除。

validation_groups

类型: array, string, callable, GroupSequence 或 null 默认值: null

此选项仅在根表单上有效，用于指定验证器将使用的组。

对于 null，验证器将仅使用 Default 组。

如果您将组指定为数组或字符串，它们将按原样被验证器使用

1
2
3
4
5
6

public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'validation_groups' => 'Registration',
    ]);
}

这等效于将组作为数组传递

1

'validation_groups' => ['Registration'],

表单的数据将针对所有给定的组进行验证。

如果验证组依赖于表单的数据，则可以将可调用对象传递给该选项。然后，Symfony 将在调用它时传递表单

1
2
3
4
5
6
7
8
9
10
11
12
13
14

use Symfony\Component\Form\FormInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

// ...
public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'validation_groups' => function (FormInterface $form): array {
            $entity = $form->getData();

            return $entity->isUser() ? ['User'] : ['Company'];
        },
    ]);
}

在某些情况下，您希望逐步验证您的组。为此，您可以将 GroupSequence 传递给此选项。这使您能够针对多个组进行验证，就像您在数组中传递多个组一样，但不同之处在于，只有当先前的组通过且没有错误时，才会验证组。这是一个例子

1
2
3
4
5
6
7
8
9
10
11
12
13
14

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Validator\Constraints\GroupSequence;
// ...

class MyType extends AbstractType
{
    // ...
    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'validation_groups' => new GroupSequence(['First', 'Second']),
        ]);
    }
}

attr

类型：array 默认值：[]

如果您想向 HTML 字段表示形式添加额外的属性，您可以使用 attr 选项。它是一个关联数组，其中 HTML 属性作为键。当您需要为某些小部件设置自定义类时，这可能很有用

1
2
3

$builder->add('body', TextareaType::class, [
    'attr' => ['class' => 'tinymce'],
]);

auto_initialize

类型：boolean 默认值：true

内部选项：设置是否应自动初始化表单。对于所有字段，此选项仅应对于根表单为 true。您无需更改此选项，也可能无需担心它。

block_name

类型: string 默认值: 表单的名称（请参阅了解要自定义哪个块）

允许您向默认用于呈现表单类型的块添加自定义块名称。例如，如果您有同一表单的多个实例，并且需要单独个性化表单的呈现，则此功能很有用。

例如，如果您将此选项设置为 my_custom_name 并且字段的类型为 text，Symfony 将使用以下名称（并按此顺序）来查找用于呈现字段小部件的块：_my_custom_name_widget、text_widget 和 form_widget。

block_prefix

类型: string 或 null 默认值: null （请参阅了解要自定义哪个块）

允许您添加自定义块前缀并覆盖用于呈现表单类型的块名称。例如，如果您有同一表单的多个实例，并且需要个性化所有表单的呈现，而无需创建新的表单类型，则此功能很有用。

disabled

类型：boolean 默认值：false

如果您不希望用户修改字段的值，您可以将 disabled 选项设置为 true。任何提交的值都将被忽略。

label

类型: string 或 TranslatableMessage 默认值: 标签是根据字段名称“猜测”的

设置呈现字段时将使用的标签。设置为 false 将抑制标签

1
2
3
4
5
6
7
8

use Symfony\Component\Translation\TranslatableMessage;

$builder
    ->add('zipCode', null, [
        'label' => 'The ZIP/Postal code',
        // optionally, you can use TranslatableMessage objects as the label content
        'label' => new TranslatableMessage('address.zipCode', ['%country%' => $country], 'address'),
    ])

标签也可以在模板中设置

1

{{ form_label(form.name, 'Your name') }}

1
2
3
4

echo $view['form']->label(
    $form['name'],
    'Your name'
);

label_html

类型：boolean 默认值：false

默认情况下，label 选项的内容在模板中呈现之前会被转义。将此选项设置为 true 以不转义它们，这在标签包含 HTML 元素时很有用。

row_attr

类型：array 默认值：[]

添加到用于呈现表单类型行的元素的 HTML 属性的关联数组

1
2
3

$builder->add('body', TextareaType::class, [
    'row_attr' => ['class' => 'text-editor', 'id' => '...'],
]);

translation_domain

类型: string, null 或 false 默认值: null

这是将用于此字段呈现的任何标签或选项的翻译域。使用 null 重用父表单的翻译域（或根表单的翻译器的默认域）。使用 false 禁用翻译。

label_translation_parameters

类型：array 默认值：[]

label 选项的内容在显示之前会被翻译，因此它可以包含翻译占位符。此选项定义用于替换这些占位符的值。

给定此翻译消息

1
2

# translations/messages.en.yaml
form.order.id: 'Identifier of the order to %company%'

您可以按如下方式指定占位符值

1
2
3
4
5
6

$builder->add('id', null, [
    'label' => 'form.order.id',
    'label_translation_parameters' => [
        '%company%' => 'ACME Inc.',
    ],
]);

子字段的 label_translation_parameters 选项与其父字段的相同选项合并，因此子字段可以重用和/或覆盖任何父占位符。

attr_translation_parameters

类型：array 默认值：[]

在 attr 选项中定义的 title 和 placeholder 值的内容在显示之前会被翻译，因此它可以包含翻译占位符。此选项定义用于替换这些占位符的值。

给定此翻译消息

1
2
3

# translations/messages.en.yaml
form.order.id.placeholder: 'Enter unique identifier of the order to %company%'
form.order.id.title: 'This will be the reference in communications with %company%'

您可以按如下方式指定占位符值

1
2
3
4
5
6
7
8
9

$builder->add('id', null, [
    'attr' => [
        'placeholder' => 'form.order.id.placeholder',
        'title' => 'form.order.id.title',
    ],
    'attr_translation_parameters' => [
        '%company%' => 'ACME Inc.',
    ],
]);

子字段的 attr_translation_parameters 选项与其父字段的相同选项合并，因此子字段可以重用和/或覆盖任何父占位符。

priority

类型: integer 默认值: 0

字段按照它们包含在表单中的顺序呈现。此选项更改字段呈现优先级，允许您比其原始顺序更早或更晚显示字段。

此选项将仅影响视图顺序。此优先级越高，字段将越早呈现。优先级也可以为负数，并且具有相同优先级的字段将保持其原始顺序。