Travailler simultanément avec plusieurs plages dans des compléments Excel

Vous pouvez appliquer des opérations ou définir des propriétés sur plusieurs plages à la fois, même si elles ne sont pas contiguës. Cela rend le code plus court et plus efficace par rapport à l’accès à chaque plage séparément.

Points essentiels

Utilisez RangeAreas pour lire ou définir la même chose sur plusieurs plages distinctes dans un seul appel.
Une propriété est null sauf si toutes les plages de membres partagent la même valeur.
Définissez une propriété une fois sur l’objet RangeAreas au lieu d’effectuer une boucle, sauf si chaque plage a besoin d’une logique différente.
Évitez les objets volumineux RangeAreas constitués de plusieurs cellules uniques. Restreindre d’abord avec getSpecialCells ou d’autres filtres.
Soyez prudent avec des colonnes ou des lignes entières. Pour plus d’informations, consultez Lecture ou écriture dans une plage non délimitée.

RangeAreas

Un objet RangeAreas représente un ensemble de plages qui peuvent ne pas toucher. Il partage de nombreux membres avec Range, avec quelques différences dans la façon dont les valeurs sont retournées.

Exemples :

address retourne une chaîne délimitée par des virgules de toutes les adresses.
dataValidation retourne un seul objet uniquement si chaque plage a la même règle ; sinon, elle retourne null.
cellCount est le nombre total de cellules dans toutes les plages.
calculate recalcule toutes les cellules de l’ensemble.
getEntireColumn et getEntireRow retournent une nouvelle RangeAreas colonne complète couvrant les colonnes ou lignes pour chaque membre.
copyFrom accepte un Range ou un RangeAreas comme source.

La liste complète des membres plage sont également disponibles sur RangeAreas

Propriétés

Être familiarisé avecLire les propriétés de RangeAreas avant d’écrire de code qui lit les propriétés répertoriées. Il existe des subtilités sur ce qui est renvoyé.

address
addressLocal
cellCount
conditionalFormats
context
dataValidation
format
isEntireColumn
isEntireRow
style
worksheet

Méthodes

calculate()
clear()
convertDataTypeToText()
convertToLinkedDataType()
copyFrom()
getEntireColumn()
getEntireRow()
getIntersection()
getIntersectionOrNullObject()
getOffsetRange() (nommé getOffsetRangeAreas sur l’objet RangeAreas )
getSpecialCells()
getSpecialCellsOrNullObject()
getTables()
getUsedRange() (nommé getUsedRangeAreas sur l’objet RangeAreas )
getUsedRangeOrNullObject() (nommé getUsedRangeAreasOrNullObject sur l’objet RangeAreas )
load()
set()
setDirty()
toJSON()
track()
untrack()

Méthodes et propriétés propres à une langue RangeArea

Le RangeAreas type possède des propriétés et des méthodes qui ne sont pas sur l’Rangeobjet. Voici une sélection d’entre eux.

areas: ARangeCollection objet qui contient toutes les plages représentées par l’ RangeAreasobjet. L’RangeCollectionobjet est également nouveau et est semblable à d’autres objets de collection de sites Excel. Il possède uneitemspropriété est une matrice d’Range objets représentant les plages.
areaCount: Le nombre total de plages dans leRangeAreas.
getOffsetRangeAreas: Fonctionne commeRange.getOffsetRange, sauf qu’une RangeAreas est renvoyée et il contient des plages sont en décalage avec des plages du fichier d’origineRangeAreas.

Créer l’objet RangeAreas

Vous pouvez créer un RangeAreas objet de plusieurs façons. La liste suivante contient quelques exemples.

AppelerWorksheet.getRanges() et de transmettre une chaîne comportant des adresses de plage séparées par des virgules. Si une plage que vous souhaitez inclure a été modifiée enNamedItem, vous pouvez inclure le nom, au lieu de l’adresse, dans la chaîne.
Appelez et retournez Range.getSpecialCells() un RangeAreas objet avec des cellules d’un type spécifique, telles que les cellules qui contiennent des formules, la validation des données ou la mise en forme conditionnelle.
Appel Workbook.getSelectedRanges(). Cette méthode renvoie uneRangeAreasreprésentation de toutes les plages qui sont sélectionnées sur la feuille de calcul active actuelle.

Une fois que vous avez unRangeAreasobjet, vous pouvez en créer d’autres à l’aide des méthodes sur l’objet qui renvoieRangeAreastel quegetOffsetRangeAreasetgetIntersection.

Remarque

Vous ne pouvez pas ajouter directement des plages supplémentaires à un objetRangeAreas. Par exemple, la collection dansRangeAreas.areasn’a pas une méthodeadd.

Avertissement

N’essayez pas d’ajouter ou de supprimer directement des membres du RangeAreas.areas.items tableau. Cela mènera à un comportement indésirable dans votre code. Par exemple, il est possible de pousser un objetRange supplémentaire sur le tableau, mais ceci entrainera des erreurs car les propriétésRangeAreaset les méthodes se comportent comme si le nouvel élément n’existait pas. Par exemple, la propriétéareaCountn’inclut pas les plages poussées de cette manière, et le RangeAreas.getItemAt(index) lance une erreur siindexest plus grand queareasCount-1. De la même façon, supprimer un objetRangedans la plageRangeAreas.areas.itemsen obtenant une référence liée à celui-ci et en appelant sa méthodeRange.delete entraîne des bogues: bien que Rangel’objetsoitsupprimé, les propriétés et les méthodes de l’objetRangeAreasparent se comporte, ou tente de le faire, comme s’il existait encore. Par exemple, si votre code appelleRangeAreas.calculate, Office essaiera de calculer la plage, mais comprendra une erreur car l’objet de la plage n’est plus là.

Définir les propriétés sur plusieurs plages

Paramétrer une propriété sur un objet RangeAreas établit une propriété correspondante sur toutes les plages dans la collectionRangeAreas.areas.

Ce qui suit est un exemple de paramétrage d’une propriété sur des plages multiples. La fonction surligne les plagesF3:F5 and H3:H5.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let rangeAreas = sheet.getRanges("F3:F5, H3:H5");
    rangeAreas.format.fill.color = "pink";

    await context.sync();
});

Cet exemple s’applique aux scénarios dans lesquels vous pouvez coder en dur les adresses de plage que vous passez àgetRangesou facilement les calculer à l’exécution. Certains des scénarios dans lesquels ceci peut s’appliquer incluent:

Le code s’exécute dans le contexte d’un modèle connu.
Le code s’exécute dans le contexte de données importées où le schéma des données est connu.

Combiner `RangeAreas` avec `getSpecialCells`

Filtrez un RangeAreas sur les cellules qui correspondent à un critère, comme les formules, avant d’appliquer une mise en forme ou une validation.

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // Two discontiguous vertical bands.
    const targets = sheet.getRanges("A1:A100, C1:C100");

    // Narrow to only the formula cells within those bands.
    const formulaCells = targets.getSpecialCells(Excel.SpecialCellType.formulas);
    formulaCells.format.fill.color = "lightYellow";
    await context.sync();
});

Obtenir des cellules spéciales à partir de plusieurs plages

Les méthodes getSpecialCells et getSpecialCellsOrNullObject sur l’objet RangeAreas fonctionnent de manière analogue aux méthodes du même nom sur l’objet Range. Ces méthodes retournent les cellules disposant de la caractéristique spécifiée à partir de toutes les plages dans la collection RangeAreas.areas. Pour plus d’informations sur les cellules spéciales, consultez Rechercher des cellules spéciales dans une plage.

Lors de l’appel de la méthode getSpecialCells ou getSpecialCellsOrNullObject sur un objet RangeAreas :

si vous passez Excel.SpecialCellType.sameConditionalFormat en tant que premier paramètre, la méthode renvoie toutes les cellules disposant de la même mise en forme conditionnelle que la cellule supérieure gauche de la première plage dans la collection RangeAreas.areas.
Si vous passez Excel.SpecialCellType.sameDataValidation en tant que premier paramètre, la méthode renvoie toutes les cellules disposant de la même règle de validation des données que la cellule supérieure gauche de la première plage dans la collection RangeAreas.areas.

Lire les propriétés de RangeAreas

La lecture des valeurs de propriété de RangeAreas nécessite un soin, car une propriété donnée peut avoir des valeurs différentes pour des plages différentes au sein duRangeAreas. La règle générales est que si une valeur consistantepeutêtre renvoyée, elle sera renvoyée. Par exemple, dans le code suivant, le code RVB pour rose (#FFC0CB) et true sera journalisé dans la console, car les deux plages de l’objet RangeAreas ont un remplissage rose et sont toutes deux des colonnes entières.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();

    // The ranges are the F column and the H column.
    let rangeAreas = sheet.getRanges("F:F, H:H");  
    rangeAreas.format.fill.color = "pink";

    rangeAreas.load("format/fill/color, isEntireColumn");
    await context.sync();

    console.log(rangeAreas.format.fill.color); // #FFC0CB
    console.log(rangeAreas.isEntireColumn); // true
});

Étant donné que les valeurs de propriété peuvent différer, gardez ces règles simples à l’esprit.

Les propriétés booléennes sont true uniquement si elles ont la valeur true dans toutes les plages ; sinon, elles sont false.
address retourne toujours la chaîne d’adresses délimitées par des virgules.
Les autres propriétés sont null , sauf si toutes les plages partagent la même valeur.

Par exemple, le code suivante crée unRangeAreasdans lequel seule une plage est une colonne entière et seule une est remplie de rose. La console s’afficheranullpour un remplissage de couleur,falsepour la propriétéisEntireRow et «Sheet1!F3:F5, Sheet1!H:H» (en présumant que la feuille de calcule soit «Sheet1») pour la propriétéaddress.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let rangeAreas = sheet.getRanges("F3:F5, H:H");

    let pinkColumnRange = sheet.getRange("H:H");
    pinkColumnRange.format.fill.color = "pink";

    rangeAreas.load("format/fill/color, isEntireColumn, address");
    await context.sync();

    console.log(rangeAreas.format.fill.color); // null
    console.log(rangeAreas.isEntireColumn); // false
    console.log(rangeAreas.address); // "Sheet1!F3:F5, Sheet1!H:H"
});

Voir aussi

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-10-02