Synchrone benutzerdefinierte Funktionen (Vorschau)

Hinweis

Synchrone benutzerdefinierte Funktionen sind in der öffentlichen Vorschau verfügbar und können je nach Feedback geändert werden. Verwenden Sie keine synchronen benutzerdefinierten Funktionen in einem Produktions-Add-In.

Um dieses Feature verwenden zu können, müssen Sie die Vorschauversion der Office JavaScript-API-Bibliothek aus dem Office.js Content Delivery Network (CDN) verwenden. Die Typdefinitionsdatei für die TypeScript-Kompilierung und IntelliSense finden Sie unter CDN und DefinitelyTyped. Sie können diese Typen mit npm install --save-dev @types/office-js-preview installieren.

Synchrone benutzerdefinierte Funktionen ermöglichen es, die Auswertungs- und bedingten Formatierungsprozesse in Excel gleichzeitig mit der benutzerdefinierten Funktion auszuführen. Aktivieren Sie synchrone Unterstützung, wenn Ihre benutzerdefinierte Funktion zusammen mit einem der in diesem Artikel aufgeführten Excel-Prozesse ausgeführt werden muss. Benutzerdefinierte Funktionen, die keine synchronen Vorgänge unterstützen, geben einen Fehler zurück, z. B #CALC! . wenn #VALUE! sie gleichzeitig mit diesen Excel-Prozessen ausgeführt werden.

Warnung

Synchrone benutzerdefinierte Funktionen unterstützen keine Schreibvorgänge mit Office JavaScript-APIs, z. B. die Verwendung Range.values zum Festlegen eines Zellwerts. Das Aufrufen eines Schreibvorgangs in einer synchronen benutzerdefinierten Funktion kann dazu führen, dass Excel einfriert.

Excel-Prozesse, die von synchronen benutzerdefinierten Funktionen unterstützt werden

Die folgenden Aktionen und Prozesse arbeiten mit synchronen benutzerdefinierten Funktionen.

Unterstützte Evaluierungsaktionen

  • Auswählen von Formeln und anschließendes Auswerten der Formel in Excel.
  • Auswählen von Formeln und anschließendes Einfügen einer Funktion in Excel.
  • Im Zellbearbeitungsmodus: Markieren eines Teils einer Formel und Verwenden von F9, um Teilergebnisse der Berechnung anzuzeigen.
  • Die Application.Calculate Methode in VBA.

Unterstützte Aktionen für bedingte Formatierung

Die folgende Liste gilt für Aktionen zur bedingten Formatierung, die sowohl von der Excel-Benutzeroberfläche als auch von Office JavaScript-APIs ausgelöst werden.

  • Erstellen Sie eine neue Regel.
  • Regeln bearbeiten.
  • Regeln löschen.
  • Regeln zum Neuanordnen von Regeln.
  • Ändern Sie den Bereich "Gilt für".
  • Aktivieren oder deaktivieren Sie "Stopp, wenn wahr".
  • Löschen Sie alle Regeln.
  • Schneiden Sie Zellen mit bedingter Formatierung aus und fügen Sie sie ein.
  • Kopieren Sie Zellen, die bedingte Formatierungen enthalten, und fügen Sie sie ein.

Hinweis

Wenn eine synchrone benutzerdefinierte Funktion viel Zeit in Anspruch nimmt, blockiert Excel möglicherweise vorübergehend die Benutzeroberfläche, während auf das Ergebnis gewartet wird. Um längere Unterbrechungen zu vermeiden, können Benutzer die Ausführung der Funktion jederzeit abbrechen, indem sie die Esc-Taste verwenden oder eine beliebige Stelle außerhalb der Zelle oder des Dialogfelds auswählen.

Aktivieren der synchronen Unterstützung in Ihrem Add-In

Führen Sie die folgenden Schritte aus, um synchrone Szenarien in Ihrem Add-In zu unterstützen.

  • Wenn Sie JSON-Metadaten automatisch generieren, verwenden Sie das @supportSync JSDoc-Tag.
  • Wenn Sie JSON-Metadaten manuell erstellen, verwenden Sie die "supportSync": true Einstellung im "options" Objekt Ihrer functions.json Datei.
  • Wenn die Funktion Excel.RequestContextverwendet, rufen Sie die setInvocation Methode von Excel.RequestContext auf und übergeben Sie das CustomFunctions.Invocation Objekt. Ein Beispiel finden Sie im Codebeispiel.

Wichtig

Synchrone benutzerdefinierte Funktionen können keine Streaming - oder veränderlichen Funktionen sein. Wenn Sie das @supportSync Tag mit @volatile oder-Tags @streaming verwenden, ignoriert Excel die synchrone Unterstützung. Die Unterstützung für flüchtige Elemente oder Streaming hat Vorrang.

Codebeispiel

Das folgende Codebeispiel zeigt, wie eine synchrone benutzerdefinierte Funktion erstellt wird.

/** 
 * A synchronous custom function that takes a cell address and returns the value of that cell.
 * @customfunction
 * @supportSync
 * @param {string} address The address of the cell from which to retrieve the value.
 * @param {CustomFunctions.Invocation} invocation Invocation object.
 * @returns The value of the cell at the input address.
 */ 
export async function getCellValue(address, invocation) {
  const context = new Excel.RequestContext();
  context.setInvocation(invocation); // The `invocation` object must be passed in the `setInvocation` method for synchronous functions.

  const range = context.workbook.worksheets.getActiveWorksheet().getRange(address);
  range.load("values");

  await context.sync(); 
  return range.values[0][0];
}

Tipp

Informationen zum Erkunden synchroner benutzerdefinierter Funktionen in einem vollständigen Add-In finden Sie unter Erstellen synchroner benutzerdefinierter Funktionen in Excel (Vorschau) in unserem Codebeispielrepository für Office-Add-Ins.

Siehe auch

  • Zuletzt aktualisiert um