Фоновые эффекты

Фоновый эффект — анимированный фон, который рисуется в одной области страницы: художественная половина страницы входа, фон крупного блока, группа карточек, сквозь которые видна одна сцена. Эффект состоит из манифеста effect.json и одного модуля JavaScript. По манифесту продукт показывает эффект в списке, описывает его и строит форму настроек, не запуская его код. Правила эффекта задаёт стандарт simai.effect 1.1.0; Framework даёт схему манифеста, SF.Effects в ядре и набор проверок, готовые эффекты лежат в каталоге эффектов, а установка, включение и хранение настроек остаются за продуктом.

Манифест

{
  "schema": "simai.effect",
  "schema_version": 1,
  "id": "sample-dots",
  "version": "1.0.0",
  "label": {"ru": "Точки", "en": "Dots"},
  "entry": "sample-dots.js",
  "surfaces": ["sign-in", "hero"],
  "schemes": ["dark", "light"],
  "capabilities": ["windows"],
  "settings": [
    {"key": "count", "type": "integer", "label": {"ru": "Сколько точек"}, "default": 24, "min": 4, "max": 200},
    {"key": "speed", "type": "number", "label": {"ru": "Скорость"}, "default": 1, "min": 0.25, "max": 4, "step": 0.25},
    {"key": "shape", "type": "choice", "label": {"ru": "Форма"}, "default": "round",
      "options": [{"value": "round", "label": {"ru": "Круг"}}, {"value": "square", "label": {"ru": "Квадрат"}}]}
  ],
  "needs": {"network": false}
}

Других полей нет. Схема манифеста — версия 1.2.0, она лежит в поставке ui (distr/core/contracts/effect.v1.schema.json); манифест без schemes, pair и capabilities проходит её так же.

Пара

pair называет эффект другой схемы, который играет ту же роль. Его называет только эффект с одной схемой. Пара проверяется так же строго, как сам эффект:

• идентификатор ищется в том же каталоге и сверяется с отпечатком SHA-256 из его индекса до запуска;
• адрес https://…/effect.json вне закреплённого каталога — чужой эффект: он работает только в изолированном фрейме. Такого исполнителя Framework не поставляет, поэтому чужую пару SF.Effects не запускает: размещение скрывается с причиной foreign-pair-needs-sandbox и отправляет sf-effect-refused.

Доверенный эффект никогда не подтягивает недоверенную пару на страницу.

Настройки

У каждой настройки есть key (латинская буква, затем до 40 букв и цифр), type, label и default, который сам проходит проверку настройки. Необязательные поля — hint, unit и step.

Значение вне границ не подрезается, а считается неверным. Хранимые значения приводятся только там, где смысл очевиден: числовая строка для числа, "1", "0", "true", "false" для логического значения. Форму настроек продукт строит из settings своим представлением записи, а не пишет руками для каждого эффекта.

Схемы, цвет и контраст

Каждая схема эффекта нарисована для своего фона: тёмная — для тёмного, светлая — для светлого, а не перевёрнутая картинка другой схемы. Область, в которой эффект нарисован, получает класс этой схемы (theme-dark или theme-light), какой бы ни была тема страницы, поэтому текст и элементы управления над эффектом берут роли его темы. Класс темы область не красит: своей области задайте фон и цвет текста, например bg-surface color-on-surface (Участок другой темы).

Эффект рисует тонами палитр — --sf-<палитра>-<тон>, например --sf-primary-40 или --sf-neutral-98. Тоны одинаковы во всех темах и несут цвета проекта; тон для каждой схемы эффект выбирает сам. Ролями темы (--sf-surface, --sf-on-surface и другими) эффект не рисует: они меняются под ним вместе с темой области и на странице без таблиц Framework их нет. Тон читают через короткоживущий пробный элемент, чтобы цепочки var() и light-dark() разрешились, держат запасной цвет для страницы без таблиц Framework и читают тоны заново, когда меняется тема или цвета проекта (Цветовые примитивы и палитры).

Контраст текста над эффектом при настройках по умолчанию, на самом ярком кадре:

Приглушённый текст над эффектом поэтому только крупный — 24px, или 18.66px жирным, как WCAG допускает при 3:1. Мелкий текст над эффектом берёт основную роль. Кто поднял настройку выше значения по умолчанию, отвечает за получившийся контраст: обещание эффекта — его значения по умолчанию.

При настройках по умолчанию эффект рисует одно и то же: без Math.random без затравки. Случайность берут с постоянной затравкой или с затравкой из настроек, иначе проверки контраста и схемы набора дают разный результат от запуска к запуску.

Модуль эффекта

Модуль экспортирует одну функцию mount(host, settings, context) и возвращает объект с методами update(settings, context), pause(), resume() и destroy(). context содержит:

export function mount(host, settings, context) {
  const canvas = document.createElement('canvas');
  canvas.style.cssText = 'position:absolute;inset:0;inline-size:100%;block-size:100%';
  host.append(canvas);
  const ratio = Math.min(globalThis.devicePixelRatio || 1, 2);
  let values = settings;
  let scheme = context.scheme;
  let frame = 0;
  let running = false;
  const paint = () => { /* рисует кадр по values тонами схемы scheme с плотностью ratio */ };
  const tick = () => { paint(); frame = requestAnimationFrame(tick); };
  const start = () => { if (running || context.reducedMotion) return; running = true; frame = requestAnimationFrame(tick); };
  const stop = () => { running = false; cancelAnimationFrame(frame); };
  paint();
  start();
  return {
    update(next, nextContext) { values = next; scheme = nextContext.scheme; paint(); },
    pause: stop,
    resume: start,
    destroy() { stop(); canvas.remove(); }
  };
}

Эффект рисует только внутри host — добавляет туда свой canvas или video — и не трогает остальную страницу. Плотность пикселей он ограничивает двумя. При reducedMotion он рисует один неподвижный кадр и больше кадров не просит. Новые настройки и смена схемы приходят в update(settings, context) без повторного монтирования, а после destroy не остаётся ни узлов, ни кадров, ни наблюдателей, ни слушателей.

Каталог эффектов

Официальный каталог — effects.simai.io: галерея эффектов, их схем и настроек. Исходники и файлы каталога лежат в репозитории simai/ui-effects; страница подключает каталог по адресу с коммитом, а не с веткой. Выпуск каталога v2.0.0 — коммит d955c66ae024552f5e2f98c418e2923959484877, 17 эффектов без пар:

https://cdn.jsdelivr.net/gh/simai/ui-effects@d955c66ae024552f5e2f98c418e2923959484877/

Все 17 объявляют capabilities: ["windows"]. Каталог подключают до core.js:

<script>
  window.SF_BOOT_CONFIG = {
    effects: {
      catalogue: 'https://cdn.jsdelivr.net/gh/simai/ui-effects@d955c66ae024552f5e2f98c418e2923959484877/',
      indexSha256: '9a594fa4d9bb452419aaafbbd4af72443034ce5b1c71d6805be95b1fb868e01e',
    },
  };
</script>
<script src="…/core/js/core.js"></script>

Каждый файл эффекта — effect.json, модуль и стили из styles — загружается один раз, и его SHA-256 сверяется с индексом каталога (effects[].files[].sha256) до того, как что-то запустится. Модуль выполняется из проверенных байтов, повторно он не загружается. Проверке нужен crypto.subtle, то есть защищённый контекст: страница по https или localhost. Эффект по адресу вне закреплённого каталога — чужой: он работает только в изолированном фрейме, и SF.Effects его не запускает, а отклоняет с причиной foreign-effect-needs-sandbox.

Подключение разметкой

Область с атрибутом data-sf-effect получает эффект из каталога после загрузки страницы. Когда каталог задан, ядро так же находит области, добавленные позже, и убирает размещение, когда область уходит со страницы.

Эффект рисует в слое [data-sf-effect-layer], который ядро ставит первым потомком области. Статичная область получает position: relative, и каждая — isolation: isolate, поэтому слой остаётся под содержимым. Состояние размещения область показывает атрибутами:

<section data-sf-effect="constellation-net" data-sf-effect-settings='{"speed": 80}' class="p-4 radius-4 bg-surface color-on-surface" aria-labelledby="effect-title">
  <h2 id="effect-title" class="m-0 text-4">Вход в кабинет</h2>
  <p>Фон рисует эффект из каталога. Мелкий текст над ним — в основной роли.</p>
</section>
<p id="effect-state" role="status" class="text-1/2 color-on-surface-variant">Эффект загружается…</p>

// Каталог закреплён коммитом в адресе; объявить его нужно до core.js.
window.SF_BOOT_CONFIG = Object.assign({}, window.SF_BOOT_CONFIG, {
  effects: {catalogue: 'https://cdn.jsdelivr.net/gh/simai/ui-effects@d955c66ae024552f5e2f98c418e2923959484877/'},
});

// Состояние размещения видно в атрибутах области.
const area = document.querySelector('[data-sf-effect]');
const state = document.querySelector('#effect-state');
const show = () => {
  const value = area.getAttribute('data-sf-effect-state');
  const reason = area.getAttribute('data-sf-effect-reason');
  if (value) state.textContent = `data-sf-effect-state="${value}"${reason ? `, data-sf-effect-reason="${reason}"` : ''}`;
};
new MutationObserver(show).observe(area, {attributes: true, attributeFilter: ['data-sf-effect-state', 'data-sf-effect-reason']});

Режим темы

У размещения есть режим темы: auto — как у страницы, dark — всегда тёмная, light — всегда светлая. Что рисовать, решается по порядку:

1. сам эффект, если он рисует нужную схему;
2. его пара, если она рисует нужную схему;
3. в auto эффект только с тёмной схемой остаётся тёмным и на светлой странице;
4. иначе эффект скрыт: область получает класс нужной темы и показывает обычную поверхность. Эффект только со светлой схемой на тёмной цели не показывается — читатель выбрал тёмную тему, чтобы не слепило.

В auto размещение следует за страницей: за классом темы на <html>, за событием sf-theme-change и за prefers-color-scheme. Тот же эффект переключает схему через update без повторного монтирования. Редактор предлагает только те постоянные режимы, которые эффект или его пара умеют рисовать (allowedModes).

<div class="flex flex-wrap gap-4">
  <section data-sf-effect="halftone-tide" data-sf-effect-theme="dark" class="flex-1 p-4 radius-4 bg-surface color-on-surface">
    <h3 class="m-0 text-3">dark</h3>
    <p data-effect-state>…</p>
  </section>
  <section data-sf-effect="halftone-tide" data-sf-effect-theme="light" class="flex-1 p-4 radius-4 bg-surface color-on-surface">
    <h3 class="m-0 text-3">light</h3>
    <p data-effect-state>…</p>
  </section>
  <section data-sf-effect="aurora-curtain" data-sf-effect-theme="light" class="flex-1 p-4 radius-4 bg-surface color-on-surface">
    <h3 class="m-0 text-3">light, только тёмная схема</h3>
    <p data-effect-state>…</p>
  </section>
</div>

window.SF_BOOT_CONFIG = Object.assign({}, window.SF_BOOT_CONFIG, {
  effects: {catalogue: 'https://cdn.jsdelivr.net/gh/simai/ui-effects@d955c66ae024552f5e2f98c418e2923959484877/'},
});

// Каждая область пишет своё состояние и причину, если эффект скрыт.
for (const area of document.querySelectorAll('[data-sf-effect]')) {
  const state = area.querySelector('[data-effect-state]');
  const show = () => {
    const value = area.getAttribute('data-sf-effect-state');
    const reason = area.getAttribute('data-sf-effect-reason');
    if (value) state.textContent = reason ? `${value}: ${reason}` : value;
  };
  new MutationObserver(show).observe(area, {attributes: true, attributeFilter: ['data-sf-effect-state', 'data-sf-effect-reason']});
}

Режим окон

В режиме окон один эффект рисуется один раз — в слое размером с группу — и виден только сквозь карточки-окна, поэтому сцена непрерывна от окна к окну. Маску окон ядро перестраивает при изменении размеров, прокрутке и при добавлении, удалении или пометке карточек. Только окна получают тему эффекта; остальные карточки сохраняют тему страницы. Свой фон окна не рисуют. Режим доступен только эффекту с capabilities: ["windows"]: разметка с другим эффектом получает refused и причину windows-not-declared.

<div data-sf-effect-windows="aurora-curtain" data-sf-effect-theme="dark" class="flex flex-wrap gap-4 p-4 radius-4">
  <article data-sf-effect-window class="flex-1 p-3 radius-3 color-on-surface">
    <h3 class="m-0 text-3">Окно</h3>
    <p>Сцена видна сквозь карточку.</p>
  </article>
  <article class="flex-1 p-3 radius-3 bg-surface-container color-on-surface">
    <h3 class="m-0 text-3">Обычная карточка</h3>
    <p>Без атрибута окна: своя поверхность и тема страницы.</p>
  </article>
  <article data-sf-effect-window class="flex-1 p-3 radius-3 color-on-surface">
    <h3 class="m-0 text-3">Окно</h3>
    <p>Та же сцена, без шва между окнами.</p>
  </article>
</div>

window.SF_BOOT_CONFIG = Object.assign({}, window.SF_BOOT_CONFIG, {
  effects: {catalogue: 'https://cdn.jsdelivr.net/gh/simai/ui-effects@d955c66ae024552f5e2f98c418e2923959484877/'},
});

Подключение из скрипта

SF.Effects доступен сразу после выполнения core.js:

loadEffect и placeEffect

loadEffect(reference, {catalogue}) принимает идентификатор эффекта или адрес его effect.json под адресом каталога; catalogue по умолчанию берётся из SF_BOOT_CONFIG.effects.catalogue. Он возвращает обещание {id, url, manifest, module, styles}, а отказ — ошибку с полем reason:

placeEffect(element, {effect, settings, themeMode, windows, catalogue, locale}) загружает эффект, а если его пара — идентификатор каталога, то и пару, и рисует его в слое под содержимым области. С windows (true или селектор окон) он рисует эффект за окнами группы. Возвращает объект размещения или null, если эффект отклонён: тогда у области data-sf-effect-state="refused" и data-sf-effect-reason. Эффект без capabilities: ["windows"] в режиме окон отклоняется с причиной windows-not-declared.

<section id="effect-area" class="p-4 radius-4 bg-surface color-on-surface" aria-labelledby="catalogue-title">
  <h2 id="catalogue-title" class="m-0 text-4">Эффект из скрипта</h2>
  <p>Каждый файл сверен с индексом каталога до запуска.</p>
</section>
<pre id="effect-log" class="text-1/2"></pre>

// Каталог и отпечаток его индекса: индекс тоже проверяется.
window.SF_BOOT_CONFIG = Object.assign({}, window.SF_BOOT_CONFIG, {
  effects: {
    catalogue: 'https://cdn.jsdelivr.net/gh/simai/ui-effects@d955c66ae024552f5e2f98c418e2923959484877/',
    indexSha256: '9a594fa4d9bb452419aaafbbd4af72443034ce5b1c71d6805be95b1fb868e01e',
  },
});

const log = document.querySelector('#effect-log');
const write = (line) => { log.textContent += `${line}\n`; };
// SF.Effects появляется, когда выполнен core.js.
const effects = () => new Promise((resolve) => {
  const check = () => (window.SF?.Effects ? resolve(window.SF.Effects) : setTimeout(check, 50));
  check();
});

async function start() {
  const Effects = await effects();
  const effect = await Effects.loadEffect('contour-map');
  write(`loadEffect: ${effect.id}, схемы ${Effects.effectSchemes(effect.manifest).join(', ')}`);
  write(`allowedModes: ${Effects.allowedModes(effect.manifest).join(', ')}`);

  const area = document.querySelector('#effect-area');
  const handle = await Effects.placeEffect(area, {effect: 'contour-map', settings: {}, themeMode: 'auto'});
  write(handle ? `placeEffect: ${handle.effect}, схема ${handle.scheme}` : `placeEffect: ${area.getAttribute('data-sf-effect-reason')}`);

  // Адрес вне каталога — чужой эффект: он не запускается.
  try {
    await Effects.loadEffect('https://example.com/effects/other/effect.json');
  } catch (error) {
    write(`чужой адрес: ${error.reason}`);
  }
}
start().catch((error) => write(`ошибка: ${error.reason ?? error.message}`));

mountEffect и mountWindows

mountEffect и mountWindows монтируют модуль, который продукт уже загрузил и проверил сам: встроенный эффект продукта.

const manifest = await fetch('/effects/sample-dots/effect.json').then((response) => response.json());
const module = await import('/effects/sample-dots/sample-dots.js');
const host = document.querySelector('.sign-in-art');

const effect = SF.Effects.mountEffect(host, {manifest, module, stored: savedValues, scheme: 'dark'});
effect.update(newValues, {scheme: 'light'});

const placement = SF.Effects.mountEffect(host, {manifest, module, stored: savedValues, themeMode: 'auto', area: section});
placement.update(savedValues, {themeMode: 'dark'});
placement.destroy();

Объект размещения, кроме update, pause, resume и destroy, отвечает полями effect ('self', 'pair' или null, если эффект скрыт), resolution (ответ resolveTheme), scheme (нарисованная схема или null) и themeMode. После destroy область возвращает свои классы темы. Пара, заданная адресом, не запускается, даже если её модуль передан: размещение скрывается с причиной foreign-pair-needs-sandbox.

mountWindows(group, {manifest, module, stored, pair, locale, themeMode, windows}) рисует эффект за окнами группы; windows — селектор окон, по умолчанию [data-sf-effect-window], themeMode по умолчанию auto. Метод refresh() перестраивает маску, если окна изменились не через разметку, например классом по своему селектору. Эффект без capabilities: ["windows"] mountWindows не принимает и выбрасывает TypeError.

mountEffect выбрасывает TypeError, если манифест неверен или модуль не экспортирует mount. Каждое монтирование:

• ставит элементу, в котором рисует эффект (host; у placeEffect и разметки — слою), aria-hidden="true", pointer-events: none и data-sf-effect с именем эффекта — фон не читается экранным диктором и не мешает указателю;
• передаёт эффекту настройки через effectSettings, поэтому неверное или отсутствующее значение заменяется значением по умолчанию;
• вызывает pause(), пока вкладка скрыта или область вне экрана, и resume(), когда она снова видна;
• монтирует эффект заново, когда человек включает или выключает уменьшение движения, — неподвижный кадр появляется сразу;
• после destroy() очищает этот элемент и снимает свои слушатели. Методы можно вызывать в любом порядке и повторно.

События

Ошибку монтирования ловит продукт: он показывает вместо эффекта свой эффект по умолчанию. Эффект, который продукт не поставляет и не проверял сам, запускается только во фрейме с sandbox без allow-same-origin, со строгой политикой безопасности содержимого и получает проверенные настройки сообщением.

Набор проверок

Перед тем как показать эффект в списке, продукт прогоняет на нём набор проверок — скрипт scripts/effect-kit.mjs из исходников Framework (simai/ui-source, ревизия выпуска). Скрипту нужны Node.js и Playwright с установленным Chromium. Он принимает папку эффекта (effect.json и файлы, которые тот называет) и корень собранного Framework — выход sf-build framework --out (Сборка пакета: sf-build): скрипт берёт из него core/core/js/core.js. Подойдёт и папка, в которой core/core — это distr/core поставки ui того же выпуска.

node scripts/effect-kit.mjs ./effects/sample-dots ./framework-build

Скрипт печатает каждую проверку с результатом (ok или FAIL и подробности) и завершается с кодом 1, если хотя бы одна не прошла. Одиннадцать проверок проходит каждый эффект:

Остальные проверки идут по тому, что объявляет манифест:

В исходниках лежат образцы: tests/fixtures/effect-sample проходит все проверки, tests/fixtures/effect-schemes — эффект с двумя схемами и режимом окон, а tests/fixtures/effect-bad нарушает четыре правила — ходит в сеть, рисует при уменьшении движения и в скрытой вкладке, продолжает просить кадры после destroy — и не проходит no-network, still-motion, hidden-tab и cleanup.

Требования стандарта

Стандарт simai.effect 1.1.0 — двадцать требований, все обязательные.

Стандарт опирается на правила взаимодействия компонентов в части движения и изоляции сбоев. Проверка ручная, а набор проверок меряет то, что можно измерить в браузере.

Смотрите также

• Карта стандартов — место стандарта среди остальных и машиночитаемые копии.
• Правила взаимодействия компонентов — уменьшение движения и изоляция сбоев.
• Темы — классы theme-dark и theme-light и участок другой темы.
• Цветовые примитивы и палитры — тоны, которыми рисует эффект.
• Движение — системная настройка уменьшения движения.
• Сборка пакета: sf-build — как получить собранный Framework для набора проверок.