IntegerType 欄位

grouping

type: boolean default: false

當使用 PHP 的 NumberFormatter 類別時，此值在內部作為 NumberFormatter::GROUPING_USED 值使用。其文件不存在，但似乎如果您將其設定為 true，數字將使用逗號或句點 (取決於您的地區設定) 分組：12345.123 將顯示為 12,345.123。

rounding_mode

type: integer default: \NumberFormatter::ROUND_DOWN

預設情況下，如果使用者輸入非整數數字，它將向下捨入。您有幾個可配置的選項用於該捨入。每個選項都是 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。

compound

type: boolean default: false

此選項指定類型是否包含子類型。此選項在內建類型中內部管理，因此無需明確配置它。

invalid_message

type: string default: This value is not valid

如果輸入到此欄位的資料沒有意義 (即驗證失敗)，則會使用此驗證錯誤訊息。

例如，如果使用者在 TimeType 欄位中輸入無法轉換為真實時間的無意義字串，或者如果使用者在數字欄位中輸入字串 (例如 apple)，則可能會發生這種情況。

正常的 (業務邏輯) 驗證 (例如設定欄位的最小長度) 應使用驗證規則的驗證訊息來設定 (參考)。

attr

type: array default: []

如果您想將額外的屬性新增至 HTML 欄位表示法，您可以使用 attr 選項。它是一個關聯陣列，其中 HTML 屬性作為鍵。當您需要為某些小工具設定自訂類別時，這會很有用

1
2
3

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

data

type: mixed default: 預設為基礎結構的欄位。

當您建立表單時，每個欄位最初都會顯示表單網域資料的對應屬性值 (例如，如果您將物件繫結到表單)。如果您想覆寫表單或個別欄位的此初始值，您可以在 data 選項中設定它

1
2
3
4
5
6

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

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

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

invalid_message_parameters

type: array default: []

當設定 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

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