Manuelles Erstellen von JSON-Metadaten für benutzerdefinierte Funktionen

  • Artikel

Wie im Artikel Übersicht über benutzerdefinierte Funktionen beschrieben, muss ein Projekt für benutzerdefinierte Funktionen sowohl eine JSON-Metadatendatei als auch eine Skriptdatei (JavaScript oder TypeScript) enthalten, um eine Funktion zu registrieren und zur Verwendung verfügbar zu machen. Benutzerdefinierte Funktionen werden registriert, wenn der Benutzer das Add-In zum ersten Mal ausführt und danach für denselben Benutzer in allen Arbeitsmappen verfügbar sind.

Wichtig

Beachten Sie, dass benutzerdefinierte Excel-Funktionen auf den folgenden Plattformen verfügbar sind.

  • Office unter Windows
    • Microsoft 365-Abonnement
    • retail unbefristete Office 2016 und höher
  • Office für Mac
  • Office im Web

Benutzerdefinierte Excel-Funktionen werden derzeit in den folgenden Artikeln nicht unterstützt:

  • Office auf dem iPad
  • Volumenlizenzierte unbefristete Versionen von Office 2019 oder früheren Versionen

Es wird empfohlen, nach Möglichkeit die automatische JSON-Generierung zu verwenden, anstatt eine eigene JSON-Datei zu erstellen. Die automatische Generierung ist weniger anfällig für Benutzerfehler, und die yo office Gerüstdateien enthalten dies bereits. Weitere Informationen zu JSDoc-Tags und dem PROZESS der automatischen JSON-Generierung finden Sie unter Automatisches Generieren von JSON-Metadaten für benutzerdefinierte Funktionen.

Sie können jedoch ein Projekt für benutzerdefinierte Funktionen von Grund auf neu erstellen. Dieser Prozess erfordert Folgendes:

  • Schreiben Sie Ihre JSON-Datei.
  • Überprüfen Sie, ob Ihre Manifestdatei mit Ihrer JSON-Datei verbunden ist.
  • Ordnen Sie die Eigenschaften und name ihrer Funktionen id in der Skriptdatei zu, um Ihre Funktionen zu registrieren.

In der folgenden Abbildung werden die Unterschiede zwischen der Verwendung von yo office Gerüstdateien und dem Schreiben von JSON von Grund auf erläutert.

Abbildung der Unterschiede zwischen der Verwendung des Yeoman-Generators für Office-Add-Ins und dem Schreiben Ihres eigenen JSON-Codes.

Hinweis

Denken Sie daran, Ihr Manifest über den Abschnitt Ressourcen> in Ihrer XML-Manifestdatei mit der< von Ihnen erstellten JSON-Datei zu verbinden, wenn Sie nicht den Yeoman-Generator für Office-Add-Ins verwenden.

Erstellen von Metadaten und Herstellen einer Verbindung mit dem Manifest

Erstellen Sie eine JSON-Datei in Ihrem Projekt, und geben Sie alle Details zu Ihren Darin enthaltenen Funktionen an, z. B. die Parameter der Funktion. Eine vollständige Liste der Funktionseigenschaften finden Sie im folgenden Metadatenbeispiel und in der Metadatenreferenz .

Stellen Sie sicher, dass Ihre XML-Manifestdatei auf Ihre JSON-Datei im <Abschnitt Ressourcen> verweist, ähnlich wie im folgenden Beispiel.

<Resources>
    <bt:Urls>
        <bt:Url id="JSON-URL" DefaultValue="https://subdomain.contoso.com/config/customfunctions.json"/>
        <bt:Url id="JS-URL" DefaultValue="https://subdomain.contoso.com/dist/win32/ship/index.win32.bundle"/>
            <bt:Url id="HTML-URL" DefaultValue="https://subdomain.contoso.com/index.html"/>
    </bt:Urls>
    <bt:ShortStrings>
        <bt:String id="namespace" DefaultValue="CONTOSO"/>
    </bt:ShortStrings>
</Resources>

Beispiel für JSON-Metadaten

Das folgende Beispiel zeigt den Inhalt einer JSON-Metadatendatei für ein Add-In, das benutzerdefinierte Funktionen definiert. Die Abschnitte nach diesem Beispiel enthalten ausführliche Informationen zu den einzelnen Eigenschaften innerhalb dieses JSON-Beispiels.

{
  "allowCustomDataForDataTypeAny": true,
  "allowErrorForDataTypeAny": true,
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      "description": "Add two numbers",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "type": "number",
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "first",
          "description": "first number to add",
          "type": "number",
          "dimensionality": "scalar"
        },
        {
          "name": "second",
          "description": "second number to add",
          "type": "number",
          "dimensionality": "scalar"
        }
      ]
    },
    {
      "id": "GETDAY",
      "name": "GETDAY",
      "description": "Get the day of the week",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": []
    },
    {
      "id": "INCREMENTVALUE",
      "name": "INCREMENTVALUE",
      "description": "Count up from zero",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "increment",
          "description": "the number to be added each time",
          "type": "number",
          "dimensionality": "scalar"
        }
      ],
      "options": {
        "stream": true,
        "cancelable": true
      }
    },
    {
      "id": "SECONDHIGHEST",
      "name": "SECONDHIGHEST",
      "description": "Get the second highest number from a range",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "range",
          "description": "the input range",
          "type": "number",
          "dimensionality": "matrix"
        }
      ]
    }
  ]
}

Hinweis

Eine vollständige JSON-Beispieldatei ist im Commitverlauf des GitHub-Repositorys OfficeDev/Excel-Custom-Functions verfügbar. Da das Projekt so angepasst wurde, dass es automatisch JSON generiert, ist ein vollständiges Beispiel für handschriftliches JSON nur in früheren Versionen des Projekts verfügbar.

Metadatenreferenz

allowCustomDataForDataTypeAny

Die allowCustomDataForDataTypeAny -Eigenschaft ist ein boolescher Datentyp. Durch Festlegen dieses Werts auf true kann eine benutzerdefinierte Funktion Datentypen als Parameter und Rückgabewerte akzeptieren. Weitere Informationen finden Sie unter Benutzerdefinierte Funktionen und Datentypen.

Hinweis

Im Gegensatz zu den meisten anderen JSON-Metadateneigenschaften allowCustomDataForDataTypeAny ist eine Eigenschaft der obersten Ebene und enthält keine Untergeordneten Eigenschaften. Im obigen JSON-Metadatencodebeispiel finden Sie ein Beispiel für das Formatieren dieser Eigenschaft.

allowErrorForDataTypeAny

Die allowErrorForDataTypeAny -Eigenschaft ist ein boolescher Datentyp. Durch Festlegen des Werts auf true kann eine benutzerdefinierte Funktion Fehler als Eingabewerte verarbeiten. Alle Parameter mit dem Typ any oder any[][] können Fehler als Eingabewerte akzeptieren, wenn allowErrorForDataTypeAny auf truefestgelegt ist. Der Standardwert allowErrorForDataTypeAny ist false.

Hinweis

Im Gegensatz zu den anderen JSON-Metadateneigenschaften allowErrorForDataTypeAny ist eine Eigenschaft der obersten Ebene und enthält keine Untergeordneten Eigenschaften. Im obigen JSON-Metadatencodebeispiel finden Sie ein Beispiel für das Formatieren dieser Eigenschaft.

functions

Die functions-Eigenschaft ist ein Array von benutzerdefinierten Funktionsobjekten. In der folgenden Tabelle sind die Eigenschaften der einzelnen Objekte aufgeführt.

Eigenschaft Datentyp Erforderlich Beschreibung
description string Nein Die Beschreibung der Funktion, die Endbenutzern in Excel angezeigt wird. Konvertiert beispielsweise einen Celsius-Wert in Fahrenheit.
helpUrl string Nein URL, die Informationen zur Funktion bereitstellt. (Es wird in einem Aufgabenbereich angezeigt.) Beispiel: http://contoso.com/help/convertcelsiustofahrenheit.html.
id string Ja Eine eindeutige ID für die Funktion. Diese ID darf nur alphanumerische Zeichen und Punkte enthalten und sollte nachträglich nicht mehr geändert werden.
name string Ja Der Name der Funktion, die Endbenutzern in Excel angezeigt wird. In Excel wird diesem Funktionsnamen der benutzerdefinierte Funktionsnamespace vorangestellt, der in der XML-Manifestdatei angegeben ist.
options Objekt Nein Ermöglicht das Anpassen einiger Aspekte, die steuern, wie und wann Excel die Funktion ausführt. Weitere Informationen finden Sie unter Optionen .
parameters Array Ja Array, das die Eingabeparameter für die Funktion definiert. Weitere Informationen finden Sie unter Parameter .
result Objekt Ja Objekt, das die Art der Informationen definiert, die von der Funktion zurückgegeben werden. Weitere Informationen finden Sie im Ergebnis .

options

Mit options dem -Objekt können Sie einige Aspekte der Ausführung und des Zeitpunkts der Ausführung der Funktion in Excel anpassen. In der folgenden Tabelle sind die Eigenschaften des options -Objekts aufgeführt.

Eigenschaft Datentyp Erforderlich Beschreibung
cancelable Boolescher Wert Nein

Der Standardwert ist false.		 Gibt truean, ruft Excel den CancelableInvocation Handler auf, wenn der Benutzer eine Aktion ausführt, die die Funktion abbricht, z. B. manuell eine Neuberechnung auslöst oder eine Zelle bearbeitet, auf die von der Funktion verwiesen wird. Abbrechbare Funktionen werden in der Regel nur für asynchrone Funktionen verwendet, die ein einzelnes Ergebnis zurückgeben und den Abbruch einer Datenanforderung verarbeiten müssen. Eine Funktion kann nicht sowohl die -Eigenschaft als auch die streamcancelable -Eigenschaft verwenden.
requiresAddress Boolescher Wert Nein

Der Standardwert ist false.		 Gibt truean, dass Ihre benutzerdefinierte Funktion auf die Adresse der Zelle zugreifen kann, die sie aufgerufen hat. Die address -Eigenschaft des Aufrufparameters enthält die Adresse der Zelle, die Ihre benutzerdefinierte Funktion aufgerufen hat. Eine Funktion kann nicht sowohl die -Eigenschaft als auch die streamrequiresAddress -Eigenschaft verwenden.
requiresParameterAddresses Boolescher Wert Nein

Der Standardwert ist false.		 Gibt truean, dass Ihre benutzerdefinierte Funktion auf die Adressen der Eingabeparameter der Funktion zugreifen kann. Diese Eigenschaft muss in Kombination mit der dimensionality -Eigenschaft des Ergebnisobjekts verwendet werden und dimensionality muss auf matrixfestgelegt werden. Weitere Informationen finden Sie unter Ermitteln der Adresse eines Parameters .
stream Boolescher Wert Nein

Der Standardwert ist false.		 Gibt truean, kann die Funktion wiederholt an die Zelle ausgeben, auch wenn sie nur einmal aufgerufen wird. Diese Option ist nützlich für sich schnell ändernde Datenquellen, z. B. einen Aktienkurs. Die Funktion sollte keine return -Anweisung haben. Stattdessen wird der Ergebniswert als Argument der StreamingInvocation.setResult Rückruffunktion übergeben. Weitere Informationen finden Sie unter Erstellen einer Streamingfunktion.
volatile Boolescher Wert Nein

Der Standardwert ist false.		 Wenn true, wird die Funktion bei jeder Neuberechnung von Excel neu berechnet, und nicht nur, wenn sich die abhängigen Werte der Formel geändert haben. Eine Funktion kann nicht sowohl die -Eigenschaft als auch die streamvolatile -Eigenschaft verwenden. Wenn die stream Eigenschaften und volatile auf truefestgelegt sind, wird die flüchtige Eigenschaft ignoriert.

Parameter

Die parameters -Eigenschaft ist ein Array von Parameterobjekten. In der folgenden Tabelle sind die Eigenschaften der einzelnen Objekte aufgeführt.

Eigenschaft Datentyp Erforderlich Beschreibung
description string Nein Eine Beschreibung des Parameters. Dies wird in Excel IntelliSense angezeigt.
dimensionality string Nein Muss entweder scalar (ein Nicht-Array-Wert) oder matrix (ein 2-dimensionales Array) sein.
name string Ja Der Name des Parameters. Dieser Name wird in IntelliSense von Excel angezeigt.
type string Nein Der Datentyp des Parameters. Kann , number, stringoder anyseinboolean, sodass Sie einen der vorherigen drei Typen verwenden können. Wenn diese Eigenschaft nicht angegeben ist, ist der Datentyp standardmäßig auf anyfestgelegt.
optional Boolescher Wert Nein Gibt truean, ist der Parameter optional.
repeating Boolescher Wert Nein Gibt truean, dass Parameter aus einem angegebenen Array aufgefüllt werden. Beachten Sie, dass Funktionen alle wiederholten Parameter definitionsgemäß als optionale Parameter gelten.

result

Das result -Objekt definiert den Informationstyp, der von der Funktion zurückgegeben wird. In der folgenden Tabelle sind die Eigenschaften des result -Objekts aufgeführt.

Eigenschaft Datentyp Erforderlich Beschreibung
dimensionality string Nein Muss entweder scalar (ein Nicht-Array-Wert) oder matrix (ein 2-dimensionales Array) sein.
type string Nein Der Datentyp des Ergebnisses. Kann , number, stringoder any sein boolean(wodurch Sie einen der drei vorherigen Typen verwenden können). Wenn diese Eigenschaft nicht angegeben ist, ist der Datentyp standardmäßig auf anyfestgelegt.

Zuordnen von Funktionsnamen zu JSON-Metadaten

Damit eine Funktion ordnungsgemäß funktioniert, müssen Sie die -Eigenschaft der Funktion id der JavaScript-Implementierung zuordnen. Stellen Sie sicher, dass eine Zuordnung vorhanden ist. Andernfalls wird die Funktion nicht registriert und kann in Excel nicht verwendet werden. Im folgenden Codebeispiel wird gezeigt, wie die Zuordnung mithilfe der CustomFunctions.associate() -Funktion hergestellt wird. Im Beispiel wird die benutzerdefinierte Funktion add dem Objekt in der JSON-Metadatendatei zugeordnet, in der den Wert der id-Eigenschaft ADD lautet.

/**
 * Add two numbers
 * @customfunction
 * @param {number} first First number
 * @param {number} second Second number
 * @returns {number} The sum of the two numbers.
 */
function add(first, second) {
  return first + second;
}

CustomFunctions.associate("ADD", add);

Der folgende JSON-Code zeigt die JSON-Metadaten, die dem javaScript-Code der vorherigen benutzerdefinierten Funktion zugeordnet sind.

{
  "functions": [
    {
      "description": "Add two numbers",
      "id": "ADD",
      "name": "ADD",
      "parameters": [
        {
          "description": "First number",
          "name": "first",
          "type": "number"
        },
        {
          "description": "Second number",
          "name": "second",
          "type": "number"
        }
      ],
      "result": {
        "type": "number"
      }
    }
  ]
}

Beachten Sie beim Erstellen von benutzerdefinierten Funktionen in Ihrer JavaScript-Datei und beim Angeben entsprechender Informationen in der JSON-Metadatendatei die folgenden bewährten Methoden.

  • Stellen Sie in der JSON-Metadatendatei sicher, dass der Wert jeder id-Eigenschaft nur alphanumerische Zeichen und Punkte enthält.

  • Stellen Sie in der JSON-Metadatendatei sicher, dass der Wert jeder id-Eigenschaft innerhalb des Bereichs der Datei eindeutig ist. Das bedeutet, dass keine zwei Funktionsobjekte in der Metadatendatei den gleichen Wert für id aufweisen dürfen.

  • Ändern Sie nicht den Wert einer id-Eigenschaft in der JSON-Metadatendatei, nachdem sie einem entsprechenden JavaScript-Funktionsnamen zugeordnet wurde. Sie können den Funktionsnamen, der Endbenutzern in Excel angezeigt wird, ändern, indem Sie die Eigenschaft name innerhalb der JSON-Metadatendatei aktualisieren, aber Sie sollten den Wert einer id-Eigenschaft nach ihrer Einrichtung niemals ändern.

  • Geben Sie in der JavaScript-Datei mit nach jeder Funktion eine benutzerdefinierte Funktionszuordnung an CustomFunctions.associate .

Das folgende Beispiel zeigt die JSON-Metadaten, die den im vorherigen JavaScript-Codebeispiel definierten Funktionen entsprechen. Die id Eigenschaftswerte und name sind in Großbuchstaben enthalten. Dies ist eine bewährte Methode beim Beschreiben Ihrer benutzerdefinierten Funktionen. Sie müssen diesen JSON-Code nur hinzufügen, wenn Sie Ihre eigene JSON-Datei manuell vorbereiten und nicht die automatische Generierung verwenden. Weitere Informationen zur automatischen Generierung finden Sie unter Automatisches Generieren von JSON-Metadaten für benutzerdefinierte Funktionen.

{
  "$schema": "https://developer.microsoft.com/json-schemas/office-js/custom-functions.schema.json",
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      ...
    },
    {
      "id": "INCREMENT",
      "name": "INCREMENT",
      ...
    }
  ]
}

Nächste Schritte

Lernen Sie die bewährten Methoden zum Benennen Ihrer Funktion kennen, oder erfahren Sie, wie Sie Ihre Funktion mithilfe der zuvor beschriebenen handschriftlichen JSON-Methode lokalisieren.

Siehe auch