Erstellen von benutzerdefinierten Funktionen in Excel

Mithilfe benutzerdefinierter Funktionen können Entwickler Excel neue Funktionen hinzufügen, indem sie diese in JavaScript als Teil eines Add-Ins definieren. Benutzer können auf benutzerdefinierte Funktionen in Excel auf die gleiche Weise zugreifen wie auf die nativen Funktionen in Excel (beispielsweise SUM()).

Hinweis

Benutzerdefinierte Funktion ist ein allgemeiner Begriff, der durch benutzerdefinierte Funktion ersetzt werden kann. Beide Bedingungen gelten für VBA-, COM- und Office.js-Add-Ins. In der Dokumentation zu Office-Add-Ins wird der Begriff benutzerdefinierte Funktion verwendet, wenn auf benutzerdefinierte Funktionen verwiesen wird, die Office JavaScript-APIs verwenden.

Das folgende animierte Bild zeigt Ihre Arbeitsmappe und ruft eine Funktion auf, die Sie mit JavaScript oder Typescript erstellt haben. In diesem Beispiel berechnet die benutzerdefinierte Funktion =MYFUNCTION.SPHEREVOLUME das Volumen der Sphäre.

Animiertes Bild, das einen Endbenutzer zeigt, der die benutzerdefinierte Funktion MYFUNCTION.SPHEREVOLUME in eine Zelle eines Excel-Arbeitsblatts einfügt.

Der folgende Code definiert die benutzerdefinierte Funktion =MYFUNCTION.SPHEREVOLUME.

/**
 * Returns the volume of a sphere.
 * @customfunction
 * @param {number} radius
 */
function sphereVolume(radius) {
  return Math.pow(radius, 3) * 4 * Math.PI / 3;
}

Wie eine benutzerdefinierte Funktion im Code definiert wird

Wenn Sie den Yeoman-Generator für Office-Add-Ins zum Erstellen eines Excel-Add-In-Projekts mit benutzerdefinierten Funktionen verwenden, erstellt er Dateien, die Ihre Funktionen und Ihren Aufgabenbereich steuern. Wir konzentrieren uns auf die Dateien, die für benutzerdefinierte Funktionen wichtig sind.

Datei Dateiformat Beschreibung
./src/functions/functions.js
oder
./src/functions/functions.ts		 JavaScript
oder
TypeScript		 Enthält den Code, der benutzerdefinierte Funktionen definiert.
./src/functions/functions.html HTML Stellt einen <script>-Verweis auf die JavaScript-Datei bereit, die benutzerdefinierte Funktionen definiert.
./manifest.xml oder ./manifest.json XML oder JSON Gibt den Speicherort für mehrere Dateien an, die Ihre benutzerdefinierten Funktionen verwenden, z. B. für JavaScript-, JSON- und HTML-Dateien. Außerdem listet sie die Speicherorte von Aufgabenbereichsdateien und Befehlsdateien auf und gibt an, welche Laufzeit (Runtime) Ihre benutzerdefinierten Funktionen verwenden sollten. Der Yeoman-Generator für Office-Add-Ins erstellt ein Projekt mit einem XML-Manifest.

Tipp

Der Yeoman-Generator für Office-Add-Ins bietet mehrere Excel-Projekte für benutzerdefinierte Funktionen . Wir empfehlen die Auswahl des Projekttyps Excel Custom Functions mit einer Shared Runtime und dem Skripttyp JavaScript.

Skriptdatei

Die Skriptdatei (./src/functions/functions.js oder ./src/functions/functions.ts) enthält den Code, der benutzerdefinierte Funktionen und Kommentare definiert, die die Funktion definieren.

Der folgende Code definiert die benutzerdefinierte Funktion add. Die Codekommentare werden verwendet, um eine JSON-Metadatendatei zu generieren, die die benutzerdefinierte Funktion für Excel beschreibt. Der erforderliche @customfunction-Kommentar wird zuerst deklariert, um anzugeben, dass es sich um eine benutzerdefinierte Funktion handelt. Als Nächstes werden zwei Parameter deklariert, first und second, gefolgt von deren description-Eigenschaften. Und schließlich gibt es eine returns-Beschreibung. Weitere Informationen dazu, welche Kommentare für Ihre benutzerdefinierte Funktion erforderlich sind, finden Sie unter Automatisches Erstellen von JSON-Metadaten für benutzerdefinierte Funktionen.

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number.
 * @param second Second number.
 * @returns The sum of the two numbers.
 */

function add(first, second){
  return first + second;
}

Tipp

In Excel im Web werden benutzerdefinierte Funktionsbeschreibungen und Parameterbeschreibungen inline angezeigt. Dadurch erhalten Benutzer zusätzliche Informationen beim Schreiben benutzerdefinierter Funktionen. Erfahren Sie, wie Sie die Inlinebeschreibungen konfigurieren, indem Sie sich mit den benutzerdefinierten Funktionen vertraut machen Script Lab-Beispiele in Excel im Web. Im folgenden Screenshot sehen Sie ein Beispiel.

Eine benutzerdefinierte Funktion mit Inlinebeschreibungen, die in Excel im Web angezeigt werden.

Manifestdatei

Die Manifestdatei für ein Add-In, das benutzerdefinierte Funktionen definiert, konfiguriert den Namespace, gibt Dateispeicherorte an und definiert die Laufzeit. Wählen Sie die Registerkarte für den Manifesttyp aus, den Sie verwenden.

Benutzerdefinierte Funktionen erfordern Lese-/Schreibberechtigungen für Dokumente. Angabe im einheitlichen Manifest für Microsoft 365 oder ReadWriteDocument im Nur-Add-In-ManifestDocument.ReadWrite.User. Schreibgeschützte Berechtigungen können dazu führen, dass Funktionen den #BUSY! Fehler zurückgeben.

Das einheitliche Manifest für ein Add-In, das benutzerdefinierte Funktionen definiert (./manifest.json im Projekt), hat mehrere Funktionen.

  • Definiert den Namespace für Ihre benutzerdefinierten Funktionen, die das customFunctions.namespace Objekt verwenden. Ein Namespace stellt sich Ihren benutzerdefinierten Funktionen voran und hilft Kunden so, Ihre Funktionen als Teil Ihres Add-Ins zu identifizieren.
  • Verwendet die customFunctions Erweiterung, um Metadaten zu benutzerdefinierten Funktionen anzugeben, einschließlich des Speicherorts der JSON-Metadatendatei über die metadataUrl Eigenschaft.
  • Konfiguriert die Laufzeit für benutzerdefinierte Funktionen mithilfe des runtimes Arrays mit einer actions.type Eigenschaft, die auf festgelegt ist."executeFunction"

Ein vollständig funktionsfähiges Manifest eines Beispiel-Add-Ins finden Sie im Manifest in einem unserer GitHub-Repositorys für Office-Add-In-Beispiele.

Tipp

Wenn Sie Ihr Add-In in mehreren Umgebungen testen (z. B. in Entwicklung, Staging, Demo usw.), empfehlen wir, dass Sie für jede Umgebung eine andere Manifestdatei verwenden. In jeder Manifestdatei haben Sie folgende Möglichkeiten:

  • Geben Sie die URLs an, die der Umgebung entsprechen.

  • Passen Sie Metadatenwerte an, sodass Endbenutzer die entsprechende Umgebung eines quergeladenen Add-Ins identifizieren können. Zum Beispiel:

    • Passen Sie im einheitlichen Manifest für Microsoft 365 die "name" Eigenschaft des Add-Ins und die "label" Eigenschaften für verschiedene UI-Steuerelemente an, um die Umgebung anzugeben.
    • Passen Sie im Nur-Add-In-Manifest das Element und die DisplayName Beschriftungen innerhalb des Resources Elements an, um die Umgebung anzugeben.

  • Passen Sie die benutzerdefinierten Funktionen namespace an, um die Umgebung anzugeben, wenn Ihr Add-In benutzerdefinierte Funktionen definiert.

Durch Befolgen dieser Anleitung optimieren Sie den Testprozess und vermeiden Probleme, die andernfalls auftreten würden, wenn ein Add-In für mehrere Umgebungen gleichzeitig quergeladen wird.

Gemeinsame Dokumenterstellung

Excel im Web und auf Windows, die mit einem Microsoft 365-Abonnement verbunden sind, ermöglichen Endbenutzern die gemeinsame Dokumenterstellung in Excel. Wenn die Arbeitsmappe eines Endbenutzers eine benutzerdefinierte Funktion verwendet, wird der mitverfassende Kollege des Endbenutzers aufgefordert, das entsprechende Add-In für die benutzerdefinierte Funktion zu laden. Sobald beide Benutzer das Add-In geladen haben, gibt die benutzerdefinierte Funktion die Ergebnisse über die gemeinsame Dokumenterstellung frei.

Weitere Informationen zur gemeinsamen Dokumenterstellung finden Sie unter Informationen zur gemeinsamen Dokumenterstellung in Excel.

Unterstützte Plattformen

Benutzerdefinierte Excel-Funktionen werden von den meisten Office-Clientanwendungen unterstützt. Benutzerdefinierte Excel-Funktionen werden derzeit in Office auf iPad oder unbefristeten volumenlizenzierten Versionen von Office 2021 oder früher unter Windows nicht unterstützt. Weitere Informationen finden Sie unter Anforderungssätze für benutzerdefinierte Funktionen.

Nächste Schritte

Möchten Sie benutzerdefinierte Funktionen ausprobieren? Schauen Sie sich die einfache Schnellstartanleitung für benutzerdefinierte Funktionen oder das ausführlichere Tutorial für benutzerdefinierte Funktionen an, falls Sie es noch nicht getan haben.

Eine weitere einfache Möglichkeit, benutzerdefinierte Funktionen auszuprobieren, ist die Verwendung von Script Lab, einem Add-In, mit dem Sie mit benutzerdefinierten Funktionen direkt in Excel experimentieren können. Sie können ausprobieren, eigene benutzerdefinierte Funktion zu erstellen, oder mit den bereitgestellten Beispielen experimentieren.

Siehe auch

  • Zuletzt aktualisiert um