LanguageType 欄位

alpha3

類型：boolean 預設值：false

如果此選項為 true，則選項值會使用 ISO 639-2 alpha-3 (2T) 三字母代碼 (例如，法文 = fra)，而不是預設的 ISO 639-1 alpha-2 雙字母代碼 (例如，法文 = fr)。

choice_self_translation

類型：boolean 預設值：false

預設情況下，語言名稱會翻譯成應用程式目前的語系。例如，當以英文瀏覽應用程式時，您會得到一個類似 [..., 'cs' => 'Czech', ..., 'es' => 'Spanish', ..., 'zh' => 'Chinese'] 的陣列，而當以法文瀏覽時，您會得到以下陣列：[..., 'cs' => 'tchèque', ..., 'es' => 'espagnol', ..., 'zh' => 'chinois']。

如果此選項為 true，則每個語言都會翻譯成其自己的語言，而與目前應用程式的語系無關：[..., 'cs' => 'čeština', ..., 'es' => 'español', ..., 'zh' => '中文']。

choice_translation_locale

類型：string 或 null 預設值：null

此選項決定選項值是否應翻譯成與目前語系不同的語系。

choice_translation_locale 選項的值可以是 null (重複使用目前的翻譯語系) 或代表要使用的確切翻譯語系的字串。

choices

預設值：Symfony\Component\Intl\Languages::getNames()。

choices 選項預設為所有語言。預設語系用於翻譯語言名稱。

choice_translation_domain

類型：string、boolean 或 null 預設值：false

此選項決定選項值是否應翻譯以及在哪個翻譯網域中翻譯。

choice_translation_domain 選項的值可以是 true (重複使用目前的翻譯網域)、false (停用翻譯)、null (使用父翻譯網域或預設網域) 或代表要使用的確切翻譯網域的字串。

invalid_message

類型：string 預設值：This value is not valid

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

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

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

duplicate_preferred_choices

類型：boolean 預設值：true

當使用 preferred_choices 選項時，預設情況下，這些偏好選項會顯示兩次：在列表的頂部和下面的完整列表中。將此選項設定為 false，僅在列表頂部顯示偏好選項

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

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

$builder->add('language', ChoiceType::class, [
    'choices' => [
        'English' => 'en',
        'Spanish' => 'es',
        'Bork' => 'muppets',
        'Pirate' => 'arr',
    ],
    'preferred_choices' => ['muppets', 'arr'],
    'duplicate_preferred_choices' => false,
]);

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

expanded

類型：boolean 預設值：false

如果設定為 true，將會呈現單選按鈕或核取方塊 (取決於 multiple 值)。如果為 false，則會呈現 select 元素。

multiple

類型：boolean 預設值：false

如果為 true，使用者將能夠選擇多個選項 (而不是僅選擇一個選項)。根據 expanded 選項的值，如果為 true，則會呈現 select 標籤或核取方塊，如果為 false，則會呈現 select 標籤或單選按鈕。傳回的值將會是一個陣列。

placeholder

類型：string 或 TranslatableMessage 或 boolean

此選項決定是否會在 select 小工具的頂端顯示特殊的「空」選項 (例如「選擇一個選項」)。此選項僅在 multiple 選項設定為 false 時適用。

• 新增一個空白值，文字為「選擇一個選項」

  1
  2
  3
  4
  5
  6
  7
  8
  9

  use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
  // ...
  
  $builder->add('states', ChoiceType::class, [
      'placeholder' => 'Choose an option',
  
      // or if you want to translate the text
      'placeholder' => new TranslatableMessage('form.placeholder.select_option', [], 'form'),
  ]);

• 保證不顯示「空」值選項

  1
  2
  3
  4
  5
  6

  use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
  // ...
  
  $builder->add('states', ChoiceType::class, [
      'placeholder' => false,
  ]);

如果您將 placeholder 選項保持未設定狀態，則僅當 required 選項為 false 時，才會自動新增空白 (沒有文字) 選項

1
2
3
4
5
6
7

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

// a blank (with no text) option will be added
$builder->add('states', ChoiceType::class, [
    'required' => false,
]);

placeholder_attr

類型：array 預設值：[]

使用此選項可將額外的 HTML 屬性新增至 placeholder 選項

1
2
3
4
5
6
7
8
9
10

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

$builder->add('fruits', ChoiceType::class, [
    // ...
    'placeholder' => '...',
    'placeholder_attr' => [
        ['title' => 'Choose an option'],
    ],
]);

preferred_choices

類型：array、callable、string 或 PropertyPath 預設值：[]

此選項可讓您在列表頂端顯示某些選項，並在它們與完整的選項列表之間加上視覺分隔符號。如果您有一個語言表單，您可以將最受歡迎的語言列在頂端，例如 Bork 和 Pirate

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

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

$builder->add('language', ChoiceType::class, [
    'choices' => [
        'English' => 'en',
        'Spanish' => 'es',
        'Bork' => 'muppets',
        'Pirate' => 'arr',
    ],
    'preferred_choices' => ['muppets', 'arr'],
]);

此選項也可以是一個回呼函式，為您提供更大的彈性。如果您的值是物件，這可能會特別有用

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

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

$builder->add('publishAt', ChoiceType::class, [
    'choices' => [
        'now' => new \DateTime('now'),
        'tomorrow' => new \DateTime('+1 day'),
        '1 week' => new \DateTime('+1 week'),
        '1 month' => new \DateTime('+1 month'),
    ],
    'preferred_choices' => function ($choice, $key, $value): bool {
        // prefer options within 3 days
        return $choice <= new \DateTime('+3 days');
    },
]);

這只會「偏好」 「now」 和 「tomorrow」 選項

最後，如果您的值是物件，您也可以在物件上指定一個屬性路徑字串，該字串將傳回 true 或 false。

偏好選項僅在呈現 select 元素時才有意義 (即 expanded 為 false)。偏好選項和一般選項在視覺上以一組虛線分隔 (即 -------------------)。這可以在呈現欄位時自訂

1

{{ form_widget(form.publishAt, { 'separator': '=====' }) }}

1
2
3

<?= $view['form']->widget($form['publishAt'], [
    'separator' => '=====',
]) ?>

1
2
3
4
5
6

use Symfony\Component\Form\ChoiceList\ChoiceList;

// ...
$builder->add('choices', ChoiceType::class, [
    'preferred_choices' => ChoiceList::preferred($this, 'taggedAsFavorite'),
]);

trim

類型：boolean 預設值：false

預設情況下會停用修剪，因為選取的值或值必須與給定的選項值完全匹配 (而且它們可能包含空格)。

這些選項繼承自 FormType

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

empty_data

類型：mixed

此選項的實際預設值取決於其他欄位選項

• 如果 multiple 為 false 且 expanded 為 false，則為 '' (空字串)；
• 否則為 [] (空陣列)。

此選項決定當提交的值為空 (或遺失) 時，欄位將傳回的值。如果未在視圖中呈現表單時提供初始值，則此選項不會設定初始值。

這表示它可以協助您處理具有空白欄位的表單提交。例如，如果您希望在未選取任何值時，將 name 欄位明確設定為 John Doe，您可以這樣做

1
2
3
4

$builder->add('name', null, [
    'required'   => false,
    'empty_data' => 'John Doe',
]);

這仍然會呈現一個空的文字框，但是提交後，John Doe 值將會被設定。使用 data 或 placeholder 選項來在呈現的表單中顯示這個初始值。

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

類型：array 預設值：[]

設定用於顯示表單欄位說明訊息的 HTML 元素的 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

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

類型：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

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

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