DateType 字段

渲染单个 HTML5 文本框

为了获得更好的用户体验，您可能希望渲染单个文本字段并使用某种“日期选择器”来帮助用户填写正确的格式。为此，请使用 single_text widget

1
2
3
4
5
6
7

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

$builder->add('publishedAt', DateType::class, [
    // renders it as a single text box
    'widget' => 'single_text',
]);

这将渲染为 input type="date" HTML5 字段，这意味着 某些（但不是全部）浏览器将为该字段添加不错的日期选择器功能。如果您想绝对确保每个用户都有一个一致的日期选择器，请使用外部 JavaScript 库。

例如，假设您想使用 Bootstrap Datepicker 库。首先，进行以下更改

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

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

$builder->add('publishedAt', DateType::class, [
    'widget' => 'single_text',

    // prevents rendering it as type="date", to avoid HTML5 date pickers
    'html5' => false,

    // adds a class that can be selected in JavaScript
    'attr' => ['class' => 'js-datepicker'],
]);

然后，在您的模板中添加以下 JavaScript 代码以初始化日期选择器

1
2
3
4
5
6
7
8

<script>
    $(document).ready(function() {
        // you may need to change this code if you are not using Bootstrap Datepicker
        $('.js-datepicker').datepicker({
            format: 'yyyy-mm-dd'
        });
    });
</script>

此 format 键告诉日期选择器使用 Symfony 期望的日期格式。这可能很棘手：如果日期选择器配置错误，Symfony 将无法理解该格式并会抛出验证错误。您还可以通过 format 选项配置 Symfony 应该期望的格式。

days

类型：array 默认值：1 到 31

可用于日期字段类型的日期列表。此选项仅在 widget 选项设置为 choice 时相关。

1

'days' => range(1,31)

placeholder

类型：string | array

如果您的 widget 选项设置为 choice，则此字段将表示为一系列 select 框。当 placeholder 值是一个字符串时，它将用作所有选择框的空白值

1
2
3

$builder->add('dueDate', DateType::class, [
    'placeholder' => 'Select a value',
]);

或者，您可以使用一个数组，为年、月和日字段配置不同的 placeholder 值

1
2
3
4
5

$builder->add('dueDate', DateType::class, [
    'placeholder' => [
        'year' => 'Year', 'month' => 'Month', 'day' => 'Day',
    ],
]);

format

类型：integer 或 string 默认值：IntlDateFormatter::MEDIUM（如果 widget 为 single_text，则为 yyyy-MM-dd）

传递给 IntlDateFormatter 类的选项，用于将用户输入转换为正确的格式。当 widget 选项设置为 single_text 时，这至关重要，并将定义用户将如何输入数据。默认情况下，格式是根据当前用户区域设置确定的：这意味着不同用户的预期格式将不同。您可以通过将格式作为字符串传递来覆盖它。

有关有效格式的更多信息，请参阅 日期/时间格式语法

1
2
3
4
5
6
7
8

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

$builder->add('dateCreated', DateType::class, [
    'widget' => 'single_text',
    // this is actually the default format for single_text
    'format' => 'yyyy-MM-dd',
]);

html5

类型：boolean 默认值：true

如果设置为 true（默认值），它将使用 HTML5 类型（date、time 或 datetime-local）来渲染字段。当设置为 false 时，它将使用 text 类型。

当您想使用自定义 JavaScript 日期选择器时，这很有用，自定义 JavaScript 日期选择器通常需要 text 类型而不是 HTML5 类型。

input

类型：string 默认值：datetime

input 数据的格式 - 即日期存储在底层对象上的格式。有效值包括：

• string (例如 2011-06-05)
• datetime (DateTime 对象)
• datetime_immutable (DateTimeImmutable 对象)
• array (例如 ['year' => 2011, 'month' => 06, 'day' => 05])
• timestamp (例如 1307232000)

从表单返回的值也将被规范化回此格式。

input_format

类型：string 默认值：Y-m-d

如果 input 选项设置为 string，则此选项指定日期的格式。这必须是有效的 PHP 日期格式。

model_timezone

类型：string 默认值：系统默认时区

输入数据存储的时区。这必须是 PHP 支持的时区之一。

months

类型：array 默认值：1 到 12

可用于月份字段类型的月份列表。此选项仅在 widget 选项设置为 choice 时相关。

view_timezone

类型：string 默认值：系统默认时区

数据应如何显示给用户的时区（因此也是用户提交的数据的时区）。这必须是 PHP 支持的时区之一。

calendar

类型：integer 或 \IntlCalendar 默认值：null

用于格式化和解析日期的日历。该值应该是来自 IntlDateFormatter 日历常量的 integer，或是要使用的 IntlCalendar 的实例。默认情况下，使用应用程序默认区域设置的公历。

widget

类型：string 默认值：single_text

此字段应渲染的基本方式。可以是以下之一：

• choice：渲染三个选择输入。选择的顺序在 format 选项中定义。
• text：渲染三个类型为 text 的字段输入（月、日、年）。
• single_text：渲染单个类型为 date 的输入。用户的输入根据 format 选项进行验证。

years

类型：array 默认值：当前年份前五年到后五年

可用于年份字段类型的年份列表。此选项仅在 widget 选项设置为 choice 时相关。

by_reference

默认值：false

DateTime 类被视为不可变对象。

choice_translation_domain

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

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

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

compound

类型：boolean 默认值：false

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

data_class

类型：string 默认值：null

此类型的内部规范化表示是一个数组，而不是 \DateTime 对象。因此，data_class 选项被初始化为 null，以避免 FormType 对象将其初始化为 \DateTime。

error_bubbling

默认值：false

invalid_message

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

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

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

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

attr

类型：array 默认值：[]

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

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。任何提交的值都将被忽略。

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

inherit_data

类型：boolean 默认值：false

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

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

mapped

类型：boolean 默认值：true

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

row_attr

类型：array 默认值：[]

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

1
2
3

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