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

Фоновый эффект — анимация под текстом первого экрана: звёздное небо, сетка, волны и другие. Эффект заменяет фоновую картинку, поэтому на других языках сайта ничего перерисовывать не нужно. Текст поверх эффекта остаётся обычным текстом страницы: его можно выделить, перевести и найти поиском.

Эффекты рисует SIMAI Framework, а берёт их из каталога эффектов SIMAI. Docara только записывает в Hero, какой эффект нужен, и проверяет настройки при сборке.

Как подключить эффект

1. Подключите каталог

Каталог задаётся один раз для всего сайта в docara.json:

{
  "effects": {
    "catalogue": "https://cdn.jsdelivr.net/gh/simai/ui-effects@ad508268dbf322ecaaf2820a06da8dc8285d4ec1/"
  }
}

catalogue — адрес каталога. Закрепляйте его на конкретном коммите, а не на ветке (@main): иначе эффекты на сайте могут измениться без вашего ведома. Этот сайт подключает каталог по адресу выше.

Ещё два поля необязательны:

2. Выберите эффект

Все эффекты каталога, их вид и настройки собраны на сайте effects.simai.io. Там же можно подобрать настройки и скопировать их. Docara не скачивает каталог во время сборки, поэтому полный список эффектов ведётся на этом сайте, а не здесь.

Запомните идентификатор эффекта: строчные латинские буквы, цифры и дефис, например constellation-net или aurora-curtain.

3. Укажите эффект в Hero

:::hero {variant=centered padding=2xl effect=constellation-net}
# Документация, которую удобно читать

Эффект рисуется под текстом и не мешает читать.

[Открыть быстрый старт](/ru/start/)
:::

Так устроен первый экран главной страницы этого сайта. Эффект сочетается с любым вариантом Hero, но не с фоновой картинкой: укажите либо effect, либо media=background.

Параметры

:::hero {variant=centered effect=aurora-curtain effect_theme=dark effect_settings='{"speed": 80}'}
# Тёмный первый экран

Эффект всегда рисуется в тёмной версии, а текст становится светлым.
:::

Тема эффекта

С effect_theme=auto эффект следует теме страницы: читатель переключил тему — эффект тоже сменился. С dark или light эффект всегда в одной версии, и текст Hero подстраивается под неё. Пока эффект загружается, Hero уже имеет фон и цвет текста этой темы, поэтому текст читается сразу.

Если у эффекта нет нужной версии, например он умеет только тёмную, а страница светлая, эффект не показывается, и Hero выглядит как без эффекта.

Пауза и уменьшение движения

Пока эффект движется, в правом нижнем углу Hero (на языках с письмом справа налево — в левом) есть кнопка «Остановить фоновую анимацию». Она не закрывает текст и картинку даже на телефоне. Повторное нажатие снова запускает эффект. Выбор запоминается в браузере читателя для всего сайта.

Кнопка помещается в нижний отступ Hero. При padding=2xl высота Hero не меняется. При lg и xl нижний отступ Hero с эффектом становится чуть больше: 52 px на узком экране и 56 px от 960 px.

Если в системе читателя включено уменьшение движения, эффект показывает один неподвижный кадр, а кнопка не появляется.

Подписи кнопки берутся из строк effects.pause и effects.play файла lang.json. Для русского и английского они встроены; для другого языка задайте их, как описано в разделе Языковые пакеты.

Где эффект не нарисуется

Сайт с эффектом остаётся статическим, но эффект загружается из каталога в браузере читателя. Эффект не появится, и Hero будет выглядеть как без него, если:

• браузер не может скачать файлы каталога, например читатель без интернета;
• файл эффекта не совпадает с контрольной суммой в списке каталога;
• у эффекта нет версии для нужной темы;
• сайт собран с версией SIMAI Framework без поддержки эффектов (раньше ui-08c07b3e938a). Docara поставляется с подходящей версией.

Почему эффект не нарисовался, видно в инструментах разработчика браузера: у секции Hero атрибут data-sf-effect-state равен refused или failed, а в data-sf-effect-reason записана причина, например fetch-failed или integrity.

Content-Security-Policy

Docara не задаёт заголовок Content-Security-Policy. Если ваш хостинг его добавляет, разрешите в нём то, что нужно эффекту:

Без этих разрешений браузер заблокирует эффект, а Hero останется без него.

Ошибки сборки

Сборка останавливается, если эффект указан неверно. Причина и способ исправления каждой ошибки — в справочнике: ошибки страниц и ошибки настроек сайта.