范围主题 0.5.3+

Facade API	可付费升级	需要 Univer 服务端	Univer on Node.js	Preset
✅	-	-	-	UniverSheetsCorePreset

为了丰富表格的展示效果，我们提供了一些预设的区域主题，也开放了定制主题的能力，供 Univer 用户使用。

预设主题

我们提供类似 Excel Table 默认样式的主题作为默认主题，主题名称为 default ，可通过 theme 属性设置。同时提供了一系列的 color 主题，你可以通过以下 Facade API 获取当前支持的主题。


const fWorkbook = univerAPI.getActiveWorkbook();
const themes = fWorkbook.getRegisteredRangeThemes();
console.log(themes); // ['default', 'light-blue', 'light-grey', 'light-red', 'light-orange', 'light-yellow', 'light-green', 'light-azure', 'light-indigo', 'light-purple', 'light-magenta', 'middle-blue', 'middle-grey', 'middle-red', 'middle-orange', 'middle-yellow', 'middle-green', 'middle-azure', 'middle-indigo', 'middle-purple', 'middle-magenta', 'dark-blue', 'dark-grey', 'dark-red', 'dark-orange', 'dark-yellow', 'dark-green', 'dark-azure', 'dark-indigo', 'dark-purple', 'dark-magenta']

Range Theme

设置主题

在 Univer 中您可以通过以下两种方式来设置主题：

通过设置 snapshot 来支持主题
通过 Facade API 来支持主题

通过设置 snapshot 来设置主题

Univer 的主题存储在 snapshot 的 resource 中， key 值为 SHEET_RANGE_THEME_MODEL_PLUGIN ，数据结构如下：


interface IRangeThemeRangeInfo {
  range: IRange;
  unitId: string;
  subUnitId: string;
}
 
interface IRangeThemeStyleRule {
  rangeInfo: IRangeThemeRangeInfo;
  themeName: string;
}
 
interface ISheetRangeThemeModelJSON {
  // 存储设置主题的 range，theme 信息的 json, key 为 id 只要保证不重复即可, value 位对应的 range 信息以及模板名称
  rangeThemeStyleRuleMap: Record<string, IRangeThemeStyleRule>;
  // 存储主题的 json, key 为 主题名称， value 为主题序列化json
  rangeThemeStyleMapJson: Record<string, IRangeThemeStyleJSON>;
}

通过 Facade API 来设置主题

我们推荐使用 Facade API 来设置主题，再利用 Univer 提供的序列化反序列化方法来存储主题信息。

以下是主题相关的一些 API 介绍：


// 获取当前支持的主题
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const themes = fWorkbook.getRegisteredRangeThemes();
console.log(themes);
 
// A1:E20 设置默认主题
const fRange = fWorksheet.getRange('A1:E20');
fRange.useThemeStyle('default'); // 使用默认主题
 
// 获取当前使用的主题
const currentTheme = fRange.getUsedThemeStyle();
console.log(currentTheme);
 
// 清除主题样式
fRange.useThemeStyle(undefined);
fRange.removeThemeStyle(currentTheme);

自定义主题

Univer 除了内置主题，还提供了自定义主题的能力，你可以通过以下 API 来自定义主题：


// 创建自定义主题
const fWorkbook = univerAPI.getActiveWorkbook();
const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {
  secondRowStyle: {
    bg: {
      rgb: 'rgb(214,231,241)',
    }
  }
});
fWorkbook.registerRangeTheme(rangeThemeStyle);
 
// A1:E20 使用自定义主题
const fWorksheet = fWorkbook.getActiveSheet();
const fRange = fWorksheet.getRange('A1:E20');
// 请保证主题已经注册，否则会报错
fRange.useThemeStyle('MyTheme');

我们也提供了删除注册主题的 API ：


const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.unregisterRangeTheme('MyTheme');

RangeThemeStyle 类

Univer 主题的核心类 RangeThemeStyle 上提供提供了以下属性供用户自定义主题：

name: 主题名称
wholeStyle: 整个区域的样式
firstRowStyle: 第一行的样式
secondRowStyle: 第二行的样式
headerRowStyle: 表头行的样式
lastRowStyle: 最后一行的样式
firstColumnStyle: 第一列的样式
secondColumnStyle: 第二列的样式
headerColumnStyle: 表头列的样式
lastColumnStyle: 最后一列的样式

在 RangeThemeStyle 类上可以通过 getXXX/setXXX 方法来获取/设置样式，例如：


const rangeThemeStyle = new RangeThemeStyle('MyTheme');
rangeThemeStyle.setSecondRowStyle({
  bg: {
    rgb: 'rgb(214,231,241)',
  },
});

也可以在创建的时候使用可选参数直接创建:


/**
 * @constructor
 * @param {string} name The name of the range theme style, it used to identify the range theme style.
 * @param {IRangeThemeStyleJSON} [options] The options to initialize the range theme style.
 */
class RangeThemeStyle{};
 
// 示例
const rangeThemeStyle = new RangeThemeStyle('MyTheme', {
  secondRowStyle: {
    bg: {
      rgb: 'rgb(214,231,241)',
    },
  },
});

当您定义了多个样式时，会按照以下优先级来应用样式：

lastRowStyle > headerRowStyle > lastColumnStyle > headerColumnStyle > secondRowStyle > firstRowStyle > secondColumnStyle > firstColumnStyle > wholeStyle

同时，如果某个单元格定义的样式与 range theme 中的样式冲突时，会以单元格样式为准。这里的冲突是指同时在 style data 中定义相同的样式属性，比如单元格样式中定义了背景色为红色，而 range theme 中定义了背景色为蓝色，那么单元格的背景色会是红色。