FormType 欄位

action

type: string default: 空字串

此選項指定在提交時將表單的資料傳送到何處 (通常是 URI)。其值會呈現為 form 元素的 action 屬性。空值被視為同文件參考，即表單將提交到呈現表單的相同 URI。

allow_extra_fields

type: boolean default: false

通常，如果您提交未在表單中設定的額外欄位，您會收到「此表單不應包含額外欄位。」的驗證錯誤。

您可以透過在表單上啟用 allow_extra_fields 選項來關閉此驗證錯誤。

by_reference

type: boolean default: true

在大多數情況下，如果您有 author 欄位，那麼您會期望在底層物件上呼叫 setAuthor()。 但是，在某些情況下，可能不會呼叫 setAuthor()。 將 by_reference 設定為 false 可確保在所有情況下都會呼叫 setter。

為了進一步解釋，以下是一個簡單的範例

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

use Symfony\Component\Form\Extension\Core\Type\EmailType;
use Symfony\Component\Form\Extension\Core\Type\FormType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
// ...

$builder = $this->createFormBuilder($article);
$builder
    ->add('title', TextType::class)
    ->add(
        $builder->create('author', FormType::class, ['by_reference' => ?])
            ->add('name', TextType::class)
            ->add('email', EmailType::class)
    )

如果 by_reference 為 true，當您在表單上呼叫 submit() (或 handleRequest()) 時，幕後會發生以下情況

1
2
3

$article->setTitle('...');
$article->getAuthor()->setName('...');
$article->getAuthor()->setEmail('...');

請注意，setAuthor() 沒有被呼叫。作者是透過參考修改的。

如果您將 by_reference 設定為 false，則提交看起來像這樣

1
2
3
4
5

$article->setTitle('...');
$author = clone $article->getAuthor();
$author->setName('...');
$author->setEmail('...');
$article->setAuthor($author);

因此，by_reference=false 真實的作用是複製物件，這會強制框架在父物件上呼叫 setter。

同樣地，如果您正在使用 CollectionType 欄位，而您的底層集合資料是一個物件 (例如使用 Doctrine 的 ArrayCollection)，那麼如果您需要呼叫 adder 和 remover (例如 addAuthor() 和 removeAuthor())，則必須將 by_reference 設定為 false。

compound

type: boolean default: true

複合表單可以是整個 <form> 元素或一組表單欄位 (例如在 <div> 或 <tr> 容器元素內呈現)。 複合表單使用 DataMapperInterface 初始化其子項或寫回其提交的資料。

簡單 (非複合) 表單會呈現為以下任何 HTML 元素：<input> (TextType、FileType、HiddenType)、<textarea> (TextareaType) 或 <select> (ChoiceType)。

某些核心類型 (例如日期相關類型或 ChoiceType) 根據其他選項 (例如 expanded 或 widget) 可能是簡單的或複合的。 它們將表現為簡單的文字欄位或文字或選項欄位群組。

constraints

type: array 或 Constraint default: []

允許您將一個或多個驗證約束附加到特定欄位。 如需更多資訊，請參閱 新增驗證。 此選項新增於 FormTypeValidatorExtension 表單擴充功能中。

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

data_class

type: string

此選項用於設定表單要使用的適當資料映射器，因此您可以將其用於任何需要物件的表單欄位類型

1
2
3
4
5
6
7

use App\Entity\Media;
use App\Form\MediaType;
// ...

$builder->add('media', MediaType::class, [
    'data_class' => Media::class,
]);

empty_data

type: mixed

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

• 如果設定了 data_class 且 required 為 true，則為 new $data_class()；
• 如果設定了 data_class 且 required 為 false，則為 null；
• 如果未設定 data_class 且 compound 為 true，則為 [] (空陣列)；
• 如果未設定 data_class 且 compound 為 false，則為 '' (空字串)。

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

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

1
2
3
4

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

這仍然會呈現一個空的文字方塊，但在提交時，將會設定 John Doe 值。 使用 data 或 placeholder 選項以在呈現的表單中顯示此初始值。

is_empty_callback

type: callable default: null

此可呼叫物件會取得表單資料，並傳回值是否被視為空。

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

extra_fields_message

type: string default: This form should not contain extra fields.

如果提交的表單資料包含一個或多個不屬於表單定義的欄位，則會使用此驗證錯誤訊息。 佔位符 {{ extra_fields }} 可用於顯示提交的額外欄位名稱的逗號分隔列表。

此訊息可以複數化，請參閱 格式化複數訊息 以取得詳細資訊。

form_attr

type: boolean 或 string default: false

當 true 且用於表單元素時，它會將 「form」屬性 新增到其 HTML 欄位表示中，並帶有其 HTML 表單 ID。 這樣做，表單元素可以在 HTML 表單之外呈現，同時仍能如預期般運作

1
2
3

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

當您需要解決巢狀表單問題時，這可能很有用。 您也可以在根表單上將此設定為 true，以在所有子項上自動設定「form」屬性。

getter

type: callable default: null

如果提供，將會調用此可呼叫物件，以從底層物件讀取值，該值將用於填入表單欄位。

更多詳細資訊可在 何時以及如何使用資料映射器 章節中取得。

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 元素時，此選項非常有用。

help_translation_parameters

type: array default: []

help 選項的內容在顯示前會先經過翻譯，因此它可以包含翻譯預留位置。此選項定義用於取代這些預留位置的值。

假設有以下翻譯訊息

1
2

# translations/messages.en.yaml
form.order.id.help: 'This will be the reference in communications with %company%'

您可以如下指定預留位置的值

1
2
3
4
5
6

$builder->add('id', null, [
    'help' => 'form.order.id.help',
    'help_translation_parameters' => [
        '%company%' => 'ACME Inc.',
    ],
]);

子欄位的 help_translation_parameters 選項會與其父欄位的相同選項合併，因此子欄位可以重複使用和/或覆寫任何父欄位的預留位置。

inherit_data

type: boolean default: false

此選項決定表單是否將繼承其父表單的資料。如果您有多個表單中重複使用的欄位組，這會很有用。請參閱如何使用 "inherit_data" 減少程式碼重複。

invalid_message

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

這是驗證錯誤訊息，當輸入到此欄位的資料不合理（即驗證失敗）時會使用此訊息。

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

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

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_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_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

type: boolean default: true

如果您希望在讀取或寫入物件時忽略該欄位，您可以將 mapped 選項設定為 false。

method

類型: string 預設值: POST

此選項指定用於提交表單資料的 HTTP 方法。其值會呈現為 form 元素的 method 屬性，並用於決定是否在提交後於 handleRequest() 方法中處理表單提交。可能的值為

• POST
• GET
• PUT
• DELETE
• PATCH

post_max_size_message

類型: string 預設值: The uploaded file was too large. Please try to upload a smaller file.

這是驗證錯誤訊息，當提交的 POST 表單資料超過 php.ini 的 post_max_size 指令時會使用此訊息。{{ max }} 預留位置可用於顯示允許的大小。

property_path

類型: PropertyPathInterface|string|null 預設值: null

預設情況下（當此選項的值為 null 時），表單欄位會從表單網域物件中具有相同名稱的屬性讀取和寫入。property_path 選項可讓您定義欄位從哪個屬性讀取和寫入。此選項的值可以是任何有效的 PropertyAccess 語法。

required

type: boolean default: true

如果為 true，將會呈現 HTML5 required 屬性。對應的 label 也將以 required 類別呈現。

這是表面的，並且獨立於驗證。在最好的情況下，如果您讓 Symfony 猜測您的欄位類型，那麼此選項的值將會從您的驗證資訊中猜測出來。

setter

type: callable default: null

當提供時，將會調用此可調用物件，以將表單值對應回底層物件。

更多詳細資訊可在 何時以及如何使用資料映射器 章節中取得。

trim

type: boolean default: true

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

validation_groups

類型: array、string、callable、GroupSequence 或 null 預設值: null

此選項僅在根表單上有效，並用於指定驗證器將使用的群組。

對於 null，驗證器將僅使用 Default 群組。

如果您將群組指定為陣列或字串，它們將按原樣被驗證器使用

1
2
3
4
5
6

public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'validation_groups' => 'Registration',
    ]);
}

這相當於將群組作為陣列傳遞

1

'validation_groups' => ['Registration'],

表單的資料將針對所有給定的群組進行驗證。

如果驗證群組取決於表單的資料，則可以將可調用物件傳遞給選項。然後，Symfony 將在調用它時傳遞表單

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

use Symfony\Component\Form\FormInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

// ...
public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'validation_groups' => function (FormInterface $form): array {
            $entity = $form->getData();

            return $entity->isUser() ? ['User'] : ['Company'];
        },
    ]);
}

在某些情況下，您想要逐步驗證您的群組。為此，您可以將 GroupSequence 傳遞給此選項。這使您可以針對多個群組進行驗證，就像您在陣列中傳遞多個群組時一樣，但不同之處在於，只有在前一個群組通過且沒有錯誤的情況下，才會驗證群組。以下是一個範例

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

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Validator\Constraints\GroupSequence;
// ...

class MyType extends AbstractType
{
    // ...
    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'validation_groups' => new GroupSequence(['First', 'Second']),
        ]);
    }
}

attr

type: array default: []

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

1
2
3

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

auto_initialize

type: boolean default: true

一個內部選項：設定是否應自動初始化表單。對於所有欄位，此選項僅應對根表單為 true。您不需要變更此選項，可能也不需要擔心它。

block_name

類型: string 預設值: 表單的名稱（請參閱 了解要自訂哪個區塊）

允許您將自訂區塊名稱新增到預設用於呈現表單類型的區塊名稱中。例如，當您有多個相同表單的實例，並且需要個別個人化表單的呈現方式時，這會很有用。

如果您例如將此選項設定為 my_custom_name 且欄位類型為 text，Symfony 將使用以下名稱（依此順序）來尋找用於呈現欄位小工具的區塊：_my_custom_name_widget、text_widget 和 form_widget。

block_prefix

類型: string 或 null 預設值: null（請參閱 了解要自訂哪個區塊）

允許您新增自訂區塊前綴並覆寫用於呈現表單類型的區塊名稱。例如，當您有多個相同表單的實例，並且需要個人化所有這些表單的呈現方式，而無需建立新的表單類型時，這會很有用。

disabled

type: boolean default: false

如果您不希望使用者修改欄位的值，您可以將 disabled 選項設定為 true。任何提交的值都將被忽略。

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_html

type: boolean default: false

預設情況下，label 選項的內容在範本中呈現之前會先經過跳脫處理。將此選項設定為 true 以不進行跳脫處理，當標籤包含 HTML 元素時，此選項非常有用。

row_attr

type: array default: []

新增到用於呈現表單類型列之元素的 HTML 屬性關聯陣列

1
2
3

$builder->add('body', TextareaType::class, [
    'row_attr' => ['class' => 'text-editor', 'id' => '...'],
]);

translation_domain

類型: string、null 或 false 預設值: null

這是將用於此欄位呈現的任何標籤或選項的翻譯網域。使用 null 以重複使用父表單的翻譯網域（或根表單的翻譯器的預設網域）。使用 false 以停用翻譯。

label_translation_parameters

type: array default: []

label 選項的內容在顯示前會先經過翻譯，因此它可以包含翻譯預留位置。此選項定義用於取代這些預留位置的值。

假設有以下翻譯訊息

1
2

# translations/messages.en.yaml
form.order.id: 'Identifier of the order to %company%'

您可以如下指定預留位置的值

1
2
3
4
5
6

$builder->add('id', null, [
    'label' => 'form.order.id',
    'label_translation_parameters' => [
        '%company%' => 'ACME Inc.',
    ],
]);

子欄位的 label_translation_parameters 選項會與其父欄位的相同選項合併，因此子欄位可以重複使用和/或覆寫任何父欄位的預留位置。

attr_translation_parameters

type: array default: []

attr 選項中定義的 title 和 placeholder 值的內容在顯示前會先經過翻譯，因此它可以包含翻譯預留位置。此選項定義用於取代這些預留位置的值。

假設有以下翻譯訊息

1
2
3

# translations/messages.en.yaml
form.order.id.placeholder: 'Enter unique identifier of the order to %company%'
form.order.id.title: 'This will be the reference in communications with %company%'

您可以如下指定預留位置的值

1
2
3
4
5
6
7
8
9

$builder->add('id', null, [
    'attr' => [
        'placeholder' => 'form.order.id.placeholder',
        'title' => 'form.order.id.title',
    ],
    'attr_translation_parameters' => [
        '%company%' => 'ACME Inc.',
    ],
]);

子欄位的 attr_translation_parameters 選項會與其父欄位的相同選項合併，因此子欄位可以重複使用和/或覆寫任何父欄位的預留位置。

priority

類型: integer 預設值: 0

欄位會以它們包含在表單中的相同順序呈現。此選項會變更欄位呈現優先順序，讓您可以比原始順序更早或更晚顯示欄位。

此選項將僅影響檢視順序。此優先順序越高，欄位將越早呈現。優先順序也可以是負數，且具有相同優先順序的欄位將保留其原始順序。