advance-semi-theme

v1.0.2

Published

3 months ago

将 Ant Design Vue / Element Plus 组件一键转换为 Semi Design 视觉风格的主题包

0High
0Medium
0Low

chenjingsheng

ant-design-vue element-plus semi-design theme vue3 ui css

semi-theme

将 Ant Design Vue / Element Plus 组件一键转换为 Semi Design 视觉风格

为什么用 semi-theme？

零改造成本：不改一行业务代码，不替换任何组件，直接用原生 API
即插即用：3 行代码完成接入，所有组件自动获得 Semi Design 风格
组件级控制：支持全局 / 按需 / 排除三种模式，灵活控制主题范围
深色模式：内置暗色主题，一行代码切换
70+ 组件：覆盖 Button、Input、Select、Table、Form 等全部常用组件

安装

npm install advance-semi-theme
# or
pnpm add advance-semi-theme
# or
yarn add advance-semi-theme

快速开始

用于 Ant Design Vue

// main.ts
import { createApp } from 'vue'
import Antd from 'ant-design-vue'
import { createSemiTheme } from 'advance-semi-theme/antd'
import 'ant-design-vue/dist/reset.css'
import 'advance-semi-theme/antd/styles'

const app = createApp(App)
app.use(Antd)
app.use(createSemiTheme())  // 就这一行，所有组件变成 Semi 风格
app.mount('#app')

用于 Element Plus

// main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import { createSemiTheme } from 'advance-semi-theme/element'
import 'element-plus/dist/index.css'
import 'advance-semi-theme/element/styles'

const app = createApp(App)
app.use(ElementPlus)
app.use(createSemiTheme())  // 就这一行，所有组件变成 Semi 风格
app.mount('#app')

然后正常写代码就行了，不需要改任何组件用法：

<template>
  <!-- 原生 Ant Design Vue / Element Plus 写法，自动变成 Semi 风格 -->
  <a-button type="primary">Semi 风格按钮</a-button>
  <a-input placeholder="Semi 风格输入框" />
  <a-select placeholder="Semi 风格选择器">
    <a-select-option value="1">选项一</a-select-option>
  </a-select>
</template>

进阶用法

只对部分组件应用主题

app.use(createSemiTheme({
  components: ['Button', 'Input', 'Select', 'Table']
  // 只有这 4 个组件会变成 Semi 风格，其他保持原样
}))

排除某些组件

app.use(createSemiTheme({
  exclude: ['Table', 'Form']
  // Table 和 Form 保持原样，其他全变成 Semi 风格
}))

深色模式

// 方式一：初始化时指定
app.use(createSemiTheme({ dark: true }))

// 方式二：运行时动态切换
import { getCurrentInstance } from 'vue'

const { proxy } = getCurrentInstance()!
proxy.$semiTheme.setDark(true)   // 切换到深色
proxy.$semiTheme.setDark(false)  // 切换到浅色

运行时开关组件主题

const { proxy } = getCurrentInstance()!
proxy.$semiTheme.toggle('Table', false)  // 关闭 Table 的 Semi 主题
proxy.$semiTheme.toggle('Table', true)   // 重新开启

工作原理

semi-theme 的核心设计是 纯 CSS 覆盖 + 自动类名注入：

createSemiTheme() 插件在 <body> 上添加 .semi 类名和 data-semi 属性
所有样式通过高优先级的 CSS 选择器（如 .semi .ant-btn、body.semi .el-button）覆盖原有样式
对于 Portal/Teleport 组件（下拉菜单、对话框等），使用 body.semi 选择器确保样式生效
组件级控制通过 data-semi-{component} 属性 + CSS :where() 选择器实现

你不需要：

修改任何组件的类名
添加任何自定义属性
包裹任何额外的容器

覆盖的组件列表

| 类别 | 组件 | |------|------| | 通用 | Button, Icon, Typography, Divider, Space | | 布局 | Grid, Layout, Flex | | 数据录入 | Input, InputNumber, Select, Cascader, AutoComplete, Mentions, Checkbox, Radio, Switch, Slider, Rate, DatePicker, TimePicker, ColorPicker, Upload, Transfer, TreeSelect, Form | | 数据展示 | Table, Card, Tag, Tabs, Collapse, List, Avatar, Badge, Timeline, Tree, Tooltip, Popover, Popconfirm, Descriptions, Statistic, Empty, Skeleton, Image, Carousel, Calendar, Segmented, QRCode, Tour | | 反馈 | Modal, Drawer, Message, Notification, Progress, Alert, Spin, Result | | 导航 | Steps, Pagination, Menu, Dropdown, Breadcrumb, Anchor, BackTop, PageHeader, Affix | | 其他 | App, ConfigProvider, FloatButton, Watermark |

| 类别 | 组件 | |------|------| | 通用 | Button, Divider, Space, Link, Text | | 数据录入 | Input, InputNumber, Select, Cascader, Autocomplete, Mention, Checkbox, Radio, Switch, Slider, Rate, DatePicker, TimePicker, ColorPicker, Upload, Transfer, TreeSelect, Form | | 数据展示 | Table, Card, Tag, CheckTag, Tabs, Collapse, Avatar, Badge, Timeline, Tree, Tooltip, Popover, Descriptions, Statistic, Empty, Skeleton, Image, Carousel, Calendar, Segmented | | 反馈 | Dialog, Drawer, Message, Notification, Progress, Alert, Loading, Result, Popconfirm, Tour | | 导航 | Steps, Pagination, Menu, Dropdown, Breadcrumb, Backtop, PageHeader | | 其他 | Affix, Anchor, Scrollbar, Container, Row, Watermark, InfiniteScroll, VirtualizedList |

API 参考

`createSemiTheme(options?)`

创建 Vue 插件实例。

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | components | string[] | — | 指定要应用主题的组件列表 | | exclude | string[] | — | 指定不应用主题的组件列表 | | dark | boolean | false | 是否启用深色模式 | | target | string | 'body' | 挂载目标选择器 |

全局方法 `$semiTheme`

安装插件后，可通过 $semiTheme 访问以下方法：

| 方法 | 说明 | |------|------| | setDark(isDark: boolean) | 切换深色/浅色模式 | | toggle(component: string, enabled: boolean) | 开关指定组件的主题 |

包导出

advance-semi-theme/
├── antd                        # Ant Design Vue 主题插件
├── antd/styles                 # Ant Design Vue 完整样式
├── antd/styles/base            # 基础样式（不含组件）
├── antd/styles/dark            # 深色模式样式
├── antd/styles/components/*    # 单组件样式（按需引入）
├── element                     # Element Plus 主题插件
├── element/styles              # Element Plus 完整样式
├── element/styles/base         # 基础样式（不含组件）
├── element/styles/dark         # 深色模式样式
├── element/styles/components/* # 单组件样式（按需引入）
├── core                        # 共享核心模块
└── core/variables.css          # Semi Design CSS 变量

按需引入样式

如果你不想引入全部组件样式，可以只引入需要的：

// 只引入基础样式 + 需要的组件
import 'advance-semi-theme/antd/styles/base'
import 'advance-semi-theme/antd/styles/components/button'
import 'advance-semi-theme/antd/styles/components/input'
import 'advance-semi-theme/antd/styles/components/select'

License

MIT