Package Exports

@mega-apps/postcss-theme-helper
@mega-apps/postcss-theme-helper/unplugin

Readme

@mega-apps/postcss-theme-helper

PostCSS 主题助手

特性

支持主题颜色替换
支持对Vue ElementUI Ver2.x 组件的主题颜色替换（内置预设）
支持对Vue Ant Design Ver1.x 组件的主题颜色替换（内置预设）
提供Webpack插件，自动注入主题替换代码

安装

yarn add @mega-apps/postcss-theme-helper --dev

使用说明

Nuxt.js 项目

// nuxt.config.js

build: {
  plugins: [
    // 引入自动注入代码
    require('@mega-apps/postcss-theme-helper/unplugin').default.webpack({debug: false})
  ],
  postcss: {
        postcss: {
          plugins: {
            "@mega-apps/postcss-theme-helper": {
              debug: false,
              colorVariableReplacer: [
                // 类似于CSS的解析，从上而下，最小优先级最高
                {
                  matchColors: ["black", "rgb(239, 68, 68)"],
                  initVarColors: ["red", "blue"],
                  strict: true,
                  cssVarPrefix: "--myColor",
                  wrapper: ":root",
                },
                {
                  matchColors: ["black"],
                  initVarColors: ["yellow"],
                  strict: true,
                  cssVarPrefix: "--hiColor",
                  wrapper: "div",
                },
              ],
            },
          },
          // 调整postcss插件的次序，参照文档：https://nuxtjs.org/docs/configuration-glossary/configuration-build#postcss
          // 插件必须在 tailwindcss 之后，这样才能对tailwindcss的样式进行处理替换
          order: ["tailwindcss", "@mega-apps/postcss-theme-helper"],
        },
  }
}

浏览器客户端

主题替换

获得主题颜色

参数说明

Webpack 注入插件参数

主题颜色替换参数

参数接口原型

export type TMatchBaseSupportFilter = string |
  readonly string[] |
  RegExp |
  readonly RegExp[];

export type TMatchSupportFilter = TMatchBaseSupportFilter |
  ((...args: any[]) => TMatchBaseSupportFilter);

/**
 * 可序列化的颜色变量替换选项类型
 */
export interface IColorVariablesReplacerOptionsPure {
  // 需要匹配的包含颜色的属性名称, 任何一个条件符合都算匹配到
  matchProps?: string | readonly string[],
  
  // 排除的CSS属性名称, 任何一个条件符合都算匹配到
  excludeProps?: TMatchSupportFilter,

  // 需要匹配的css颜色值数组
  matchColors?: string[],

  // 需要匹配的选择器, 任何一个条件符合都算匹配到
  matchSelectors?: TMatchSupportFilter,
  
  // 排除的选择器, 任何一个条件符合都算匹配到
  excludeSelectors?: TMatchSupportFilter,

  // 默认替换颜色与matchColors成对出现
  initVarColors?: string[],

  // 生成的css变量的前缀
  cssVarPrefix?: string,

  // cssVar 使用matchColors中的颜色值
  useMatchColorValueForCssVar?: boolean,

  // 定义的css变量值，外部包装器，例如: :root
  wrapper?: string,

  // 是否严格模式，如果为true，则忽略alpha的颜色相近处理
  strict?: boolean,

  // 是否单独输出日志
  debug?: boolean,

  // 预设值preset
  preset?: EColorVariablesReplacePreset[]
}

示例代码

// 示例代码
plugins: {
  "@mega-apps/postcss-theme-helper": {
      debug: false,
      colorVariableReplacer: [
      // 类似于CSS的解析，从上而下，优先级高低：按序降低
      {
        matchColors: ["black", "rgb(239, 68, 68)"],
        initVarColors: ["red", "blue"],
        strict: true,
        cssVarPrefix: "--myColor",
        wrapper: ":root",
      },
      {
        matchColors: ["black"],
        initVarColors: ["yellow"],
        strict: true,
        cssVarPrefix: "--hiColor",
        wrapper: "div",
      }
    ]
  }
}

参数：matchColors

特指要匹配的颜色值数组; 这些颜色值将支持主题替换

支持颜色值的模式：
- 主要：
  - 16进制（3位，4位，6位，8位）：#fff, #ffff, #ffffff, #ffffffff
  - RGB/RGBA 字符串：rgb(192, 192, 192), rgba(192, 192, 192, 0.5)
  - HSL/HSLA 字符串: hsl(0, 50%, 50%), hsl(0, 50%, 50%, 0.25)
  - 颜色名称: red, black, blue, green
- 其他：
  - HWB 字符串
  - CMYK 字符串
  - LCH 字符串
  - LAB 字符串
  - XYZ 字符串
自动去重

参数：matchProps

特指需要匹配的包含颜色的属性名称

默认值为: ['*'], 表示所有CSS属性都会被遍历
可以指定自己的默认的属性包含, 如：background, color

  matchProps: ['background'] // 只查找css样式中，包含background的规则

参数：excludeProps

特指需要排除的属性名称

默认值: [], 表示不排除任何项
支持的值形式：字符串数组、正则表达式、正则表达式数组、函数

  excludeProps: ['border*'] // 以border开头的全部排除在外

参数：matchSelectors

特指需要匹配的选择器

默认值为: ['*'], 表示所有css选择器都会遍历匹配，作为主题替换
支持的值形式：字符串数组、正则表达式、正则表达式数组、函数

// 字符串数组形式，使用glob形式，参见：https://www.npmjs.com/package/micromatch
matchSelectors: ['ele-*']

// 正则表达式形式
matchSelectors: /ele/gi

// 正则表达式数组
matchSelectors: [/^ele/gi, /^ant/gi]

// 函数形式
matchSelectors: (...args) => { return []}

参数：excludeSelectors

特指需要排除的CSS选择器

默认：[], 表示不排除任何项
支持的值形式：字符串数组、正则表达式、正则表达式数组、函数

excludeSelectors: ['.el-button:active']

参数：initVarColors

特指：默认初始化颜色，例如：匹配到 black，可以让生成的颜色变成 red 默认替换颜色与matchColors成对出现

matchColors: ['black', 'rgb(22,22,22)', 'rgb(44,44,23)']
initVarColors: ['red', 'green']

// 转换结果： black -> red; rgb(22,22,22) -> green; rgb(44,44,23) -> green

参数：strict

特指是否严格模式，如果为true，则忽略alpha的颜色相近处理

默认是true

// 设置strict: false
matchColors: ['black']
strict: false

// 结果
// rgba(0,0,0, 0.5) 也会被匹配上

// 设置strict: true
matchColors: ['black']
strict: true

// 结果
// rgba(0,0,0, 0.5) 不会被匹配上

参数：cssVarPrefix

生成的css变量的前缀

/* cssVarPrefix: --myVar */
:root {
  --myVar-name: 'black'
}

参数：useMatchColorValueForCssVar

cssVar 使用matchColors中的颜色值

默认：true

/* useMatchColorValueForCssVar: true*/
:root {
  --myVar-black: 'black'
}

/* useMatchColorValueForCssVar: false */
:root {
  --myVar-black: '#000'
}

参数：wrapper

定义的css变量值，外部包装器，例如: :root

/* wrapper: ':root' */
:root {
  --myVar-black: 'black'
}

/* wrapper: 'body > div' */
body > div {
  --myVar-black: 'black'
}

参数：debug

是否单独输出调试日志

默认值：false

参数：preset

预设值preset

preset: ['vue-antd-ui.v1']

技巧：启动 Ant Design Vue 主题替换

当前内置预设，支持的 Ant Design Vue版本是:

"vue-antd-ui.v1": 对应 "ant-design-vue": "^1.x"

// postcss plugins
plugins: {
  "@mega-apps/postcss-theme-helper": {
      debug: false,
      colorVariableReplacer: [
      // 类似于CSS的解析，从上而下，优先级高低：按序降低
      {
        matchColors: ["black", "rgb(239, 68, 68)"],
        initVarColors: ["red", "blue"],
        strict: true,
        cssVarPrefix: "--myColor",
        wrapper: ":root",
        preset: ['vue-antd-ui.v1'], // 预设为数组，可以将 'vue-antd-ui.v1' 添加进来
      }
    ]
  }
}

技巧：启用 Element UI 主题替换

当前内置预设，支持的 Element UI版本是:

"vue-element-ui.v2": 对应 "element-ui": "^2.x"
"vue-element-ui-plus.v1": 对应 "element-plus": "^1.3.0"

// postcss plugins
plugins: {
  "@mega-apps/postcss-theme-helper": {
      debug: false,
      colorVariableReplacer: [
      // 类似于CSS的解析，从上而下，优先级高低：按序降低
      {
        matchColors: ["black", "rgb(239, 68, 68)"],
        initVarColors: ["red", "blue"],
        strict: true,
        cssVarPrefix: "--myColor",
        wrapper: ":root",
        preset: ['vue-element-ui.v2'], // 预设为数组，可以将 'vue-element-ui.v2' 添加进来
      }
    ]
  }
}

技巧：启用多个UI库主题替换

// postcss plugins
plugins: {
  "@mega-apps/postcss-theme-helper": {
      debug: false,
      colorVariableReplacer: [
      // 类似于CSS的解析，从上而下，优先级高低：按序降低
      {
        matchColors: ["black", "rgb(239, 68, 68)"],
        initVarColors: ["red", "blue"],
        strict: true,
        cssVarPrefix: "--myColor",
        wrapper: ":root",
        preset: ['vue-antd-ui.v1', 'vue-element-ui.v2'], // 启用Antd 及 Element UI
      }
    ]
  }
}

变更日志

CHANGELOG