Automatisches Erstellen von JSON-Metadaten für benutzerdefinierte Funktionen

  • Artikel

Wenn eine benutzerdefinierte Excel-Funktion in JavaScript oder TypeScript geschrieben wird, werden JSDoc-Tags verwendet, um zusätzliche Informationen über die benutzerdefinierte Funktion bereitzustellen. Wir stellen ein Webpack-Plug-In bereit, das diese JSDoc-Tags verwendet, um die JSON-Metadatendatei automatisch zur Buildzeit zu erstellen. Die Verwendung des Plug-Ins erspart Ihnen den Aufwand, die JSON-Metadatendatei manuell zu bearbeiten.

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

CustomFunctionsMetadataPlugin

Das Plug-In ist CustomFunctionsMetadataPlugin. Führen Sie die folgenden Schritte aus, um sie zu installieren und zu konfigurieren.

Hinweis

  • Das Tool kann nur in einem NodeJS-basierten Projekt verwendet werden.
  • In diesen Anweisungen wird davon ausgegangen, dass Ihr Projekt Webpack verwendet und installiert und konfiguriert ist.
  • Wenn Ihr benutzerdefiniertes Funktions-Add-In-Projekt mit dem Yeoman-Generator für Office-Add-Ins erstellt wird, wird Webpack installiert, und alle diese Schritte werden automatisch ausgeführt, aber falls zutreffend, müssen Sie die Schritte unter Mehrere benutzerdefinierte Funktionsquelldateien manuell ausführen.

  1. Öffnen Sie eine Eingabeaufforderung oder bash-Shell, und führen Sie im Stammverzeichnis des Projekts aus npm install custom-functions-metadata-plugin.

  2. Öffnen Sie die webpack.config.js-Datei, und fügen Sie oben die folgende Zeile hinzu: const CustomFunctionsMetadataPlugin = require("custom-functions-metadata-plugin");.

  3. Scrollen Sie nach unten zum plugins Array, und fügen Sie Folgendes am anfang des Arrays hinzu. Ändern Sie den input Pfad und Dateinamen nach Bedarf, damit sie ihrem Projekt entsprechen, aber der output Wert muss "functions.json" lauten. Wenn Sie TypeScript verwenden, verwenden Sie den Quelldateinamen *.ts, nicht die transpilierte *.js-Datei.

    new CustomFunctionsMetadataPlugin({
   output: "functions.json",
   input: "./src/functions/functions.js", 
}),

Mehrere Quelldateien für benutzerdefinierte Funktionen

Wenn Und nur wenn Sie Ihre benutzerdefinierten Funktionen in mehreren Quelldateien organisiert haben, gibt es zusätzliche Schritte.

  1. Ersetzen Sie in der webpack.config.js-Datei den Zeichenfolgenwert von input durch ein Array von Zeichenfolgen-URLs, die auf jede der Dateien verweisen. Es folgt ein Beispiel:

    new CustomFunctionsMetadataPlugin({
   output: "functions.json",
   input: [
            "./src/functions/someFunctions.js", 
            "./src/functions/otherFunctions.js"
          ], 
}),

  2. Scrollen Sie zur entry.functions -Eigenschaft, und ersetzen Sie deren Wert durch das gleiche Array, das Sie im vorherigen Schritt verwendet haben. Es folgt ein Beispiel:

    entry: {
   polyfill: ["core-js/stable", "regenerator-runtime/runtime"],
   taskpane: ["./src/taskpane/taskpane.js", "./src/taskpane/taskpane.html"],
   functions: [
            "./src/functions/someFunctions.js", 
            "./src/functions/otherFunctions.js"
          ],
 },

Ausführen des Tools

Sie müssen nichts tun, um das Tool auszuführen. Wenn Webpack ausgeführt wird, wird die functions.json Datei erstellt und im Entwicklungsmodus im Arbeitsspeicher oder im Produktionsmodus im Ordner /dist abgelegt.

Grundlagen von JSDoc-Tags

Fügen Sie das @customfunction-Tag in den Codekommentaren für eine JavaScript- oder TypeScript-Funktion hinzu, um diese als benutzerdefinierte Funktion zu markieren.

Die Funktionsparametertypen können unter Verwendung des @param-Tags in JavaScript oder über den Funktionstyp in TypeScript angegeben werden. Weitere Informationen finden Sie im Abschnitt für den @param-Tag und zu den Typen.

Hinzufügen einer Beschreibung zu einer Funktion

Die Beschreibung wird dem Benutzer als Hilfetext angezeigt, wenn er Hilfe benötigt, um die Funktionsweise Ihrer benutzerdefinierten Funktion zu verstehen. Die Beschreibung erfordert kein bestimmtes Tag. Geben Sie einfach eine kurze Textbeschreibung in den JSDoc-Kommentar ein. Die Beschreibung wird normalerweise an den Anfang des JSDoc-Kommentarabschnitts gesetzt, aber Sie funktioniert unabhängig davon, an welcher Stelle Sie platziert wird.

Wenn Sie Beispiele für die integrierten Funktionsbeschreibungen anzeigen möchten, öffnen Sie Excel, navigieren Sie zur Registerkarte Formeln, und wählen Sie Funktion einfügen aus. Dann können alle Funktionsbeschreibungen durchsuchen, und auch ihre eigenen benutzerdefinierten Funktionen werden dort aufgelistet.

Im folgenden Beispiel ist der Ausdruck "Berechnet das Volumen einer Kugel." die Beschreibung für die benutzerdefinierte Funktion.

/**
/* Calculates the volume of a sphere.
/* @customfunction VOLUME
...
 */

Unterstützte JSDoc-Tags

Die folgenden JSDoc-Tags werden in benutzerdefinierten Excel-Funktionen unterstützt.

@cancelable

Gibt an, dass eine benutzerdefinierte Funktion eine Aktion ausführt, wenn die Funktion abgebrochen wird.

Der letzte Funktionsparameter muss vom Typ CustomFunctions.CancelableInvocation sein. Die Funktion kann der oncanceled -Eigenschaft eine Funktion zuweisen, um das Ergebnis anzugeben, wenn die Funktion abgebrochen wird.

Wenn der letzte Funktionsparameter vom Typ CustomFunctions.CancelableInvocation ist, wird dies als @cancelable betrachtet, obwohl das Tag nicht vorhanden ist.

Eine Funktion kann nicht die beiden Tags @cancelable und @streaming aufweisen.

@customfunction

Syntax: @customfunctionID-Name

Dieses Tag gibt an, dass die JavaScript/TypeScript-Funktion eine benutzerdefinierte Excel-Funktion ist. Es ist erforderlich, Metadaten für die benutzerdefinierte Funktion zu erstellen.

Im Folgenden sehen Sie ein Beispiel für dieses Tag.

/**
 * Increments a value once a second.
 * @customfunction
 * ...
 */

id

Der id identifiziert eine benutzerdefinierte Funktion.

  • Wenn id nicht angegeben wird, wird der JavaScript-/TypeScript-Funktionsname in Großbuchstaben konvertiert, und unzulässige Zeichen werden entfernt.
  • id muss für alle benutzerdefinierten Funktionen eindeutig sein.
  • Die zulässigen Zeichen sind beschränkt auf: A-Z, a-z, 0-9, Unterstriche (_) und Punkt (.).

Im folgenden Beispiel ist "increment" die id und der name der Funktion.

/**
 * Increments a value once a second.
 * @customfunction INCREMENT
 * ...
 */

name

Gibt den Anzeigenamen für die benutzerdefinierte Funktion an.

  • Wenn kein Name angegeben wird, wird die ID auch als Name verwendet.
  • Zulässige Zeichen: Buchstaben Unicode Alphabetisches Zeichen, Zahlen, Punkt (.) und Unterstrich (_).
  • Muss mit einem Buchstaben beginnen.
  • Die maximale Länge beträgt 128 Zeichen.

Im folgenden Beispiel ist "INC" die id der Funktion, und increment ist der name.

/**
 * Increments a value once a second.
 * @customfunction INC INCREMENT
 * ...
 */

description

Benutzern in Excel wird beim Eingeben der Funktion eine Beschreibung angezeigt, die angibt, was die Funktion ausführt. Eine Beschreibung erfordert kein bestimmtes Tag. Sie können einer benutzerdefinierten Funktion eine Beschreibung hinzufügen, indem Sie Text hinzufügen, der beschreibt, was die Funktion innerhalb des JSDoc-Kommentars bewirkt. Standardmäßig wird sämtlicher im JSDoc-Kommentarabschnitt enthaltener Text ohne Tag als Beschreibung der Funktion verwendet.

Im folgenden Beispiel ist der Text "Eine Funktion, die zwei Zahlen addiert" die Beschreibung für die benutzerdefinierte Funktion mit der ID-Eigenschaft ADD.

/**
 * A function that adds two numbers.
 * @customfunction ADD
 * ...
 */

@helpurl

Syntax: @helpurlurl

Die angegebene URL wird in Excel angezeigt.

Im folgenden Beispiel ist http://www.contoso.com/weatherhelpder helpurl .

/**
 * A function which streams the temperature in a town you specify.
 * @customfunction getTemperature
 * @helpurl http://www.contoso.com/weatherhelp
 * ...
 */

@param

JavaScript

JavaScript-Syntax: @param {type}-Namensbeschreibung

  • {type} gibt die Typinformationen in geschweiften Klammern an. Unter dem AbschnittTypen finden Sie weitere Informationen zu den Typen, die verwendet werden können. Wenn kein Typ angegeben wird, wird der Standardtyp any verwendet.
  • name gibt den Parameter an, auf den das @param Tag angewendet wird. Dies ist erforderlich.
  • description gibt die Beschreibung an, die in Excel für den Funktionsparameter angezeigt wird. Sie ist optional.

Um einen benutzerdefinierten Funktionsparameter als optional zu kennzeichnen, setzen Sie eckige Klammern um den Parameternamen. Beispiel: @param {string} [text] Optional text.

Hinweis

Der Standardwert für optionale Parameter ist null.

Das folgende Beispiel zeigt eine ADD-Funktion, die zwei oder drei Zahlen mit der dritten Zahl als optionalen Parameter hinzufügt.

/**
 * A function which sums two, or optionally three, numbers.
 * @customfunction ADDNUMBERS
 * @param firstNumber {number} First number to add.
 * @param secondNumber {number} Second number to add.
 * @param [thirdNumber] {number} Optional third number you wish to add.
 * ...
 */

TypeScript

TypeScript-Syntax: @paramNamensbeschreibung

  • name gibt den Parameter an, auf den das @param Tag angewendet wird. Dies ist erforderlich.
  • description gibt die Beschreibung an, die in Excel für den Funktionsparameter angezeigt wird. Sie ist optional.

Unter den AbschnittTypen finden Sie weitere Informationen zu den Funktionsparametertypen, die verwendet werden können.

Gehen Sie folgendermaßen vor, um einen benutzerdefinierten Funktionsparameter als optional zu kennzeichnen:

  • Verwenden Sie einen optionalen Parameter. Beispiel: function f(text?: string)
  • Geben Sie dem Parameter einen Standardwert. Beispiel: function f(text: string = "abc")

Eine ausführliche Beschreibung von @param finden Sie unter JSDoc.

Hinweis

Der Standardwert für optionale Parameter ist null.

Das folgende Beispiel zeigt die add-Funktion, die zwei Zahlen addiert.

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

@requiresAddress

Gibt an, dass die Adresse der Zelle, in der die Funktion ausgewertet wird, angegeben werden muss.

Der letzte Funktionsparameter muss vom Typ CustomFunctions.Invocation oder einem abgeleiteten Typ sein, um zu verwenden @requiresAddress. Wenn die Funktion aufgerufen wird, enthält die address-Eigenschaft die Adresse.

Das folgende Beispiel zeigt, wie Sie den invocation Parameter in Kombination mit @requiresAddress verwenden, um die Adresse der Zelle zurückzugeben, die Ihre benutzerdefinierte Funktion aufgerufen hat. Weitere Informationen finden Sie unter Aufrufparameter .

/**
 * Return the address of the cell that invoked the custom function. 
 * @customfunction
 * @param {number} first First parameter.
 * @param {number} second Second parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @requiresAddress 
 */
function getAddress(first, second, invocation) {
  const address = invocation.address;
  return address;
}

@requiresParameterAddresses

Gibt an, dass die Funktion die Adressen von Eingabeparametern zurückgeben soll.

Der letzte Funktionsparameter muss vom Typ CustomFunctions.Invocation oder einem abgeleiteten Typ sein, um zu verwenden @requiresParameterAddresses. Der JSDoc-Kommentar muss auch ein @returns Tag enthalten, das angibt, dass der Rückgabewert eine Matrix ist, z @returns {string[][]} . B. oder @returns {number[][]}. Weitere Informationen finden Sie unter Matrixtypen .

Wenn die Funktion aufgerufen wird, enthält die parameterAddresses -Eigenschaft die Adressen der Eingabeparameter.

Das folgende Beispiel zeigt, wie Sie den invocation Parameter in Kombination mit @requiresParameterAddresses verwenden, um die Adressen von drei Eingabeparametern zurückzugeben. Weitere Informationen finden Sie unter Ermitteln der Adresse eines Parameters .

/**
 * Return the addresses of three parameters. 
 * @customfunction
 * @param {string} firstParameter First parameter.
 * @param {string} secondParameter Second parameter.
 * @param {string} thirdParameter Third parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @returns {string[][]} The addresses of the parameters, as a 2-dimensional array.
 * @requiresParameterAddresses
 */
function getParameterAddresses(firstParameter, secondParameter, thirdParameter, invocation) {
  const addresses = [
    [invocation.parameterAddresses[0]],
    [invocation.parameterAddresses[1]],
    [invocation.parameterAddresses[2]]
  ];
  return addresses;
}

@returns

Syntax: @returns {Typ}

Gibt den Typ für den Rückgabewert an.

Wenn {type} nicht angegeben wird, werden die TypeScript-Typinformationen verwendet. Wenn keine Typeninformationen vorhanden sind, ist der Typ any.

Das folgende Beispiel zeigt die add-Funktion, die das @returns-Tag verwendet.

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

@streaming

Wird verwendet, um anzugeben, dass eine benutzerdefinierte Funktion eine Streamingfunktion ist.

Der letzte Parameter ist vom Typ CustomFunctions.StreamingInvocation<ResultType>. Die Funktion gibt zurück void.

Streamingfunktionen geben Werte nicht direkt zurück, sondern rufen mit dem letzten Parameter auf setResult(result: ResultType) .

Ausnahmen, die von einer Streamingfunktion ausgelöst werden, werden ignoriert. setResult() kann mit „Error“ aufgerufen werden, um ein fehlerhaftes Ergebnis anzugeben. Ein Beispiel für eine Streamingfunktion und weitere Informationen finden Sie unter Erstellen einer Streamingfunktion.

Streamingfunktionen können nicht als @volatile gekennzeichnet werden.

@volatile

Eine veränderliche Funktion ist eine Funktion, deren Ergebnis nicht immer gleich ist, auch wenn sie keine Argumente verwendet oder sich die Argumente nicht geändert haben. Excel wertet Zellen mit veränderlichen Funktionen und alle untergeordneten Zellen bei jeder Neuberechnung neu aus. Aus diesem Grund kann die Verwendung einer großen Anzahl von veränderlichen Funktionen die Neuberechnung verlangsamen. Verwenden Sie diese daher nur selten.

Streamingfunktionen können nicht veränderlich sein.

Die folgende Funktion ist veränderlich und verwendet das @volatile-Tag.

/**
 * Simulates rolling a 6-sided die.
 * @customfunction
 * @volatile
 */
function roll6sided(): number {
  return Math.floor(Math.random() * 6) + 1;
}

Typen

Indem Sie einen Parametertyp angeben, konvertiert Excel Werte in diesen Typ, bevor die Funktion aufgerufen wird. Wenn der Typ any ist, wird keine Konvertierung ausgeführt.

Werttypen

Ein einzelner Wert kann mit einem der folgenden Typen dargestellt werden: boolean, number, string.

Matrixtyp

Verwenden Sie einen zweidimensionalen Arraytyp, damit der Parameter oder der Rückgabewert eine Wertematrix ist. Der Typ gibt z. B number[][] . eine Matrix von Zahlen und string[][] eine Matrix von Zeichenfolgen an.

Fehlertyp

Eine Nicht-Streamingfunktion kann durch Zurückgeben eines Fehlertyps einen Fehler angeben.

Eine Streamingfunktion kann durch Aufrufen von setResult() mit einem Fehlertyp einen Fehler angeben.

Zusage

Eine benutzerdefinierte Funktion kann eine Zusage zurückgeben, die den Wert bereitstellt, wenn die Zusage aufgelöst wird. Wenn die Zusage abgelehnt wird, löst die benutzerdefinierte Funktion einen Fehler aus.

Andere Typen

Jeder andere Typ wird als Fehler behandelt.

Nächste Schritte

Erfahren Sie mehr über die Benennung und Lokalisierung für benutzerdefinierte Funktionen.

Siehe auch