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

Article
04/07/2023

La bibliothèque JavaScript Excel permet à votre complément d’effectuer des opérations et définir des propriétés, de manière simultanée sur plusieurs plages. Les plages n’ont pas besoin d’être contigus. En plus de rendre votre code plus simple, cette manière de paramétrer une propriété s’exécute beaucoup plus rapidement que paramétrer la même propriété pour chaque les plages de manière individuelle.

RangeAreas

Un ensemble de plages (éventuellement discontiguées) est représenté par un objet RangeAreas . Il possède des propriétés et des méthodes similaires au typeRange (bon nombre des noms identiques ou similaires,), mais les ajustements ont été apportées à:

Les types de données pour les propriétés et le comportement des méthodes et des getters.
Les types de données de paramètres et des comportements de la méthode.
Les types de données de méthodes renvoient des valeurs.

Quelques exemples :

RangeAreas a uneaddress propriété qui renvoie une chaîne séparée par des virgules de plage d’adresses, au lieu d’une adresse comme avec la Range.address propriété.
RangeAreas a unedataValidation propriété qui renvoie unDataValidation objet qui représente la validation des données de toutes les plages dans la RangeAreas, s’il est cohérent. La propriété estnull si les objetsDataValidation identiques ne sont pas appliqués à toutes les plages dans laRangeAreas. Il s’agit d’un principe général, mais pas universel, avec l’objet RangeAreas : Si une propriété n’a pas de valeurs cohérentes sur toutes les plages du RangeAreas, il s’agit nullde . Pour plus d’informations et quelques exceptions, consultez Lire les propriétés de RangeAreas .
RangeAreas.cellCount Obtient le nombre total de cellules dans toutes les plages dans laRangeAreas.
RangeAreas.calculate recalcule les cellules de toutes les plages dans laRangeAreas.
RangeAreas.getEntireColumn et RangeAreas.getEntireRow retourner un autreRangeAreas objet qui représente toutes les colonnes (ou lignes) dans toutes les plages dans la RangeAreas. Par exemple, si leRangeAreas représente « A1 : C4 » et « F14:L15 », puis RangeAreas.getEntireColumn renvoie unRangeAreas objet qui représente « A:C » et « F:L ».
RangeAreas.copyFrom peut prendre un Range paramètre ou représentant RangeAreas les plages sources de l’opération de copie.

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éerRangeAreasl’objet selon deux méthodes de base:

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.
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 les membres du tableauRangeAreas.areas.items. 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.

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
});

Les choses se compliquent lorsque la consistance est impossible. Le comportement de propriétésRangeAreas suit ces trois principes:

Une propriété booléenne d’un objetRangeAreas renvoiefalseà moins que la propriété soit vraie pour toutes les plages membres.
Les propriétés non-booléennes, avec l’exception de la propriétéaddressrenvoienullà moins que la propriété correspondante sur toutes les plages membres dispose de la même valeur.
La propriétéaddressrenvoie une chaîne délimitée à virgule des adresses des plages membres.

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

Partager via