MoneyType 字段

currency

类型: string 默认值: EUR

指定货币所使用的币种。 这决定了文本框应显示的货币符号。 根据货币的不同 - 货币符号可以在输入文本字段之前或之后显示。

这可以是任何 3 个字母的 ISO 4217 代码。 您也可以将其设置为 false 以隐藏货币符号。

divisor

类型: integer 默认值: 1

如果您需要在将其渲染给用户之前将起始值除以某个数字，则可以使用 divisor 选项。 例如，如果您以整数形式存储价格以避免 舍入误差，您可以自动转换以分为单位的值

1
2
3
4
5
6

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

$builder->add('price', MoneyType::class, [
    'divisor' => 100,
]);

在这种情况下，如果 price 字段设置为 9900，则值 99 实际上将呈现给用户。 当用户提交值 99 时，它将乘以 100，并且 9900 最终将被设置回您的对象。

grouping

类型: boolean 默认值: false

此值在内部用作 PHP 的 NumberFormatter 类时的 NumberFormatter::GROUPING_USED 值。 它的文档不存在，但似乎如果您将其设置为 true，则数字将用逗号或句点分组（取决于您的语言环境）：12345.123 将显示为 12,345.123。

rounding_mode

类型: integer 默认值: \NumberFormatter::ROUND_DOWN 用于 IntegerType，\NumberFormatter::ROUND_HALFUP 用于 MoneyType 和 NumberType

• IntegerType

默认值: \NumberFormatter::ROUND_DOWN

• MoneyType、NumberType 和 PercentType

默认值: \NumberFormatter::ROUND_HALFUP

如果提交的数字需要四舍五入（基于 scale 选项），您有几个可配置的舍入选项。 每个选项都是 NumberFormatter 类上的常量

• \NumberFormatter::ROUND_DOWN 向零舍入。 它将 1.4 舍入为 1，将 -1.4 舍入为 -1。
• \NumberFormatter::ROUND_FLOOR 向负无穷大舍入。 它将 1.4 舍入为 1，将 -1.4 舍入为 -2。
• \NumberFormatter::ROUND_UP 远离零舍入。 它将 1.4 舍入为 2，将 -1.4 舍入为 -2。
• \NumberFormatter::ROUND_CEILING 向正无穷大舍入。 它将 1.4 舍入为 2，将 -1.4 舍入为 -1。
• \NumberFormatter::ROUND_HALFDOWN 向“最近的邻居”舍入。 如果两个邻居等距，则向下舍入。 它将 2.5 和 1.6 舍入为 2，将 1.5 和 1.4 舍入为 1。
• \NumberFormatter::ROUND_HALFEVEN 向“最近的邻居”舍入。 如果两个邻居等距，则向偶数邻居舍入。 它将 2.5、1.6 和 1.5 舍入为 2，将 1.4 舍入为 1。
• \NumberFormatter::ROUND_HALFUP 向“最近的邻居”舍入。 如果两个邻居等距，则向上舍入。 它将 2.5 舍入为 3，将 1.6 和 1.5 舍入为 2，将 1.4 舍入为 1。

html5

类型: boolean 默认值: false

如果设置为 true，HTML 输入将呈现为原生 HTML5 <input type="number"> 元素。

input

类型: string 默认值: float

默认情况下，货币值将转换为 float PHP 类型。 如果您需要将值转换为整数（例如，因为某些库需要以分为单位存储的货币值），请将此选项设置为 integer。

scale

类型: integer 默认值: 2

如果由于某种原因，您需要除 2 位小数以外的其他精度，则可以修改此值。 除非例如您想四舍五入到最接近的美元（将精度设置为 0），否则您可能不需要这样做。

compound

类型: boolean 默认值: false

此选项指定类型是否包含子类型。 此选项在内置类型中进行内部管理，因此无需显式配置它。

invalid_message

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

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

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

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

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

默认值为 '' （空字符串）。

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

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

1
2
3
4

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

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

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

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 元素时，这非常有用。

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

类型: 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' => '...'],
]);