# 主题 Theme

组件库提供基于 CSS Variables 的主题系统。2026-04 起，主题配置的主接口升级为三层 token 模型：

  • global token：基础值，如文字、背景、边框、圆角、阴影
  • alias token：语义值，如页面背景、默认面板、弱化面板
  • component token：组件专属槽位，如表格表头背景、弹窗头部背景

旧版 --ctcMain* 变量仍然兼容，但已经降级为 alias 层的兼容映射，不再是推荐主接口。

# 初始化配置

在 main.js 安装插件时，可以通过 theme 选项启用并配置主题：

import CtcUI from "ctc-components-ui";

Vue.use(CtcUI, {
	theme: {
		enabled: true,
		default: "lightTheme",
		list: {
			lightTheme: {
				title: "白色主题",
				url: "",
				vars: {
					"--ctc-page-bg": "#f8f8f8",
					"--ctc-surface-default": "#ffffff",
					"--ctc-surface-muted": "#f3f5f9",
					"--ctc-text-primary": "#2e3544",
					"--ctc-border-default": "#dbdfe7",
					"--ctc-table-header-bg": "#f3f5f9",
					"--ctc-dialog-header-bg": "#f8f8f8"
				}
			},
			blueTheme: {
				title: "蓝色主题",
				url: "https://cdn.example.com/blue-theme.css",
				vars: {
					"--ctc-page-bg": "#012447",
					"--ctc-surface-default": "#004774",
					"--ctc-surface-muted": "#023462",
					"--ctc-text-primary": "#ffffff",
					"--ctc-border-default": "#004a70"
				}
			}
		}
	}
});

# 切换主题

在组件中，你可以通过挂载在 Vue 原型上的 $ctcTheme 对象来管理主题。

export default {
	methods: {
		handleThemeChange(themeName) {
			// 切换主题，自动加载 CSS 和注入变量
			this.$ctcTheme.switch(themeName);
		},
	},
	computed: {
		currentTheme() {
			// 获取当前主题名 (响应式)
			return this.$ctcTheme.current;
		},
		themeList() {
			// 获取配置的主题列表
			return this.$ctcTheme.list;
		},
		themeSchema() {
			// 获取变量定义的 Schema (用于生成配置界面)
			return this.$ctcTheme.schema;
		},
	},
};

组件库使用 theme.vars 覆盖 token。推荐直接覆盖新 token；如果业务系统仍传入旧版 --ctcMain* 变量，运行时会自动映射到新 token，并补齐 legacy alias。

# Token 分层说明

packages/theme/vars.js 是当前主题系统的公开定义源。下游业务如果要扩主题、做配置面板、生成主题 JSON，应该优先参考这里的 THEME_SCHEMA。

  • global：基础设计值，偏设计系统层，如品牌色、基础文字色、基础背景、边框、圆角、阴影
  • alias：语义层 token，偏业务使用层，如页面背景、默认面板、主次文字、默认边框
  • component：组件专属 token，偏落地层，如 dialog、drawer、table、report

推荐顺序：

  1. 先改 alias token
  2. 不够时再改 component token
  3. 只有做系统级换肤时才直接改 global token

# 下游配置建议

建议业务系统维护自己的主题配置文件，而不是直接改组件库源码。一个最小示例如下：

const themeConfig = {
	default: "lightTheme",
	list: {
		lightTheme: {
			title: "浅色主题",
			url: "",
			vars: {
				// 页面背景
				"--ctc-page-bg": "#f8f8f8",
				// 默认容器背景
				"--ctc-surface-default": "#ffffff",
				// 主文字色
				"--ctc-text-primary": "#2e3544",
				// Dialog 标题栏背景
				"--ctc-dialog-header-bg": "#f8f8f8"
			}
		}
	}
};

如果你要给业务系统开放“主题编辑器”，可以直接用 $ctcTheme.schema 渲染出表单，再把修改后的 vars 存成本地配置。

# 主题对象能力

安装后可通过 $ctcTheme 获取：

  • current：当前主题名
  • list：主题列表
  • schema：完整 token schema，可用于生成主题配置界面
  • switch(name)：切换主题

# 默认行为说明

组件库内置默认主题只提供一套最小可用默认 token，不再默认依赖宿主项目的静态资源路径，也不再内置演示用途的扩展主题。

  • 只做 token 换肤时，可以只配置 vars，url 留空
  • 需要覆盖 Element UI 或其他全局样式时，再显式提供 theme.list.xxx.url
  • 当前仓库下的 public/theme/* 只属于 demo 站点，不应作为 npm 包消费者的默认路径假设

# CSS 变量参考

以下表格直接读取代码中的 THEME_SCHEMA，展示当前推荐使用的新 token。

变量名 (Name) 含义与作用范围 (Description) 默认值
--ctc-color-brand
品牌主色
全局品牌强调色，供后续交互态和业务扩展使用
#1677ff
--ctc-color-text-primary
全局主文字色
正文、标题、表格主体文字默认颜色
#2E3544
--ctc-color-text-secondary
全局次文字色
辅助说明、弱化信息默认颜色
#5B6577
--ctc-color-text-inverse
反色文字
深色背景上的默认文字颜色
#FFFFFF
--ctc-color-surface-base
基础面板背景
白色卡片、弹层内容区等基础背景
#FFFFFF
--ctc-color-surface-muted
弱化背景
表头、斑马纹、次级区域背景
#F3F5F9
--ctc-color-surface-emphasis
强调背景
报表容器、需要层次感的背景面
#EEF0F4
--ctc-color-page-bg
页面背景
页面整体大背景色
#F8F8F8
--ctc-color-border-base
基础边框色
常规边框与分割线颜色
#DBDFE7
--ctc-color-border-strong
加强边框色
比基础边框略强的描边颜色
#C5CCD8
--ctc-radius-sm
小圆角
小尺寸圆角 token
2px
--ctc-radius-md
中圆角
中尺寸圆角 token
4px
--ctc-shadow-sm
浅层阴影
浅层容器阴影
0px 2px 4px 0px rgba(186, 200, 220, 0.6)
--ctc-shadow-md
中层阴影
主要卡片或容器阴影
0px 1px 4px 0px rgba(186, 200, 220, 1)
--ctc-page-bg
语义页面背景
页面级背景语义 token
#F8F8F8
--ctc-surface-default
语义默认面板背景
普通面板与内容容器背景
#FFFFFF
--ctc-surface-muted
语义弱化背景
次级区域、表头、斑马纹背景
#F3F5F9
--ctc-surface-emphasis
语义强调背景
带层次感的区块背景
#EEF0F4
--ctc-text-primary
语义主文字色
主要正文和标题颜色
#2E3544
--ctc-text-secondary
语义次文字色
辅助文字颜色
#5B6577
--ctc-text-inverse
语义反色文字
深背景上的文字颜色
#FFFFFF
--ctc-border-default
语义默认边框
常规边框语义 token
#DBDFE7
--ctc-border-strong
语义强调边框
更强的边框语义 token
#C5CCD8
--ctc-table-body-bg
表格主体背景
表格行默认背景色
#FFFFFF
--ctc-table-header-bg
表格表头背景
表头背景色
#F3F5F9
--ctc-table-header-text
表格表头文字
表头文字颜色
#2E3544
--ctc-table-striped-bg
表格斑马纹背景
斑马纹偶数行背景色
#F3F5F9
--ctc-table-border-color
表格边框色
表格边框与分割线颜色
#DBDFE7
--ctc-table-toolbar-text
表格工具文字
表格下载等辅助文字颜色
#2E3544
--ctc-dialog-panel-bg
弹窗面板背景
弹窗主体背景色
#FFFFFF
--ctc-dialog-header-bg
弹窗头部背景
弹窗头部背景色
#F8F8F8
--ctc-dialog-header-text
弹窗头部文字
弹窗头部文字和关闭图标颜色
#2E3544
--ctc-dialog-border-color
弹窗边框色
弹窗头部边框颜色
#DBDFE7
--ctc-drawer-panel-bg
抽屉面板背景
抽屉主体背景色
#FFFFFF
--ctc-drawer-header-bg
抽屉头部背景
抽屉头部背景色
#FFFFFF
--ctc-drawer-header-text
抽屉头部文字
抽屉标题和按钮图标颜色
#2E3544
--ctc-drawer-border-color
抽屉边框色
抽屉头部和区域边框颜色
#DBDFE7
--ctc-drawer-footer-border-color
抽屉底部边框色
固定底部操作区边框颜色
#DBDFE7
--ctc-report-page-bg
报表页面背景
报表整体页面背景色
#EEF0F4
--ctc-report-toolbar-bg
报表工具栏背景
顶部工具栏背景色
#FFFFFF
--ctc-report-toolbar-text
报表工具栏文字
顶部工具栏文字颜色
#2C3240
--ctc-report-search-bg
报表搜索栏背景
搜索栏背景色
#FFFFFF
--ctc-report-search-shadow
报表搜索栏阴影
搜索栏阴影
0px 2px 4px 0px rgba(186, 200, 220, 0.6)
--ctc-report-container-bg
报表容器背景
报表主体容器背景色
#FFFFFF
--ctc-report-container-text
报表容器文字
报表容器正文文字颜色
#2E3544
--ctc-report-container-shadow
报表容器阴影
报表主体容器阴影
0px 1px 4px 0px rgba(186, 200, 220, 1)
--ctc-report-title-text
报表标题文字
报表标题颜色
#2E3544
--ctc-report-info-text
报表信息文字
报表信息区文字颜色
#2E3544
--ctc-report-border-color
报表边框色
报表工具栏边框颜色
#EDEFF3
Last Updated: 4/16/2026, 4:49:34 PM

← 更新日志 →