Compartilhar via

ExcelScript.ConditionalFormat interface

  • Referência
Pacote:
ExcelScript

Um objeto que encapsula o intervalo, formato, regra e outras propriedades de um formato condicional.

Métodos

delete()

Exclui esse formato condicional.
getCellValue()

Devolve as propriedades do formato condicional do valor da célula se o formato condicional atual for um CellValue tipo.
getColorScale()

Devolve as propriedades do formato condicional da escala de cores se o formato condicional atual for um ColorScale tipo.
getCustom()

Devolve as propriedades de formato condicional personalizado se o formato condicional atual for um tipo personalizado.
getDataBar()

Devolve as propriedades da barra de dados se o formato condicional atual for uma barra de dados.
getIconSet()

Devolve as propriedades do formato condicional do conjunto de ícones se o formato condicional atual for um IconSet tipo.
getId()

A prioridade do formato condicional no atual ConditionalFormatCollection.
getPreset()

Devolve o formato condicional dos critérios predefinidos. Veja ExcelScript.PresetCriteriaConditionalFormat para obter detalhes.
getPriority()

A prioridade (ou índice) na coleção de formatos condicionais em que este formato condicional existe atualmente. Alterar esta opção também altera as prioridades de outros formatos condicionais, para permitir uma ordem de prioridade contígua. Utilize uma prioridade negativa para começar a partir de trás. As prioridades maiores do que os limites obterão e serão definidas para a prioridade máxima (ou mínima se negativa). Tenha também em atenção que, se alterar a prioridade, terá de obter novamente uma nova cópia do objeto nessa nova localização prioritária se quiser fazer mais alterações à mesma.
getRange()

Devolve o intervalo ao qual o formato condicional é aplicado. Se o formato condicional for aplicado a vários intervalos, este método devolve undefined.
getRanges()

Devolve o RangeAreas, composto por um ou mais intervalos retangulares, aos quais o formato condicional é aplicado.
getStopIfTrue()

Se as condições desse formato condicional forem atendidas, nenhum formato de prioridade mais baixa terá efeito nessa célula. O valor está null nas barras de dados, nos conjuntos de ícones e nas escalas de StopIfTrue cores, uma vez que não existe nenhum conceito para estas.
getTextComparison()

Devolve as propriedades específicas do formato condicional de texto se o formato condicional atual for um tipo de texto. Por exemplo, para formatar células que correspondam à palavra "Texto".
getTopBottom()

Devolve as propriedades de formato condicional superior/inferior se o formato condicional atual for um TopBottom tipo. Por exemplo, para formatar os 10% ou 10 itens mais baixos.
getType()

Um tipo de formato condicional. Apenas um pode ser definido de cada vez.
setPriority(priority)

A prioridade (ou índice) na coleção de formatos condicionais em que este formato condicional existe atualmente. Alterar esta opção também altera as prioridades de outros formatos condicionais, para permitir uma ordem de prioridade contígua. Utilize uma prioridade negativa para começar a partir de trás. As prioridades maiores do que os limites obterão e serão definidas para a prioridade máxima (ou mínima se negativa). Tenha também em atenção que, se alterar a prioridade, terá de obter novamente uma nova cópia do objeto nessa nova localização prioritária se quiser fazer mais alterações à mesma.
setStopIfTrue(stopIfTrue)

Se as condições desse formato condicional forem atendidas, nenhum formato de prioridade mais baixa terá efeito nessa célula. O valor está null nas barras de dados, nos conjuntos de ícones e nas escalas de StopIfTrue cores, uma vez que não existe nenhum conceito para estas.

Detalhes do método

delete()

Exclui esse formato condicional.

delete(): void;

Retornos

void

getCellValue()

Devolve as propriedades do formato condicional do valor da célula se o formato condicional atual for um CellValue tipo.

getCellValue(): CellValueConditionalFormat | undefined;

Retornos

ExcelScript.CellValueConditionalFormat | undefined

Exemplos

/**
 * 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()

Devolve as propriedades do formato condicional da escala de cores se o formato condicional atual for um ColorScale tipo.

getColorScale(): ColorScaleConditionalFormat | undefined;

Retornos

ExcelScript.ColorScaleConditionalFormat | undefined

Exemplos

/**
 * 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()

Devolve as propriedades de formato condicional personalizado se o formato condicional atual for um tipo personalizado.

getCustom(): CustomConditionalFormat | undefined;

Retornos

ExcelScript.CustomConditionalFormat | undefined

Exemplos

/**
 * 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()

Devolve as propriedades da barra de dados se o formato condicional atual for uma barra de dados.

getDataBar(): DataBarConditionalFormat | undefined;

Retornos

ExcelScript.DataBarConditionalFormat | undefined

Exemplos

/**
 * 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()

Devolve as propriedades do formato condicional do conjunto de ícones se o formato condicional atual for um IconSet tipo.

getIconSet(): IconSetConditionalFormat | undefined;

Retornos

ExcelScript.IconSetConditionalFormat | undefined

Exemplos

/**
 * 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()

A prioridade do formato condicional no atual ConditionalFormatCollection.

getId(): string;

Retornos

string

getPreset()

Devolve o formato condicional dos critérios predefinidos. Veja ExcelScript.PresetCriteriaConditionalFormat para obter detalhes.

getPreset(): PresetCriteriaConditionalFormat | undefined;

Retornos

ExcelScript.PresetCriteriaConditionalFormat | undefined

Exemplos

/**
 * 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()

A prioridade (ou índice) na coleção de formatos condicionais em que este formato condicional existe atualmente. Alterar esta opção também altera as prioridades de outros formatos condicionais, para permitir uma ordem de prioridade contígua. Utilize uma prioridade negativa para começar a partir de trás. As prioridades maiores do que os limites obterão e serão definidas para a prioridade máxima (ou mínima se negativa). Tenha também em atenção que, se alterar a prioridade, terá de obter novamente uma nova cópia do objeto nessa nova localização prioritária se quiser fazer mais alterações à mesma.

getPriority(): number;

Retornos

number

getRange()

Devolve o intervalo ao qual o formato condicional é aplicado. Se o formato condicional for aplicado a vários intervalos, este método devolve undefined.

getRange(): Range;

Retornos

ExcelScript.Range

getRanges()

Devolve o RangeAreas, composto por um ou mais intervalos retangulares, aos quais o formato condicional é aplicado.

getRanges(): RangeAreas;

Retornos

ExcelScript.RangeAreas

getStopIfTrue()

Se as condições desse formato condicional forem atendidas, nenhum formato de prioridade mais baixa terá efeito nessa célula. O valor está null nas barras de dados, nos conjuntos de ícones e nas escalas de StopIfTrue cores, uma vez que não existe nenhum conceito para estas.

getStopIfTrue(): boolean;

Retornos

boolean

getTextComparison()

Devolve as propriedades específicas do formato condicional de texto se o formato condicional atual for um tipo de texto. Por exemplo, para formatar células que correspondam à palavra "Texto".

getTextComparison(): TextConditionalFormat | undefined;

Retornos

ExcelScript.TextConditionalFormat | undefined

Exemplos

/**
 * 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()

Devolve as propriedades de formato condicional superior/inferior se o formato condicional atual for um TopBottom tipo. Por exemplo, para formatar os 10% ou 10 itens mais baixos.

getTopBottom(): TopBottomConditionalFormat | undefined;

Retornos

ExcelScript.TopBottomConditionalFormat | undefined

Exemplos

/**
 * 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()

Um tipo de formato condicional. Apenas um pode ser definido de cada vez.

getType(): ConditionalFormatType;

Retornos

ExcelScript.ConditionalFormatType

setPriority(priority)

A prioridade (ou índice) na coleção de formatos condicionais em que este formato condicional existe atualmente. Alterar esta opção também altera as prioridades de outros formatos condicionais, para permitir uma ordem de prioridade contígua. Utilize uma prioridade negativa para começar a partir de trás. As prioridades maiores do que os limites obterão e serão definidas para a prioridade máxima (ou mínima se negativa). Tenha também em atenção que, se alterar a prioridade, terá de obter novamente uma nova cópia do objeto nessa nova localização prioritária se quiser fazer mais alterações à mesma.

setPriority(priority: number): void;

Parâmetros

priority

number

Retornos

void

setStopIfTrue(stopIfTrue)

Se as condições desse formato condicional forem atendidas, nenhum formato de prioridade mais baixa terá efeito nessa célula. O valor está null nas barras de dados, nos conjuntos de ícones e nas escalas de StopIfTrue cores, uma vez que não existe nenhum conceito para estas.

setStopIfTrue(stopIfTrue: boolean): void;

Parâmetros

stopIfTrue

boolean

Retornos

void