ExcelScript.ConditionalFormat interface

包:

ExcelScript

一个对象，该对象封装条件格式的范围、格式、规则和其他属性。

方法

changeRuleToCellValue(properties)	将条件格式规则类型更改为单元格值。
changeRuleToColorScale()	将条件格式规则类型更改为色阶。
changeRuleToContainsText(properties)	将条件格式规则类型更改为文本比较。
changeRuleToCustom(formula)	将条件格式规则类型更改为自定义。
changeRuleToDataBar()	将条件格式规则类型更改为数据栏。
changeRuleToIconSet()	将条件格式规则类型更改为图标集。
changeRuleToPresetCriteria(properties)	将条件格式规则类型更改为预设条件。
changeRuleToTopBottom(properties)	将条件格式规则类型更改为顶部/底部。
delete()	删除此条件格式。
getCellValue()	如果当前条件格式是 CellValue 类型，则返回单元格值条件格式属性。
getColorScale()	如果当前条件格式是 ColorScale 类型，则返回色阶条件格式属性。
getCustom()	如果当前条件格式是自定义类型，则返回自定义条件格式属性。
getDataBar()	如果当前条件格式为数据条，则返回数据条属性。
getIconSet()	如果当前条件格式是类型 IconSet ，则返回图标集条件格式属性。
getId()	当前 ConditionalFormatCollection中条件格式的优先级。
getPreset()	返回预设条件条件格式。 有关详细信息，请参阅 ExcelScript.PresetCriteriaConditionalFormat。
getPriority()	此条件格式当前存在于的条件格式集合中的优先级 (或索引) 。 更改此项还会更改其他条件格式的优先级，以允许连续的优先级顺序。 使用负优先级从后面开始。 如果优先级为负) ，则大于边界的优先级将设置为最大 (或最小值。 另请注意，如果更改优先级，则必须在该新优先级位置重新提取对象的新副本，以便对其进行进一步更改。
getRange()	返回应用条件格式的区域。 如果条件格式应用于多个区域，则此方法返回 undefined。
getRanges()	返回 ， RangeAreas它包含应用条件格式的一个或多个矩形区域。
getStopIfTrue()	如果满足此条件格式的条件，则不会有任何低优先级格式应在此单元格上生效。 值位于 null 数据条、图标集和色阶上，因为这些值没有概念 StopIfTrue 。
getTextComparison()	如果当前条件格式是文本类型，则返回特定的文本条件格式属性。 例如，设置与单词“Text”匹配的单元格的格式。
getTopBottom()	如果当前条件格式是类型 TopBottom ，则返回顶部/底部的条件格式属性。 例如，设置前 10% 或后 10 个项目的格式。
getType()	条件格式的类型。 一次只能设置一个。
setPriority(priority)	此条件格式当前存在于的条件格式集合中的优先级 (或索引) 。 更改此项还会更改其他条件格式的优先级，以允许连续的优先级顺序。 使用负优先级从后面开始。 如果优先级为负) ，则大于边界的优先级将设置为最大 (或最小值。 另请注意，如果更改优先级，则必须在该新优先级位置重新提取对象的新副本，以便对其进行进一步更改。
setRanges(ranges)	设置条件格式规则应用于的范围。
setStopIfTrue(stopIfTrue)	如果满足此条件格式的条件，则不会有任何低优先级格式应在此单元格上生效。 值位于 null 数据条、图标集和色阶上，因为这些值没有概念 StopIfTrue 。

方法详细信息

changeRuleToCellValue(properties)

将条件格式规则类型更改为单元格值。

changeRuleToCellValue(properties: ConditionalCellValueRule): void;

参数

properties

ExcelScript.ConditionalCellValueRule

要为单元格值条件格式规则设置的属性。

返回

void

changeRuleToColorScale()

将条件格式规则类型更改为色阶。

changeRuleToColorScale(): void;

返回

void

changeRuleToContainsText(properties)

将条件格式规则类型更改为文本比较。

changeRuleToContainsText(
            properties: ConditionalTextComparisonRule
        ): void;

参数

properties

ExcelScript.ConditionalTextComparisonRule

要为文本比较条件格式规则设置的属性。

返回

void

changeRuleToCustom(formula)

将条件格式规则类型更改为自定义。

changeRuleToCustom(formula: string): void;

参数

formula

string

要为自定义条件格式规则设置的公式。

返回

void

changeRuleToDataBar()

将条件格式规则类型更改为数据栏。

changeRuleToDataBar(): void;

返回

void

changeRuleToIconSet()

将条件格式规则类型更改为图标集。

changeRuleToIconSet(): void;

返回

void

changeRuleToPresetCriteria(properties)

将条件格式规则类型更改为预设条件。

changeRuleToPresetCriteria(
            properties: ConditionalPresetCriteriaRule
        ): void;

参数

properties

ExcelScript.ConditionalPresetCriteriaRule

要为预设条件条件格式规则设置的属性。

返回

void

changeRuleToTopBottom(properties)

将条件格式规则类型更改为顶部/底部。

changeRuleToTopBottom(properties: ConditionalTopBottomRule): void;

参数

properties

ExcelScript.ConditionalTopBottomRule

要为顶部/底部条件格式规则设置的属性。

返回

void

delete()

删除此条件格式。

delete(): void;

返回

void

getCellValue()

如果当前条件格式是 CellValue 类型，则返回单元格值条件格式属性。

getCellValue(): CellValueConditionalFormat | undefined;

返回

ExcelScript.CellValueConditionalFormat | undefined

示例

/**
 * This script applies conditional formatting to a range.
 * That formatting is conditional upon the cell's numerical value.
 * Any value between 50 and 75 will have the cell fill color changed and the font made italic.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the range to format.
  const sheet = workbook.getActiveWorksheet();
  const ratingColumn = sheet.getRange("D2:D20");

  // Add cell value conditional formatting.
  const cellValueConditionalFormatting =
    ratingColumn.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue();
  
  // Create the condition, in this case when the cell value is between 50 and 75.
  let rule: ExcelScript.ConditionalCellValueRule = {
    formula1: "50",
    formula2: "75",
    operator: ExcelScript.ConditionalCellValueOperator.between
  };
  cellValueConditionalFormatting.setRule(rule);

  // Set the format to apply when the condition is met.
  let format = cellValueConditionalFormatting.getFormat();
  format.getFill().setColor("yellow");
  format.getFont().setItalic(true);

}

getColorScale()

如果当前条件格式是 ColorScale 类型，则返回色阶条件格式属性。

getColorScale(): ColorScaleConditionalFormat | undefined;

返回

ExcelScript.ColorScaleConditionalFormat | undefined

示例

/**
 * This script applies a red, white, and blue color scale to the selected range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the selected range.
  let selectedRange = workbook.getSelectedRange();

  // Create a new conditional formatting object by adding one to the range.
  let conditionalFormatting = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.colorScale);

  // Set the colors for the three parts of the scale: minimum, midpoint, and maximum.
  conditionalFormatting.getColorScale().setCriteria({
    minimum: {
      color:"#F8696B", /* A pale red. */
      type:ExcelScript.ConditionalFormatColorCriterionType.lowestValue
    },
    midpoint: {
      color: "#FCFCFF", /* Slightly off-white. */
      formula:'=50',type:ExcelScript.ConditionalFormatColorCriterionType.percentile
    },
    maximum: {
      color: "#5A8AC6", /* A pale blue. */
      type:ExcelScript.ConditionalFormatColorCriterionType.highestValue
    }
  });
}

getCustom()

如果当前条件格式是自定义类型，则返回自定义条件格式属性。

getCustom(): CustomConditionalFormat | undefined;

返回

ExcelScript.CustomConditionalFormat | undefined

示例

/**
 * This script applies a custom conditional formatting to the selected range.
 * A light-green fill is applied to a cell if the value is larger than the value in the row's previous column.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the selected cells.
  let selectedRange = workbook.getSelectedRange();

  // Apply a rule for positive change from the previous column.
  let positiveChange = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
  positiveChange.getCustom().getFormat().getFill().setColor("lightgreen");
  positiveChange.getCustom().getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}>${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
}

getDataBar()

如果当前条件格式为数据条，则返回数据条属性。

getDataBar(): DataBarConditionalFormat | undefined;

返回

ExcelScript.DataBarConditionalFormat | undefined

示例

/**
 * This script creates data bar conditional formatting on the selected range.
 * The scale of the data bar goes from 0 to 1000.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the selected range.
  const selected = workbook.getSelectedRange();
  
  // Create new conditional formatting on the range.
  const format = selected.addConditionalFormat(ExcelScript.ConditionalFormatType.dataBar);
  const dataBarFormat = format.getDataBar();

  // Set the lower bound of the data bar formatting to be 0.
  const lowerBound: ExcelScript.ConditionalDataBarRule = {
    type: ExcelScript.ConditionalFormatRuleType.number,
    formula: "0"
  };
  dataBarFormat.setLowerBoundRule(lowerBound);

  // Set the upper bound of the data bar formatting to be 1000.
  const upperBound: ExcelScript.ConditionalDataBarRule = {
    type: ExcelScript.ConditionalFormatRuleType.number,
    formula: "1000"
  };
  dataBarFormat.setUpperBoundRule(upperBound);
}

getIconSet()

如果当前条件格式是类型 IconSet ，则返回图标集条件格式属性。

getIconSet(): IconSetConditionalFormat | undefined;

返回

ExcelScript.IconSetConditionalFormat | undefined

示例

/**
 * This script applies icon set conditional formatting to a range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the range "A1:A5" on the current worksheet.
  const sheet = workbook.getActiveWorksheet();
  const range = sheet.getRange("A1:A5");

  // Create icon set conditional formatting on the range.
  const conditionalFormatting = range.addConditionalFormat(ExcelScript.ConditionalFormatType.iconSet);

  // Use the "3 Traffic Lights (Unrimmed)" set.
  conditionalFormatting.getIconSet().setStyle(ExcelScript.IconSet.threeTrafficLights1);

  // Set the criteria to use a different icon for the bottom, middle, and top thirds of the values in the range.
  conditionalFormatting.getIconSet().setCriteria([
    {
      formula:'=0',operator:ExcelScript.ConditionalIconCriterionOperator.greaterThanOrEqual,
      type:ExcelScript.ConditionalFormatIconRuleType.percent
    },
    {
      formula:'=33',operator:ExcelScript.ConditionalIconCriterionOperator.greaterThanOrEqual,
      type:ExcelScript.ConditionalFormatIconRuleType.percent},
    {
      formula:'=67',operator:ExcelScript.ConditionalIconCriterionOperator.greaterThanOrEqual,
      type:ExcelScript.ConditionalFormatIconRuleType.percent
    }]);
}

getId()

当前 ConditionalFormatCollection中条件格式的优先级。

getId(): string;

返回

string

getPreset()

返回预设条件条件格式。 有关详细信息，请参阅 ExcelScript.PresetCriteriaConditionalFormat。

getPreset(): PresetCriteriaConditionalFormat | undefined;

返回

ExcelScript.PresetCriteriaConditionalFormat | undefined

示例

/**
 * This script applies a conditional format that uses a preset criterion.
 * Any cell in row 1 will have the color fill set to green if it is a duplicate value
 * (of anything else in row 1).
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the range for row 1.
  const sheet = workbook.getActiveWorksheet();
  const formattedRange = sheet.getRange("1:1");

  // Add new conditional formatting to that range.
  const conditionalFormat = formattedRange.addConditionalFormat(
    ExcelScript.ConditionalFormatType.presetCriteria);

  // Set the conditional formatting to apply a green fill.
  const presetFormat = conditionalFormat.getPreset();
  presetFormat.getFormat().getFill().setColor("green");

  // Set a rule to apply the conditional format when values are duplicated in the range.
  const duplicateRule: ExcelScript.ConditionalPresetCriteriaRule = {
    criterion: ExcelScript.ConditionalFormatPresetCriterion.duplicateValues
  };
  presetFormat.setRule(duplicateRule);
}

getPriority()

此条件格式当前存在于的条件格式集合中的优先级 (或索引) 。 更改此项还会更改其他条件格式的优先级，以允许连续的优先级顺序。 使用负优先级从后面开始。 如果优先级为负) ，则大于边界的优先级将设置为最大 (或最小值。 另请注意，如果更改优先级，则必须在该新优先级位置重新提取对象的新副本，以便对其进行进一步更改。

getPriority(): number;

返回

number

getRange()

返回应用条件格式的区域。 如果条件格式应用于多个区域，则此方法返回 undefined。

getRange(): Range;

返回

ExcelScript.Range

getRanges()

返回 ， RangeAreas它包含应用条件格式的一个或多个矩形区域。

getRanges(): RangeAreas;

返回

ExcelScript.RangeAreas

getStopIfTrue()

如果满足此条件格式的条件，则不会有任何低优先级格式应在此单元格上生效。 值位于 null 数据条、图标集和色阶上，因为这些值没有概念 StopIfTrue 。

getStopIfTrue(): boolean;

返回

boolean

getTextComparison()

如果当前条件格式是文本类型，则返回特定的文本条件格式属性。 例如，设置与单词“Text”匹配的单元格的格式。

getTextComparison(): TextConditionalFormat | undefined;

返回

ExcelScript.TextConditionalFormat | undefined

示例

/**
 * This script adds conditional formatting to the first column in the worksheet.
 * This formatting gives the cells a green fill if they have text starting with "Excel".
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first column in the current worksheet.
  const currentSheet = workbook.getActiveWorksheet();
  const firstColumn = currentSheet.getRange("A:A");

  // Add conditional formatting based on the text in the cells.
  const textConditionFormat = 
    firstColumn.addConditionalFormat(ExcelScript.ConditionalFormatType.containsText).getTextComparison();

  // Set the conditional format to provide a green fill.
  textConditionFormat.getFormat().getFill().setColor("green");

  // Apply the condition rule that the text begins with "Excel".
  const textRule: ExcelScript.ConditionalTextComparisonRule = {
    operator: ExcelScript.ConditionalTextOperator.beginsWith,
    text: "Excel"
  };
  textConditionFormat.setRule(textRule);
}

getTopBottom()

如果当前条件格式是类型 TopBottom ，则返回顶部/底部的条件格式属性。 例如，设置前 10% 或后 10 个项目的格式。

getTopBottom(): TopBottomConditionalFormat | undefined;

返回

ExcelScript.TopBottomConditionalFormat | undefined

示例

/**
 * This script applies top/bottom conditional formatting to a range.
 * The top 2 values in the range will have the cell fill color changed to green.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the range to format.
  const sheet = workbook.getWorksheet("TopBottom");
  const dataRange = sheet.getRange("B2:D5");

  // Set the fill color to green for the top 2 values in the range.
  const topBottomFormat = dataRange.addConditionalFormat(
    ExcelScript.ConditionalFormatType.topBottom).getTopBottom();
  topBottomFormat.getFormat().getFill().setColor("green");
  topBottomFormat.setRule({
    rank: 2, /* The numeric threshold. */
    type: ExcelScript.ConditionalTopBottomCriterionType.topItems /* The type of the top/bottom condition. */
  });
}

getType()

条件格式的类型。 一次只能设置一个。

getType(): ConditionalFormatType;

返回

ExcelScript.ConditionalFormatType

setPriority(priority)

此条件格式当前存在于的条件格式集合中的优先级 (或索引) 。 更改此项还会更改其他条件格式的优先级，以允许连续的优先级顺序。 使用负优先级从后面开始。 如果优先级为负) ，则大于边界的优先级将设置为最大 (或最小值。 另请注意，如果更改优先级，则必须在该新优先级位置重新提取对象的新副本，以便对其进行进一步更改。

setPriority(priority: number): void;

参数

priority

number

返回

void

setRanges(ranges)

设置条件格式规则应用于的范围。

setRanges(ranges: Range | RangeAreas | string): void;

参数

ranges

ExcelScript.Range | ExcelScript.RangeAreas | string

此规则要应用到的一个或多个范围的集合。

返回

void

setStopIfTrue(stopIfTrue)

如果满足此条件格式的条件，则不会有任何低优先级格式应在此单元格上生效。 值位于 null 数据条、图标集和色阶上，因为这些值没有概念 StopIfTrue 。

setStopIfTrue(stopIfTrue: boolean): void;

参数

stopIfTrue

boolean

返回

void