Arbeiten mit mehreren Bereichen gleichzeitig in Excel-Add-Ins

Sie können Vorgänge anwenden oder Eigenschaften auf mehrere Bereiche gleichzeitig festlegen, auch wenn sie nicht zusammenhängend sind. Dadurch wird der Code im Vergleich zum separaten Zugriff auf jeden Bereich kürzer und effizienter.

Wichtige Punkte

• Verwenden Sie RangeAreas , um die gleiche Sache in mehreren separaten Bereichen in einem Aufruf zu lesen oder festzulegen.
• Eine -Eigenschaft ist null , es sei denn, alle Memberbereiche haben denselben Wert.
• Legen Sie eine Eigenschaft einmal für das RangeAreas Objekt fest, anstatt eine Schleife auszuführen, es sei denn, jeder Bereich benötigt eine andere Logik.
• Vermeiden Sie große RangeAreas Objekte, die aus vielen einzelnen Zellen bestehen. Grenzen Sie zuerst mit getSpecialCells oder anderen Filtern ein.
• Seien Sie vorsichtig mit ganzen Spalten oder Zeilen. Weitere Informationen finden Sie unter Lesen oder Schreiben in einen unbegrenzten Bereich.

RangeAreas

Ein RangeAreas-Objekt stellt eine Reihe von Bereichen dar, die möglicherweise nicht berührt werden. Es teilt viele Member mit Range, mit einigen Unterschieden in der Rückgabe von Werten.

Beispiele:

• address gibt eine durch Trennzeichen getrennte Zeichenfolge aller Adressen zurück.
• dataValidation gibt nur dann ein einzelnes Objekt zurück, wenn jeder Bereich dieselbe Regel aufweist, andernfalls wird zurückgegeben null.
• cellCount ist die Gesamtanzahl der Zellen in allen Bereichen.
• calculate berechnet alle Zellen im Satz neu.
• getEntireColumn und getEntireRow geben eine neue RangeAreas zurück, die sich über vollständige Spalten oder Zeilen für jedes Element erstreckt.
• copyFrom akzeptiert entweder ein Range oder ein RangeAreas als Quelle.

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 verschiedene Arten erstellen. Die folgende Liste enthält einige Beispiele.

• 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 Range.getSpecialCells() ein RangeAreas Objekt mit Zellen eines bestimmten Typs auf, und geben Sie es zurück, z. B. Zellen, die Formeln, Datenüberprüfungen oder bedingte Formatierungen enthalten.
• Aufrufen von Workbook.getSelectedRanges() 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.

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.

Kombinieren mit RangeAreasgetSpecialCells

Filtern Sie einen RangeAreas nach unten, um nur die Zellen anzuzeigen, die einem Kriterium entsprechen, z. B. Formeln, bevor Sie Formatierungen oder Überprüfungen anwenden.

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

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

Da Eigenschaftswerte abweichen können, sollten Sie diese einfachen Regeln berücksichtigen.

• Boolesche Eigenschaften sind nur dann true vorhanden, wenn sie in allen Bereichen true sind, andernfalls false.
• address gibt immer die durch Trennzeichen getrennte Adresszeichenfolge zurück.
• Andere Eigenschaften sind, null es sei denn, alle Bereiche haben denselben Wert.

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

Siehe auch

• Grundlegende Konzepte der Programmierung mit der Excel JavaScript-API
• Lesen oder Schreiben in einem großen Bereich mithilfe der Excel-JavaScript-API
• Lesen oder Schreiben in einen unbegrenzten Bereich mithilfe der Excel-JavaScript-API