CollectionType 字段

allow_add

type: boolean default: false

如果设置为 true，则如果将无法识别的项目提交到集合，它们将被添加为新项目。最终数组将包含现有项目以及提交数据中的新项目。有关更多详细信息，请参阅上面的示例。

prototype 选项可用于帮助渲染原型项目，该原型项目可以与 JavaScript 一起使用，以在客户端动态创建新的表单项目。有关更多信息，请参阅上面的示例和 如何嵌入表单集合。

allow_delete

type: boolean default: false

如果设置为 true，则如果现有项目未包含在提交的数据中，则它将正确地从最终项目数组中删除。这意味着您可以通过 JavaScript 实现“删除”按钮，该按钮从 DOM 中删除表单元素。当用户提交表单时，它在提交数据中不存在意味着它将从最终数组中删除。

有关更多信息，请参阅 如何嵌入表单集合。

delete_empty

type: Boolean 或 callable default: false

如果您想从表单中显式删除完全为空的集合条目，则必须将此选项设置为 true。但是，只有在启用 allow_delete 选项的情况下，才会删除现有集合条目。否则，将保留空值。

仅当归一化值为 null 时，才会从集合中删除值。但是，您也可以将选项值设置为可调用对象，该可调用对象将针对提交的集合中的每个值执行。如果可调用对象返回 true，则该值将从集合中删除。例如

1
2
3
4
5
6
7
8
9

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

$builder->add('users', CollectionType::class, [
    // ...
    'delete_empty' => function (?User $user = null): bool {
        return null === $user || empty($user->getFirstName());
    },
]);

在使用复合表单类型的情况下，可调用对象特别有用，复合表单类型可以定义复杂的条件来考虑它们是否为空。

entry_options

type: array default: []

这是传递给 entry_type 选项中指定的表单类型的数组。例如，如果您将 ChoiceType 用作您的 entry_type 选项（例如，对于下拉菜单的集合），那么您至少需要将 choices 选项传递给底层类型

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

use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\Extension\Core\Type\CollectionType;
// ...

$builder->add('favoriteCities', CollectionType::class, [
    'entry_type'   => ChoiceType::class,
    'entry_options'  => [
        'choices'  => [
            'Nashville' => 'nashville',
            'Paris'     => 'paris',
            'Berlin'    => 'berlin',
            'London'    => 'london',
        ],
    ],
]);

prototype_options

type: array default: []

这是在创建原型时传递给 entry_type 选项中指定的表单类型的数组。它允许您根据是添加新条目还是编辑现有条目来设置不同的选项

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

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

$builder->add('names', CollectionType::class, [
    'entry_type' => TextType::class,
    'entry_options' => [
        'help' => 'You can edit this name here.',
    ],
    'prototype_options'  => [
        'help' => 'You can enter a new name here.',
    ],
]);

entry_type

type: string default: Symfony\Component\Form\Extension\Core\Type\TextType

这是此集合中每个项目的字段类型（例如，TextType、ChoiceType 等）。例如，如果您有一个电子邮件地址数组，您将使用 EmailType。如果您想嵌入某个其他表单的集合，请将表单类型类作为此选项传递（例如，MyFormType::class）。

keep_as_list

type: boolean default: false

当设置为 true 时，keep_as_list 选项会影响集合中嵌套表单名称的重新索引。当使用集合类型并在表单提交期间从集合中删除项目时，此功能特别有用。

当此选项设置为 false 时，如果您有一个包含 3 个项目的集合，并且您删除了第二个项目，则验证集合时索引将为 0 和 2。但是，通过启用 keep_as_list 选项并将其设置为 true，索引将重新索引为 0 和 1。这确保了索引保持连续且没有间隙，为您的嵌套表单提供了更清晰、更可预测的结构。

prototype

type: boolean default: true

当使用 allow_add 选项时，此选项很有用。如果 true（并且如果 allow_add 也为 true），则会提供一个特殊的“prototype”属性，以便您可以在页面上渲染一个“模板”示例，说明新元素应如何显示。赋予此元素的 name 属性是 __name__。这允许您通过 JavaScript 添加“添加另一个”按钮，该按钮读取原型，将 __name__ 替换为某个唯一名称或数字，并在您的表单中渲染它。提交后，由于 allow_add 选项，它将被添加到您的底层数组中。

原型字段可以通过集合字段中的 prototype 变量渲染

1

{{ form_row(form.emails.vars.prototype) }}

请注意，您真正需要的只是“widget”，但是根据您渲染表单的方式，拥有整个“表单行”可能对您来说更容易。

有关如何实际使用此选项的详细信息，请参阅上面的示例以及 如何嵌入表单集合。

prototype_data

type: mixed default: null

允许您为原型定义特定数据。每个添加的新行最初都将包含此选项设置的数据。默认情况下，将使用为所有条目配置的数据和 entry_options 选项

1
2
3
4
5
6
7
8
9
10

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

$builder->add('tags', CollectionType::class, [
    'entry_type' => TextType::class,
    'allow_add' => true,
    'prototype' => true,
    'prototype_data' => 'New Tag Placeholder',
]);

prototype_name

type: string default: __name__

如果您的表单中有多个集合，或者更糟的是，嵌套集合，您可能需要更改占位符，以便不相关的占位符不会被替换为相同的值。

invalid_message

type: string default: This value is not valid

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

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

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

attr

type: array default: []

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

1
2
3

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

by_reference

type: boolean default: 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。

empty_data

type: mixed

默认值为 []（空数组）。

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

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

1
2
3
4

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

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

error_bubbling

type: boolean default: true

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

error_mapping

type: array default: []

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

假设您有一个名为 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',
    ],
]);

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

type: array default: []

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

1
2
3

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

help_html

type: boolean default: false

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

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_attr

type: array default: []

设置 <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_html

type: boolean default: false

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

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

type: boolean default: true

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

required

type: boolean default: true

如果为 true，则会渲染 HTML5 required 属性。相应的 label 也会使用 required 类进行渲染。

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

row_attr

type: array default: []

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

1
2
3

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