Benutzerdefinierte Metadaten-FunktionenCustom functions metadata

Wie im Artikel zur Übersicht über die benutzerdefinierten Funktionen beschrieben, muss ein Projekt für benutzerdefinierte Funktionen sowohl eine JSON-Metadatendatei als auch eine Skriptdatei (entweder JavaScript oder eine Skript) enthalten, um eine Funktion zu registrieren und zur Verwendung bereitzustellen.As described in the custom functions overview article, a custom functions project must include both a JSON metadata file and a script (either JavaScript or TypeScript) file to register a function, making it available for use. Benutzerdefinierte Funktionen werden registriert, wenn der Benutzer das Add-in zum ersten Mal ausführt und danach für denselben Benutzer in allen Arbeitsmappen zur Verfügung steht.Custom functions are registered when the user runs the add-in for the first time and after that are available to the same user in all workbooks.

Wichtig

Beachten Sie, dass benutzerdefinierte Excel-Funktionen auf den folgenden Plattformen verfügbar sind.Note that Excel custom functions are available on the following platforms.

  • Office unter Windows (Version 1904 oder höher, verbunden mit Office 365 Abonnement)Office on Windows (version 1904 or later, connected to Office 365 subscription)
  • Office auf dem Mac (Version 16,24 oder höher, verbunden mit Office 365 Abonnement)Office on Mac (version 16.24 or later, connected to Office 365 subscription)
  • Office im InternetOffice on the web

Benutzerdefinierte Excel-Funktionen werden derzeit auf dem iPad oder in einmaligen Kaufversionen von Office 2019 oder früher nicht unterstützt.Excel custom functions are currently not supported on iPad or in one-time purchase versions of Office 2019 or earlier.

Es wird empfohlen, dass Sie die JSON-automatische Generierung, wenn möglich yo office , mithilfe der Gerüst Dateien verwenden, ähnlich dem im Lernprogramm zur benutzerdefinierten Excel-Funktion dargestellten Prozess, da dieser Prozess einfacher und unempfindlicher für Benutzer Fehler ist.It is recommended that you use JSON autogeneration when possible, using the yo office scaffold files, similar to the process shown in the Excel Custom Function tutorial because this process is easier and less prone to user error. Weitere Informationen zum Prozess der JSDoc-Kommentar-JSON-Dateigenerierung finden Sie unter Generieren von JSON-Metadaten für benutzerdefinierte Funktionen.For more information on the process of JSDoc comment JSON file generation, see Generate JSON metadata for custom functions.

Sie können jedoch ein Projekt mit benutzerdefinierten Funktionen neu erstellen; Sie erfordert Folgendes:However, you can make a custom functions project from scratch; it requires that you:

  • Schreiben der JSON-Datei von HandWrite your JSON file by hand
  • Überprüfen, ob Ihre Manifestdatei mit Ihrer Hand erstellten JSON-Datei verbunden istCheck that your manifest file is connected to your hand-authored JSON file
  • Ordnen Sie Ihre Funktionen id und name Eigenschaften in der Skriptdatei an, um ihre Funktionen zu registrieren.Associate your functions' id and name properties in the script file in order to register your functions

In diesem Artikel wird gezeigt, wie Sie alle drei Schritte ausführen.This article will show you how to do all three of these steps.

Hinweis

Im Gegensatz zu den yo office Gerüst Dateien müssen Sie Ihr Manifest mit der JSON-Datei, die Sie erstellen, über den <Resources> Abschnitt in Ihrer XML-Manifestdatei verknüpfen.In contrast with the yo office scaffold files, you need to hook your manifest up with the JSON file you create, through the <Resources> section in your XML manifest file. Beachten Sie, dass für die Servereinstellungen auf dem Server, auf dem die JSON-Datei gehostet wird, CORS aktiviert sein muss, damit benutzerdefinierte Funktionen in Excel im Internet ordnungsgemäß funktionieren.Note that the server settings on the server that hosts the JSON file must have CORS enabled in order for custom functions to work correctly in Excel on the web.

Erstellen von Metadaten und einbinden in das ManifestAuthoring metadata and hooking up to the manifest

Sie müssen eine JSON-Datei in Ihrem Projekt erstellen und alle Details zu ihren Funktionen bereitstellen, beispielsweise die Parameter der Funktion.You need to create a JSON file in your project and provide all the details about your functions in it, such as the function's parameters. Eine vollständige Liste der Funktionseigenschaften finden Sie im folgenden Beispiel für Metadaten und in der Metadatendatei.See the following metadata example and the metadata reference for a complete list of function properties.

Sie müssen außerdem sicherstellen, dass Ihre XML-Manifestdatei auf Ihre JSON- <Resources> Datei im Abschnitt verweist, ähnlich wie im folgenden Beispiel.You also need to make sure your XML manifest file references your JSON file in the <Resources> section, similar to the following example.

<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-MetadatenJSON metadata example

Das folgende Beispiel zeigt den Inhalt einer JSON-Metadatendatei für ein Add-In, das benutzerdefinierte Funktionen definiert.The following example shows the contents of a JSON metadata file for an add-in that defines custom functions. Die Abschnitte nach diesem Beispiel enthalten ausführliche Informationen zu den einzelnen Eigenschaften innerhalb dieses JSON-Beispiels.The sections that follow this example provide detailed information about the individual properties within this JSON example.

{
  "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 Commit-Verlauf des OfficeDev/Excel-Custom-Functions -GitHub-Repositorys verfügbar.A complete sample JSON file is available in the OfficeDev/Excel-Custom-Functions GitHub repository's commit history. Da das Projekt so angepasst wurde, dass JSON automatisch generiert wird, ist ein vollständiges Beispiel für handschriftliches JSON nur in früheren Versionen des Projekts verfügbar.As the project has been adjusted to automatically generate JSON, a full sample of handwritten JSON is only available in previous versions of the project.

Metadatendatei (Referenz)Metadata reference

functionsfunctions

Die functions-Eigenschaft ist ein Array von benutzerdefinierten Funktionsobjekten.The functions property is an array of custom function objects. In der folgenden Tabelle sind die Eigenschaften der einzelnen Objekte aufgeführt.The following table lists the properties of each object.

EigenschaftProperty DatentypData type ErforderlichRequired BeschreibungDescription
description Stringstring NeinNo Die Beschreibung der Funktion, die Endbenutzer in Excel sehen.The description of the function that end users see in Excel. Konvertiert beispielsweise einen Celsius-Wert in Fahrenheit.For example, Converts a Celsius value to Fahrenheit.
helpUrl stringstring NeinNo URL, die Informationen zur Funktion bereitstellt.URL that provides information about the function. (Sie wird in einem Aufgabenbereich angezeigt.) Beispiel: http://contoso.com/help/convertcelsiustofahrenheit.html.(It is displayed in a task pane.) For example, http://contoso.com/help/convertcelsiustofahrenheit.html.
id stringstring JaYes Eine eindeutige ID für die Funktion.A unique ID for the function. Diese ID darf nur alphanumerische Zeichen und Punkte enthalten und sollte nachträglich nicht mehr geändert werden.This ID can only contain alphanumeric characters and periods and should not be changed after it is set.
name stringstring JaYes Der Name der Funktion, die Endbenutzer in Excel sehen.The name of the function that end users see in Excel. In Excel wird diesem Funktionsnamen der Namespace der benutzerdefinierten Funktionen vorangestellt, der in der XML-Manifestdatei angegeben ist.In Excel, this function name will be prefixed by the custom functions namespace that's specified in the XML manifest file.
options Objektobject NeinNo Ermöglicht das Anpassen einiger Aspekte, die steuern, wie und wann Excel die Funktion ausführt.Enables you to customize some aspects of how and when Excel executes the function. Weitere Informationen finden Sie unter options .See options for details.
parameters Arrayarray JaYes Array, das die Eingabeparameter für die Funktion definiert.Array that defines the input parameters for the function. Details finden Sie unter Parameters .See parameters for details.
result Objektobject JaYes Objekt, das die Art der Informationen definiert, die von der Funktion zurückgegeben werden.Object that defines the type of information that is returned by the function. Details finden Sie unter Result .See result for details.

optionsoptions

Mit options dem-Objekt können Sie einige Aspekte anpassen, wie und wann Excel die Funktion ausführt.The options object enables you to customize some aspects of how and when Excel executes the function. In der folgenden Tabelle sind die Eigenschaften des options Objekts aufgeführt.The following table lists the properties of the options object.

EigenschaftProperty DatentypData type ErforderlichRequired BeschreibungDescription
cancelable booleanboolean NeinNo

Der Standardwert ist false.Default value is false.
Wenn trueExcel den CancelableInvocation Handler aufruft, wenn der Benutzer eine Aktion ausführt, die den Abbruch der Funktion bewirkt; beispielsweise Manuelles Auslösen der Neuberechnung oder Bearbeiten einer Zelle, auf die durch die Funktion verwiesen wird.If true, Excel calls the CancelableInvocation handler whenever the user takes an action that has the effect of canceling the function; for example, manually triggering recalculation or editing a cell that is referenced by the function. Aufhebungs Funktionen werden normalerweise nur für asynchrone Funktionen verwendet, die ein einzelnes Ergebnis zurückgeben und den Abbruch einer Anforderung für Daten behandeln müssen.Cancelable functions are typically only used for asynchronous functions that return a single result and need to handle the cancellation of a request for data. Eine Funktion kann nicht sowohl Streaming als auch Abbruch fähig sein.A function cannot be both streaming and cancelable. Weitere Informationen finden Sie in dem Hinweis am Ende der Funktion "Erstellen einer Streamingfunktion".For more information, see the note near the end of Make a streaming function.
requiresAddress booleanboolean NeinNo

Der Standardwert ist false.Default value is false.
Wenn trueIhre benutzerdefinierte Funktion auf die Adresse der Zelle zugreifen kann, die Ihre benutzerdefinierte Funktion aufgerufen hat.If true, your custom function can access the address of the cell that invoked your custom function. Um die Adresse der Zelle abzurufen, die Ihre benutzerdefinierte Funktion aufgerufen hat, verwenden Sie Context. Address in Ihrer benutzerdefinierten Funktion.To get the address of the cell that invoked your custom function, use context.address in your custom function. Weitere Informationen finden Sie unter context-Parameter der Adressierungs Zelle.For more information, see Addressing cell's context parameter. Benutzerdefinierte Funktionen können nicht als Streaming-und requiresAddress festgelegt werden.Custom functions cannot be set as both streaming and requiresAddress. Bei Verwendung dieser Option muss der Aufrufparameter der letzte Parameter sein, der in Optionen übergeben wurde.When using this option, the 'invocation' parameter must be the last parameter passed in options.
stream booleanboolean NeinNo

Der Standardwert ist false.Default value is false.
Wenn true, kann die Funktion wiederholt in die Zelle ausgeben, auch wenn nur einmal aufgerufen.If true, the function can output repeatedly to the cell even when invoked only once. Diese Option ist nützlich für sich schnell ändernde Datenquellen, beispielsweise einen Aktienkurs.This option is useful for rapidly-changing data sources, such as a stock price. Die Funktion sollte keine return Anweisung haben.The function should have no return statement. Stattdessen wird der Ergebniswert als Argument der StreamingInvocation.setResult Rückrufmethode übergeben.Instead, the result value is passed as the argument of the StreamingInvocation.setResult callback method. Weitere Informationen finden Sie unter Streaming Functions.For more information, see Streaming functions.
volatile booleanboolean NeinNo

Der Standardwert ist false.Default value is false.


Wenn truedie Funktion bei jedem erneuten berechnen von Excel neu berechnet wird, statt nur, wenn sich die abhängigen Werte der Formel geändert haben.If true, the function will recalculate each time Excel recalculates, instead of only when the formula's dependent values have changed. Eine Funktion kann nicht sowohl Streaming als auch flüchtig sein.A function cannot be both streaming and volatile. Wenn die stream Eigenschaften volatile und auf truefestgelegt sind, wird die Option volatile ignoriert.If the stream and volatile properties are both set to true, the volatile option will be ignored.

Parameterparameters

Die parameters -Eigenschaft ist ein Array von Parameter-Objekten.The parameters property is an array of parameter objects. In der folgenden Tabelle sind die Eigenschaften der einzelnen Objekte aufgeführt.The following table lists the properties of each object.

EigenschaftProperty DatentypData type ErforderlichRequired BeschreibungDescription
description Stringstring NeinNo Eine Beschreibung des Parameters.A description of the parameter. Dies wird in Excel intelliSense angezeigt.This is displayed in Excel's intelliSense.
dimensionality stringstring NeinNo Muss entweder Skalar (ein nicht-Array-Wert) oder Matrix (ein zweidimensionales Array) sein.Must be either scalar (a non-array value) or matrix (a 2-dimensional array).
name stringstring JaYes Der Name des Parameters.The name of the parameter. Dieser Name wird in Excel intelliSense angezeigt.This name is displayed in Excel's intelliSense.
type stringstring NeinNo Der Datentyp des Parameters.The data type of the parameter. Kann Boolean, Number, Stringoder anysein, sodass Sie einen der vorherigen drei Typen verwenden können.Can be boolean, number, string, or any, which allows you to use of any of the previous three types. Wenn diese Eigenschaft nicht angegeben wird, wird der Datentyp standardmäßig auf anyfestgelegt.If this property is not specified, the data type defaults to any.
optional booleanboolean NeinNo Wenn trueder Parameter optional ist.If true, the parameter is optional.
repeating booleanboolean NeinNo Wenn trueParameter aus einem angegebenen Array aufgefüllt werden.If true, parameters will populate from a specified array. Beachten Sie, dass Funktionen alle wiederholten Parameter per Definition als optionale Parameter betrachtet werden.Note that functions all repeating parameters are considered optional parameters by definition.

resultresult

Das result -Objekt definiert den Typ der Informationen, die von der Funktion zurückgegeben werden.The result object defines the type of information that is returned by the function. In der folgenden Tabelle sind die Eigenschaften des result Objekts aufgeführt.The following table lists the properties of the result object.

EigenschaftProperty DatentypData type ErforderlichRequired BeschreibungDescription
dimensionality Stringstring NeinNo Muss entweder Skalar (ein nicht-Array-Wert) oder Matrix (ein zweidimensionales Array) sein.Must be either scalar (a non-array value) or matrix (a 2-dimensional array).

Zuordnen von Funktionsnamen zu JSON-MetadatenAssociating function names with JSON metadata

Damit eine Funktion ordnungsgemäß funktioniert, müssen Sie die id Eigenschaft der Funktion der JavaScript-Implementierung zuordnen.For a function to work properly, you need to associate the function's id property with the JavaScript implementation. Stellen Sie sicher, dass eine Zuordnung vorhanden ist, andernfalls wird die Funktion nicht registriert und ist in Excel nicht nutzbar.Make sure there is an association, otherwise the function will not be registered and not useable in Excel. Im folgenden Codebeispiel wird veranschaulicht, wie die Zuordnung mithilfe der CustomFunctions.associate() -Methode vorgenommen wird.The following code sample shows how to make the association using the CustomFunctions.associate() method. Im Beispiel wird die benutzerdefinierte Funktion add dem Objekt in der JSON-Metadatendatei zugeordnet, in der den Wert der id-Eigenschaft ADD lautet.The sample defines the custom function add and associates it with the object in the JSON metadata file where the value of the id property is ADD.

/**
 * 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);

Die folgende JSON zeigt die JSON-Metadaten, die dem vorherigen JavaScript-Code für die benutzerdefinierte Funktion zugeordnet sind.The following JSON shows the JSON metadata that is associated with the previous custom function JavaScript code.

{
  "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.Keep in mind the following best practices when creating custom functions in your JavaScript file and specifying corresponding information in the JSON metadata file.

  • Stellen Sie in der JSON-Metadatendatei sicher, dass der Wert jeder id-Eigenschaft nur alphanumerische Zeichen und Punkte enthält.In the JSON metadata file, ensure that the value of each id property contains only alphanumeric characters and periods.

  • Stellen Sie in der JSON-Metadatendatei sicher, dass der Wert jeder id-Eigenschaft innerhalb des Bereichs der Datei eindeutig ist.In the JSON metadata file, ensure that the value of each id property is unique within the scope of the file. Das bedeutet, dass keine zwei Funktionsobjekte in der Metadatendatei den gleichen Wert für id aufweisen dürfen.That is, no two function objects in the metadata file should have the same id value.

  • Ändern Sie nicht den Wert einer id-Eigenschaft in der JSON-Metadatendatei, nachdem sie einem entsprechenden JavaScript-Funktionsnamen zugeordnet wurde.Do not change the value of an id property in the JSON metadata file after it's been associated with a corresponding JavaScript function name. 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.You can change the function name that end users see in Excel by updating the name property within the JSON metadata file, but you should never change the value of an id property after it's been established.

  • Geben Sie in der JavaScript-Datei eine benutzerdefinierte Funktions CustomFunctions.associate Zuordnung an, die nach jeder Funktion verwendet wird.In the JavaScript file, specify a custom function association using CustomFunctions.associate after each function.

Das folgende Beispiel zeigt die JSON-Metadaten, die den in diesem JavaScript-Codebeispiel definierten Funktionen entsprechen.The following sample shows the JSON metadata that corresponds to the functions defined in this JavaScript code sample. Die id - name und-Eigenschaftswerte sind in Großbuchstaben, was bei der Beschreibung der benutzerdefinierten Funktionen eine bewährte Methode ist.The id and name property values are in uppercase, which is a best practice when describing your custom functions. Sie müssen diese JSON nur hinzufügen, wenn Sie Ihre eigene JSON-Datei manuell vorbereiten und nicht die automatische Generierung verwenden.You only need to add this JSON if you are preparing your own JSON file manually and not using autogeneration. Weitere Informationen zur automatische Generierung finden Sie unter Erstellen von JSON-Metadaten für benutzerdefinierte Funktionen.For more information on autogeneration, see Create JSON metadata for custom functions.

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

Nächste SchritteNext steps

Erfahren Sie mehr über die bewährten Methoden zum Benennen Ihrer Funktion , oder ermitteln Sie, wie Sie ihre Funktion mit der zuvor beschriebenen handschriftlichen JSON-Methode lokalisieren.Learn the best practices for naming your function or discover how to localize your function using the previously described handwritten JSON method.

Siehe auchSee also