Настройка в runtime

Настройка в runtime — ключевая возможность системы тем lh-ui: без повторной компиляции стилей менять облик компонентов в runtime. Три API, каждое ведает своим слоем.

1. themeVars —— глобальное переопределение токенов

ConfigProvider принимает themeVars; ключи — сокращённые:

<lh-config-provider
  :theme-vars="{
    'primary-color': '#1677ff',
    'border-radius-base': '8px',
  }"
>
  <App />
</lh-config-provider>

Дополнение префикса в сокращённых ключах

'primary-color' автоматически дополняется до --lh-primary-color. Это дополнение выполняет toCssVarName, и оно идемпотентно (ключи, уже несущие префикс, возвращаются как есть и не превращаются в --lh---lh-...).

Можно записывать и полные имена:

{ '--lh-primary-color': '#1677ff' }   // Эквивалентно

Под капотом — cssVars(themeVars), превращающий пары ключ-значение в объект CSS-переменных, пригодный для прямой привязки к :style.

Область действия —— поддерево DOM

CSS-переменные по своей природе каскадны: ConfigProvider инъектирует переменные на оборачивающий элемент, и только его компоненты-потомки видят новые значения. Это позволяет делать локальную смену облика:

<lh-config-provider :theme-vars="brandVars">
  <Header />
</lh-config-provider>

<lh-config-provider :theme-vars="neutralVars">
  <Content />
</lh-config-provider>

То, что экспортирует сайт docs, —— это то же самое

Текст :root { --lh-*: ... }, который экспортирует страница настройки тем в docs, и themeVars — одно и то же, оформленное в виде файла: его можно напрямую вставить во входной файл проекта:

/* Входной файл проекта */
:root {
  --lh-primary-color: #2B4C7C;
  --lh-primary-color-hover: #3D649E;
  /* ... */
}

2. componentTheme —— переопределение на уровне компонентов

themeVars действует глобально; иногда нужно изменить токены только одного компонента (например, скругление всех кнопок, оставив остальные компоненты нетронутыми).

<lh-config-provider
  :component-theme="{
    button: { 'border-radius': '20px' },
    input: { 'control-height-medium': '40px' },
  }"
>
  <App />
</lh-config-provider>

Ключ — имя компонента (имя каталога в styles/), значение — themeVars в области действия этого компонента. При инъекции переменные получают префикс области действия компонента и затрагивают только указанный компонент. Имя ключа должно точно совпадать с именем токена (control-height-medium → --lh-control-height-medium) — шагом по умолчанию для input является medium, а control-height без суффикса шага никем из компонентов не потребляется.

Важно: токены уровня компонента требуют, чтобы в SCSS этого компонента соответствующий токен потреблялся через var(--lh-<name>-*) — далеко не все компоненты токенизировали все точки стилей; за тем, что именно можно изменить, обращайтесь к строке этого компонента в таблице Токены дизайна.

3. patternComponents —— белый список узоров

Узоры в китайском стиле (см. Узоры в китайском стиле) по умолчанию не включены. При включении они влияют на фон, а это подходит далеко не всем компонентам (цветы сливы, напечатанные на фоне таблицы, выглядят неаккуратно).

patternComponents управляет тем, к каким компонентам применяется узор:

<lh-config-provider
  :pattern-components="['card', 'dialog', 'drawer']"
  pattern="plum"
>
  <App />
</lh-config-provider>

Узор получат только компоненты из белого списка. Конкретные имена prop-ов — см. документацию ConfigProvider соответствующей UI-библиотеки.

4. Насложение пресета и настройки

Три механизма можно накладывать друг на друга; приоритет — «потомок перекрывает предка, конкретное перекрывает глобальное»:

<lh-config-provider
  theme="cerblue"
  :theme-vars="{ 'border-radius-base': '4px' }"
>
  <!-- Сначала применяется пресет 青花瓷 (сине-белый фарфор), затем через themeVars тонко настраивается скругление -->
  <App />
</lh-config-provider>

5. Тёмная тема и связь с настройкой

То, на каком элементе инъектируются настроенные themeVars, и определяет, на какое поддерево они влияют в светлой и тёмной теме:

<!-- Этот блок принудительно тёмный -->
<div data-theme="dark">
  <lh-button>Тёмная кнопка</lh-button>
</div>

Переключатель тёмной темы — атрибут [data-theme='dark'] или класс .dark (селекторы в var-dark.scss).
Не записывайте themeVars во встроенный style на documentElement — специфичность встроенного style выше, чем у целого блока тёмных переменных в var-dark.scss, что приведёт к искажению цветовой палитры в тёмной теме (см. ограничение инъекции в обзоре системы тем).

6. Что нельзя изменить в runtime

Что меняем	Можно ли	Альтернатива
Токены: основной цвет, цвет текста, скругление, отступы и т. п.	✅ `themeVars`	—
Токены отдельного компонента	✅ `componentTheme`	—
Узоры	✅ `pattern` + `patternComponents`	—
Высота компонентов (input 37px и т. п.)	⚠️ Ограниченно	Токены высоты ещё не унифицированы; см. известные пробелы
Структура DOM / имена классов компонента	❌	Использовать проброс pt или слоты
Многослойная компоновка теней	❌ Этап компиляции	Переопределить SCSS-переменные `$lh-*` и пересобрать
Кривые анимаций	✅ `--lh-animation-timing-function`	—

Пример: полная конфигурация темы

<template>
  <lh-config-provider
    theme="songhua"
    :theme-vars="{
      'border-radius-base': '8px',
      'font-size-base': '15px',
    }"
    :component-theme="{
      button: { 'border-radius': '999px' },
    }"
    :pattern-components="['card', 'dialog']"
  >
    <App />
  </lh-config-provider>
</template>

Примечания

Сокращённые ключи не должны дублировать префикс: 'primary-color', а не '--lh-primary-color' (хотя идемпотентность это допускает, единообразное использование сокращённых ключей аккуратнее).
Утечка области действия: themeVars влияет только на компоненты-потомки; и наоборот, переменные предка ConfigProvider перекрываются переменными потомка (правило CSS-каскада).
Место инъекции: ConfigProvider инъектирует на оборачивающий элемент (а не на documentElement), что обеспечивает удаляемость и локализацию.
SSR: инъектируются обычные CSS-переменные; при server-side rendering выводится inline style, а после гидратации на клиенте они согласованы.