条件格式

预设模式插件模式

预设信息

@univerjs/preset-sheets-conditional-formatting

需要服务端支持

否

条件格式功能允许用户根据特定条件自动更改单元格的格式，以便突出显示重要数据或趋势。它支持多种条件和格式设置选项，帮助用户更直观地理解数据。

预设模式

安装

npm install @univerjs/preset-sheets-conditional-formatting

使用

import { UniverSheetsConditionalFormattingPreset } from '@univerjs/preset-sheets-conditional-formatting'
import UniverPresetSheetsConditionalFormattingZhCN from '@univerjs/preset-sheets-conditional-formatting/locales/zh-CN'
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-conditional-formatting/lib/index.css'

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetSheetsCoreZhCN,
      UniverPresetSheetsConditionalFormattingZhCN, 
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsConditionalFormattingPreset(), 
  ],
})

插件模式

安装

npm install @univerjs/sheets-conditional-formatting @univerjs/sheets-conditional-formatting-ui

使用

import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverSheetsConditionalFormattingPlugin } from '@univerjs/sheets-conditional-formatting'
import { UniverSheetsConditionalFormattingUIPlugin } from '@univerjs/sheets-conditional-formatting-ui'
import SheetsConditionalFormattingUIZhCN from '@univerjs/sheets-conditional-formatting-ui/locale/zh-CN'

import '@univerjs/sheets-conditional-formatting-ui/lib/index.css'

import '@univerjs/sheets-conditional-formatting/facade'

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      SheetsConditionalFormattingUIZhCN, 
    ),
  },
})

univer.registerPlugin(UniverSheetsConditionalFormattingPlugin) 
univer.registerPlugin(UniverSheetsConditionalFormattingUIPlugin)

Facade API

完整 Facade API 类型定义，请查看 FacadeAPI

创建条件格式规则

FWorksheet.newConditionalFormattingRule() 创建一个条件格式构建器，返回一个 FConditionalFormattingBuilder 实例，可以通过链式调用生成条件格式规则。

以下是 FConditionalFormattingBuilder 上的一些成员方法：

方法	描述
build	构建条件格式规则
setRanges	设置条件格式规则应用的范围
setAverage	设置平均值条件格式规则
setUniqueValues	设置唯一值条件格式规则
setDuplicateValues	设置重复值条件格式规则
setRank	设置排名条件格式规则
setIconSet	设置图标集条件格式规则
setColorScale	设置色阶条件格式规则
setDataBar	设置数据条条件格式规则
setBackground	设置条件格式的背景色
setBold	设置条件格式的字体是否加粗
setFontColor	设置条件格式的字体颜色
setItalic	设置条件格式的字体是否斜体
setStrikethrough	设置条件格式的字体是否有删除线
setUnderline	设置条件格式的字体是否有下划线
whenCellEmpty	设置条件格式规则在单元格为空时触发
whenCellNotEmpty	设置条件格式规则在单元格非空时触发
whenDate	设置条件格式规则在日期为满足特定时间段时触发
whenFormulaSatisfied	设置条件格式规则在公式计算结果为 true 时触发
whenNumberBetween	设置条件格式规则在数字介于两个指定值之间或等于其中一个值时触发
whenNumberEqualTo	设置条件格式规则在数字等于给定值时触发
whenNumberGreaterThan	设置条件格式规则在数字大于给定值时触发
whenNumberGreaterThanOrEqualTo	设置条件格式规则在数字大于或等于给定值时触发
whenNumberLessThan	设置条件格式规则在数字小于给定值时触发
whenNumberLessThanOrEqualTo	设置条件格式规则在数字小于或等于给定值时触发
whenNumberNotBetween	设置条件格式规则在数字不介于两个指定值之间且不等于这两个值时触发
whenNumberNotEqualTo	设置条件格式规则在数字不等于给定值时触发
whenTextContains	设置条件格式规则在文本包含指定值时触发
whenTextDoesNotContain	设置条件格式规则在文本不包含指定值时触发
whenTextEndsWith	设置条件格式规则在文本以指定值结尾时触发
whenTextEqualTo	设置条件格式规则在文本等于给定值时触发
whenTextStartsWith	设置条件格式规则在文本以指定值开头时触发

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个条件格式规则，使范围 A1:T100 中的非空单元格字体变为斜体，背景色为红色，字体颜色为绿色
const fRange = fWorksheet.getRange('A1:T100')
const rule = fWorksheet.newConditionalFormattingRule()
  .whenCellNotEmpty()
  .setRanges([fRange.getRange()])
  .setItalic(true)
  .setBackground('red')
  .setFontColor('green')
  .build()
fWorksheet.addConditionalFormattingRule(rule)

获取条件格式规则

FWorksheet.getConditionalFormattingRules() 获取工作表的所有条件格式规则
FRange.getConditionalFormattingRules() 获取范围的所有条件格式规则

const fWorkbook = univerAPI.getActiveWorkbook()

// 获取活动工作表的所有条件格式规则
const fWorksheet = fWorkbook.getActiveSheet()
const rulesOfSheet = fWorksheet.getConditionalFormattingRules()

// 获取范围 A1:T100 的所有条件格式规则
const fRange = fWorksheet.getRange('A1:T100')
const rulesOfRange = fRange.getConditionalFormattingRules()

删除条件格式规则

FWorksheet.deleteConditionalFormattingRule(cfId) 方法可以删除工作表的条件格式规则，cfId 为条件格式规则的 id。

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const rules = fWorksheet.getConditionalFormattingRules()

// 删除第一个规则
fWorksheet.deleteConditionalFormattingRule(rules[0]?.cfId)

更新条件格式规则

FWorksheet.setConditionalFormattingRule(cfId, rule) 方法可以更新工作表的条件格式规则，cfId 为条件格式规则的 id，rule 为新的条件格式规则。

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个条件格式规则，使非空单元格字体变为斜体，背景色为红色，字体颜色为绿色
const fRange = fWorksheet.getRange('A1:T100')
const rule = fWorksheet.newConditionalFormattingRule()
  .whenCellNotEmpty()
  .setRanges([fRange.getRange()])
  .setItalic(true)
  .setBackground('red')
  .setFontColor('green')
  .build()
fWorksheet.addConditionalFormattingRule(rule)

// 修改第一个规则应用到新的范围
const rules = fWorksheet.getConditionalFormattingRules()
const newRuleRange = fWorksheet.getRange('A1:D10')
fWorksheet.setConditionalFormattingRule(rules[0]?.cfId, { ...rules[0], ranges: [newRuleRange.getRange()] })

修改条件格式规则的优先级

FWorksheet.moveConditionalFormattingRule(cfId, toCfId, type) 方法可以修改工作表的条件格式规则的优先级，cfId 为条件格式规则的 id，toCfId 为目标条件格式规则的 id，type 为移动类型。

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const rules = fWorksheet.getConditionalFormattingRules()

// 移动第三个规则到第一个规则之前
const rule = rules[2]
const targetRule = rules[0]
fWorksheet.moveConditionalFormattingRule(rule?.cfId, targetRule?.cfId, 'before')

清除所有条件格式规则

FWorksheet.clearConditionalFormatRules() 清除工作表的所有条件格式规则
FRange.clearConditionalFormatRules() 清除范围的所有条件格式规则

const fWorkbook = univerAPI.getActiveWorkbook()

// 清除活动工作表的所有条件格式规则
const fWorksheet = fWorkbook.getActiveSheet()
fWorksheet.clearConditionalFormatRules()

// 清除范围 A1:T100 的所有条件格式规则
const fRange = fWorksheet.getRange('A1:T100')
fRange.clearConditionalFormatRules()

目录