org.apache.poi.ss.formula

Class ConditionalFormattingEvaluator

java.lang.Object

org.apache.poi.ss.formula.ConditionalFormattingEvaluator

public class ConditionalFormattingEvaluator
extends java.lang.Object

Evaluates Conditional Formatting constraints.

For performance reasons, this class keeps a cache of all previously evaluated rules and cells. Be sure to call clearAllCachedFormats() if any conditional formats are modified, added, or deleted, and clearAllCachedValues() whenever cell values change.

(评估条件格式约束。出于性能原因，此类保留所有先前评估的规则和单元的缓存。如果有任何条件格式被修改、添加或删除，请务必调用 clearAllCachedFormats()，并在单元格值更改时调用 clearAllCachedValues()。)

Constructor Summary

Constructors

Constructor and Description
ConditionalFormattingEvaluator(Workbook wb, WorkbookEvaluatorProvider provider)

Method Summary

Modifier and Type	Method and Description
void	clearAllCachedFormats() Call this whenever rules are added, reordered, or removed, or a rule formula is changed (not the formula inputs but the formula expression itself) (每当添加、重新排序或删除规则或更改规则公式（不是公式输入而是公式表达式本身）时调用此函数)
void	clearAllCachedValues() Call this whenever cell values change in the workbook, so condional formats are re-evaluated for all cells. (每当工作簿中的单元格值发生变化时调用此函数，以便为所有单元格重新评估条件格式。)
java.util.List<EvaluationConditionalFormatRule>	getConditionalFormattingForCell(Cell cell) This checks all applicable ConditionalFormattingRules for the cell's sheet, in defined "priority" order, returning the matches if any. (这将按照定义的“优先级”顺序检查单元格工作表的所有适用 ConditionalFormattingRules，如果有匹配项，则返回匹配项。)
java.util.List<EvaluationConditionalFormatRule>	getConditionalFormattingForCell(CellReference cellRef) This checks all applicable ConditionalFormattingRules for the cell's sheet, in defined "priority" order, returning the matches if any. (这将按照定义的“优先级”顺序检查单元格工作表的所有适用 ConditionalFormattingRules，如果有匹配项，则返回匹配项。)
java.util.List<EvaluationConditionalFormatRule>	getFormatRulesForSheet(Sheet sheet) Retrieve all formatting rules for the given sheet. (检索给定工作表的所有格式规则。)
java.util.List<EvaluationConditionalFormatRule>	getFormatRulesForSheet(java.lang.String sheetName) Retrieve all formatting rules for the sheet with the given name. (检索具有给定名称的工作表的所有格式规则。)
java.util.List<Cell>	getMatchingCells(EvaluationConditionalFormatRule rule) Retrieve all cells where the given formatting rule evaluates to true. (检索给定格式规则评估为真的所有单元格。)
java.util.List<Cell>	getMatchingCells(Sheet sheet, int conditionalFormattingIndex, int ruleIndex) Conditional formatting rules can apply only to cells in the sheet to which they are attached. (条件格式规则只能应用于它们所附加到的工作表中的单元格。)
static CellReference	getRef(Cell cell)
protected java.util.List<EvaluationConditionalFormatRule>	getRules(Sheet sheet) lazy load by sheet since reading can be expensive (延迟加载，因为阅读可能很昂贵)
protected WorkbookEvaluator	getWorkbookEvaluator()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ConditionalFormattingEvaluator

public ConditionalFormattingEvaluator(Workbook wb,
                                      WorkbookEvaluatorProvider provider)

Method Detail

getWorkbookEvaluator

protected WorkbookEvaluator getWorkbookEvaluator()

clearAllCachedFormats

public void clearAllCachedFormats()

Call this whenever rules are added, reordered, or removed, or a rule formula is changed (not the formula inputs but the formula expression itself) (每当添加、重新排序或删除规则或更改规则公式（不是公式输入而是公式表达式本身）时调用此函数)

clearAllCachedValues

public void clearAllCachedValues()

Call this whenever cell values change in the workbook, so condional formats are re-evaluated for all cells.

TODO: eventually this should work like EvaluationCache.notifyUpdateCell(int, int, EvaluationCell) and only clear values that need recalculation based on the formula dependency tree.

(每当工作簿中的单元格值发生变化时调用此函数，以便为所有单元格重新评估条件格式。 TODO：最终这应该像 EvaluationCache.notifyUpdateCell(int, int, EvaluationCell) 一样工作，并且只清除需要基于公式依赖树重新计算的值。)

getRules

protected java.util.List<EvaluationConditionalFormatRule> getRules(Sheet sheet)

lazy load by sheet since reading can be expensive (延迟加载，因为阅读可能很昂贵)

Parameters:

sheet - The sheet to look at (sheet - 要查看的工作表)

Returns:

unmodifiable list of rules (不可修改的规则列表)

getConditionalFormattingForCell

public java.util.List<EvaluationConditionalFormatRule> getConditionalFormattingForCell(CellReference cellRef)

This checks all applicable ConditionalFormattingRules for the cell's sheet, in defined "priority" order, returning the matches if any. This is a property currently not exposed from CTCfRule in XSSFConditionalFormattingRule.

Most cells will have zero or one applied rule, but it is possible to define multiple rules that apply at the same time to the same cell, thus the List result.

Note that to properly apply conditional rules, care must be taken to offset the base formula by the relative position of the current cell, or the wrong value is checked. This is handled by WorkbookEvaluator.evaluate(String, CellReference, CellRangeAddressBase).

If the cell exists and is a formula cell, its cached value may be used for rule evaluation, so make sure it is up to date. If values have changed, it is best to call FormulaEvaluator.evaluateFormulaCell(Cell) or FormulaEvaluator.evaluateAll() first, or the wrong conditional results may be returned.

(这将按照定义的“优先级”顺序检查单元格工作表的所有适用 ConditionalFormattingRules，如果有匹配项，则返回匹配项。这是当前未从 XSSFConditionalFormattingRule 中的 CTCfRule 公开的属性。大多数单元格将有零个或一个应用规则，但可以定义同时应用于同一单元格的多个规则，因此是 List 结果。请注意，要正确应用条件规则，必须注意将基本公式偏移当前单元格的相对位置，否则会检查错误的值。这由 WorkbookEvaluator.evaluate(String, CellReference, CellRangeAddressBase) 处理。如果单元格存在并且是公式单元格，则其缓存值可用于规则评估，因此请确保它是最新的。如果值发生了变化，最好先调用 FormulaEvaluator.evaluateFormulaCell(Cell) 或 FormulaEvaluator.evaluateAll()，否则可能返回错误的条件结果。)

Parameters:

cellRef - NOTE: if no sheet name is specified, this uses the workbook active sheet (cellRef - 注意：如果未指定工作表名称，则使用工作簿活动工作表)

Returns:

Unmodifiable List of EvaluationConditionalFormatRules that apply to the current cell value, in priority order, as evaluated by Excel (smallest priority # for XSSF, definition order for HSSF), or null if none apply (适用于当前单元格值的评估条件格式规则的不可修改列表，按优先级顺序，由 Excel 评估（XSSF 的最小优先级 #，HSSF 的定义顺序），如果不适用，则为 null)

getConditionalFormattingForCell

public java.util.List<EvaluationConditionalFormatRule> getConditionalFormattingForCell(Cell cell)

This checks all applicable ConditionalFormattingRules for the cell's sheet, in defined "priority" order, returning the matches if any. This is a property currently not exposed from CTCfRule in XSSFConditionalFormattingRule.

Most cells will have zero or one applied rule, but it is possible to define multiple rules that apply at the same time to the same cell, thus the List result.

Note that to properly apply conditional rules, care must be taken to offset the base formula by the relative position of the current cell, or the wrong value is checked. This is handled by WorkbookEvaluator.evaluate(String, CellReference, CellRangeAddressBase).

If the cell exists and is a formula cell, its cached value may be used for rule evaluation, so make sure it is up to date. If values have changed, it is best to call FormulaEvaluator.evaluateFormulaCell(Cell) or FormulaEvaluator.evaluateAll() first, or the wrong conditional results may be returned.

(这将按照定义的“优先级”顺序检查单元格工作表的所有适用 ConditionalFormattingRules，如果有匹配项，则返回匹配项。这是当前未从 XSSFConditionalFormattingRule 中的 CTCfRule 公开的属性。大多数单元格将有零个或一个应用规则，但可以定义同时应用于同一单元格的多个规则，因此是 List 结果。请注意，要正确应用条件规则，必须注意将基本公式偏移当前单元格的相对位置，否则会检查错误的值。这由 WorkbookEvaluator.evaluate(String, CellReference, CellRangeAddressBase) 处理。如果单元格存在并且是公式单元格，则其缓存值可用于规则评估，因此请确保它是最新的。如果值发生了变化，最好先调用 FormulaEvaluator.evaluateFormulaCell(Cell) 或 FormulaEvaluator.evaluateAll()，否则可能返回错误的条件结果。)

Parameters:

cell - The cell to look for (cell - 要查找的单元格)

Returns:

Unmodifiable List of EvaluationConditionalFormatRules that apply to the current cell value, in priority order, as evaluated by Excel (smallest priority # for XSSF, definition order for HSSF), or null if none apply (适用于当前单元格值的评估条件格式规则的不可修改列表，按优先级顺序，由 Excel 评估（XSSF 的最小优先级 #，HSSF 的定义顺序），如果不适用，则为 null)

getRef

public static CellReference getRef(Cell cell)

getFormatRulesForSheet

public java.util.List<EvaluationConditionalFormatRule> getFormatRulesForSheet(java.lang.String sheetName)

Retrieve all formatting rules for the sheet with the given name. (检索具有给定名称的工作表的所有格式规则。)

Parameters:

sheetName - The name of the sheet to look at (sheetName - 要查看的工作表的名称)

Returns:

unmodifiable list of all Conditional format rules for the given sheet, if any (给定工作表的所有条件格式规则的不可修改列表（如果有）)

getFormatRulesForSheet

public java.util.List<EvaluationConditionalFormatRule> getFormatRulesForSheet(Sheet sheet)

Retrieve all formatting rules for the given sheet. (检索给定工作表的所有格式规则。)

Parameters:

sheet - The sheet to look at (sheet - 要查看的工作表)

Returns:

unmodifiable list of all Conditional format rules for the given sheet, if any (给定工作表的所有条件格式规则的不可修改列表（如果有）)

getMatchingCells

public java.util.List<Cell> getMatchingCells(Sheet sheet,
                                             int conditionalFormattingIndex,
                                             int ruleIndex)

Conditional formatting rules can apply only to cells in the sheet to which they are attached. The POI data model does not have a back-reference to the owning sheet, so it must be passed in separately.

We could overload this with convenience methods taking a sheet name and sheet index as well.

(条件格式规则只能应用于它们所附加到的工作表中的单元格。 POI 数据模型没有对所属工作表的反向引用，因此必须单独传入。我们可以使用带有工作表名称和工作表索引的便捷方法来重载它。)

Parameters:

sheet - containing the rule (sheet - 包含规则)

conditionalFormattingIndex - of the ConditionalFormatting instance in the sheet's array (conditionalFormattingIndex - 工作表数组中的 ConditionalFormatting 实例)

ruleIndex - of the ConditionalFormattingRule instance within the ConditionalFormatting (ruleIndex - ConditionalFormatting 中的 ConditionalFormattingRule 实例)

Returns:

unmodifiable List of all cells in the rule's region matching the rule's condition (规则区域中与规则条件匹配的所有单元格列表)

getMatchingCells

public java.util.List<Cell> getMatchingCells(EvaluationConditionalFormatRule rule)

Retrieve all cells where the given formatting rule evaluates to true. (检索给定格式规则评估为真的所有单元格。)

Parameters:

rule - The rule to look at (rule - 要查看的规则)

Returns:

unmodifiable List of all cells in the rule's region matching the rule's condition (规则区域中与规则条件匹配的所有单元格列表)