Arbeiten mit mehreren Bereichen gleichzeitig in Excel-Add-Ins

Artikel
04/07/2023

Mithilfe der Excel-JavaScript-Bibliothek kann das Add-In in mehreren Bereichen gleichzeitig Vorgänge ausführen und Eigenschaften festlegen. Die Bereiche müssen nicht zusammenhängend sein. Abgesehen davon, dass Ihr Code vereinfacht wird, wird das Festlegen einer Eigenschaft auf diese Art und Weise schneller ausgeführt als wenn die gleiche Eigenschaft einzeln für jeden Bereich festgelegt wird.

RangeAreas

Ein Satz von (möglicherweise nicht zusammenhängenden) Bereichen wird durch ein RangeAreas-Objekt dargestellt. Diese enthält Eigenschaften und Methoden, die dem Range-Typ ähnlich sind zu geben (viele mit demselben oder einem ähnlichen Namen), aber die Anpassungen wurden an Folgendem vorgenommen:

Die Datentypen für Eigenschaften und das Verhalten der Setter und Getter.
Die Datentypen von Methodenparametern und die Verhaltensweisen der Methoden.
Die Datentypen der Methode geben Werte zurück.

Beispiele:

RangeAreas hat eine address-Eigenschaft, die eine durch Trennzeichen getrennte Zeichenfolge von Bereichsadressen und nicht nur eine Adresse wie bei der Range.address-Eigenschaft zurückgibt.
RangeAreas hat eine dataValidation-Eigenschaft, die ein DataValidation-Objekt zurückgibt, das die Datenüberprüfung aller Bereiche in RangeAreas darstellt, wenn dies einheitlich ist. Die Eigenschaft ist null, wenn identische DataValidation-Objekte nicht auf alle Bereiche in der RangeAreas angewendet werden. Dies ist ein allgemeines, aber nicht universelles Prinzip mit dem RangeAreas -Objekt: Wenn eine Eigenschaft nicht über konsistente Werte für alle Bereiche im RangeAreasverfügt, ist nullsie . Weitere Informationen und einige Ausnahmen finden Sie unter Lesen der Eigenschaften von RangeAreas .
RangeAreas.cellCount Ruft die Gesamtzahl der Zellen in allen Bereichen in RangeAreas ab.
RangeAreas.calculate berechnet die Zellen in allen Bereichen in RangeAreas neu.
RangeAreas.getEntireColumn und RangeAreas.getEntireRow geben ein anderes RangeAreas-Objekt zurück, das alle Spalten (oder Zeilen) in allen Bereichen in RangeAreas darstellt. Wenn RangeAreas zum Beispiel "A1: C4" und "F14:L15" darstellt, so gibt RangeAreas.getEntireColumn ein RangeAreas-Objekt zurück, das "A:C" und "F:L" darstellt.
RangeAreas.copyFrom kann entweder einen Range - oder einen RangeAreas -Parameter verwenden, der die Quellbereiche des Kopiervorgangs darstellt.

Vollständige Liste von Bereichselementen, die auch in RangeAreas verfügbar sind

Eigenschaften

Bevor Sie Code schreiben, der aufgelistete Eigenschaften liest, sollten Sie sich mit Lesen von Eigenschaften von RangeAreas vertraut machen. Es gibt Besonderheiten dahingehend, was zurückgegeben wird.

address
addressLocal
cellCount
conditionalFormats
context
dataValidation
format
isEntireColumn
isEntireRow
style
worksheet

Methoden

calculate()
clear()
convertDataTypeToText()
convertToLinkedDataType()
copyFrom()
getEntireColumn()
getEntireRow()
getIntersection()
getIntersectionOrNullObject()
getOffsetRange()(für das RangeAreas Objekt benanntgetOffsetRangeAreas)
getSpecialCells()
getSpecialCellsOrNullObject()
getTables()
getUsedRange()(für das RangeAreas Objekt benanntgetUsedRangeAreas)
getUsedRangeOrNullObject()(für das RangeAreas Objekt benanntgetUsedRangeAreasOrNullObject)
load()
set()
setDirty()
toJSON()
track()
untrack()

RangeArea-spezifische Eigenschaften und Methoden

Der RangeAreas-Typ verfügt über einige Eigenschaften und Methoden, die sich nicht im Range-Objekt befinden. Im Folgenden ist eine Auswahl dieser Optionen aufgeführt.

areas: Ein RangeCollection-Objekt, das alle vom RangeAreas-Objekt dargestellten Bereiche enthält. Das RangeCollection-Objekt ist auch neu und ähnelt den anderen Excel-Auflistungsobjekten. Es enthält eine items-Eigenschaft, die ein Array von Range-Objekten ist, die die Bereiche darstellen.
areaCount: Die Gesamtanzahl von Bereichen in RangeAreas.
getOffsetRangeAreas: Funktioniert genauso wie Range.getOffsetRange, mit dem Unterschied, dass RangeAreas zurückgegeben wird und Bereiche enthält, die alle von einem der Bereiche im ursprünglichen RangeAreas versetzt sind.

Erstellen von RangeAreas

Sie können ein RangeAreas-Objekt auf zwei grundlegende Arten erstellen:

Rufen Sie Worksheet.getRanges() auf, und übergeben Sie eine Zeichenfolge mit durch Trennzeichen getrennten Bereichsadressen. Wenn einer der Bereiche, den Sie einschließen möchten, in ein NamedItem umgewandelt wurde, können Sie den Namen anstelle der Adresse in die Zeichenfolge einschließen.
Rufen Sie Workbook.getSelectedRanges() auf. Diese Methode gibt ein RangeAreas-Objekt zurück, das alle Bereiche darstellt, die in dem derzeit aktiven Arbeitsblatt ausgewählt sind.

Wenn Sie ein RangeAreas-Objekt haben, können Sie andere Objekte mithilfe der Methoden in dem Objekt erstellen, die RangeAreas zurückgeben, z. B. getOffsetRangeAreas und getIntersection.

Hinweis

Einem RangeAreas-Objekt können nicht direkt weitere Bereiche hinzugefügt werden. Die Auflistung in RangeAreas.areas weist beispielsweise keine add-Methode auf.

Warnung

Versuchen Sie nicht, Elemente des RangeAreas.areas.items-Arrays direkt hinzuzufügen oder zu löschen. Dies führt zu unerwünschtem Verhalten im Code. Es ist beispielsweise möglich, ein weiteres Range-Objekt in das Array zu pushen, dadurch werden aber Fehler verursacht, da sich RangeAreas-Eigenschaften und -Methoden so verhalten, als wäre das neue Element nicht vorhanden. Die areaCount-Eigenschaft schließt beispielsweise keine Bereiche ein, die auf diese Weise gepusht wurden, und RangeAreas.getItemAt(index) löst einen Fehler aus, wenn index größer ist als areasCount-1. In ähnlicher Weise werden durch Löschen eines Range-Objekts im RangeAreas.areas.items-Array durch Abrufen eines Verweises darauf und durch Aufrufen der Range.delete-Methode Fehler verursacht: Obwohl das Range-Objekt gelöscht wurde, verhalten sich die Eigenschaften und Methoden des übergeordneten RangeAreas-Objekts so, als wäre es immer noch vorhanden. Wenn der Code beispielsweise RangeAreas.calculate aufruft, versucht Office den Bereich zu berechnen, schlägt jedoch fehl, da das Bereichsobjekt fehlt.

Festlegen von Eigenschaften für mehrere Bereiche

Durch Festlegen einer Eigenschaft für ein RangeAreas-Objekt wird die entsprechende Eigenschaft in allen Bereichen in der RangeAreas.areas-Sammlung festgelegt.

Nachfolgend finden Sie ein Beispiel zum Festlegen einer Eigenschaft in mehreren Bereichen. Die Funktion hebt die Bereiche F3:F5 und H3:H5 hervor.

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

Dieses Beispiel gilt für Szenarien, in denen Sie die Bereichsadressen, die Sie an getRanges übergeben, hartcodieren oder einfach zur Laufzeit berechnen. Zu einigen der Szenarien, in denen dies der Fall ist, gehören die Folgenden:

Der Code wird im Kontext einer bekannten Vorlage ausgeführt.
Der Code wird im Kontext importierter Daten ausgeführt, in denen das Schema der Daten bekannt ist.

Abrufen von bestimmten Zellen aus mehreren Bereichen

Die getSpecialCells- und getSpecialCellsOrNullObject-Methoden für das RangeAreas-Objekt funktionieren analog zu den Methoden mit demselben Namen für das Range-Objekt. Mit diesen Methoden werden die Zellen mit den angegebenen Eigenschaften aus allen Bereichen in der RangeAreas.areas-Sammlung zurückgegeben. Weitere Informationen zu speziellen Zellen finden Sie unter Suchen nach speziellen Zellen innerhalb eines Bereichs.

Beim Aufrufen der getSpecialCells- oder getSpecialCellsOrNullObject-Methode für ein RangeAreas-Objekt trifft Folgendes zu:

Wenn Sie Excel.SpecialCellType.sameConditionalFormat als ersten Parameter übergeben, gibt die Methode alle Zellen mit der gleichen bedingten Formatierung wie die obere linke Zelle im ersten Bereich in der RangeAreas.areas-Sammlung zurück.
Wenn Sie Excel.SpecialCellType.sameDataValidation als ersten Parameter übergeben, gibt die Methode alle Zellen mit der gleichen Regel für die Datenüberprüfung wie die obere linke Zelle im ersten Bereich in der RangeAreas.areas-Sammlung zurück.

Lesen von Eigenschaften von RangeAreas

Das Lesen von Eigenschaftswerten von RangeAreas erfordert Sorgfalt, da eine bestimmte Eigenschaft möglicherweise unterschiedliche Werte für unterschiedliche Bereiche innerhalb von RangeAreas haben kann. Die allgemeine Regel besteht darin, dass, wenn ein konsistenter Wert zurückgegeben werden kann, dieser auch zurückgegeben wird. Im folgenden Code wird beispielsweise der RGB-Code für Pink (#FFC0CB) und true in der Konsole protokolliert, da beide Bereiche im RangeAreas Objekt eine rosa Füllung aufweisen und beide ganze Spalten sind.

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

Wenn Konsistenz nicht möglich ist, wird alles komplizierter. Das Verhalten von RangeAreas-Eigenschaften folgt den folgenden drei Prinzipien:

Eine boolesche Eigenschaft eines RangeAreas-Objekts gibt false zurück, sofern die Eigenschaft für alle Elementbereiche nicht „true“ ist.
Nicht boolesche Eigenschaften, mit Ausnahme der address-Eigenschaft, geben null zurück, sofern die entsprechende Eigenschaft in allen Elementbereichen nicht denselben Wert aufweist.
Die address-Eigenschaft gibt eine durch Trennzeichen getrennte Zeichenfolge der Adressen der Elementbereiche zurück.

Der folgende Code erstellt beispielsweise ein RangeAreas, in dem nur ein Bereich eine ganze Spalte ist und nur eine mit pink gefüllt ist. In der Konsole wird null für die Füllfarbe, false für die isEntireRow-Eigenschaft und „Sheet1!F3:F5, Sheet1!H:H“ (davon ausgehend, dass der Blattname „Sheet1“ ist) für die address-Eigenschaft angezeigt.

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

Freigeben über