Suchen nach speziellen Zellen innerhalb eines Bereichs mithilfe der Excel-JavaScript-API

  • Artikel

Dieser Artikel enthält Codebeispiele, die mithilfe der Excel-JavaScript-API nach speziellen Zellen innerhalb eines Bereichs suchen. Eine vollständige Liste der Eigenschaften und Methoden, die das Range Objekt unterstützt, finden Sie unter Excel.Range-Klasse.

Suchen von Bereichen mit speziellen Zellen

Die Methoden Range.getSpecialCells und Range.getSpecialCellsOrNullObject suchen Bereiche basierend auf den Merkmalen ihrer Zellen und den Werttypen ihrer Zellen. Beide Methoden geben RangeAreas-Objekte zurück. Nachfolgend finden Sie die Signaturen der Methoden aus der TypeScript-Datentypdatei:

getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

Im folgenden Codebeispiel wird die getSpecialCells -Methode verwendet, um alle Zellen mit Formeln zu finden. Bei diesem Code ist Folgendes zu beachten:

  • Er beschränkt den Teil des Arbeitsblattes, das durchsucht werden muss, indem zunächst Worksheet.getUsedRange und dann getSpecialCells nur für diesen Bereich aufgerufen wird.
  • Die getSpecialCells-Methode gibt ein RangeAreas-Objekt zurück, alle Zellen mit Formeln werden daher pink eingefärbt, auch dann, wenn sie nicht zusammenhängen.
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaRanges = usedRange.getSpecialCells(Excel.SpecialCellType.formulas);
    formulaRanges.format.fill.color = "pink";

    await context.sync();
});

Wenn keine Zellen mit dem gesuchten Merkmal im Bereich vorhanden sind, gibt getSpecialCells einen ItemNotFound-Fehler aus. Dies leitet den Fluss des Steuerelements zu einem catch-Block um, falls vorhanden. Wenn kein catch Block vorhanden ist, wird die -Methode durch den Fehler angehalten.

Wenn Sie davon ausgehen können, dass immer Zellen mit dem gesuchten Merkmal vorhanden sind, möchten Sie wahrscheinlich, dass der Code einen Fehler auslöst, wenn diese Zellen nicht vorhanden sind. Falls es jedoch möglich ist, dass keine entsprechenden Zellen vorhanden sind, sollte der Code die Möglichkeit überprüfen und den Vorgang ordnungsgemäß abwickeln, ohne einen Fehler auszulösen. Dieses Verhalten können Sie mit der getSpecialCellsOrNullObject-Methode und der zurückgegebenen isNullObject-Eigenschaft erreichen. Im folgenden Codebeispiel wird dieses Muster verwendet. Bei diesem Code ist Folgendes zu beachten:

  • Die getSpecialCellsOrNullObject Methode gibt immer ein Proxyobjekt zurück, sodass es nie null im normalen JavaScript-Sinne ist. Wenn keine übereinstimmenden Zellen gefunden werden, wird die isNullObject-Eigenschaft des Objekts auf true festgelegt.
  • Sie ruft aufcontext.sync, bevor die isNullObject -Eigenschaft getestet wird. Dies ist eine Voraussetzung für alle *OrNullObject-Methoden und Eigenschaften, da Sie eine Eigenschaft immer laden und synchronisieren müssen, um sie lesen zu können. Es ist jedoch nicht erforderlich, die isNullObject Eigenschaft explizit zu laden. Es wird automatisch von context.sync geladen, auch wenn load nicht für das -Objekt aufgerufen wird. Weitere Informationen finden Sie unter *OrNullObject-Methoden und -Eigenschaften.
  • Sie können diesen Code testen, indem Sie zuerst einen Bereich auswählen, der keine Formelzellen aufweist, und diesen ausführen. Wählen Sie dann einen Bereich, der mindestens eine Zelle mit einer Formel enthält, und führen Sie diesen erneut aus.
await Excel.run(async (context) => {
    let range = context.workbook.getSelectedRange();
    let formulaRanges = range.getSpecialCellsOrNullObject(Excel.SpecialCellType.formulas);
    await context.sync();
        
    if (formulaRanges.isNullObject) {
        console.log("No cells have formulas");
    }
    else {
        formulaRanges.format.fill.color = "pink";
    }
    
    await context.sync();
});

Der Einfachheit halber verwenden alle anderen Codebeispiele in diesem Artikel die getSpecialCells -Methode anstelle von getSpecialCellsOrNullObject.

Einschränken der Zielzellen mit Zellwerttypen

Die Methoden Range.getSpecialCells() und Range.getSpecialCellsOrNullObject() akzeptieren einen optionalen zweiten Parameter, der verwendet wird, um die Zielzellen weiter einzuschränken. Dieser zweite Parameter ist ein Excel.SpecialCellValueType, den Sie verwenden, um anzugeben, dass Sie nur Zellen wünschen, die bestimmte Arten von Werten enthalten.

Hinweis

Der Excel.SpecialCellValueType-Parameter kann nur verwendet werden, wenn Excel.SpecialCellTypeExcel.SpecialCellType.formulas oder Excel.SpecialCellType.constants ist.

Überprüfen auf einen einzelnen Zellwerttyp

Die Excel.SpecialCellValueType-Enumeration verfügt über diese vier grundlegenden Arten (zusätzlich zu den anderen kombinierten Werten, die weiter unten in diesem Abschnitt beschrieben werden):

  • Excel.SpecialCellValueType.errors
  • Excel.SpecialCellValueType.logical (d. h. boolesch)
  • Excel.SpecialCellValueType.numbers
  • Excel.SpecialCellValueType.text

Im folgenden Codebeispiel werden spezielle Zellen gesucht, die numerische Konstanten sind, und diese Zellen rosa gefärbt. Bei diesem Code ist Folgendes zu beachten:

  • Es werden nur Zellen hervorgehoben, die über einen Literalzahlwert verfügen. Zellen, die eine Formel (auch wenn das Ergebnis eine Zahl ist) oder boolesche Zellen, Text- oder Fehlerzustandszellen werden nicht hervorgehoben.
  • Um den Code zu testen, müssen Sie sicherstellen, dass das Arbeitsblatt einige Zellen mit Literalwerten, einige Zellen mit anderen Arten von Literalwerten und einige Zellen mit Formeln aufweist.
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let constantNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.constants,
        Excel.SpecialCellValueType.numbers);
    constantNumberRanges.format.fill.color = "pink";

    await context.sync();
});

Überprüfen auf mehrere Zellwerttypen

Manchmal müssen Sie mehrere Zellwerttypen bearbeiten, z. B. Zellen mit Textwerten oder booleschen Werten (Excel.SpecialCellValueType.logical). Die Excel.SpecialCellValueType-Enumeration besitzt Werte mit kombinierten Typen. Excel.SpecialCellValueType.logicalText zielt beispielsweise auf alle boolesche Zellen und Zellen mit Textwerten ab. Excel.SpecialCellValueType.all ist der Standardwert, der die zurückgegeben Zellwerttypen nicht einschränkt. Im folgenden Codebeispiel werden alle Zellen mit Formeln, die eine Zahl oder einen booleschen Wert erzeugen, farbig dargestellt.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaLogicalNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.formulas,
        Excel.SpecialCellValueType.logicalNumbers);
    formulaLogicalNumberRanges.format.fill.color = "pink";

    await context.sync();
});

Siehe auch