EmailType 欄位

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

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

trim

type: boolean default: true

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