Поле FileType
Дата обновления перевода 2025-02-05
Поле FileType
FileType
представляет ввод файла в вашей форме.
???????????? ??? | ???? input file |
????????? ???????????? ?? ????????? | ??????????, ???????? ???????? ????. |
???????????? ??? | FormType |
????? | FileType |
Дата обновления перевода 2025-02-21
Tip
Полный список опций, определенных и унаследованных этим типом формы, доступен путем
выполнения этой команды в вашем приложении:
1 2
# замените 'FooType' именем класса вашего типа формы
$ php bin/console debug:form FooType
Базовое применение
Допустим, у вас есть такое определение формы:
1 2 3 4
use Symfony\Component\Form\Extension\Core\Type\FileType;
// ...
$builder->add('attachment', FileType::class);
Когда отправляется форма, поле attachment
будет экземпляром
UploadedFile. Он может
быть использован для перемещения файла attachment
в постоянную локацию:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
use Symfony\Component\HttpFoundation\File\UploadedFile;
public function upload(): Response
{
// ...
if ($form->isSubmitted() && $form->isValid()) {
$someNewFilename = ...
$file = $form['attachment']->getData();
$file->move($dir, $someNewFilename);
// ...
}
// ...
}
Метод move()
берёт каталог и имя файла в качестве своих аргументов. Вы
можете вычислить имя файла одним из следующих способов:
1 2 3 4 5 6 7 8 9 10
// использовать оригинальное имя файла
$file->move($dir, $file->getClientOriginalName());
// создать случайное имя и попробовать угадать расширение (более безопасно)
$extension = $file->guessExtension();
if (!$extension) {
// расширение не может быть угадано
$extension = 'bin';
}
$file->move($dir, rand(1, 99999).'.'.$extension);
Использование оригинального имени через getClientOriginalName()
не безопасно,
так как оно могло быть изменено конечным пользователем. Однако, оно может содержать
символы, которые не разрешены в имени файлов. Вы должны очистить имя перед тем, как
использовать его напрямую.
Прочтите Как загружать файлы, чтобы увидеть пример того, как управлять загрузкой файла, связанного с сущностью Doctrine.
Опции поля
multiple
тип: Boolean
по умолчанию: false
Когда установлена, как "true", пользователь сможет загрузать несколько файлов одновременно.
Переопределённые опции
Дата обновления перевода 2025-02-22
compound
тип: boolean
по умолчанию: false
Эта опция указывает, содержит ли тип дочерние типы. Эта опция управляется внутренне для встроенных типов, так что нет необходимости конфигурировать её ясно.
data_class
тип: string
default: File
Эта опция устанавливает правильный преобразователь данных, связанный с данными, для использования типом.
empty_data
тип: mixed
по умолчанию: null
Эта опция определяет, какое значение будет возвращать поле, когда отправленное значение пусто.
Переопределённые опции
Дата обновления перевода 2025-02-24
invalid_message
тип: string
по умолчанию: Это значение не валидно
Это сообщение ошибки валидации, которое используется, если данные, введенные в это поле, не имеют смысла (т.е. валидация проходит неудачно).
Это может случиться, к примеру, если пользователь вводит в поле
TimeType асбурдную строку, которая
не может быть конвертирована в настоящее время, или если пользователь вводит
строку (например, apple
) в числовое поле.
Нормальная (программный код) валидация (например, установка минимальной длины для поля), должна быть установлена с использованием сообщений валидации с вашими правилами валидации (справочник ).
Наследуемые опции
Эти опции наследуются из FormType:
Дата обновления перевода 2025-02-21
attr
тип: array
по умолчанию: []
Если вы хотите добавить дополнительные атрибуты к HTML представлению поля, то
вы можете использовать опцию attr
. Это ассоциативный массив с HTML-атрибутами
в качестве ключей. Этоможет быть полезно, когда вам нужно установить для некоторого
виджета пользовательский класс:
1 2 3
$builder->add('body', TextareaType::class, [
'attr' => ['class' => 'tinymce'],
]);
See also
Используйте опцию row_attr
, если вы хотите добавить эти атрибуты к
к элементу строки типа формы
Дата обновления перевода 2025-02-24
disabled
тип: boolean
по умолчанию: false
Если вы не хотите, чтобы пользователь изменял значение поля, то вы можете установить опцию отключения, как "true". Любые отправленные данные будут проигнорированы.
Дата обновления перевода 2025-02-24
error_bubbling
тип: boolean
по умолчанию: false
, кроме случаев, когда форма compound
Если true
, то любые ошибки в этом поле будут переданы родительскому
полю или форме. Например, если установлена, как true
в нормальном
поле, то любые ошибки для этого поля будут присоединены к главной форме,
а не к конкретному полю.
Дата обновления перевода 2024-07-26
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',
],
]);
Дата обновления перевода 2024-07-26
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'),
])
;
Дата обновления перевода 2025-02-24
help_attr
тип: array
по умолчанию: []
Устанавливает HTML-атрибуты для элемента, используемого для отображения сообщения помощи в поле формы. Его значение представляет собой ассоциативный массив с именами HTML-атрибутов в качестве ключей. Эти атрибуты также могут быть заданы в шаблоне:
1 2 3
{{ form_help(form.name, 'Your name', {
'help_attr': {'class': 'CUSTOM_LABEL_CLASS'}
}) }}
Дата обновления перевода 2025-02-24
help_html
тип: boolean
по умолчанию: false
По умолчанию содержание опции help
экранируется перед отображением в шаблоне.
Установите для этой опции значение true
, чтобы не экранировать их, что полезно,
когда справка содержит элементы HTML.
Дата обновления перевода 2023-01-12
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',
// по желанию, вы можете использовать объекты TranslatableMessage как содержание ярлыка
'label' => new TranslatableMessage('address.zipCode', ['%country%' => $country], 'address'),
])
Ярлык также может быть установлен внутри шаблона:
1
{{ form_label(form.name, 'Your name') }}
Дата обновления перевода 2025-02-24
label_attr
тип: array
по умолчанию: []
Устанавливает HTML-атрибуты для элемента <label>
, который будет использован
при отображении ярлыка для поля. Это ассоциативный массив с HTML-атрибутом в
качестве ключа. Этот атрибут может также быть установлен прямо внутри шаблона:
1 2 3
{{ form_label(form.name, 'Your name', {
'label_attr': {'class': 'CUSTOM_LABEL_CLASS'}
}) }}
Дата обновления перевода 2025-02-24
label_html
тип: boolean
по умолчанию: false
По умолчанию, содержание опции label
экранируется перед отображением
в шаблоне. Установите для этой опции значение true
, чтобы не экранировать
ее, что может быть полезно, когда ярлык содержит HTML-элементы.
Дата обновления перевода 2025-02-24
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
) приводит к
"человеческой" версии имени поля.
Note
Опция label_format
оценивается в теме формы. Убедитесь в том, что вы
обновили ваши щаблоны, в случае, если вы настраивали темизацию форм.
Дата обновления перевода 2025-02-24
mapped
тип: boolean
по умолчанию: true
Если вы хотите, чтобы поле было проигнорировано про чтении или записи в него
объекта, вы можете установить опцию mapped
, как false
.
Дата обновления перевода 2023-09-25
required
тип: boolean
по умолчанию: true
Если "true", то будет отображён обязательный атрибут HTML5.
Соответствующий label
также отобразится с классом required
.
Эта опция внешняя и не зависит от валидации. В лучшем случае, если вы позволите Symfony отгадать ваш тип поля, тогда значение этой опции будет угадано из вашей информации о валидации.
Note
Обязательная опция также влияет на то, как будут обработаны пустые данные для каждого поля. Чтобы узнать больше, см. опцию empty_data.
Дата обновления перевода 2025-02-24
row_attr
тип: array
по умолчанию: []
Ассоциативный массив атрибутов HTML, добавляемых к элементу, который используется для отображения строки типа формы :
1 2 3
$builder->add('body', TextareaType::class, [
'row_attr' => ['class' => 'text-editor', 'id' => '...'],
]);
See also
Используйте опцию attr
, если вы хотите добавить эти атрибуты к
к элементу виджета типа формы .
Переменные формы
?????????? | ??? | ??????????? |
---|---|---|
type |
string |
??? ?????????? ??????????, ??? file , ????? ?????????? ? ???? ???? ????? ?????. |