Range Theme

To enrich the display effects of tables, we provide some preset range themes and open the ability to customize themes for Univer users.

Built-in Themes

We provide a theme similar to the Excel Table default style as the default theme, named default, which can be set through the theme attribute. We also provide a series of color themes, which you can get through the following Facade API to see the currently supported themes.

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

Setting Themes

In Univer, you can set themes in the following two ways:

Support themes by setting snapshots
Support themes through the Facade API

Setting Themes by Snapshots

The themes in Univer are stored in the snapshot's resource with the key SHEET_RANGE_THEME_MODEL_PLUGIN. The data structure is as follows:

interface IRangeThemeRangeInfo {
  range: IRange
  unitId: string
  subUnitId: string
}

interface IRangeThemeStyleRule {
  rangeInfo: IRangeThemeRangeInfo
  themeName: string
}

interface ISheetRangeThemeModelJSON {
  // JSON storing the range and theme information for setting themes, the key is the id, please ensure it is not repeated, the value is the corresponding range information and template name.
  rangeThemeStyleRuleMap: Record<string, IRangeThemeStyleRule>
  // JSON storing the themes, the key is the theme name, and the value is the serialized JSON of the theme.
  rangeThemeStyleMapJson: Record<string, IRangeThemeStyleJSON>
}

Setting Themes through Facade API

We recommend using the Facade API to set themes and then using the serialization and deserialization methods provided by Univer to store theme information.

Here are some API introductions related to themes:

// Get the currently supported themes
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const themes = fWorkbook.getRegisteredRangeThemes()

// Set the default theme for A1:E20
const fRange = fWorksheet.getRange('A1:E20')
fRange.useThemeStyle('default') // 使用默认主题

// Get the currently used theme
const currentTheme = fRange.getUsedThemeStyle()

// Clear the theme style
fRange.useThemeStyle(undefined)
fRange.removeThemeStyle(currentTheme)

Custom Themes

Univer provides the ability to customize themes in addition to built-in themes. You can customize themes using the following API:

// Create a custom theme
const fWorkbook = univerAPI.getActiveWorkbook()
const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {
  secondRowStyle: {
    bg: {
      rgb: 'rgb(214,231,241)',
    },
  },
})
fWorkbook.registerRangeTheme(rangeThemeStyle)

// Use the custom theme for A1:E20
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:E20')
// Make sure the theme is registered, otherwise it will throw an error.
fRange.useThemeStyle('MyTheme')

Univer also provides an API to delete registered themes:

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

`RangeThemeStyle` Class

The core class of Univer themes, RangeThemeStyle, provides the following properties for users to customize themes:

name: Theme name
wholeStyle: Style for the entire range
firstRowStyle: Style for the first row
secondRowStyle: Style for the second row
headerRowStyle: Style for the header row
lastRowStyle: Style for the last row
firstColumnStyle: Style for the first column
secondColumnStyle: Style for the second column
headerColumnStyle: Style for the header column
lastColumnStyle: Style for the last column

You can use the getXXX/setXXX methods in the RangeThemeStyle class to get/set styles, for example:

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

Alternatively, you can create it directly with optional parameters during instantiation:

/**
 * @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 {};

// For example:
const rangeThemeStyle = new RangeThemeStyle('MyTheme', {
  secondRowStyle: {
    bg: {
      rgb: 'rgb(214,231,241)',
    },
  },
})

When you define multiple styles, they will be applied in the following order of priority:

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

If a cell's defined style conflicts with the style in the range theme, the cell's style will take precedence. A conflict here refers to defining the same style property in both the cell's style data and the range theme. For example, if the cell's style defines a background color of red while the range theme defines it as blue, the cell's background color will be red.