Ініціатива та пакети Symfony UX

Дата оновлення перекладу 2023-05-29

Ініціатива та пакети Symfony UX

Tip

Перегляньте живі демо Symfony UX тут: https://ux.symfony.com!

Symfony UX - це ініціатива та набір бібліотек для плавної інтеграції інструментів JavaScript у ваш додаток. Наприклад, ви хочете відобразити діаграму за допомогою Chart.js? Використайте UX Chart.js, щоб побудувати діаграму у PHP. JavaScript обробляється за вас автоматично.

За лаштунками, пакети UX використовують Stimulus: маленьку, але потужну бібліотеку, для поєднання функціональності JavaScript з елементами на вашій сторінці.

Установка 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

Дата оновлення перекладу 2022-12-14

Інструменти Stimulus по всьому світу

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

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

Як працює Symfony UX?

Коли ви встановлюєте пакет UX PHP, 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.

Note

Якщо ви пишете свої контролери, використовуючи TypeScript, переконайтеся, що removeComments не встановлено як true у вашій конфігурації TypeScript.

Більш просунуте налаштування

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