CountryType 字段

alpha3

类型：boolean 默认值：false

如果此选项为 true，则选择值使用 ISO 3166-1 alpha-3 三字母代码（例如，新西兰 = NZL），而不是默认的 ISO 3166-1 alpha-2 双字母代码（例如，新西兰 = NZ）。

choice_translation_locale

类型：string 或 null 默认值：null

此选项确定是否应将选择值翻译成与当前语言环境不同的语言环境。

choice_translation_locale 选项的值可以是 null（重用当前的翻译语言环境）或表示要使用的确切翻译语言环境的字符串。

choices

默认值：Symfony\Component\Intl\Countries::getNames()

国家类型默认将 choices 选项设置为完整的国家列表。 语言环境用于翻译国家名称。

choice_translation_domain

类型：string，boolean 或 null 默认值：false

此选项确定是否应翻译选择值以及在哪个翻译域中翻译。

choice_translation_domain 选项的值可以是 true（重用当前的翻译域），false（禁用翻译），null（使用父翻译域或默认域）或表示要使用的确切翻译域的字符串。

invalid_message

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

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

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

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

duplicate_preferred_choices

类型：boolean 默认值：true

当使用 preferred_choices 选项时，这些首选选项默认显示两次：在列表的顶部和下面的完整列表中。 将此选项设置为 false，以仅在列表顶部显示首选选项

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

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

$builder->add('language', ChoiceType::class, [
    'choices' => [
        'English' => 'en',
        'Spanish' => 'es',
        'Bork' => 'muppets',
        'Pirate' => 'arr',
    ],
    'preferred_choices' => ['muppets', 'arr'],
    'duplicate_preferred_choices' => false,
]);

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',
    ],
]);

expanded

类型：boolean 默认值：false

如果设置为 true，将渲染单选按钮或复选框（取决于 multiple 值）。 如果为 false，将渲染一个 select 元素。

multiple

类型：boolean 默认值：false

如果为 true，则用户将能够选择多个选项（而不是仅选择一个选项）。 根据 expanded 选项的值，如果为 true，这将渲染一个 select 标签或复选框，如果为 false，则渲染一个 select 标签或单选按钮。 返回值将是一个数组。

placeholder

类型：string 或 TranslatableMessage 或 boolean

此选项确定是否在 select 小部件的顶部显示特殊的“空”选项（例如“选择一个选项”）。 此选项仅在 multiple 选项设置为 false 时适用。

• 添加一个空值，文本为“选择一个选项”

  1
  2
  3
  4
  5
  6
  7
  8
  9

  use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
  // ...
  
  $builder->add('states', ChoiceType::class, [
      'placeholder' => 'Choose an option',
  
      // or if you want to translate the text
      'placeholder' => new TranslatableMessage('form.placeholder.select_option', [], 'form'),
  ]);

• 保证不显示“空”值选项

  1
  2
  3
  4
  5
  6

  use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
  // ...
  
  $builder->add('states', ChoiceType::class, [
      'placeholder' => false,
  ]);

如果你不设置 placeholder 选项，则仅当 required 选项为 false 时，才会自动添加一个空白（没有文本）选项

1
2
3
4
5
6
7

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

// a blank (with no text) option will be added
$builder->add('states', ChoiceType::class, [
    'required' => false,
]);

placeholder_attr

类型：array 默认值：[]

使用此选项可向占位符选项添加其他 HTML 属性

1
2
3
4
5
6
7
8
9
10

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

$builder->add('fruits', ChoiceType::class, [
    // ...
    'placeholder' => '...',
    'placeholder_attr' => [
        ['title' => 'Choose an option'],
    ],
]);

preferred_choices

类型：array，callable，string 或 PropertyPath 默认值：[]

此选项允许你在列表顶部显示某些选项，并在它们与完整的选项列表之间添加视觉分隔符。 如果你有一个语言表单，你可以在顶部列出最流行的语言，例如 Bork 和 Pirate

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

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

$builder->add('language', ChoiceType::class, [
    'choices' => [
        'English' => 'en',
        'Spanish' => 'es',
        'Bork' => 'muppets',
        'Pirate' => 'arr',
    ],
    'preferred_choices' => ['muppets', 'arr'],
]);

此选项也可以是回调函数，以提供更大的灵活性。 如果你的值是对象，这可能特别有用

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

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

$builder->add('publishAt', ChoiceType::class, [
    'choices' => [
        'now' => new \DateTime('now'),
        'tomorrow' => new \DateTime('+1 day'),
        '1 week' => new \DateTime('+1 week'),
        '1 month' => new \DateTime('+1 month'),
    ],
    'preferred_choices' => function ($choice, $key, $value): bool {
        // prefer options within 3 days
        return $choice <= new \DateTime('+3 days');
    },
]);

这将仅“首选” “now” 和 “tomorrow” 选项

最后，如果你的值是对象，你还可以在对象上指定一个属性路径字符串，该字符串将返回 true 或 false。

首选选项仅在渲染 select 元素时才有意义（即 expanded 为 false）。 首选选项和普通选项在视觉上由一组虚线分隔（即 -------------------）。 这可以在渲染字段时自定义

1

{{ form_widget(form.publishAt, { 'separator': '=====' }) }}

1
2
3

<?= $view['form']->widget($form['publishAt'], [
    'separator' => '=====',
]) ?>

1
2
3
4
5
6

use Symfony\Component\Form\ChoiceList\ChoiceList;

// ...
$builder->add('choices', ChoiceType::class, [
    'preferred_choices' => ChoiceList::preferred($this, 'taggedAsFavorite'),
]);

trim

类型：boolean 默认值：false

默认情况下禁用修剪，因为所选值或多个值必须与给定的选择值完全匹配（并且它们可能包含空格）。

这些选项继承自 FormType

attr

类型：array 默认值：[]

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

1
2
3

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

data

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

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

1
2
3
4
5
6

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

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

disabled

类型：boolean 默认值：false

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

empty_data

类型：mixed

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

• 如果 multiple 为 false 且 expanded 为 false，则为 ''（空字符串）；
• 否则为 []（空数组）。

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

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

1
2
3
4

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

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

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 元素时很有用。

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

类型：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_html

类型：boolean 默认值：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

类型：boolean 默认值：true

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

required

类型：boolean 默认值：true

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

这是表面现象，与验证无关。 在最好的情况下，如果你让 Symfony 猜测你的字段类型，那么此选项的值将从你的验证信息中猜测出来。

row_attr

类型：array 默认值：[]

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

1
2
3

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