К содержанию

Навигация

Главное

Содержание

Генератор темы

<sf-theme-generator> строит тему из одного цвета. Человек выбирает основной цвет, а компонент строит восемь тональных палитр Framework — основную, вторичную, дополнительную, нейтральную, ошибку, предупреждение, успех и информацию: 128 тонов --sf-<палитра>-<тон> и 98 полупрозрачных ступеней --sf-<палитра>-<тон>--alfa-<ступень>, из которых читаются семантические токены. Ниже выбора показан предпросмотр палитр. Берите его в настройках сайта или документации, где владелец выбирает фирменный цвет.

Пример

Применение

Цвет, тон и насыщенность

value — основной цвет в виде #rgb или #rrggbb. Пустое значение — цвет Framework #005bbe и его собственная тема. Цвет компонент читает в модели HCT как тон (hue, от 0 до 360) и насыщенность (chroma, от 0 до 150): по ним строятся все восемь палитр (см. Как строятся палитры из одного цвета).

hue и chroma задают поля «Тонкая настройка». Заданные, они важнее прочтения цвета: хост, который хранит все три значения, получает обратно ту же тему. swatches — цвета продукта рядом с выбором, как у <sf-color>: #hex|Название, #hex. size — 1/2, 1 (по умолчанию) или 2.

Применение к странице или участку

Без apply компонент на странице ничего не меняет: он только сообщает о выборе. С apply он применяет тему при каждом изменении — пишет 226 переменных во встроенный стиль элемента target (CSS-селектор; по умолчанию корневой элемент документа). Предыдущее применение снимается перед следующим и при удалении компонента.

Семантические токены (--sf-primary и другие) объявлены на классах theme-light и theme-dark. Поэтому участок страницы, к которому применяется тема, тоже несёт такой класс, как в примере: без него на участке сменятся только примитивы, а роли останутся прочитанными на корне.

Тема пишет и тона, и полупрозрачные ступени тонов (--sf-primary-50--alfa-12 и другие), из которых собраны заливки *-container и фоны наведения и выбора, поэтому тональные кнопки и заливки перекрашиваются вместе с основными.

Сохранение выбора и события

Компонент ничего не хранит: выбор хранит хост — в настройках сайта или документации. Он узнаёт о выборе событиями на самом элементе:

Событие Когда
sf-theme-generator-change выбор меняется: перетаскивание в палитре, образец цвета, число в поле
sf-theme-generator-apply выбор зафиксирован: change палитры, образец цвета, Enter или уход из поля, «Сбросить»

В detail обоих — value (пусто, пока действует цвет Framework), hue, chroma, theme (объект темы), variables (226 переменных) и css — правило под selector (по умолчанию :root). Сохраните css в CSS сайта — и тема будет на каждой странице без компонента.

Прежние имена sf-theme-change и sf-theme-apply компонент отправляет рядом с новыми для совместимости до 2026-12-01 (запись журнала event-theme-generator-names); в новом коде слушайте новые имена. sf-theme-change — ещё и событие Loader на window о смене светлой и тёмной темы (см. События загрузчика).

JavaScript
const generator = document.querySelector('sf-theme-generator');
generator.addEventListener('sf-theme-generator-apply', ({detail}) => {
  saveSiteSetting('theme', {value: detail.value, hue: detail.hue, chroma: detail.chroma, css: detail.css});
});

Методы: toCSS(selector) — правило темы под селектором, toJSON() — объект темы, reset() — вернуться к цвету Framework; свойство theme — текущий объект темы.

Расчёт без компонента

Расчёт — модуль ядра theme-palette, опубликованный как SF.ThemePalette. Он приходит на страницу вместе с кодом <sf-theme-generator>; на странице без этого элемента его нет. Сервер или сборка проекта вызывают те же функции из исходников Framework: файл src/core/js/theme-palette.js открытого репозитория simai/ui-source на коммите исходников выпуска (build_inputs.source.commit в записи выпуска). Модуль зависит только от файлов material-color-utilities, которые лежат рядом в src/core/js/vendor/, и в Node.js 20 импортируется напрямую:

JavaScript
import {themeFromColor, themeVariables} from './ui-source/src/core/js/theme-palette.js';

const variables = themeVariables(themeFromColor('#833ab6'));   // 226 пар {имя: значение}

Тот же расчёт без модуля описан в Как построить палитру.

Функция Что делает
themeFromColor(color, options) тема из цвета #rgb или #rrggbb
themeFromHct({hue, chroma}, options) тема из тона и насыщенности; options[палитра] — свои {hue, chroma} для палитры
colorToHct(color) как цвет читается: {hex, hue, chroma, tone}
themeVariables(theme) 226 переменных {имя: значение}: 128 тонов и 98 полупрозрачных ступеней
themeToCss(theme, selector) правило CSS с теми же 226 переменными под селектором, по умолчанию :root
applyTheme(theme, target) пишет переменные во встроенный стиль target и возвращает функцию, которая их снимает
JavaScript
const theme = SF.ThemePalette.themeFromColor('#2e7d32');
const css = SF.ThemePalette.themeToCss(theme, ':root');

themeToCss() возвращает правило без слоя. Оно сильнее слоёв Framework и работает как есть; по соглашению проекта его кладут в @layer project.

Тема всегда содержит все восемь палитр. Чтобы сменить только акцент, оставьте из themeVariables() переменные --sf-primary-* (и --sf-info-*, если info должен следовать за брендом), а остальные не записывайте:

JavaScript
const variables = SF.ThemePalette.themeVariables(theme);
const accent = Object.entries(variables).filter(([name]) => name.startsWith('--sf-primary-'));
const css = `@layer project { :root { ${accent.map(([name, value]) => `${name}: ${value};`).join(' ')} } }`;

Модель HCT — из пакета Google material-color-utilities 0.4.0 (лицензия Apache-2.0): нужные модули лежат в исходниках Framework без изменений и перечислены в уведомлениях о стороннем коде поставки.

Доступность

  • Компонент — группа (role="group"); назовите её aria-label, если рядом нет видимого заголовка.
  • В порядке Tab — выбор цвета, «Сбросить», раскрытие «Тонкая настройка» и два числовых поля; Enter в поле фиксирует тему.
  • Предпросмотр — именованная область из подписанных образцов: у каждого названы палитра, тон и значение.

Справочник API

Раздел собран из манифеста компонента выпуска ui-106d5901f8c3 и обновляется вместе с выпуском. Чтобы исправить описание, исправьте манифест.

Каждому атрибуту соответствует свойство элемента с тем же именем в camelCase: search-placeholder — searchPlaceholder. Свойство атрибута template называется templateName.
Тег <sf-theme-generator>
Назначение Тема из одного цвета: человек выбирает основной цвет (или тон и насыщенность генератора), а компонент строит восемь тональных палитр Framework — 128 примитивов, из которых читаются все семантические токены, и 98 полупрозрачных ступеней, которые ядро выводит из них, — с предпросмотром, событиями с CSS и применением к странице по желанию.
Контракт smart.theme-generator, версия 1.0.0
Поставка выпуск Framework ui-106d5901f8c3
Жизненный цикл экспериментальный: API может меняться между выпусками
Готовность работает в сценарии студии, продуктовой приёмки нет
Заготовка до прихода кода сервер пишет data-sf-skeleton="block"; своего скелетона при загрузке данных нет (Заготовка до прихода кода)

Атрибуты

  • value — string, по умолчанию пусто. Основной цвет, #rrggbb. Пусто — цвет Framework (#005bbe) и собственная тема Framework.
  • hue — string, по умолчанию пусто. Тон генератора, от 0 до 360; важнее прочтения цвета, задаётся полями тонкой настройки. Пусто — берётся из цвета.
  • chroma — string, по умолчанию пусто. Насыщенность генератора, от 0 до 150; важнее прочтения цвета, задаётся полями тонкой настройки. Пусто — берётся из цвета.
  • size — string, по умолчанию 1, значения: 1/2, 1, 2.
  • swatches — string, по умолчанию пусто. Цвета продукта рядом с выбором, как у sf-color: '#hex|Название, #hex'.
  • apply — boolean, по умолчанию false. Применять тему к target встроенными переменными, сразу при каждом изменении; предыдущее применение снимается перед следующим и при удалении элемента. Без атрибута страница не меняется.
  • target — string, по умолчанию пусто. Селектор CSS элемента, к которому применяется тема; пусто — корневой элемент документа. Цель, отличная от корня, несёт класс темы (theme-light или theme-dark): на нём объявлены семантические токены, и без него на цели сменятся только примитивы.
  • selector — string, по умолчанию :root. Селектор правила в css событий и в toCSS().
  • root-class — string, по умолчанию пусто.
  • template — string, по умолчанию default.

Методы

  • toCSS(selector?: string) — возвращает string. Тема одним правилом CSS из 128 примитивов и 98 полупрозрачных ступеней под переданным селектором или под атрибутом selector.
  • toJSON() — возвращает object. Объект темы (simai.framework.theme с schema_version: 1): тон и насыщенность источника и у каждой палитры её тон, насыщенность и тона.
  • reset() — возвращает object. Возвращает цвет Framework; отправляет sf-theme-generator-change и sf-theme-generator-apply (и их прежние имена до 2026-12-01).

События

Все события приходят на сам элемент и всплывают. Общие события базового элемента перечислены в главе Жизненный цикл → Этапы.

  • sf-theme-generator-change — detail: { value?: string, hue?: number, chroma?: number, theme?: object, variables?: object, css?: string }. Выбор меняется: перетаскивание в палитре, образец цвета, число в поле.
  • sf-theme-generator-apply — detail: { value?: string, hue?: number, chroma?: number, theme?: object, variables?: object, css?: string }. Выбор зафиксирован: change палитры, образец цвета, Enter или уход из поля, «Сбросить».
  • sf-theme-change — detail: { value?: string, hue?: number, chroma?: number, theme?: object, variables?: object, css?: string }. Прежнее имя; ещё отправляется с тем же detail до 2026-12-01 (запись журнала event-theme-generator-names). Это имя носит и событие Loader о светлой и тёмной теме. Подписывайтесь на sf-theme-generator-change.
  • sf-theme-apply — detail: { value?: string, hue?: number, chroma?: number, theme?: object, variables?: object, css?: string }. Прежнее имя; ещё отправляется с тем же detail до 2026-12-01 (запись журнала event-theme-generator-names). Это имя носит и событие Loader о светлой и тёмной теме. Подписывайтесь на sf-theme-generator-apply.

Доступность

  • Роль: группа (group).
  • Доступное имя: рекомендуется.
  • Клавиши: Tab, Enter, Space.
  • Фокус: В порядке фокуса — выбор цвета, «Сбросить», раскрытие «Тонкая настройка» и два числовых поля; Enter в поле фиксирует тему. Предпросмотр — именованная область подписанных образцов, у каждого названы палитра, тон и значение.

Минимальная разметка

HTML
<sf-theme-generator value="#2e7d32" apply></sf-theme-generator>

Источник

  • simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/smart/theme-generator
  • simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/rule/rule.json#name=cl-theme-generator

См. также

Поиск по документации

Введите минимум 2 символа

    Настройки

    Тема
    Размер шрифта
    Ширина страницы