Web SDK

條件格式

條件格式功能允許使用者根據特定條件自動更改單元格的格式，以便突出顯示重要資料或趨勢。它支援多種條件和格式設定選項，幫助使用者更直觀地理解資料。

外掛模式

安裝

Shell
pnpm add @univerjs/sheets-conditional-formatting @univerjs/sheets-conditional-formatting-ui

使用

TypeScript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverSheetsConditionalFormattingPlugin } from '@univerjs/sheets-conditional-formatting'import { UniverSheetsConditionalFormattingUIPlugin } from '@univerjs/sheets-conditional-formatting-ui'import SheetsConditionalFormattingUIZhTW from '@univerjs/sheets-conditional-formatting-ui/locale/zh-TW'import '@univerjs/sheets-conditional-formatting-ui/lib/index.css'import '@univerjs/sheets-conditional-formatting/facade'const univer = new Univer({  locale: LocaleType.ZH_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      SheetsConditionalFormattingUIZhTW,     ),  },})univer.registerPlugin(UniverSheetsConditionalFormattingPlugin)univer.registerPlugin(UniverSheetsConditionalFormattingUIPlugin)

行動裝置支援

先設定行動版編輯器。在本頁外掛模式的初始化程式碼中，將下列桌面版註冊替換為同一套件匯出的行動版外掛，並在開啟文件前完成。保留模型外掛、樣式、語言套件與 Facade 匯入，請勿同時註冊兩個版本。

套件桌面版註冊行動版註冊
@univerjs/sheets-conditional-formatting-uiUniverSheetsConditionalFormattingUIPluginUniverSheetsConditionalFormattingMobileUIPlugin

預設模式

安裝

Shell
pnpm add @univerjs/preset-sheets-conditional-formatting

使用

TypeScript
import { UniverSheetsConditionalFormattingPreset } from '@univerjs/preset-sheets-conditional-formatting'import UniverPresetSheetsConditionalFormattingZhTW from '@univerjs/preset-sheets-conditional-formatting/locales/zh-TW'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'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_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      UniverPresetSheetsCoreZhTW,      UniverPresetSheetsConditionalFormattingZhTW,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsConditionalFormattingPreset(),   ],})

Facade API

完整 Facade API 型別定義，請檢視 FacadeAPI

引入

外掛模式提示

僅外掛模式需要手動引入 Facade 套件。預設模式已內建對應的 Facade 套件，無需額外引入。

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

建立條件格式規則

FWorksheet.newConditionalFormattingRule() 建立一個條件格式構建器，返回一個 FConditionalFormattingBuilder 例項，可以透過鏈式呼叫生成條件格式規則。

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

方法描述
build構建條件格式規則
copy深拷貝目前構建器
createCfId建立條件格式 ID
getRanges取得目前條件格式的範圍
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設定條件格式規則在文字以指定值開頭時觸發
TypeScript
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() 獲取範圍的所有條件格式規則
TypeScript
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。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const rules = fWorksheet.getConditionalFormattingRules()// 刪除第一個規則fWorksheet.deleteConditionalFormattingRule(rules[0]?.cfId)

更新條件格式規則

FWorksheet.setConditionalFormattingRule(cfId, rule) 方法可以更新工作表的條件格式規則，cfId 為條件格式規則的 id，rule 為新的條件格式規則。

TypeScript
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 為移動型別。

TypeScript
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() 清除範圍的所有條件格式規則
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()// 清除活動工作表的所有條件格式規則const fWorksheet = fWorkbook.getActiveSheet()fWorksheet.clearConditionalFormatRules()// 清除範圍 A1:T100 的所有條件格式規則const fRange = fWorksheet.getRange('A1:T100')fRange.clearConditionalFormatRules()

重用規則描述與預覽

自訂規則清單時，可從 @univerjs/sheets-conditional-formatting-ui 匯入 getRuleDescribe 和 ConditionalFormattingRulePreview。前者接收完整規則 getRuleDescribe(rule, localeService)，後者只接收規則設定 rule.rule。預覽顯示設定的外觀，不會計算工作表儲存格的實際結果；請在 Univer 的 React 上下文中呈現。

CF_PANEL_KEY 是內建面板的元件覆寫識別碼。面板屬性 IConditionFormattingPanelProps.onEditorExit 在提交、取消或工作表啟用／移除導致編輯結束時觸發，不代表儲存成功，也不代表側邊欄關閉。

TSX
import type { IConditionFormattingRule } from '@univerjs/sheets-conditional-formatting'import { LocaleService } from '@univerjs/core'import { ConditionalFormattingRulePreview, getRuleDescribe } from '@univerjs/sheets-conditional-formatting-ui'import { useDependency } from '@univerjs/ui'interface IRuleSummaryProps {  rule: IConditionFormattingRule}function RuleSummary({ rule }: IRuleSummaryProps) {  const localeService = useDependency(LocaleService)  return (    <div>      <span>{getRuleDescribe(rule, localeService)}</span>      <ConditionalFormattingRulePreview rule={rule.rule} />    </div>  )}

你覺得這篇文檔如何？

© 2026 DreamNum Co., Ltd.