Подключение к проекту

Подключение — это несколько тегов в шаблоне страницы и глобальные настройки до загрузки Core. Здесь — порядок подключения, настройки и граница между Framework и компонентами проекта.

Подключение к проекту

Что лежит в поставке

Внутри distr/ пять основных папок:

distr/
├── core/       ядро: core.css, core.js и его части, общая основа
│               Smart-компонентов smart-base.js, шрифты, контракты
├── utility/    модули утилит, по папке на модуль и контрольную точку
├── component/  обычные компоненты, по папке на компонент
├── rule/       реестр правил загрузки (rule.json)
└── smart/      Smart-компоненты, по папке на компонент: скрипт js/<имя>.js
                и манифест smart.manifest.json

У каждого стиля и скрипта есть сжатая форма рядом с читаемой: core/css/core.min.css рядом с core/css/core.css, core/js/core.min.js рядом с core/js/core.js и так же у модулей (см. Сжатые файлы). Дальше в тексте core.css и core.js означают любую из двух форм.

Поставку выпуска берут из репозитория simai/ui по полному коммиту выпуска и сверяют с контрольной суммой из записи о выпуске (см. Выпуск и запись о выпуске). Для подключения с CDN тот же выпуск издан пакетом npm @simai-studio/ui: в нём ядро целиком, а у модулей утилит, компонентов и Smart-компонентов только сжатая форма (см. Пакет npm).

Собранный пакет продукта устроен так же, как distr/smart/: по папке на компонент и файл правил загрузки rule.js (см. Пакеты компонентов).

Копировать нужно папку целиком. Loader вычисляет адреса файлов по этой структуре, поэтому выбранные вручную отдельные файлы работать не будут.

Порядок подключения

На странице нужны три вещи, и порядок важен:

1. стиль ядра core.min.css;
2. глобальные настройки — до ядра;
3. скрипт ядра core.min.js.

<link rel="stylesheet" href="/assets/simai-framework/ui/distr/core/css/core.min.css">
<script>
  window.sfPath = '/assets/simai-framework/ui/distr/';
</script>
<script src="/assets/simai-framework/ui/distr/core/js/core.min.js"></script>

Почему настройки стоят до core.js: ядро читает их в момент запуска. Если sfPath задан позже, ядро к этому моменту уже выбрало другой адрес.

core.css подключается отдельно: core.js его не загружает. Без него токены и базовые стили не появятся, хотя модули утилит и компонентов загрузятся.

core.css сам оформляет body: фон --sf-surface-0, цвет текста --sf-on-surface и текст по умолчанию — шрифт, кегль, высоту строки (слой sf.base, см. Каскадные слои). Странице не нужно задавать их самой; свой фон или цвет body проект пишет в своём слое.

Остальные CSS и JavaScript Framework вручную не подключают — их подключит Loader.

Глобальные настройки

Три тонкости подключения.

sfSmartPath обычно не задают. Loader ищет Smart-компоненты в <sfPath>/smart/, а в поставке ui они лежат именно там. Переменная нужна, только если проект отдаёт Smart-компоненты из другого места; пустое значение считается незаданным. Компоненты пакетов этой переменной не касаются: их адрес задаёт объявление пакета (см. Пакеты компонентов).

Части ядра берутся оттуда, откуда загружен core.js. Сам core.js небольшой: свои части (правила, Loader, общую основу Smart-компонентов) он догружает из своей же папки и в той же форме, что и себя: core.min.js — сжатые части, core.js — читаемые. Модули утилит и компонентов Loader берёт из sfPath. Если core.js и sfPath указывают на разные поставки, на странице окажутся две разные версии Framework сразу. Поэтому оба адреса всегда ведут в одну и ту же папку distr/.

Метки кеша для своей копии равны идентификатору выпуска. cacheVersion и pluginListVersion — любые непустые строки: Loader сравнивает их с сохранёнными в localStorage как есть (см. Кеш и версии адресов). Для своей копии поставки обеим меткам дают идентификатор выпуска, например ui-106d5901f8c3. При переходе на другой выпуск метки меняются вместе с ним: Loader очищает сохранённые списки модулей, а адреса модулей получают новый параметр sf_v.

<script>
  window.sfPath = '/assets/simai-framework/ui/distr/';
  window.SF_BOOT_CONFIG = {
    cacheVersion: 'ui-106d5901f8c3',
    pluginListVersion: 'ui-106d5901f8c3',
  };
</script>

Если sfPath не задан, ядро берёт файлы с CDN из ветки main репозитория simai/ui и пишет в консоль предупреждение о незакреплённой ветке. Оно начинается так:

SIMAI Framework: window.sfPath is not set, so the runtime is loading from …

Ветка main — не выпуск, а репозиторий simai/ui слишком велик для отдачи с jsDelivr из GitHub: такой адрес часть файлов не отдаёт. Увидели предупреждение — задайте sfPath на свою копию distr/ или на адрес пакета npm с версией выпуска (см. CDN или своя копия); адрес из текста предупреждения для этого не подходит. Это касается и примеров во встроенных фреймах: у каждого документа свой sfPath.

Относительный sfPath вычисляется от базового адреса документа (с учётом тега <base>), а не от адреса скрипта.

CDN или своя копия

Своя копия — весь каталог distr/ одного выпуска в публичной папке проекта, например public/assets/simai-framework/ui/distr/. Его не смешивают с файлами другого выпуска и не правят.

Своя копия получается из репозитория simai/ui по полному коммиту выпуска. Контрольную сумму архива сверяют с полем runtime_sources.core.archive_sha256 записи о выпуске (см. Выпуск и запись о выпуске), и только после этого его распаковывают в публичную папку проекта. Запись о выпуске лежит в ветке main репозитория, а не в самом коммите выпуска; та же сумма есть в поле runtime.ui.sha256 файла /ai/framework-lock.json этого сайта:

git clone https://github.com/simai/ui.git simai-ui
git -C simai-ui archive --format=tar 106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4 distr | shasum -a 256
# равно runtime_sources.core.archive_sha256 в записи simai-ui/contracts/releases/ui-106d5901f8c3.lock.json
# и полю runtime.ui.sha256 в /ai/framework-lock.json этого сайта
mkdir -p public/assets/simai-framework/ui
git -C simai-ui archive --format=tar 106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4 distr | tar -x -C public/assets/simai-framework/ui

Каталог появляется как public/assets/simai-framework/ui/distr/.

При подключении с CDN страница берёт файлы из пакета npm @simai-studio/ui, и версия пакета стоит во всех трёх адресах сразу:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@simai-studio/ui@5.20261019.1559/distr/core/css/core.css">
<script>window.sfPath = 'https://cdn.jsdelivr.net/npm/@simai-studio/ui@5.20261019.1559/distr/';</script>
<script src="https://cdn.jsdelivr.net/npm/@simai-studio/ui@5.20261019.1559/distr/core/js/core.js"></script>

5.20261019.1559 — версия пакета для выпуска ui-106d5901f8c3. Версию другого выпуска и правило, по которому она получается из коммита выпуска, — см. Пакет npm. Тот же пакет отдаёт unpkg: адреса вида https://unpkg.com/@simai-studio/ui@5.20261019.1559/distr/ работают так же. Готовая страница — в быстром старте (см. Страница на Core).

В пакете npm у модулей утилит, компонентов и Smart-компонентов есть только сжатая форма, а копий .gz нет. Поэтому с CDN ядро подключают в любой форме, но режим отладки с читаемыми модулями (?sf-debug, data-sf-debug, minified: false) работает только со своей копией поставки: с адреса пакета читаемые модули не загрузятся (см. Сжатые файлы). Пакет продукта приходит в поставке продукта и объявляется пакетом (см. Пакеты компонентов).

В статическом сайте эти теги стоят в HTML, в веб-приложении — в общем шаблоне страниц. Серверная обёртка для Framework не нужна.

Сервер, который отдаёт свою копию, может кешировать файлы поставки надолго: адреса модулей Loader дополняет меткой версии (см. Кеш и версии адресов). Сам HTML-документ, который выбирает поставку, кешировать надолго нельзя.

Проверка подключения

1. Во вкладке Network нет ответов 404, все файлы Framework идут с закреплённого адреса.
2. В Console нет ошибок загрузки и предупреждения о незаданном sfPath. При подключении с CDN все адреса Framework содержат одну и ту же версию пакета @simai-studio/ui.
3. window.SF?.Loader возвращает загрузчик.
4. Основные страницы просмотрены на мобильной и настольной ширине, в светлой и тёмной теме.
5. Идентификатор выпуска (и квитанция каждого подключённого пакета) записан рядом с остальными зависимостями проекта.

Свои компоненты проекта: где граница

Проект может создавать собственные компоненты поверх Framework. Граница проходит так: Framework даёт основу, проект сам отвечает за свои файлы.

Loader знает только правила Framework и объявленных пакетов компонентов и ищет файлы только внутри поставки и каталогов этих пакетов (см. Пакеты компонентов). Свой компонент проекта он не найдёт и не загрузит — и не должен: класть файлы проекта в distr/ нельзя (см. Источник и готовые файлы).

Что проекту доступно:

• Свой Smart-компонент. Скрипт проекта дожидается sf-loader-init, вызывает SF.loadSmartBase(), наследует свой класс от SF.smart.SfBaseElement и регистрирует его со своим тегом, например ProjectGreeting.define('project-greeting'). Скрипт подключает сам проект. Тег начинается с собственного префикса проекта, а не с sf-: префикс sf- носят компоненты Framework, и тег проекта с этим префиксом может совпасть с новым компонентом Framework. SF.whenDefined() и SF.create() дописывают sf- к имени, которого нет в правилах пакетов (см. Пакеты компонентов), поэтому готовность своего тега ждут через customElements.whenDefined('project-greeting'). Если компонент должен загружаться Loader по тегу, проект оформляет его пакетом компонентов (см. Пакеты компонентов продуктов).
• Внешний шаблон Smart-компонента Framework. Если нужен другой вид без копирования поведения, проект кладёт шаблон в свою папку и указывает её в window.SF_SMART_TEMPLATE_PATH. Тогда <sf-button template="compact"> загрузит <папка>/button/compact/index.js. Шаблон — доверенный код проекта.
• Обычный компонент на классах Framework. Разметка из утилит и классов компонентов: Loader подключит всё, что в ней использовано.

Подробно о создании Smart-компонентов и шаблонов — см. Минимальный компонент, Локальные компоненты проекта и Шаблоны.