Compartilhar via


Excel.ConditionalFormat class

Um objeto que encapsula o intervalo, formato, regra e outras propriedades de um formato condicional. Para saber mais sobre o modelo de objeto de formatação condicional, leia Aplicar formatação condicional aos intervalos do Excel.

Extends

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

Propriedades

cellValue

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

cellValueOrNullObject

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

colorScale

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

colorScaleOrNullObject

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

context

O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.

custom

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

customOrNullObject

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

dataBar

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

dataBarOrNullObject

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

iconSet

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

iconSetOrNullObject

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

id

A prioridade do formato condicional no atual ConditionalFormatCollection.

preset

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

presetOrNullObject

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

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.

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.

textComparison

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".

textComparisonOrNullObject

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".

topBottom

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.

topBottomOrNullObject

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.

type

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

Métodos

delete()

Exclui esse formato condicional.

getRange()

Retorna o intervalo ao qual a formatação condicional é aplicada. Gera um erro se o formato condicional for aplicado a vários intervalos.

getRangeOrNullObject()

Devolve o intervalo ao qual o formato conditonal é aplicado. Se o formato condicional for aplicado a vários intervalos, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getRanges()

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

load(options)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNames)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNamesAndPaths)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

set(properties, options)

Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.

set(properties)

Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original Excel.ConditionalFormat é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.ConditionalFormatData) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.

Detalhes da propriedade

cellValue

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

readonly cellValue: Excel.CellValueConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/14-conditional-formatting/conditional-formatting-basic.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B21:E23");
    const conditionalFormat = range.conditionalFormats
        .add(Excel.ConditionalFormatType.cellValue);
    conditionalFormat.cellValue.format.font.color = "red";
    conditionalFormat.cellValue.rule = { formula1: "=0", operator: "LessThan" };

    await context.sync();
});

cellValueOrNullObject

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

readonly cellValueOrNullObject: Excel.CellValueConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

colorScale

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

readonly colorScale: Excel.ColorScaleConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/14-conditional-formatting/conditional-formatting-basic.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B2:M5");
    const conditionalFormat = range.conditionalFormats
        .add(Excel.ConditionalFormatType.colorScale);
    const criteria = {
        minimum: { formula: null, type: Excel.ConditionalFormatColorCriterionType.lowestValue, color: "blue" },
        midpoint: { formula: "50", type: Excel.ConditionalFormatColorCriterionType.percent, color: "yellow" },
        maximum: { formula: null, type: Excel.ConditionalFormatColorCriterionType.highestValue, color: "red" }
    };
    conditionalFormat.colorScale.criteria = criteria;

    await context.sync();
});

colorScaleOrNullObject

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

readonly colorScaleOrNullObject: Excel.ColorScaleConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

context

O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.

context: RequestContext;

Valor da propriedade

custom

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

readonly custom: Excel.CustomConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/14-conditional-formatting/conditional-formatting-basic.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B8:E13");
    const conditionalFormat = range.conditionalFormats.add(Excel.ConditionalFormatType.custom);
    conditionalFormat.custom.rule.formula = '=IF(B8>INDIRECT("RC[-1]",0),TRUE)';
    conditionalFormat.custom.format.font.color = "green";

    await context.sync();
});

customOrNullObject

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

readonly customOrNullObject: Excel.CustomConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

dataBar

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

readonly dataBar: Excel.DataBarConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/14-conditional-formatting/conditional-formatting-basic.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B8:E13");
    const conditionalFormat = range.conditionalFormats
        .add(Excel.ConditionalFormatType.dataBar);
    conditionalFormat.dataBar.barDirection = Excel.ConditionalDataBarDirection.leftToRight;

    await context.sync();
});

dataBarOrNullObject

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

readonly dataBarOrNullObject: Excel.DataBarConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

iconSet

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

readonly iconSet: Excel.IconSetConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/14-conditional-formatting/conditional-formatting-basic.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B8:E13");
    const conditionalFormat = range.conditionalFormats
        .add(Excel.ConditionalFormatType.iconSet);
    const iconSetCF = conditionalFormat.iconSet;
    iconSetCF.style = Excel.IconSet.threeTriangles;

    /*
        The iconSetCF.criteria array is automatically prepopulated with
        criterion elements whose properties have been given default settings.
        You can't write to each property of a criterion directly. Instead,
        replace the whole criteria object.

        With a "three*" icon set style, such as "threeTriangles", the third
        element in the criteria array (criteria[2]) defines the "top" icon;
        e.g., a green triangle. The second (criteria[1]) defines the "middle"
        icon. The first (criteria[0]) defines the "low" icon, but it
        can often be left empty as the following object shows, because every
        cell that does not match the other two criteria always gets the low
        icon.            
    */
    iconSetCF.criteria = [
        {} as any,
        {
            type: Excel.ConditionalFormatIconRuleType.number,
            operator: Excel.ConditionalIconCriterionOperator.greaterThanOrEqual,
            formula: "=700"
        },
        {
            type: Excel.ConditionalFormatIconRuleType.number,
            operator: Excel.ConditionalIconCriterionOperator.greaterThanOrEqual,
            formula: "=1000",
        }
    ];

    await context.sync();
});

iconSetOrNullObject

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

readonly iconSetOrNullObject: Excel.IconSetConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

id

A prioridade do formato condicional no atual ConditionalFormatCollection.

readonly id: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

preset

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

readonly preset: Excel.PresetCriteriaConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/14-conditional-formatting/conditional-formatting-basic.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B2:M5");
    const conditionalFormat = range.conditionalFormats
        .add(Excel.ConditionalFormatType.presetCriteria);
    conditionalFormat.preset.format.font.color = "white";
    conditionalFormat.preset.rule = { criterion: Excel.ConditionalFormatPresetCriterion.oneStdDevAboveAverage };

    await context.sync();
});

presetOrNullObject

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

readonly presetOrNullObject: Excel.PresetCriteriaConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

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.

priority: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

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.

stopIfTrue: boolean;

Valor da propriedade

boolean

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

textComparison

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".

readonly textComparison: Excel.TextConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/14-conditional-formatting/conditional-formatting-basic.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B16:D18");
    const conditionalFormat = range.conditionalFormats
        .add(Excel.ConditionalFormatType.containsText);
    conditionalFormat.textComparison.format.font.color = "red";
    conditionalFormat.textComparison.rule = { operator: Excel.ConditionalTextOperator.contains, text: "Delayed" };

    await context.sync();
});

textComparisonOrNullObject

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".

readonly textComparisonOrNullObject: Excel.TextConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

topBottom

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.

readonly topBottom: Excel.TopBottomConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

topBottomOrNullObject

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.

readonly topBottomOrNullObject: Excel.TopBottomConditionalFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

type

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

readonly type: Excel.ConditionalFormatType | "Custom" | "DataBar" | "ColorScale" | "IconSet" | "TopBottom" | "PresetCriteria" | "ContainsText" | "CellValue";

Valor da propriedade

Excel.ConditionalFormatType | "Custom" | "DataBar" | "ColorScale" | "IconSet" | "TopBottom" | "PresetCriteria" | "ContainsText" | "CellValue"

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/14-conditional-formatting/conditional-formatting-basic.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const worksheetRange = sheet.getRange();
    worksheetRange.conditionalFormats.load("type");

    await context.sync();

    let cfRangePairs: { cf: Excel.ConditionalFormat, range: Excel.Range }[] = [];
    worksheetRange.conditionalFormats.items.forEach(item => {
        cfRangePairs.push({
            cf: item,
            range: item.getRange().load("address")
        });
    });

    await context.sync();

    if (cfRangePairs.length > 0) {
        cfRangePairs.forEach(item => {
            console.log(item.cf.type);
        });
    } else {
        console.log("No conditional formats applied.");
    }
});

Detalhes do método

delete()

Exclui esse formato condicional.

delete(): void;

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

getRange()

Retorna o intervalo ao qual a formatação condicional é aplicada. Gera um erro se o formato condicional for aplicado a vários intervalos.

getRange(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/14-conditional-formatting/conditional-formatting-basic.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const worksheetRange = sheet.getRange();
    worksheetRange.conditionalFormats.load("type");

    await context.sync();

    let cfRangePairs: { cf: Excel.ConditionalFormat, range: Excel.Range }[] = [];
    worksheetRange.conditionalFormats.items.forEach(item => {
        cfRangePairs.push({
            cf: item,
            range: item.getRange().load("address")
        });
    });

    await context.sync();

    if (cfRangePairs.length > 0) {
        cfRangePairs.forEach(item => {
            console.log(item.cf.type);
        });
    } else {
        console.log("No conditional formats applied.");
    }
});

getRangeOrNullObject()

Devolve o intervalo ao qual o formato conditonal é aplicado. Se o formato condicional for aplicado a vários intervalos, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getRangeOrNullObject(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

getRanges()

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

getRanges(): Excel.RangeAreas;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

load(options)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(options?: Excel.Interfaces.ConditionalFormatLoadOptions): Excel.ConditionalFormat;

Parâmetros

options
Excel.Interfaces.ConditionalFormatLoadOptions

Fornece opções para as propriedades do objeto a carregar.

Retornos

load(propertyNames)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNames?: string | string[]): Excel.ConditionalFormat;

Parâmetros

propertyNames

string | string[]

Uma cadeia delimitada por vírgulas ou uma matriz de cadeias que especificam as propriedades a carregar.

Retornos

load(propertyNamesAndPaths)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.ConditionalFormat;

Parâmetros

propertyNamesAndPaths

{ select?: string; expand?: string; }

propertyNamesAndPaths.select é uma cadeia delimitada por vírgulas que especifica as propriedades a carregar e propertyNamesAndPaths.expand é uma cadeia delimitada por vírgulas que especifica as propriedades de navegação a carregar.

Retornos

set(properties, options)

Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.

set(properties: Interfaces.ConditionalFormatUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parâmetros

properties
Excel.Interfaces.ConditionalFormatUpdateData

Um objeto JavaScript com propriedades que são estruturadas isomorfoticamente para as propriedades do objeto no qual o método é chamado.

options
OfficeExtension.UpdateOptions

Fornece uma opção para suprimir erros se o objeto de propriedades tentar definir quaisquer propriedades só de leitura.

Retornos

void

set(properties)

Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.

set(properties: Excel.ConditionalFormat): void;

Parâmetros

Retornos

void

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original Excel.ConditionalFormat é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.ConditionalFormatData) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.

toJSON(): Excel.Interfaces.ConditionalFormatData;

Retornos