Partager via


Excel.ConditionalFormat class

Objet qui encapsule la plage, le format, la règle et d’autres propriétés d’un format conditionnel. Pour en savoir plus sur le modèle objet de mise en forme conditionnelle, consultez Appliquer la mise en forme conditionnelle aux plages Excel.

Extends

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

Propriétés

cellValue

Retourne les propriétés de format conditionnel de la valeur de cellule si le format conditionnel actuel est un CellValue type.

cellValueOrNullObject

Retourne les propriétés de format conditionnel de la valeur de cellule si le format conditionnel actuel est un CellValue type.

colorScale

Retourne les propriétés de format conditionnel de l’échelle de couleurs si le format conditionnel actuel est un ColorScale type.

colorScaleOrNullObject

Retourne les propriétés de format conditionnel de l’échelle de couleurs si le format conditionnel actuel est un ColorScale type.

context

Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office.

custom

Retourne les propriétés de format conditionnel personnalisé si le format conditionnel actuel est un type personnalisé.

customOrNullObject

Retourne les propriétés de format conditionnel personnalisé si le format conditionnel actuel est un type personnalisé.

dataBar

Retourne les propriétés de la barre de données si le format conditionnel actuel est une barre de données.

dataBarOrNullObject

Retourne les propriétés de la barre de données si le format conditionnel actuel est une barre de données.

iconSet

Retourne les propriétés de mise en forme conditionnelle du jeu d’icônes si le format conditionnel actuel est un IconSet type.

iconSetOrNullObject

Retourne les propriétés de mise en forme conditionnelle du jeu d’icônes si le format conditionnel actuel est un IconSet type.

id

Priorité du format conditionnel dans le actuel ConditionalFormatCollection.

preset

Retourne le format conditionnel des critères prédéfinis. Pour plus d’informations, consultez l’article Excel.PresetCriteriaConditionalFormat.

presetOrNullObject

Retourne le format conditionnel des critères prédéfinis. Pour plus d’informations, consultez l’article Excel.PresetCriteriaConditionalFormat.

priority

Priorité (ou index) dans la collection de formats conditionnels dans laquelle ce format conditionnel existe actuellement. La modification de cela modifie également les priorités des autres formats conditionnels, afin de permettre un ordre de priorité contigu. Utilisez une priorité négative pour commencer à partir de l’arrière. Les priorités supérieures aux limites obtiennent et définissent la priorité maximale (ou minimale si négative). Notez également que si vous modifiez la priorité, vous devez récupérer à nouveau une nouvelle copie de l’objet à cet emplacement de priorité si vous souhaitez y apporter d’autres modifications.

stopIfTrue

Si les conditions de cette mise en forme conditionnelle sont remplies, aucun format de priorité inférieure ne doit prendre effet sur cette cellule. La valeur se trouve null sur les barres de données, les jeux d’icônes et les échelles de couleurs, car il n’existe aucun concept de StopIfTrue pour ces.

textComparison

Retourne les propriétés de mise en forme conditionnelle de texte spécifiques si le format conditionnel actuel est un type de texte. Par exemple, pour mettre en forme les cellules correspondant au mot « Texte ».

textComparisonOrNullObject

Retourne les propriétés de mise en forme conditionnelle de texte spécifiques si le format conditionnel actuel est un type de texte. Par exemple, pour mettre en forme les cellules correspondant au mot « Texte ».

topBottom

Retourne les propriétés de format conditionnel haut/bas si le format conditionnel actuel est un TopBottom type. Par exemple, pour mettre en forme les 10 % du haut ou les 10 éléments du bas.

topBottomOrNullObject

Retourne les propriétés de format conditionnel haut/bas si le format conditionnel actuel est un TopBottom type. Par exemple, pour mettre en forme les 10 % du haut ou les 10 éléments du bas.

type

Type de format conditionnel. Un seul peut être défini à la fois.

Méthodes

delete()

Supprime cette mise en forme conditionnelle.

getRange()

Renvoie la plage à laquelle s’applique la mise en forme conditionnelle. Génère une erreur si le format conditionnel est appliqué à plusieurs plages.

getRangeOrNullObject()

Retourne la plage à laquelle le format conditonal est appliqué. Si le format conditionnel est appliqué à plusieurs plages, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getRanges()

Retourne le RangeAreas, comprenant une ou plusieurs plages rectangulaires auxquelles le format conditonal est appliqué.

load(options)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

load(propertyNames)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

load(propertyNamesAndPaths)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

set(properties, options)

Définit plusieurs propriétés d’un objet en même temps. Vous pouvez passer un objet brut avec les propriétés appropriées ou un autre objet API du même type.

set(properties)

Définit plusieurs propriétés sur l’objet en même temps, en fonction d’un objet chargé existant.

toJSON()

Remplace la méthode JavaScript toJSON() afin de fournir une sortie plus utile lorsqu’un objet API est passé à JSON.stringify(). (JSON.stringifyappelle à son tour la toJSON méthode de l’objet qui lui est passé.) Alors que l’objet d’origine Excel.ConditionalFormat est un objet API, la toJSON méthode renvoie un objet JavaScript brut (typé en tant Excel.Interfaces.ConditionalFormatDataque ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.

Détails de la propriété

cellValue

Retourne les propriétés de format conditionnel de la valeur de cellule si le format conditionnel actuel est un CellValue type.

readonly cellValue: Excel.CellValueConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

Exemples

// 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

Retourne les propriétés de format conditionnel de la valeur de cellule si le format conditionnel actuel est un CellValue type.

readonly cellValueOrNullObject: Excel.CellValueConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

colorScale

Retourne les propriétés de format conditionnel de l’échelle de couleurs si le format conditionnel actuel est un ColorScale type.

readonly colorScale: Excel.ColorScaleConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

Exemples

// 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

Retourne les propriétés de format conditionnel de l’échelle de couleurs si le format conditionnel actuel est un ColorScale type.

readonly colorScaleOrNullObject: Excel.ColorScaleConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

context

Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office.

context: RequestContext;

Valeur de propriété

custom

Retourne les propriétés de format conditionnel personnalisé si le format conditionnel actuel est un type personnalisé.

readonly custom: Excel.CustomConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

Exemples

// 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

Retourne les propriétés de format conditionnel personnalisé si le format conditionnel actuel est un type personnalisé.

readonly customOrNullObject: Excel.CustomConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

dataBar

Retourne les propriétés de la barre de données si le format conditionnel actuel est une barre de données.

readonly dataBar: Excel.DataBarConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

Exemples

// 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

Retourne les propriétés de la barre de données si le format conditionnel actuel est une barre de données.

readonly dataBarOrNullObject: Excel.DataBarConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

iconSet

Retourne les propriétés de mise en forme conditionnelle du jeu d’icônes si le format conditionnel actuel est un IconSet type.

readonly iconSet: Excel.IconSetConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

Exemples

// 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

Retourne les propriétés de mise en forme conditionnelle du jeu d’icônes si le format conditionnel actuel est un IconSet type.

readonly iconSetOrNullObject: Excel.IconSetConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

id

Priorité du format conditionnel dans le actuel ConditionalFormatCollection.

readonly id: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

preset

Retourne le format conditionnel des critères prédéfinis. Pour plus d’informations, consultez l’article Excel.PresetCriteriaConditionalFormat.

readonly preset: Excel.PresetCriteriaConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

Exemples

// 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

Retourne le format conditionnel des critères prédéfinis. Pour plus d’informations, consultez l’article Excel.PresetCriteriaConditionalFormat.

readonly presetOrNullObject: Excel.PresetCriteriaConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

priority

Priorité (ou index) dans la collection de formats conditionnels dans laquelle ce format conditionnel existe actuellement. La modification de cela modifie également les priorités des autres formats conditionnels, afin de permettre un ordre de priorité contigu. Utilisez une priorité négative pour commencer à partir de l’arrière. Les priorités supérieures aux limites obtiennent et définissent la priorité maximale (ou minimale si négative). Notez également que si vous modifiez la priorité, vous devez récupérer à nouveau une nouvelle copie de l’objet à cet emplacement de priorité si vous souhaitez y apporter d’autres modifications.

priority: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

stopIfTrue

Si les conditions de cette mise en forme conditionnelle sont remplies, aucun format de priorité inférieure ne doit prendre effet sur cette cellule. La valeur se trouve null sur les barres de données, les jeux d’icônes et les échelles de couleurs, car il n’existe aucun concept de StopIfTrue pour ces.

stopIfTrue: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

textComparison

Retourne les propriétés de mise en forme conditionnelle de texte spécifiques si le format conditionnel actuel est un type de texte. Par exemple, pour mettre en forme les cellules correspondant au mot « Texte ».

readonly textComparison: Excel.TextConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

Exemples

// 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

Retourne les propriétés de mise en forme conditionnelle de texte spécifiques si le format conditionnel actuel est un type de texte. Par exemple, pour mettre en forme les cellules correspondant au mot « Texte ».

readonly textComparisonOrNullObject: Excel.TextConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

topBottom

Retourne les propriétés de format conditionnel haut/bas si le format conditionnel actuel est un TopBottom type. Par exemple, pour mettre en forme les 10 % du haut ou les 10 éléments du bas.

readonly topBottom: Excel.TopBottomConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

topBottomOrNullObject

Retourne les propriétés de format conditionnel haut/bas si le format conditionnel actuel est un TopBottom type. Par exemple, pour mettre en forme les 10 % du haut ou les 10 éléments du bas.

readonly topBottomOrNullObject: Excel.TopBottomConditionalFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

type

Type de format conditionnel. Un seul peut être défini à la fois.

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

Valeur de propriété

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

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

Exemples

// 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.");
    }
});

Détails de la méthode

delete()

Supprime cette mise en forme conditionnelle.

delete(): void;

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

getRange()

Renvoie la plage à laquelle s’applique la mise en forme conditionnelle. Génère une erreur si le format conditionnel est appliqué à plusieurs plages.

getRange(): Excel.Range;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

Exemples

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

Retourne la plage à laquelle le format conditonal est appliqué. Si le format conditionnel est appliqué à plusieurs plages, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getRangeOrNullObject(): Excel.Range;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

getRanges()

Retourne le RangeAreas, comprenant une ou plusieurs plages rectangulaires auxquelles le format conditonal est appliqué.

getRanges(): Excel.RangeAreas;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

load(options)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

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

Paramètres

options
Excel.Interfaces.ConditionalFormatLoadOptions

Fournit des options pour les propriétés de l’objet à charger.

Retours

load(propertyNames)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

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

Paramètres

propertyNames

string | string[]

Chaîne délimitée par des virgules ou tableau de chaînes qui spécifient les propriétés à charger.

Retours

load(propertyNamesAndPaths)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

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

Paramètres

propertyNamesAndPaths

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

propertyNamesAndPaths.select est une chaîne délimitée par des virgules qui spécifie les propriétés à charger, et propertyNamesAndPaths.expand est une chaîne délimitée par des virgules qui spécifie les propriétés de navigation à charger.

Retours

set(properties, options)

Définit plusieurs propriétés d’un objet en même temps. Vous pouvez passer un objet brut avec les propriétés appropriées ou un autre objet API du même type.

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

Paramètres

properties
Excel.Interfaces.ConditionalFormatUpdateData

Objet JavaScript avec des propriétés qui sont structurées isomorphes en fonction des propriétés de l’objet sur lequel la méthode est appelée.

options
OfficeExtension.UpdateOptions

Fournit une option permettant de supprimer les erreurs si l’objet properties tente de définir des propriétés en lecture seule.

Retours

void

set(properties)

Définit plusieurs propriétés sur l’objet en même temps, en fonction d’un objet chargé existant.

set(properties: Excel.ConditionalFormat): void;

Paramètres

Retours

void

toJSON()

Remplace la méthode JavaScript toJSON() afin de fournir une sortie plus utile lorsqu’un objet API est passé à JSON.stringify(). (JSON.stringifyappelle à son tour la toJSON méthode de l’objet qui lui est passé.) Alors que l’objet d’origine Excel.ConditionalFormat est un objet API, la toJSON méthode renvoie un objet JavaScript brut (typé en tant Excel.Interfaces.ConditionalFormatDataque ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.

toJSON(): Excel.Interfaces.ConditionalFormatData;

Retours