Freigeben über

Aufrufen von Excel-JavaScript-APIs aus einer benutzerdefinierten Funktion

  • Artikel

Rufen Sie Excel-JavaScript-APIs aus Ihren benutzerdefinierten Funktionen auf, um Bereichsdaten abzurufen und mehr Kontext für Ihre Berechnungen zu erhalten. Das Aufrufen von Excel-JavaScript-APIs über eine benutzerdefinierte Funktion kann in folgenden Fällen hilfreich sein:

  • Eine benutzerdefinierte Funktion muss vor der Berechnung Informationen aus Excel abrufen. Diese Informationen können Dokumenteigenschaften, Bereichsformate, benutzerdefinierte XML-Teile, einen Arbeitsmappennamen oder andere Excel-spezifische Informationen enthalten.
  • Eine benutzerdefinierte Funktion legt das Zahlenformat der Zelle für die Rückgabewerte nach der Berechnung fest.

Wichtig

Um Excel-JavaScript-APIs aus Ihrer benutzerdefinierten Funktion aufzurufen, müssen Sie eine freigegebene Runtime verwenden. Verwenden Sie den Yeoman-Generator für Office-Add-Ins , um benutzerdefinierte Excel-Funktionen mithilfe eines Freigegebenen Runtime-Projekts zu installieren. Weitere Informationen finden Sie unter Konfigurieren Ihres Office-Add-Ins für die Verwendung einer freigegebenen Runtime .

Codebeispiel

Zum Aufrufen von Excel-JavaScript-APIs aus einer benutzerdefinierten Funktion benötigen Sie zunächst einen Kontext. Verwenden Sie das Excel.RequestContext-Objekt , um einen Kontext abzurufen. Verwenden Sie dann den Kontext, um die APIs aufzurufen, die Sie in der Arbeitsmappe benötigen.

Im folgenden Codebeispiel wird gezeigt, wie Sie verwenden Excel.RequestContext , um einen Wert aus einer Zelle in der Arbeitsmappe abzurufen. In diesem Beispiel wird der address Parameter an die Worksheet.getRange-Methode der Excel-JavaScript-API übergeben und muss als Zeichenfolge eingegeben werden. Beispielsweise muss die in die Excel-Benutzeroberfläche eingegebene benutzerdefinierte Funktion dem Muster =CONTOSO.GETRANGEVALUE("A1")folgen, wobei "A1" die Adresse der Zelle ist, aus der der Wert abgerufen werden soll.

/**
 * @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 beim Aufrufen 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 aufgerufen werden. Rufen Sie keine Excel-JavaScript-APIs 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 schlechter Leistung, 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 Kalkulationstabelle.
  • Ändern des Werts einer anderen Zelle.
  • Verschieben, Umbenennen, Löschen oder Hinzufügen von Blättern zu einer Arbeitsmappe
  • Hinzufügen von Namen zu einer Arbeitsmappe
  • Legen Sie Eigenschaften fest.
  • Ändern Sie eine der Excel-Umgebungsoptionen, z. B. den Berechnungsmodus oder Bildschirmansichten.

Das Add-In für benutzerdefinierte Funktionen kann Informationen aus Zellen außerhalb der Zelle lesen, in der die benutzerdefinierte Funktion ausgeführt wird, 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 Excel-Neuberechnung stattfindet, da dieses Szenario zu unvorhersehbaren Ergebnissen führt.

Nächste Schritte

Siehe auch