@bm-fe/components-vue3

BitMart Vue 3 Element Plus 自定义主题，基于 Design Tokens 生成，支持亮色/深色模式切换。

Element Plus 原生支持 CSS 变量，通过定义变量即可实现样式定制，无需大量 patch CSS。

安装

npm install @bm-fe/components-vue3 @bm-fe/design-tokens element-plus

使用方式

方式一：仅亮色主题

适用于不需要深色模式切换的项目。

import { createApp } from 'vue';
import ElementPlus from 'element-plus';
import '@bm-fe/design-tokens/dist/css/fonts.css'; // 字体文件（可选）
import '@bm-fe/design-tokens/dist/css/variables.css'; // 基础 CSS 变量
import 'element-plus/dist/index.css'; // Element Plus 基础样式
import '@bm-fe/components-vue3/patch'; // Element Plus 主题补丁

const app = createApp(App);
app.use(ElementPlus);

方式二：支持深色模式切换（推荐）

适用于需要运行时主题切换的项目。

import { createApp } from 'vue';
import ElementPlus from 'element-plus';
import '@bm-fe/design-tokens/dist/css/fonts.css'; // 字体文件（可选）
import '@bm-fe/design-tokens/dist/themes/light/variables.css'; // 亮色主题变量
import '@bm-fe/design-tokens/dist/themes/dark/variables.css'; // 深色主题变量
import 'element-plus/dist/index.css'; // Element Plus 基础样式
import '@bm-fe/components-vue3/patch'; // Element Plus 基础主题补丁
import '@bm-fe/components-vue3/patch/vars'; // Element Plus CSS 变量覆盖层（支持深色模式）

const app = createApp(App);
app.use(ElementPlus);

主题切换

引入 CSS 变量覆盖层后，可以通过设置 data-theme 属性来切换主题：

// 切换到深色模式
document.documentElement.setAttribute('data-theme', 'dark');

// 切换到亮色模式
document.documentElement.setAttribute('data-theme', 'light');

// 移除主题属性，使用默认（亮色）
document.documentElement.removeAttribute('data-theme');

文件说明

| 文件路径 | 说明 | 必需性 | |---------|------|--------| | @bm-fe/design-tokens/dist/css/variables.css | 基础 CSS 变量（Primitive + Semantic） | ✅ 必需 | | @bm-fe/design-tokens/dist/themes/light/variables.css | 亮色主题变量 | ✅ 深色模式必需 | | @bm-fe/design-tokens/dist/themes/dark/variables.css | 深色主题变量 | ✅ 深色模式必需 | | @bm-fe/components-vue3/patch | Element Plus 基础主题补丁 | ✅ 必需 | | @bm-fe/components-vue3/patch/vars | Element Plus CSS 变量覆盖层 | ⚠️ 深色模式必需 |

导出路径

本包提供以下导出路径：

// 基础主题补丁（仅亮色）
import '@bm-fe/components-vue3/patch';
// 或
import '@bm-fe/components-vue3/style.css';

// CSS 变量覆盖层（支持深色模式）
import '@bm-fe/components-vue3/patch/vars';
// 或
import '@bm-fe/components-vue3/style-vars.css';

特性

• ✅ 基于 Design Tokens，确保设计一致性
• ✅ 支持运行时主题切换（亮色/深色）
• ✅ 自动生成 Element Plus CSS 变量映射
• ✅ Element Plus 原生支持 CSS 变量，无需大量 patch
• ✅ 覆盖 Element Plus 组件样式，适配 BitMart 设计规范
• ✅ 支持所有 Element Plus 组件（Button、Input、Table、Dialog 等）

构建

本包的主题文件通过构建脚本自动生成：

# 生成 CSS 变量覆盖层
npm run generate:vars

# 构建完整主题
npm run build

维护说明

patch.css 文件

src/theme/patch.css 是手动维护的文件，包含：

• 无法通过 CSS 变量实现的样式覆盖（如 clip-path、特殊尺寸等）
• Element Plus 原生支持 CSS 变量，大部分样式通过变量定义即可实现

何时更新：

• 需要添加无法通过变量实现的特殊样式覆盖
• 需要调整现有组件的特殊样式细节

注意事项：

• 优先使用 CSS 变量，其次才使用 patch
• 修改后需要重新构建：npm run build

element-plus-vars.css 文件

dist/patch/element-plus-vars.css 由 scripts/generate-vars.ts 自动生成，包含：

• Element Plus CSS 变量定义（:root 和 [data-theme="dark"]）
• 基于 Design Tokens 主题数据生成
• 完整的色阶（light-3, light-5, light-7, light-8, light-9, dark-2）

何时更新：

• 修改 tokens/themes/light.json 或 tokens/themes/dark.json 后
• 运行 npm run generate:vars 重新生成

注意事项：

• ⚠️ 此文件由脚本自动生成，请勿手动修改
• 修改 Design Tokens 后需要先构建 @bm-fe/design-tokens，再运行生成脚本

开发

# 安装依赖
pnpm install

# 生成 CSS 变量覆盖层
pnpm run generate:vars

# 构建主题
pnpm run build

相关链接

• Design Tokens 文档
• Element Plus 文档