Кастомизация
ПоведениеStyle provider можно настроить - для этого необходимо передать параметры в функцию useStyleProvider. Кроме того можно переопределить глобальные переменные дефолтной темы или создать свою тему.
Параметры useStyleProvider
Функция useStyleProvider принимает следующие параметры:
- emulate - принудительно создает эмуляцию
Style providerв браузере (на сервере передавать не нужно, эмуляция будет создана автоматически), - noscript - после приведения эмуляции
Style providerк строке удаляет из нее скрипт, оставляя только начальные стили CSS (полезно дляSSG), - global (^4.2.0) - сохраняет и использует
Style providerв качестве глобального объекта, - attrs - атрибуты
Style provider:- pre - префикс для названий таблиц стилей,
- mode - режим генерации БЭМ-селекторов (
a- data-атрибуты,c- классы), - min - режим генерации минифицированных БЭМ-селекторов (булев атрибут),
- size - переопределяет глобальную CSS переменную базового размера,
- space (^4.13.0) - переопределяет глобальную CSS переменную базового расстояния,
- time - переопределяет глобальную CSS переменную базового времени,
- angle - переопределяет глобальную CSS переменную базового угла,
- color (^4.3.0) - переопределяет глобальную CSS переменную базового цвета,
- easing (^4.4.0) - переопределяет глобальную CSS переменную функции типа
<easing function>, - contrast (^4.8.0) - переопределяет глобальную CSS переменную контрастного цвета,
- neutral (^4.8.0) - переопределяет глобальную CSS переменную нейтрального цвета.
Темизация
Тема EffCSS - это набор глобальных CSS-переменных.
Создание/обновление/удаление тем производится через объект контроллера тем, доступный из свойства theme объекта Style provider:
import { useStyleProvider } from 'effcss';
const provider = useStyleProvider();
const themeVars = {
size: 18,
time: 150,
angle: 15,
color: 'green',
sz: {
s: 10,
m: 20,
l: 30
},
coef: {
1: 0.05,
32: 220,
15: 1.9
},
hue: {
sec: 220,
},
$light: {
lightness: {
bg: {
s: 0.785
}
},
chroma: {
fg: {
rich: 0.145
}
}
}
};
// можно переопределить переменные дефолтной темы
provider.theme.update(themeVars);
// можно добавить новую тему
provider.theme.add(themeVars, 'custom');
// можно включить новую тему
provider.theme.switch('custom');Обратите внимание на специальные ключи верхнего уровня $light и $dark - они задают контекст переменных для светлой и темной цветовой схемы соответственно.
Для доступа к глобальным переменным размера, расстояния,времени и угла можно использовать утилиты theme.size, theme.space, theme.time и theme.angle соответственно. Чтобы получить доступ к глобальной переменным основного, нейтрального и контрастного цвета воспользуйтесь утилитами theme.color, theme.neutral и theme.contrast соответственно. Эти переменным поддерживают установку множества значений и доступ к этим значениям по индексу:
// через сеттер
styleProvider.size = [16, 18, 24];
// или через атрибут
<script is="effcss-provider" size="16;18;24;"></script>
// внутри мейкера значения доступны по индексу
export const maker: TStyleSheetMaker = ({ theme: {size} }) => {
return {
'.sz-s': {
width: size
},
'.sz-m': {
width: size[2]
},
'.sz-l': {
width: size[3]
},
'.sz-2xl': {
// можно установить свой множитель
width: size[3](2)
}
};
};Числовые коэффициенты и их диапазоны доступны через утилиту coef.
Переменные в объектах hue, lightness и chroma используются утилитой palette.
Чтобы использовать произвольные переменные темы в своих функциях StyleSheet maker используйте утилиту theme.variable:
import { TStyleSheetMaker } from 'effcss';
type TGlobalVars = {
sz: {
s: string;
m: string;
l: string;
}
};
export const maker: TStyleSheetMaker = ({ theme: {variable} }) => {
return {
'.sz-m': {
width: variable<TGlobalVars>('sz.m', '100px') // '100px' - fallback value
}
};
};Массивы значений (v4.12.0)
Если параметр темы имеет значение в виде массива, то для каждого элемента, кроме первого, массива будет создана своя CSS переменная с суффиксом, равным индексу этого значения. Первый элемент массива имеет нулевой индекс, который будет проигнорирован:
const themeVars = {
custom: ['12px', '24px', '36px']
// --f0-custom: 12px; --f0-custom-1: 24px; --f0-custom-2: 36px;
};Для доступа к таким CSS переменным можно использовать утилиту theme.variable:
export const maker: TStyleSheetMaker = ({ theme: {variable} }) => {
return {
'.sz-m': {
width: variable<TGlobalVars>('custom.1', '100px')
}
};
};Мультитемизация
Чтобы использовать отличную от глобальной тему для конкретного HTML-элемента вызовите функцию use без аргументов и в полученный резолвер передайте модификатор с нужной темой:
import type { TBaseStyleSheetMaker } from 'effcss';
import { useStyleProvider } from 'effcss';
const consumer = useStyleProvider();
const [resolver] = consumer.use();
const attrs = resolver<TBaseStyleSheetMaker>('..theme.custom');Переопределение глобальных переменных (^4.5.0)
Вместо определения множества тем вы можете задавать и переопределеять глобальные переменные для отдельных частей верстки с помощью веб-компонента effcss-override. Для этого передайте в атрибут values строку, подготовленную с помощью утилиты prepareOverrideValues:
import { prepareOverrideValues } from 'effcss';
const overridedValues = prepareOverrideValues({
size: 32,
hue: {
pri: 10
},
$light: {
lightness: {
bg: {
xl: 0.95
}
}
}
});
export const Component = () => <effcss-override neutral="grey" color="purple" values={overridedValues}>
<div>...</div>
<effcss-override>`Начиная с версии ^4.8.0 вы также можете переопределять глобальные переменные через те же атрибуты, что и у Style provider (например, size, angle, color). Эти атрибуты имеют приоритет перед значением из values. Начиная с версии ^4.12.0 это могут быть несколько значений, разделенных символом ;:
<effcss-override size="16;18;24;" color="purple;white;#2192a7"></effcss-override>Начиная с версии ^4.9.0 вы можете переопределить цветовую схему компонента и его содержимого через атрибут scheme. Атрибут может принимать значения light или dark.
Компонент effcss-override по умолчанию имеет стиль display:contents;, чтобы не вызвать изменения в верстке.
Настройка таблицы стилей (^4.13.0)
Tuning - это еще один способ сделать ваши таблицы стилей гибкими и настраиваемыми. Он позволяет вам определять специальные переменные для внешних приложений.
Вы можете объявить эти переменные с собственным типом контракта и реализовать их с помощью утилиты theme.tuning:
type TMaker = {
sz: 's' | 'm';
rounded: '';
card: {
bg: 'pri' | 'sec';
inv: '';
footer: Record<string, never>;
}
};
type TMakerTunings = {
size: number;
card: {
color: string;
}
};
const DEF_TUNING_VAL = 'rgb(82, 119, 119)';
const maker: TStyleSheetMaker = ({ select, theme: { tuning } }) => {
const selector = select<TMaker>;
const tuningVar = tuning<TMakerTunings>
return {
[selector('sz:s')]: {
width: '10px'
},
[selector('card')]: {
boxSizing: 'border-box'
},
// ...
div: {
background: tuningVar('card.color', DEF_TUNING_VAL)
}
};
};Затем в приложениях ваша таблица стилей может быть настроена с помощью метода tune экземпляра Style provider:
styleProvider.dx<TMaker>(maker, []);
const vars = styleProvider.tune<TMakerTunings>({
card: {
color: 'oklch(0.85 0.02 196.66)'
}
}, maker);
const jsx = <div style={vars}>Welcome to the tuned area</div>;INFO
Style provider настраивает только те таблицы стилей, которые вы уже создали, поэтому убедитесь, что вы определили их с помощью методов dx, cx или use.