RangeType 欄位

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

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

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

trim

type: boolean default: true

如果為 true，則提交的字串值的空白字元將透過 trim 函數在資料繫結時移除。這保證如果提交的值包含額外的空白字元，則會在值合併回基礎物件之前將其移除。