Aufrufen von Excel-JavaScript-APIs aus einer benutzerdefinierten Funktion

Rufen Sie Excel JavaScript-APIs aus einer benutzerdefinierten Funktion auf, wenn deren Berechnung Arbeitsmappendaten benötigt, die nicht als Parameter übergeben werden. Eine benutzerdefinierte Funktion kann beispielsweise Dokumenteigenschaften, Bereichswerte oder -formate, benutzerdefinierte XML-Teile oder den Namen der Arbeitsmappe lesen.

Halten Sie diese Aufrufe schreibgeschützt. Eine benutzerdefinierte Funktion, die andere Zellen oder die Excel-Umgebung ändert, kann zu Leistungseinbußen, Timeouts oder unendlichen Rechenschleifen führen.

Bevor Sie beginnen

Ihr Add-In muss eine freigegebene Laufzeit verwenden, bevor eine benutzerdefinierte Funktion Excel-JavaScript-APIs aufrufen kann. Erstellen Sie ein Excel-Projekt für benutzerdefinierte Funktionen mit dem Microsoft 365 Agents Toolkit, oder konfigurieren Sie ein vorhandenes Add-In für die Verwendung einer freigegebenen Runtime.

Abrufen eines Werts aus der Arbeitsmappe

Erstellen Sie ein Excel.RequestContext-Objekt , um auf die Arbeitsmappe zuzugreifen. Laden Sie die Eigenschaften, die die Funktion benötigt, rufen context.sync()Sie sie auf und geben Sie dann das Ergebnis zurück.

Die folgende benutzerdefinierte Funktion verwendet Worksheet.getRange zum Lesen eines Zellwerts. Der address Parameter muss eine Zeichenfolge sein. Geben Sie =CONTOSO.GETRANGEVALUE("A1") beispielsweise in eine Zelle ein, um den Wert aus Zelle A1 zurückzugeben.

/**
 * @customfunction
 * @param {string} address The address of the cell from which to retrieve the value.
 * @returns The value of the cell at the input address.
 **/
async function getRangeValue(address) {
    // Retrieve the context object.
    const context = new Excel.RequestContext();

    // Use the context object to access the cell at the input address.
    const range = context.workbook.worksheets.getActiveWorksheet().getRange(address);
    range.load("values");
    await context.sync();

    // Return the value of the cell at the input address.
    return range.values[0][0];
}

Einschränkungen für den Aufruf von Excel-JavaScript-APIs über eine benutzerdefinierte Funktion

Ein Add-In für benutzerdefinierte Funktionen kann Excel-JavaScript-APIs aufrufen, aber Sie sollten vorsichtig sein, welche APIs es aufruft. Rufen Sie Excel JavaScript-APIs nicht aus einer benutzerdefinierten Funktion auf, die Zellen außerhalb der Zelle ändert, in der die benutzerdefinierte Funktion ausgeführt wird. Das Ändern anderer Zellen oder der Excel-Umgebung kann zu Leistungseinbußen, Timeouts und Endlosschleifen in der Excel-Anwendung führen. Dies bedeutet, dass Ihre benutzerdefinierten Funktionen keine der folgenden Aktionen ausführen sollten:

  • Einfügen, Löschen oder Formatieren von Zellen in der Tabelle.
  • Ändern des Werts einer anderen Zelle
  • Verschieben, Umbenennen, Löschen oder Hinzufügen von Arbeitsblättern zu einer Arbeitsmappe.
  • Hinzufügen von Namen zu einer Arbeitsmappe.
  • Eigenschaften festlegen.
  • Ändern Sie beliebige der Excel-Umgebungsoptionen, z. B. Berechnungsmodus oder Bildschirmansichten.

Das Add-In für benutzerdefinierte Funktionen kann Daten aus Zellen außerhalb der Zelle lesen, in der die benutzerdefinierte Funktion ausgeführt wird, es sollte jedoch keine Schreibvorgänge in andere Zellen ausführen. Nehmen Sie stattdessen Änderungen an anderen Zellen oder an der Excel-Umgebung aus dem Kontext einer Menübandschaltfläche oder eines Aufgabenbereichs vor. Darüber hinaus sollten benutzerdefinierte Funktionsberechnungen nicht ausgeführt werden, während eine Neuberechnung von Excel stattfindet, da dieses Szenario zu unvorhersehbaren Ergebnissen führt.

Nächste Schritte

Siehe auch

  • Last updated on