CheckboxType 欄位

false_values

類型：array 預設值：[null]

要解譯為 false 的值陣列。

value

類型：mixed 預設值：1

實際用作核取方塊或單選按鈕的值。這不會影響在您的物件上設定的值。

compound

類型：boolean 預設值：false

此選項指定表單是否為複合表單。由於核取方塊並非如此，因此預設情況下，該值會被 false 值覆寫。

empty_data

類型：string 預設值：mixed

此選項決定在選取 placeholder 選項時欄位將傳回的值。在核取方塊和單選類型中，empty_data 的值會被資料轉換器傳回的值覆寫（請參閱 如何使用資料轉換器）。

invalid_message

類型：string 預設值：此值無效

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

例如，如果使用者在 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。任何提交的值都將被忽略。

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

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