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
cell |
Devolve as propriedades do formato condicional do valor da célula se o formato condicional atual for um |
cell |
Devolve as propriedades do formato condicional do valor da célula se o formato condicional atual for um |
color |
Devolve as propriedades do formato condicional da escala de cores se o formato condicional atual for um |
color |
Devolve as propriedades do formato condicional da escala de cores se o formato condicional atual for um |
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. |
custom |
Devolve as propriedades de formato condicional personalizado se o formato condicional atual for um tipo personalizado. |
data |
Devolve as propriedades da barra de dados se o formato condicional atual for uma barra de dados. |
data |
Devolve as propriedades da barra de dados se o formato condicional atual for uma barra de dados. |
icon |
Devolve as propriedades do formato condicional do conjunto de ícones se o formato condicional atual for um |
icon |
Devolve as propriedades do formato condicional do conjunto de ícones se o formato condicional atual for um |
id | A prioridade do formato condicional no atual |
preset | Devolve o formato condicional dos critérios predefinidos. Veja |
preset |
Devolve o formato condicional dos critérios predefinidos. Veja |
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. |
stop |
Se as condições desse formato condicional forem atendidas, nenhum formato de prioridade mais baixa terá efeito nessa célula. O valor está |
text |
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". |
text |
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". |
top |
Devolve as propriedades de formato condicional superior/inferior se o formato condicional atual for um |
top |
Devolve as propriedades de formato condicional superior/inferior se o formato condicional atual for um |
type | Um tipo de formato condicional. Apenas um pode ser definido de cada vez. |
Métodos
delete() | Exclui esse formato condicional. |
get |
Retorna o intervalo ao qual a formatação condicional é aplicada. Gera um erro se o formato condicional for aplicado a vários intervalos. |
get |
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 |
get |
Devolve o |
load(options) | Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar |
load(property |
Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar |
load(property |
Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar |
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 |
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
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
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
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
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
id
A prioridade do formato condicional no atual ConditionalFormatCollection
.
readonly id: string;
Valor da propriedade
string
Comentários
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
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
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
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
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
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
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
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
getRanges()
Devolve o RangeAreas
, composto por um ou mais intervalos retangulares, aos quais o formato conditonal é aplicado.
getRanges(): Excel.RangeAreas;
Retornos
Comentários
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
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
- properties
- Excel.ConditionalFormat
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.stringify
por sua vez, chama o toJSON
método do objeto que lhe é transmitido.) Enquanto o objeto Excel.ConditionalFormat original é 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;