PasswordType 字段

always_empty

type: boolean default: true

如果设置为 true，即使对应的字段有值，该字段也将始终渲染为空白。当设置为 false 时，密码字段将在提交时才使用设置为其真实值的 value 属性进行渲染。

如果你想渲染密码字段，并在框中预先输入密码值，请将此项设置为 false 并提交表单。

hash_property_path

type: string default: null

如果设置，密码将使用 PasswordHasher component 进行哈希处理，并存储在给定 PropertyAccess expression 定义的属性中。

传递给表单的数据必须是一个 PasswordAuthenticatedUserInterface 对象。

1
2
3
4

$builder->add('plainPassword', PasswordType::class, [
    'hash_property_path' => 'password',
    'mapped' => false,
]);

1
2
3
4
5
6

$builder->add('plainPassword', RepeatedType::class, [
    'type' => PasswordType::class,
    'first_options'  => ['label' => 'Password', 'hash_property_path' => 'password'],
    'second_options' => ['label' => 'Repeat Password'],
    'mapped' => false,
]);

toggle

type: boolean requires: symfony/ux-toggle-password

向字段添加 "显示"/"隐藏" 链接，点击时将密码字段切换为明文。有关更多详细信息，请参阅 symfony/ux-toggle-password。

invalid_message

type: string default: This value is not valid

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

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

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

trim

type: boolean default: false

与其余表单类型不同，PasswordType 不会对用户提交的值应用 trim 函数。这确保了密码完全按照用户键入的方式合并回底层对象。

attr

type: array default: []

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

1
2
3

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

disabled

type: boolean default: false

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

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: false 除非表单是 compound

如果 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

type: string 或 TranslatableInterface default: 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

type: string 或 TranslatableMessage default: 标签从字段名称中“猜测”

设置渲染字段时将使用的标签。设置为 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

type: string default: 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' => '...'],
]);