定制化

可以通过将参数传递给“useStyleProvider”函数来自定义“Style provider”的行为。此外，您可以覆盖默认主题的全局变量或创建您自己的主题。

useStyleProvider 的参数

useStyleProvider 函数接受以下参数：

• emulate - 强制在浏览器中创建 Style provider 模拟 (无需在服务器端传递参数，模拟将自动创建。),
• noscript - 将 Style provider 模拟转换为字符串后，从中移除脚本，仅保留初始 CSS 样式（对 SSG 很有用）。,
• global (^4.2.0) - 将 Style provider 保存并用作全局对象,
• attrs - Style provider 属性:
  • pre - 样式表名称前缀,
  • mode - 用于生成唯一选择器的模式（a - 数据属性，c - 类）,
  • min - 用于生成缩减作用域选择器的模式（布尔属性）,
  • size - 覆盖全局 CSS 变量中的基础尺寸,
  • space (^4.13.0) - 覆盖全局 CSS 变量的基本间距，
  • time - 覆盖基准时间的全局 CSS 变量,
  • angle - 覆盖全局 CSS 变量中的基础角度,
  • color (^4.3.0) - 覆盖全局 CSS 变量的基础颜色,
  • easing (^4.4.0) - 覆盖全局 CSS 变量中的基础缓动函数，
  • contrast (^4.8.0) - 覆盖全局 CSS 变量中对比色，
  • neutral (^4.8.0) - 覆盖全局 CSS 变量中性色。

主题

EffCSS 主题是一组全局 CSS 变量。

主题的创建/更新/删除是通过主题控制器对象进行的，该对象可通过 Style provider 对象的 theme 属性访问：

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': {
            // you can set your own multiplier
            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' - 后备值
        }
    };
};

值数组（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)

您可以使用 Web 组件effcss-override为布局的各个部分设置和重新定义全局变量，而不是定义多个主题。为此，请将使用prepareOverrideValues实用程序准备的字符串传递给values属性：

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)
        }
    };
};

然后，在应用程序中，可以通过 Style provider 的 tune 方法来调整样式表：

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 方法定义它们。