在 SpreadJS V18.2 版本中，Designer Component（设计器组件）迎来了重大升级——全新主题系统正式上线。该系统不仅提供了契合不同场景的预设主题，还支持高度灵活的自定义配置，让开发者能轻松打造与应用品牌风格一致、适配用户视觉偏好的电子表格界面。
一、主题系统核心构成：4 种方案满足多样需求
SpreadJS V18.2 Designer Theme 系统包含 3 种预设主题与 1 套自定义主题体系，覆盖从基础使用到深度定制的全场景需求，具体如下：
| 主题类型 | 特点与适用场景 |
|---|---|
| Light（默认） | 符合现代显示偏好，优化高对比度与可读性，适配明亮使用环境（如日常办公场景） |
| Dark | 同样遵循现代设计风格，以深色基调减少视觉疲劳，适合低光环境或偏好深色界面的用户 |
| Classic | 提供传统电子表格的熟悉视觉风格，界面中性简洁，满足习惯旧版设计的用户需求 |
| 自定义主题 | 基于 Light/Dark 主题扩展，支持调整颜色、边框圆角、阴影等属性，精准匹配应用品牌形象 |
二、预设主题：快速部署，即开即用
预设主题的实现核心是引入对应 CSS 文件，操作简单且无需额外开发，具体步骤与注意事项如下：
1. 部署方式
- HTML 引入：在 HTML 的<head>标签中添加<link>，指定主题 CSS 文件路径，示例如下：
<link rel="styleSheet" href="css/gc.spread.sheets.designer.light.x.x.x.min.css" />
- 文件位置：预设主题 CSS 文件已包含在下载的 ZIP 压缩包中，路径为\SpreadJS.Release.xxxx\Designer\Designer Component\css，直接引用即可。
- 模块加载：也可通过模块加载器导入主题文件，适配不同项目架构。
2. 关键注意事项
- 同一时间仅能引用 1 个 Designer 主题 CSS 文件，避免样式冲突。
- 历史版本兼容：V18.2.0 之前，SpreadJS Designer 仅支持 Classic 主题作为唯一 UI 样式选项，升级后可无缝切换至新主题。
三、自定义主题：三种方法，实现深度个性化
自定义主题需以 Light 或 Dark 主题为基础，再通过 API、CSS 或 JavaScript 调整视觉属性，满足品牌化需求。
1. 用 API 动态定制（推荐）
通过setTheme()方法实现运行时主题修改，仅需传入需覆盖的属性（未定义属性保持默认），示例代码如下：
GC.Spread.Sheets.Designer.setTheme({
colorBackground: "#F0F4F8", // 所有标准组件的背景色
colorForeground: "#2D3436", // 所有常规文本的颜色
borderRadiusM: "6px", // 中等边框圆角
shadow8: "rgba(142, 148, 156, 0.1) 0px 2px 4px, rgba(142, 148, 156, 0.06) 0px 1px 2px" // 阴影效果
});
- 主题重置：向setTheme()传入null，可恢复当前预设主题（Light/Dark）的默认样式：
Designer.setTheme(null); // 恢复系统预设主题
- 状态查询：通过getTheme()获取当前完整主题配置（含继承的预设值）：
let currentTheme = GC.Spread.Sheets.Designer.getTheme();
console.log(currentTheme.colorBackground); // 输出当前背景色，如"#F0F4F8"
2. 用 CSS 静态覆盖
在全局 CSS 中定义主题变量（tokens），直接覆盖默认值，适合无需运行时修改的静态项目：
:root {
--sjs-color-background: #F0F4F8; // 所有标准组件的背景色
--sjs-color-foreground: #2D3436; // 所有常规文本的颜色
--sjs-border-radius-m: 6px; // 中等边框圆角
--sjs-shadow-8: rgba(142, 148, 156, 0.1) 0px 2px 4px, rgba(142, 148, 156, 0.06) 0px 1px 2px; // 阴影效果
}
3. 用 JavaScript 动态更新
通过操作 DOM 修改主题变量，支持无刷新切换主题，适合用户自主选择主题的场景：
// 动态设置主题属性
document.documentElement.style.setProperty(GC.Spread.Sheets.Designer.ThemeTokens.colorBackground, '#F0F4F8');
document.documentElement.style.setProperty(GC.Spread.Sheets.Designer.ThemeTokens.colorForeground, '#2D3436');
document.documentElement.style.setProperty(GC.Spread.Sheets.Designer.ThemeTokens.borderRadiusM, '6px');
四、主题属性参考：精准控制每一处视觉细节
SpreadJS 提供GC.Spread.Sheets.Designer.ITheme与GC.Spread.Sheets.Designer.ThemeTokens两大核心 API，涵盖颜色、边框、阴影三大类可配置属性，以下为关键属性说明：
| 类别 | 属性（Property） | 对应令牌（Token） | 功能描述 |
|---|---|---|---|
| 文本颜色 | colorForeground | --sjs-color-foreground | 常规文本颜色 |
| colorForegroundDisabled | --sjs-color-foreground-disabled | 组件禁用时的文本颜色 | |
| 背景颜色 | colorBackground | --sjs-color-background | 标准组件背景色 |
| colorBackgroundSelected | --sjs-color-background-selected | 组件选中时的背景色 | |
| colorBrandBackground | --sjs-color-brand-background | 品牌主色背景（用于突出品牌风格的组件） | |
| 边框颜色 | colorStroke | --sjs-color-stroke | 基础边框颜色 |
| colorStrokeHover | --sjs-color-stroke-hover | 组件悬浮时的边框颜色 | |
| 边框圆角 | borderRadiusM | --sjs-border-radius-m | 中等边框圆角 |
| borderRadiusXL | --sjs-border-radius-xl | 超大边框圆角 | |
| 阴影 | shadow4 | --sjs-shadow-4 | 4px 模糊半径的阴影效果 |
| shadow8 | --sjs-shadow-8 | 8px 模糊半径的阴影效果 |
五、总结：Theme 新特性的核心价值
SpreadJS V18.2 的 Designer Theme 系统，通过“预设主题快速部署+自定义主题深度适配”的组合方案，实现了三大核心价值：
- 效率提升：3 种预设主题无需开发，开箱即用，降低界面搭建成本；
- 体验优化：Light/Dark 主题适配不同使用环境，Classic 主题兼容用户习惯；
- 品牌统一：支持 API、CSS、JS 多方式定制，确保电子表格界面与应用品牌风格高度一致。
无论是快速搭建标准界面，还是打造专属品牌化设计，SpreadJS V18.2 的 Theme 新特性都能提供灵活、高效的解决方案。
