主题

SpreadJS 设计器组件（Designer Component）引入了一套高级主题系统，支持四种不同的主题选项，可增强用户界面（UI）的自定义能力和适应性。这些主题包括三种预设主题——浅色主题（Light）、深色主题（Dark） 和经典主题（Classic），以及一套灵活的自定义主题系统。

浅色主题与深色主题采用符合现代显示偏好的设计，分别针对不同使用场景优化了视觉风格，确保高对比度和良好的可读性。
经典主题采用熟悉的中性美学风格，适合偏好传统电子表格界面的用户。
自定义主题系统允许开发人员调整设计器组件的外观，可修改颜色、边框圆角和阴影等属性，以匹配特定的应用程序品牌形象或独特的用户偏好。

这套多样化的主题体系确保 SpreadJS 设计器组件能无缝集成到各种用户场景中，在提供“开箱即用”便利性的同时，也为个性化 UI 设计提供了高度灵活性。

引入设计器主题 CSS 文件

为 SpreadJS 设计器组件实现不同主题，主要依赖于在项目中引入对应的 CSS 文件。若要应用特定主题，开发人员需在项目中显式链接相应的 CSS 文件，例如在 HTML 结构的 <head> 标签内添加 <link> 标签，并确保 href 属性指向正确的 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。该目录包含所有必要的预设主题文件，可简化获取和引用目标样式文件的流程。此外，也可根据偏好使用模块加载器导入主题。

注意：
每次应仅引用一个设计器主题 CSS 文件。

预设主题

每种预设主题都具有独特的视觉特征，差异体现在配色方案、对比度级别和风格细节上——包括选项卡平整度、边框圆角、阴影柔和度、图标优化，以及基于状态的色调（如悬停/选中状态）。这些差异不仅影响整体 UI 的协调性，还会改变功能区（Ribbon）、对话框（Dialogs）和面板（Panels）等关键组件的外观，确保每种主题都能匹配特定的美学偏好。

目前提供的预设主题如下：

主题名称	CSS 文件	快照（预览界面、对话框、面板）
浅色主题（默认）	gc.spread.sheets.designer.light.x.x.x.min.css
深色主题	gc.spread.sheets.designer.dark.x.x.x.min.css
经典主题	gc.spread.sheets.designer.x.x.x.min.css

注意：
在 18.2.0 版本之前，SpreadJS 设计器仅提供经典主题（Classic） 这一种 UI 样式选项。

自定义主题系统

为 SpreadJS 设计器创建自定义主题时，必须首先以浅色主题或深色主题这两种预设主题为基础——这些预设主题将作为自定义的底层框架。选择基础主题后，可通过 API 调用、CSS 覆盖或 JavaScript 修改，进一步调整 UI 的视觉属性（如颜色、边框圆角或阴影），以匹配应用程序独特的品牌形象或用户体验目标。

通过 API 自定义

若要动态实现自定义主题，可使用 setTheme 方法。这种方式支持在运行时修改主题，同时保留底层主题架构。setTheme() 方法接受一个 Partial<GC.Spread.Sheets.Designer.ITheme> 对象，用于指定需修改的目标属性；仅已定义的属性会覆盖现有值，支持部分主题更新。示例如下：

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，可恢复为当前激活的预设主题（浅色/深色）默认值：
```
Designer.setTheme(null); // 恢复为系统预设主题  
```

当前配置获取：使用 getTheme() 方法可获取完整的主题状态（包括继承的预设主题值）：

let currentTheme = GC.Spread.Sheets.Designer.getTheme();
console.log(currentTheme.colorBackground); // 输出 "#F0F4F8"

通过 CSS 或 JS 自定义

SpreadJS 设计器支持通过 CSS 变量（令牌）和 JavaScript DOM 操作实现动态主题自定义，主要提供三种方式：

1. 静态主题覆盖（CSS）

在全局 CSS 中直接定义主题令牌，以覆盖默认值：

: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;  // 阴影效果
}

适用场景：静态应用中的永久性主题设置，无需运行时修改。

2. 动态运行时更新（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'); 
document.documentElement.style.setProperty(GC.Spread.Sheets.Designer.ThemeTokens.shadow8, 'rgba(142, 148, 156, 0.1) 0px 2px 4px, rgba(142, 148, 156, 0.06) 0px 1px 2px');

优势：支持无需刷新页面即可切换主题，适用于用户驱动的主题偏好设置。

3. 程序化规则注入

通过 JavaScript 动态生成 CSS 规则，适用于复杂的主题场景：

export function createCSSRule (selector: string, theme: GC.Spread.Sheets.Designer.ITheme | undefined): string {
    if (theme) {
        const cssVarsAsString = (Object.keys(theme) as (keyof typeof theme)[]).reduce((cssVarRule, cssVar) => {
            return `${cssVarRule}${GC.Spread.Sheets.Designer.ThemeTokens[cssVar]}: ${theme[cssVar]}; `;
        }, '');
        return `${selector} { ${cssVarsAsString} }`;
    }
    return `${selector} {}`;
}
let customThemeRule = createCSSRule(":root", {
  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",
});
let customStyleElement = document.createElement("style");
customStyleElement.sheet?.insertRule(customThemeRule);
document.head.appendChild(customStyleElement);

适用场景：批量应用主题，或为具有复杂变量依赖关系的组件设置主题。

注意：
可配置的主题令牌完整列表（包括颜色、边框圆角和阴影）将在本指南后续的“主题属性参考”章节中详细说明。

主题属性参考

SpreadJS 提供两个核心 API——GC.Spread.Sheets.Designer.ITheme 和 GC.Spread.Sheets.Designer.ThemeTokens，支持开发人员对主题进行精细化自定义控制。无论是调整颜色、边框圆角还是阴影，理解这两个 API 中的属性和令牌都是实现设计器外观定制的关键。

下方表格详细列出了 ITheme 中的所有属性、对应的 ThemeTokens 变量，以及它们对 UI 元素（从背景色到交互状态）的实际影响：

	属性（Property）	令牌（Token）	描述（Description）
1	colorForeground	--sjs-color-foreground	常规前景色，用于所有常规文本的颜色。
2	colorForegroundDisabled	--sjs-color-foreground-disabled	组件禁用时，常规文本的颜色。
3	colorBackground	--sjs-color-background	常规背景色，用于所有标准组件的背景。
4	colorBackgroundHover	--sjs-color-background-hover	标准组件处于悬停状态时的背景色。
5	colorBackgroundSelected	--sjs-color-background-selected	标准组件处于选中状态时的背景色。
6	colorBackgroundDisabled	--sjs-color-background-disable	标准组件处于禁用状态时的背景色。
7	colorBackground2	--sjs-color-background-2	设计器中最底层容器的背景色。
8	colorBackground2Hover	--sjs-color-background-2-hover	最底层容器的组件处于悬停状态时的背景色。
9	colorBackground2Selected	--sjs-color-background-2-selected	最底层容器的组件处于选中状态时的背景色。
10	colorBrandForeground	--sjs-color-brand-foreground	品牌背景色上方的文本颜色。
11	colorBrandBackground	--sjs-color-brand-background	代表品牌的颜色，用作产品的颜色标识，适用于需要突出显示或体现品牌风格的组件背景。
12	colorBrandBackgroundHover	--sjs-color-brand-background-hover	品牌背景色处于悬停状态时的颜色。
13	colorBrandBackgroundSelected	--sjs-color-brand-background-selected	品牌背景色处于选中状态时的颜色。
14	colorStroke	--sjs-color-stroke	边框颜色。
15	colorStrokeHover	--sjs-color-stroke-hover	组件处于悬停状态时的边框颜色。
16	colorStrokeSelected	--sjs-color-stroke-selected	组件处于选中状态时的边框颜色。
17	colorStrokeDisabled	--sjs-color-stroke-disabled	组件处于禁用状态时的边框颜色。
18	borderRadiusM	--sjs-border-radius-m	中等边框圆角。
19	borderRadiusL	--sjs-border-radius-l	大边框圆角。
20	borderRadiusXL	--sjs-border-radius-xl	特大边框圆角。
21	shadow4	--sjs-shadow-4	模糊半径为 4px 的阴影。
22	shadow8	--sjs-shadow-8	模糊半径为 8px 的阴影。