Générer automatiquement des métadonnées JSON pour des fonctions personnalisées

  • Article

Si vous écrivez une fonction Excel personnalisée en JavaScript ou TypeScript, vous pouvez utiliser les balises JSDoc pour la détailler en ajoutant des informations supplémentaires. Nous fournissons un plug-in Webpack qui utilise ces balises JSDoc pour créer automatiquement le fichier de métadonnées JSON au moment de la génération. L’utilisation du plug-in vous évite de modifier manuellement le fichier de métadonnées JSON.

Importante

Notez que les fonctions personnalisées Excel sont disponibles sur les plateformes suivantes.

  • Office pour Windows
    • Abonnement Microsoft 365
    • retail perpetual Office 2016 et versions ultérieures
  • Office sur Mac
  • Office sur le web

Les fonctions personnalisées Excel ne sont actuellement pas prises en charge dans les éléments suivants :

  • Office sur iPad
  • versions perpétuelles avec licence en volume d’Office 2019 ou version antérieure

CustomFunctionsMetadataPlugin

Le plug-in est CustomFunctionsMetadataPlugin. Pour l’installer et le configurer, procédez comme suit.

Remarque

  1. Ouvrez une invite de commandes ou un interpréteur de commandes bash et, à la racine du projet, exécutez npm install custom-functions-metadata-plugin.

  2. Ouvrez le fichier webpack.config.js et ajoutez la ligne suivante en haut : const CustomFunctionsMetadataPlugin = require("custom-functions-metadata-plugin");.

  3. Faites défiler jusqu’au plugins tableau et ajoutez le code suivant en haut du tableau. Modifiez le chemin d’accès et le input nom de fichier en fonction des besoins pour qu’ils correspondent à votre projet, mais la output valeur doit être « functions.json ». Si vous utilisez TypeScript, utilisez le *.ts nom de fichier source, et non le fichier *.js transpilé.

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

Plusieurs fichiers sources de fonction personnalisée

Si, et seulement si, vous avez organisé vos fonctions personnalisées en plusieurs fichiers sources, il existe des étapes supplémentaires.

  1. Dans le fichier webpack.config.js, remplacez la valeur de chaîne de input par un tableau d’URL de chaîne qui pointent vers chacun des fichiers. Voici un exemple :

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

  2. Faites défiler jusqu’à la entry.functions propriété et remplacez sa valeur par le même tableau que celui utilisé à l’étape précédente. Voici un exemple :

    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"
          ],
 },

Exécuter l’outil

Vous n’avez rien à faire pour exécuter l’outil. Lorsque Webpack s’exécute, il crée le fichier functions.json et le place en mémoire en mode développement, ou dans le dossier /dist en mode production.

Notions de base des balises JSDoc

Ajoutez la balise @customfunction dans les commentaires du code d’une fonction JavaScript ou TypeScript pour indiquer qu’il s’agit d’une fonction personnalisée.

Vous pouvez fournir les types de paramètres de la fonction en utilisant la balise@paramdans JavaScript, ou en précisant le type de fonction dans TypeScript. Si vous voulez en savoir plus, veuillez consulter les sections relatives à la balise@param et aux sectionstypes.

Ajouter une description à une fonction

La description s’affiche pour l’utilisateur sous forme de texte d’aide lorsqu’il a besoin d’aide pour comprendre le rôle de votre fonction personnalisée. La description ne nécessite aucune balise spécifique. Il vous suffit d’entrer une brève description dans le commentaire JSDoc. En général, la description est placée au début de la section commentaires JSDoc, mais elle fonctionnera peu importe son emplacement.

Pour consulter des exemples de descriptions de fonction intégrées, ouvrez Excel, accédez à l’ongletformules , puis sélectionnez insérer une fonction. Vous pouvez ensuite parcourir toutes les descriptions de fonction et voir vos propres fonctions personnalisées répertoriées.

Dans l’exemple suivant, l’expression « Calcule le volume d’une sphère » est la description de la fonction personnalisée.

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

Balises JSDoc prises en charge

Les balises JSDoc suivantes sont prises en charge dans les fonctions personnalisées Excel.

@cancelable

Indique qu’une fonction personnalisée effectue une action lorsque la fonction est annulée.

Le dernier paramètre de la fonction doit être de type CustomFunctions.CancelableInvocation. La fonction peut affecter une fonction à la oncanceled propriété pour indiquer le résultat lorsque la fonction est annulée.

Si le dernier paramètre de fonction est de type CustomFunctions.CancelableInvocation, il sera considéré comme @cancelable, même si la balise n’apparaît pas.

Une fonction ne peut pas contenir les deux balises @cancelable et @streaming.

@customfunction

Syntaxe : @customfunctionnomde l’id

Cette balise indique que la fonction JavaScript/TypeScript est une fonction personnalisée Excel. Il est nécessaire de créer des métadonnées pour la fonction personnalisée.

L’exemple suivant illustre cette balise.

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

id

Identifie id une fonction personnalisée.

  • Siidn’est pas fourni, le nom de la fonction JavaScript/TypeScript est converti en majuscules, et les caractères rejetés sont supprimés.
  • Le iddoit être unique pour toutes les fonctions personnalisées.
  • Les caractères autorisés sont limités à : A-Z, a-z, 0-9, traits de soulignement (_) et point (.).

Dans l’exemple suivant, Increments correspond à l’id et au name de la fonction.

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

name

Fournit le nom d’affichage namede la fonction personnalisée.

  • Si aucun nom n’est fourni, l’id servira aussi de nom.
  • Caractères autorisés : lettres caractère alphabétique Unicode, nombres, point (.) et trait de soulignement (_).
  • Doit commencer par une lettre.
  • Sa longueur maximale est limitée à 128 caractères.

Dans l’exemple suivant, INC correspond à l’id de la fonction, tandis que increment correspond au name.

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

description

Une description s’affiche pour les utilisateurs dans Excel au fur et à mesure qu’ils entrent dans la fonction et spécifie ce que la fonction fait. Une description ne nécessite aucune balise spécifique. Ajoutez une description à une fonction personnalisée en ajoutant une expression pour décrire le rôle de la fonction dans le commentaire JSDoc. Par défaut, le texte non balisé dans la section commentaire JSDoc est la description de la fonction.

Dans l’exemple suivant, la phrase « A function that adds two numbers » (« Une fonction qui ajoute deux nombres ») est la description de la fonction personnalisée dont la propriété ID est ADD.

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

@helpurl

Syntaxe : @helpurlURL

L’url fournie est affichée dans Excel.

Dans l’exemple suivant, est helpurlhttp://www.contoso.com/weatherhelp.

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

@param

JavaScript

Syntaxe JavaScript : @paramdescription du nom {type}

  • {type} spécifie les informations de type entre accolades. Consultez la section Types pour savoir quels types peuvent être utilisés. Si aucun type n’est spécifié, le type any par défaut est utilisé.
  • name spécifie le paramètre auquel la @param balise s’applique. Il est obligatoire.
  • descriptionfournit la description qui s’affiche dans Excel pour le paramètre de la fonction. Elle est facultative.

Pour indiquer un paramètre de fonction personnalisé comme facultatif, placez des crochets autour du nom du paramètre. Par exemple : @param {string} [text] Optional text.

Remarque

La valeur par défaut pour les paramètres facultatifs est null.

L’exemple suivant montre une fonction ADD qui ajoute deux ou trois nombres, avec le troisième nombre comme paramètre facultatif.

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

Syntaxe TypeScript : @paramdescriptiondu nom

  • name spécifie le paramètre auquel la @param balise s’applique. Il est obligatoire.
  • descriptionfournit la description qui s’affiche dans Excel pour le paramètre de la fonction. Elle est facultative.

Consultez la section Types pour savoir quels types de paramètres de fonction peuvent être utilisés.

Pour désigner un paramètre de fonction personnalisée comme étant facultatif, effectuez l’une des actions suivantes :

  • Utilisez un paramètre facultatif. Par exemple : function f(text?: string)
  • Définissez ce paramètre sur une valeur par défaut. Par exemple : function f(text: string = "abc")

Pour consulter une description détaillée du paramètre @param, reportez-vous à la page suivante : JSDoc (contenu en anglais)

Remarque

La valeur par défaut pour les paramètres facultatifs est null.

L’exemple suivant représente la fonction add qui ajoute deux nombres.

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

Indique que l’adresse de la cellule dans laquelle la fonction est évaluée doit être fournie.

Le dernier paramètre de fonction doit être de type CustomFunctions.Invocation ou un type dérivé pour utiliser @requiresAddress. Lorsque la fonction est appelée, la propriété address contiendra l’adresse.

L’exemple suivant montre comment utiliser le invocation paramètre en combinaison avec @requiresAddress pour retourner l’adresse de la cellule qui a appelé votre fonction personnalisée. Pour plus d’informations, consultez Paramètre d’appel .

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

Indique que la fonction doit retourner les adresses des paramètres d’entrée.

Le dernier paramètre de fonction doit être de type CustomFunctions.Invocation ou un type dérivé pour utiliser @requiresParameterAddresses. Le commentaire JSDoc doit également inclure une @returns balise spécifiant que la valeur de retour est une matrice, telle que @returns {string[][]} ou @returns {number[][]}. Pour plus d’informations, consultez Types de matrices .

Lorsque la fonction est appelée, la parameterAddresses propriété contient les adresses des paramètres d’entrée.

L’exemple suivant montre comment utiliser le invocation paramètre en combinaison avec @requiresParameterAddresses pour retourner les adresses de trois paramètres d’entrée. Pour plus d’informations, consultez Détecter l’adresse d’un paramètre .

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

Syntaxe : @returns {type}

Fournit le type pour la valeur renvoyée.

Si {type} est omis, les informations de type TypeScript seront utilisées. S’il n’existe aucune information définissant le type, ce dernier sera any.

L’exemple suivant représente la fonction add qui utilise la balise @returns.

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

Utilisé pour indiquer qu’une fonction personnalisée est une fonction diffusion en continu.

Le dernier paramètre est de type CustomFunctions.StreamingInvocation<ResultType>. La fonction retourne void.

Les fonctions de streaming ne retournent pas de valeurs directement, mais elles appellent setResult(result: ResultType) à l’aide du dernier paramètre.

Les exceptions levées par une fonction en continu sont ignorées. setResult()peut être appelée avec Error pour indiquer un résultat erroné. Si vous souhaitez consulter un exemple de fonction de diffusion en continu et obtenir d’autres informations, veuillez vous reporter à la section Créer une fonction de diffusion en continu.

Les fonctions de diffusion en continu ne peuvent pas être marquées comme étant @volatile.

@volatile

Une fonction volatile est une fonction dont le résultat peut changer d’un moment à l’autre, même si elle ne récupère pas d’argument ou si ses arguments ne changent pas. À chaque calcul, Excel réévalue les cellules contenant des fonctions volatiles, ainsi que toutes leurs cellules dépendantes. C’est pourquoi, un trop grand nombre de dépendances de fonctions volatiles risque de ralentir les calculs. Nous vous recommandons d’en utiliser aussi peu que possible.

Les fonctions de diffusion en continu ne peuvent pas être volatiles.

La fonction suivante est volatile et utilise la balise @volatile.

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

Types

En spécifiant un type de paramètre, Excel convertit les valeurs en ce type, avant d’appeler la fonction. Si le type est any, Excel n’effectue pas de conversion.

Types de valeur

Une valeur unique peut être représentée à l’aide d’un des types suivants : boolean, number ou string.

Type matrice

Utilisez une matrice à deux dimensions pour que le paramètre ou la valeur renvoyée soit une matrice de valeurs. Par exemple, le type number[][] indique une matrice de nombres et string[][] une matrice de chaînes.

Type d’erreur

Une fonction qui n’est pas une fonction de diffusion en continu peut indiquer une erreur en renvoyant un type Error.

Une fonction de diffusion en continu peut indiquer une erreur en appelantsetResult()avec un type Error.

Promise

Une fonction personnalisée peut retourner une promesse qui fournit la valeur lorsque la promesse est résolue. Si la promesse est rejetée, la fonction personnalisée génère une erreur.

Autres types

Tout autre type sera traité comme une erreur.

Étapes suivantes

Découvrez le nommage et la localisation des fonctions personnalisées.

Voir aussi