Подключение и использование
Глава показывает, как поставить Smart-компонент на страницу, настроить его, получить результат и дождаться готовности. Этого достаточно, чтобы пользоваться библиотечными компонентами, не читая их исходный код.
Подключение к странице
Smart-компоненты лежат в поставке ui, в distr/smart/. Loader находит их
по window.sfPath, который задаётся один раз в шаблоне проекта до подключения
core.js; полный порядок подключения и все глобальные настройки — см. Порядок подключения
и Глобальные настройки. После этого на странице достаточно тега:
<sf-button text="Сохранить" scheme="primary"></sf-button>
Увидев на странице <sf-button>, Loader подключит Smart-кнопку и обычный
компонент кнопки, от которого зависит её оформление. Подключать файлы каждого
компонента вручную не нужно. Loader следит и за элементами, которые появились
позже — например, после ответа сервера.
Общая среда Smart-компонентов. Lit, базовый класс SfBaseElement, язык
страницы, позиционирование всплывающих элементов и отступы контролов — общая
среда выполнения всех Smart-компонентов. Она лежит одним файлом рядом с
core.js: core/js/smart-base.js (в минифицированной поставке —
smart-base.min.js) и загружается один раз на страницу. Скрипт отдельного
Smart-компонента своей копии этих модулей не несёт.
- Core загружает общую среду сам, когда Loader ставит в очередь первый Smart-элемент страницы, поэтому она приходит вместе с первым скриптом компонента. Страница без Smart-элементов её не загружает.
- Скрипт компонента получает модули среды через
SF.runtimeModule()и регистрирует тег, когда среда пришла. Поэтому загруженный скрипт ещё не означает зарегистрированный тег: код, которому нужен элемент, ждёт его (см. Ожидание готовности). - Страница, которая подключает скрипты Framework вручную, а не через Loader,
ставит
core/js/smart-base.jsпослеcore.js, а страница без Core — перед скриптами Smart-компонентов.
Поставка — это выпуск. Core и Smart-компоненты проект закрепляет одним выпуском и не смешивает файлы разных выпусков (см. Выпуск и запись о выпуске).
Компоненты пакетов, например пакета продукта, подключаются так же — тегом, но только на странице, которая объявила их пакет (см. Пакеты компонентов продуктов и Пакеты компонентов). Если пакет не объявлен, Loader не загружает его компонент и сообщает в консоли, какой тег и почему не загружен.
Так подключаются <sf-table>, <sf-data-view>, <sf-property-view> и
<sf-admin-menu>: это компоненты Larena, пакет larena. Их исходники лежат в
репозитории simai/larena-ui (папка components/, лицензия Apache-2.0), а не
в поставке ui. Пакет собирает инструмент ui-builder из точной ревизии
исходников Framework; Larena отдаёт сборку в своей поставке, а каждая сборка
публикуется выпуском репозитория simai/larena-ui с архивом, его SHA-256 и
квитанцией (см. Пакет larena для проекта без Larena). Без
сборки пакета эти четыре элемента на странице не работают. Квитанция сборки
(package-receipt.json) называет выпуск Framework ui-…, с которым пакет
собран, — подключайте их вместе. Пакет объявляется до core.js, путь к нему —
по правилу из Пакеты компонентов (/assets/larena/<коммит пакета>/smart), файл
правил smart/rule.js Loader загружает сам:
<script>
window.sfPath = '/assets/simai-framework/ui/distr/';
window.SF_BOOT_CONFIG = {
packages: {
larena: {base: '/assets/larena/5f33ba576aebde377d5195ec71836eb4430aa84d/smart'},
},
};
</script>
<script src="/assets/simai-framework/ui/distr/core/js/core.js"></script>
<sf-table aria-label="Проекты" table-settings-key="projects"></sf-table>
Настройка атрибутами
Простые значения задаются атрибутами:
<sf-button text="Удалить" status="error" appearance="outline" size="1/2"></sf-button>
Объекты и массивы передаются через свойства или методы, объявленные в
документации конкретного компонента. Простое присваивание element.count = 3
не обязано вызывать перерисовку — смотрите раздел «Методы» на странице
компонента. Изменение объявленного атрибута (setAttribute) перерисовывает
компонент (см. Атрибуты, свойства и состояние).
Имена настроек
Имена настроек у Smart-компонентов те же, что у компонентов на классах:
| Настройка | Что задаёт |
|---|---|
appearance |
Как выглядит |
status |
О чём сообщает |
kind |
Чем является |
size |
Ступень общей лестницы размеров |
scheme |
Какой смысловой цвет |
В Smart-компоненте они пишутся атрибутами тега, на классах — модификаторами. Настройки независимы и складываются. Значения, правило «схема — не статус» и лестница размеров — см. Настройки: общий язык компонентов и Размер: одна лестница для всех компонентов.
Получение результата: события
Компонент сообщает о действиях событиями. Проект подписывается и решает, что делать. Пример показывает подписку на изменение даты:
const date = document.querySelector('sf-datepicker');
date.addEventListener('change', (event) => {
console.log('Выбрана дата', event.detail);
});
Изменение значения — всегда change. Любой элемент формы (поле, выбор,
дата, переключатель, слайдер, группа кнопок) сообщает о подтверждённом
изменении значения событием change на своём теге — один раз на одно действие
человека. Значение, установленное из кода, изменением не считается и change
не вызывает.
Имена прочих событий единого шаблона не имеют: sf-popover-open,
sf-page-change, sf-file-upload:select, modal:after-close,
drawer:after-open, close. Не выводите имя по аналогии — берите его из
раздела events манифеста компонента или со страницы компонента в
справочнике. Подробно — см. События.
Ожидание готовности
Если проекту нужно обратиться к компоненту сразу после появления на странице, дождитесь регистрации тега и первой отрисовки:
const button = document.querySelector('sf-button');
await customElements.whenDefined('sf-button');
await button.whenRendered();
Ждать нужно и тогда, когда скрипт компонента уже загружен: тег регистрируется
только после того, как пришла общая среда Smart-компонентов
(см. Подключение к странице). Для тега Framework
можно писать короткое имя: await SF.whenDefined('button').
Свойства компонента (value, formattedValue, triggerText и другие)
верны уже после whenDefined(); узлы внутри компонента появляются после
whenRendered().
whenRendered() работает и после первой отрисовки: если отрисовка уже
случилась, обещание выполняется сразу. Полная запись —
whenRendered(callback?, { next? }): необязательная функция callback
получает сведения об отрисовке, а { next: true } ждёт следующую отрисовку.
Чтобы дождаться следующей отрисовки без функции, передайте
whenRendered(null, { next: true }) или слушайте событие sf-after-render.
Что важно заметить:
customElements.whenDefined()иSF.whenDefined()ничего не загружают. Для тега, которого нет на странице, обещание не выполнится; новый элемент создают черезawait SF.createAsync('button')(см. События загрузчика).- Содержимое слотов может переехать. Компонент забирает детей тега до
первой отрисовки и рисует своё содержимое заново; модальное окно рисует
содержимое слотов копией в отдельном контейнере на
body. Узел, найденный в разметке до отрисовки, может оказаться вне страницы, а обработчик на нём не сработает. Ищите узлы в документе послеawait element.whenRendered()или подписывайтесь делегированием наdocument:
document.addEventListener('submit', (event) => {
if (event.target.id !== 'feedback-form') return;
event.preventDefault();
// обработка формы из модального окна
});
- Когда доступен каждый
SF.*— см. таблицу в События загрузчика.
Готовность компонента к использованию
Наличие исходников не означает готовность. У каждого компонента есть уровень готовности (см. Уровни готовности); каталог показывает его в виде статуса для людей:
| Статус в каталоге | Что означает |
|---|---|
| Готов к использованию | Основной сценарий проверен |
| Доступен для проверки | Loader подключает элемент, но ваш сценарий нужно проверить |
| Заблокирован | Штатного правила загрузки нет |
Число компонентов в каждом статусе показывает страница каталога.
Строка «Готовность» на странице справочника. Она показывает, насколько компонент проверен:
| Значение | Что можно делать |
|---|---|
| описан | Компонент подключается и работает по своему манифесту, сценарий проверки есть, но продуктовой приёмки нет. Использовать его можно, в том числе в рабочем проекте, если проект сам проверил свой сценарий в браузере |
| работает в сценарии студии | То же, и компонент проверен в сценарии студии; продуктовой приёмки нет |
| проверен приёмкой | Основной сценарий проверен приёмкой |
| принят в продукт | Компонент принят в продукт и работает в нём |
host-required |
Компонент работает только с подключённым приложением через порт хоста |
Может ли меняться API, говорит другая строка — «Жизненный цикл»: «экспериментальный» означает, что API может меняться между выпусками, и версию Framework проект закрепляет (см. Как обновить проект).
Как перенести пример в проект
- Откройте страницу компонента в справочнике.
- Скопируйте проверенный пример.
- Запустите его с тем выпуском, который закреплён в проекте.
- Проверьте загрузку файлов, клавиатуру, фокус, пустое состояние и ошибку.
- Оставьте только нужную сценарию разметку.
Для загрузки данных или файлов проверьте также повторный запуск и восстановление после ошибки. Проверяйте пример перед переносом, после обновления Framework и при использовании компонента в новом сценарии. Работа примера в Playground или похожее имя не подтверждают совместимость с вашим выпуском: пример работает только с той парой Core и Smart-компонентов, которая подключена в проекте.
Смотрите также
- Выпуск и запись о выпуске — выпуск и запись о выпуске.
- Порядок подключения и Глобальные настройки — порядок подключения и глобальные настройки.
- Пакеты компонентов продуктов и Пакеты компонентов — пакеты продуктов и пакеты компонентов.
- Настройки: общий язык компонентов и Размер: одна лестница для всех компонентов — значения настроек и лестница размеров.
- События — события.
- Уровни готовности — уровни готовности.