Установка Symfony UX

Перед тем, как вы установите любую библиотеку UX, убедитесь, что вы установили Webpack Encore.

Если он у вас уже установлен, убедитесь в том, что у вас есть файл assets/bootstrap.js (он инициализирует Stimulus и пакеты UX), файл assets/controllers.json (контролирует сторонние пакеты UX, которые вы установили) и .enableStimulusBridge('./assets/controllers.json') в вашем файле webpack.config.js. Если их нет, попробуйте обновить рецепт Flex symfony/webpack-encore-bundle. См. Обновление рецептов Flex .

Все пакеты Symfony UX

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

• ux-autocomplete: Преобразование EntityType, ChoiceType или любого элемент <select> в поле автозаполнения с помощью Ajax (см. демо)
• ux-chartjs: Простые графики с Chart.js (см. демо)
• ux-cropperjs: Тип формы и инструменты для обрезания изобажения (см. демо)
• ux-dropzone: Тип формы для стилизованной "зоны сброса" для загрузки файлов (см. демо)
• ux-lazy-image: Оптимизация загрузки изображений с BlurHash (см. демо)
• ux-live-component: Построение динамических интерфейсов без JavaScript (см. демо)
• ux-notify: Отправка нативного уведомления, отправленного сервером, с Mercure (см. демо)
• ux-react: Отображение компонента React из Twig (см. демо)
• ux-swup: Интеграция с Swup (см. демо)
• ux-turbo: Интеграция с Turbo Drive для опыта одностраничного приложения (см. демо)
• ux-twig-component: Построение компонентов Twig с поддержкой PHP-класса (см. демо)
• ux-typed: Интеграция с Typed (см. демо)
• ux-vue: Отображение компонента Vue из Twig (см. демо)

Инструменты Stimulus по всему миру

Так как Stimulus используется разработчиками вне Symfony, многие инструменты существуют вне пакетов UX:

• stimulus-use: Добавляйте составные поведения к вашим контроллерпам Stimulus, вроде дебаунсинга, обнаружения внешних кликов и многих других вещей.
• stimulus-components Большое количество предварительно созданных контроллеров Stimulus, вроде копирования в буфер обмена, Sortable, Popover (схоже с tooltips) и многое другое.

Как работает Symfony UX?

Когда вы устанавливаете PHP-пакет UX, Symfony Flex автоматически обновляет ваш файл package.json, чтобы указать на "виртуальный пакет", который живёт внутри PHP-пакета. Например:

1
2
3
4
5
6

{
    "devDependencies": {
        "...": "",
        "@symfony/ux-chartjs": "file:vendor/symfony/ux-chartjs/Resources/assets"
    }
}

Это даёт вам реальный пакет Node (например, @symfony/ux-chartjs) который, вместо его загрузки, прямо указывает на файлы, которые уже живут в вашем каталоге vendor/.

Рецепт Flex обычно также будет обновлять ваш файл assets/controllers.json, чтобы добавить новый контроллер Stimulus в ваше приложение. Например:

1
2
3
4
5
6
7
8
9
10
11

{
    "controllers": {
        "@symfony/ux-chartjs": {
            "chart": {
                "enabled": true,
                "fetch": "eager"
            }
        }
    },
    "entrypoints": []
}

Наконец, ваш файл assets/bootstrap.js - работая с @symfony/stimulus-bridge -
автоматически зарегистрирует:

• Все файлы в assets/controllers/ как контроллеры Stimulus;
• И все контроллеры, описанные в assets/controllers.json как контроллеры Stimulus.

Конечный результат: вы устанавливаете пакет, и у вас мгновенно доступен контроллер Stimulus! В этом примере он называется @symfony/ux-chartjs/chart. Ну, технически, он будет называться symfony--ux-chartjs--chart. Однако, вы можете передать оригинальное имя в функцию {{ stimulus_controller() }} из WebpackEncoreBundle, и это всё нормализует:

1
2
3
4

<div {{ stimulus_controller('@symfony/ux-chartjs/chart') }}>

<!-- отобразится как: -->
<div data-controller="symfony--ux-chartjs--chart">

Ленивые контроллеры

По умолчанию, все ваши контроллеры (т.е. файлы в assets/controllers/ + контроллеры в assets/controllers.json) будут скачаны и загружены на каждой странице.

Иногда у вас может быть контроллер, который используется только на некоторых страницах, или, может, только в вашей админ области. В таком случае, вы можете сделать контроллер "ленивым". Когда контроллер ленивый, он не скачивается при изначальной загрузке страницы. Вместо этого, как только элемент возникает на странице, совпадающей с контроллером (например, <div data-controller="hello">), контроллер - и всё, что он импортирует - будет лениво загружен через Ajax.

Чтобы сделать один из ваших пользовательских контроллеров ленивым, добавьте специальный комментарий сверху:

1
2
3
4
5
6

import { Controller } from '@hotwired/stimulus';

/* stimulusFetch: 'lazy' */
export default class extends Controller {
    // ...
}

Чтобы сделать сторонний контроллер ленивым, в assets/controllers.json, установите fetch как lazy.

Более продвинутая настройка

Чтобы узнать о более продвинутых опциях, прочтите о @symfony/stimulus-bridge, пакете Node, который отвечает за большое количество магии.