Тема формы Bootstrap 5

Дата обновления перевода 2022-01-17

New in version 5.3: Тема формы Bootstrap 5 была представлена в Symfony 5.3.

Symfony предоставляет несколько способов интеграции Bootstrap в ваше приложение. Самый простой способ - добавить обязательные элементы <link> и <script> в ваши шаблоны (обычно вы добавляете их только в главный шаблон разметки, из которого расширяются другие шаблоны):

1
2
3
4
5
6
7
8
9
{# templates/base.html.twig #}

{# имейте в виду, что блоки в вашем шаблоне могут называться по-другому #}
{% block stylesheets %}
    <!-- Скопируйте CSS из https://getbootstrap.com/docs/5.0/getting-started/introduction/#css -->
{% endblock %}
{% block javascripts %}
    <!-- Скопируйте JavaScript из https://getbootstrap.com/docs/5.0/getting-started/introduction/#js -->
{% endblock %}

Если ваше приложение использует современные практики фронтенда, лучше использовать Webpack Encore и следовать этому туториалу, чтобы импортировать источники Bootstrap в ваши файлы SCSS и JavaScript.

Следующий шаг - сконфигурировать приложение Symfony так, чтобы оно использовало стили Bootstrap 5 при отображении форм. Если вы хотите применить их ко всем формам, определите такую конфигурацию:

  • YAML
    1
    2
    3
    # config/packages/twig.yaml
    twig:
        form_themes: ['bootstrap_5_layout.html.twig']
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    <!-- config/packages/twig.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:twig="http://symfony.com/schema/dic/twig"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            https://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/twig
            https://symfony.com/schema/dic/twig/twig-1.0.xsd">
    
        <twig:config>
            <twig:form-theme>bootstrap_5_layout.html.twig</twig:form-theme>
            <!-- ... -->
        </twig:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    7
    8
    // config/packages/twig.php
    use Symfony\Config\TwigConfig;
    
    return static function(TwigConfig $twig) {
        $twig->formThemes(['bootstrap_5_layout.html.twig']);
    
        // ...
    };
    

Если вы хотите применять стили Bootstrap от формы к форме, включите тег form_theme в шаблоны, где используются эти формы:

1
2
3
4
5
6
7
8
{# ... #}
{# этот тег применяется только к формам, определенным в этом шаблоне #}
{% form_theme form 'bootstrap_5_layout.html.twig' %}

{% block body %}
    <h1>User Sign Up:</h1>
    {{ form(form) }}
{% endblock %}

Note

По умолчанию, все вводы отображаются с классом mb-3 в своем контейнере. Если вы переопределите опцию класа row_attr, mb-3 тоже будет переопределен, и вам понадобится ясно добавить его.

Сообщения об ошибках

В отличие от темы Bootstrap 4, ошибки отображаются после элемента input. Однако, это все равно формирует прочную связь между ошибкой и ее <input>, как требуется по стандарту WCAG 2.0.

Чекбоксы и селективные кнопки

Для поля чекбокса/селективной кнопки, вызов form_label() не отобразит ничего. В связи с внутренней работой Bootstrap, ярлык уже отображен form_widget().

Встраиваемые чекбоксы и селективные кнопки

Если вы хотите отобразить свои поля чекбоксов или селективных кнопок встроенными, вы можете добавить класс checkbox-inline или radio-inline (в зависимости от вашего типа Формы Symfony или конфигурации ChoiceType) к классу ярлыка.

  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    $builder
        ->add('myCheckbox', CheckboxType::class, [
            'label_attr' => [
                'class' => 'checkbox-inline',
            ],
        ])
        ->add('myRadio', RadioType::class, [
            'label_attr' => [
                'class' => 'radio-inline',
            ],
        ]);
    
  • Twig
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    {{ form_row(form.myCheckbox, {
        label_attr: {
            class: 'checkbox-inline'
        }
    }) }}
    
    {{ form_row(form.myRadio, {
        label_attr: {
            class: 'radio-inline'
        }
    }) }}
    

Переключатели

Bootstrap 5 позволяет отображать чекбоксы в виде переключателей. Вы можете включить эту функцию в вашей Форме Symfony CheckboxType, добавив класс checkbox-switch к ярлыку:

  • PHP
    1
    2
    3
    4
    5
    $builder->add('myCheckbox', CheckboxType::class, [
        'label_attr' => [
            'class' => 'checkbox-switch',
        ],
    ]);
    
  • Twig
    1
    2
    3
    4
    5
    {{ form_row(form.myCheckbox, {
        label_attr: {
            class: 'checkbox-switch'
        }
    }) }}
    

Tip

Вы также можете отобразить ваши переключатели встроенными, просто добавив класс checkbox-inline в опции label_attr:

// ...
'label_attr' => [
    'class' => 'checkbox-inline checkbox-switch',
],
// ...

Caution

Переключатели работают только с чекбоксами.

Группа ввода

Чтобы создать группу ввода в вашей Форме Symfony, просто добавьте класс input-group к опции row_attr.

  • PHP
    1
    2
    3
    4
    5
    6
    $builder->add('email', EmailType::class, [
        'label' => '@',
        'row_attr' => [
            'class' => 'input-group',
        ],
    ]);
    
  • Twig
    1
    2
    3
    4
    5
    6
    {{ form_row(form.email, {
        label: '@',
        row_attr: {
            class: 'input-group'
        }
    }) }}
    

Caution

Если вы заполните опцию help в вашей форме, она также отобразится, как часть группы.

Плавающие ярлыки

Чтобы отобразить поле ввода с плавающим ярлыком, вы должны добавить label, placeholder и класс form-floating к опции row_attr вашего типа формы.

  • PHP
    1
    2
    3
    4
    5
    6
    7
    8
    9
    $builder->add('name', TextType::class, [
        'label' => 'Name',
        'attr' => [
            'placeholder' => 'Name',
        ],
        'row_attr' => [
            'class' => 'form-floating',
        ],
    ]);
    
  • Twig
    1
    2
    3
    4
    5
    6
    7
    8
    9
    {{ form_row(form.name, {
        label: 'Name',
        attr: {
            placeholder: 'Name'
        },
        row_attr: {
            class: 'form-floating'
        }
    }) }}
    

Caution

Вы должны предоставить label и placeholder, чтобы плавающие ярлыки работали корректно.

Доступность

Фреймворк Bootstrap 5 постарался, чтобы быть доступным для функциональных вариаций вроде нарушений зрения и когнитивных способностей. Symfony пошла дальше, чтобы гарантировать, что тема формы соответствует стандарту WCAG 2.0.

This does not mean that your entire website automatically complies with the full standard, but it does mean that you have come far in your work to create a design for all users.

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.