Partager via

Créer manuellement des métadonnées JSON pour les fonctions personnalisées

  • Article

Comme décrit dans l’article vue d’ensemble des fonctions personnalisées , un projet de fonctions personnalisées doit inclure à la fois un fichier de métadonnées JSON et un fichier de script (JavaScript ou TypeScript) pour inscrire une fonction, ce qui la rend disponible pour utilisation. Les fonctions personnalisées sont inscrites lorsque l’utilisateur exécute le complément pour la première fois et après, elles sont disponibles pour le même utilisateur dans tous les classeurs.

Importante

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

  • Office sur le web
  • Office pour Windows
    • Abonnement Microsoft 365
    • retail perpetual Office 2016 et versions ultérieures
    • avec licence en volume avec licence perpétuelle Office 2021 et versions ultérieures
  • Office sur Mac

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 sur Windows

Nous vous recommandons d’utiliser la génération automatique JSON lorsque cela est possible au lieu de créer votre propre fichier JSON. La génération automatique est moins sujette aux erreurs de l’utilisateur et les yo office fichiers générés automatiquement l’incluent déjà. Pour plus d’informations sur les balises JSDoc et le processus de génération automatique JSON, consultez Générer automatiquement des métadonnées JSON pour les fonctions personnalisées.

Toutefois, vous pouvez créer un projet de fonctions personnalisées à partir de zéro. Ce processus vous oblige à :

  • Écrivez votre fichier JSON.
  • Vérifiez que votre fichier manifeste est connecté à votre fichier JSON.
  • Associez les propriétés et name les id fonctions dans le fichier de script afin d’inscrire vos fonctions.

L’image suivante explique les différences entre l’utilisation yo office de fichiers de structure automatique et l’écriture JSON à partir de zéro.

Image des différences entre l’utilisation du générateur Yeoman pour les compléments Office et l’écriture de votre propre JSON.

Remarque

N’oubliez pas de connecter votre manifeste au fichier JSON que vous créez, via la <section Ressources> de votre fichier manifeste de complément uniquement si vous n’utilisez pas le générateur Yeoman pour les compléments Office.

Création de métadonnées et connexion au manifeste

Créez un fichier JSON dans votre projet et fournissez tous les détails sur vos fonctions, telles que les paramètres de la fonction. Consultez l’exemple de métadonnées suivant et la référence des métadonnées pour obtenir la liste complète des propriétés de fonction.

Vérifiez que votre fichier manifeste de complément uniquement fait référence à votre fichier JSON dans la <section Ressources> , comme dans l’exemple suivant.

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

Exemple de métadonnées JSON

L’exemple suivant montre le contenu d’un fichier de métadonnées JSON pour un complément qui définit des fonctions personnalisées. Les sections qui suivent cet exemple fournissent des informations détaillées sur les propriétés individuelles au sein de cet exemple JSON.

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

Remarque

Un exemple complet de fichier JSON est disponible dans l’historique de validation du dépôt GitHub OfficeDev/Excel-Custom-Functions . Étant donné que le projet a été ajusté pour générer automatiquement du code JSON, un exemple complet de JSON manuscrit n’est disponible que dans les versions précédentes du projet.

Informations de référence sur les métadonnées

allowCustomDataForDataTypeAny

La allowCustomDataForDataTypeAny propriété est un type de données booléen. La définition de cette valeur sur permet à true une fonction personnalisée d’accepter les types de données comme paramètres et de retourner des valeurs. Pour plus d’informations, consultez Fonctions et types de données personnalisés.

Remarque

Contrairement à la plupart des autres propriétés de métadonnées JSON, allowCustomDataForDataTypeAny est une propriété de niveau supérieur et ne contient aucune sous-propriété. Consultez l’exemple de code de métadonnées JSON précédent pour obtenir un exemple de mise en forme de cette propriété.

allowErrorForDataTypeAny

La allowErrorForDataTypeAny propriété est un type de données booléen. La définition de la valeur sur permet à true une fonction personnalisée de traiter les erreurs en tant que valeurs d’entrée. Tous les paramètres avec le type any ou any[][] peuvent accepter des erreurs comme valeurs d’entrée lorsque allowErrorForDataTypeAny est défini sur true. La valeur par défaut allowErrorForDataTypeAny est false.

Remarque

Contrairement aux autres propriétés de métadonnées JSON, allowErrorForDataTypeAny est une propriété de niveau supérieur et ne contient aucune sous-propriété. Consultez l’exemple de code de métadonnées JSON précédent pour obtenir un exemple de mise en forme de cette propriété.

fonctions

La propriété functions est un tableau d’objets de fonction personnalisés. Le tableau suivant répertorie les propriétés de chaque objet.

Propriété Type de données Obligatoire Description
description string Non Description de la fonction que voient les utilisateurs finaux dans Excel. Par exemple, convertit une valeur Celsius en valeur Fahrenheit.
helpUrl string Non URL fournissant des informations sur la fonction (elle est affichée dans un volet des tâches). Par exemple, http://contoso.com/help/convertcelsiustofahrenheit.html.
id string Oui Un ID unique pour la fonction. Cet ID peut contenir uniquement des points et caractères alphanumériques et ne doit pas être modifié une fois défini.
name string Oui Nom de la fonction que voient les utilisateurs finaux dans Excel. Dans Excel, ce nom de fonction est précédé de l’espace de noms des fonctions personnalisées spécifié dans le fichier manifeste du complément uniquement.
options objet Non Vous permet de personnaliser certains aspects de comment et quand Excel exécute la fonction. Reportez-vous aux options pour plus d’informations.
parameters tableau Oui Tableau qui définit les paramètres d’entrée de la fonction. Pour plus d’informations, consultez paramètres.
result objet Oui Objet qui définit le type d’informations renvoyées par la fonction. Reportez-vous au résultat pour plus d’informations.

options

L’objet options vous permet de personnaliser certains aspects de comment et quand Excel exécute la fonction. Le tableau suivant répertorie les propriétés de l’objet options.

Propriété Type de données Obligatoire Description
cancelable boolean Non

La valeur par défaut est false.		 Si la valeur est true, Excel appelle le gestionnaire CancelableInvocation chaque fois que l’utilisateur effectue une action ayant pour effet d’annuler la fonction, par exemple, en déclenchant manuellement un recalcul ou en modifiant une cellule référencée par la fonction. Les fonctions annulables sont généralement utilisées uniquement pour les fonctions asynchrones qui retournent un seul résultat et doivent gérer l’annulation d’une demande de données. Une fonction ne peut pas utiliser les stream propriétés et .cancelable
requiresAddress valeur booléenne Non

La valeur par défaut est false.		 Si la valeur est true, votre fonction personnalisée peut accéder à l’adresse de la cellule qui l’a appelée. La address propriété du paramètre d’appel contient l’adresse de la cellule qui a appelé votre fonction personnalisée. Une fonction ne peut pas utiliser les stream propriétés et .requiresAddress
requiresParameterAddresses valeur booléenne Non

La valeur par défaut est false.		 Si la valeur est true, votre fonction personnalisée peut accéder aux adresses des paramètres d’entrée de la fonction. Cette propriété doit être utilisée en combinaison avec la dimensionality propriété de l’objet de résultat et dimensionality doit être définie sur matrix. Pour plus d’informations, consultez Détecter l’adresse d’un paramètre .
stream valeur booléenne Non

La valeur par défaut est false.		 Si la valeur est true, la fonction peut envoyer une sortie à la cellule à plusieurs reprises, même en cas d’appel unique. Cette option est utile pour des sources de données qui changent rapidement, telles que des valeurs boursières. La fonction ne doit pas utiliser d’instruction return. Au lieu de cela, la valeur du résultat est passée en tant qu’argument de la StreamingInvocation.setResult fonction de rappel. Pour plus d’informations, consultez Créer une fonction de diffusion en continu.
volatile valeur booléenne Non

La valeur par défaut est false.		 Si truela valeur est , la fonction recalcule chaque fois qu’Excel recalcule, au lieu de uniquement lorsque les valeurs dépendantes de la formule ont changé. Une fonction ne peut pas utiliser les stream propriétés et .volatile Si les stream propriétés et volatile sont toutes deux définies sur true, la propriété volatile est ignorée.

paramètres

La propriété parameters est un tableau d’objets paramètre. Le tableau suivant répertorie les propriétés de chaque objet.

Propriété Type de données Obligatoire Description
description string Non Description du paramètre. Cela s’affiche dans IntelliSense d’Excel.
dimensionality string Non Doit être scalar (une valeur non matricielle) ou matrix (tableau à 2 dimensions).
name string Oui Le nom du paramètre. Ce nom s’affiche dans IntelliSense d’Excel.
type string Non Type de données du paramètre. Peut être boolean, number, stringou any, ce qui vous permet d’utiliser l’un des trois types précédents. Si cette propriété n’est pas spécifiée, le type de données est anydéfini par défaut sur .
optional valeur booléenne Non Si la valeur est true, le paramètre est facultatif.
repeating valeur booléenne Non Si truela valeur est , les paramètres sont renseignés à partir d’un tableau spécifié. Notez que les fonctions de tous les paramètres répétitifs sont considérés comme des paramètres facultatifs par définition.

result

L’objet result définit le type des informations renvoyées par la fonction. Le tableau suivant répertorie les propriétés de l’objet result.

Propriété Type de données Obligatoire Description
dimensionality string Non Doit être scalar (une valeur non matricielle) ou matrix (tableau à 2 dimensions).
type string Non Type de données du résultat. Peut être boolean, number, stringou any (ce qui vous permet d’utiliser l’un des trois types précédents). Si cette propriété n’est pas spécifiée, le type de données est anydéfini par défaut sur .

Mappage des noms de fonction aux métadonnées JSON

Pour qu’une fonction fonctionne correctement, vous devez associer la propriété de id la fonction à l’implémentation JavaScript. Vérifiez qu’il existe une association, sinon la fonction n’est pas inscrite et n’est pas utilisable dans Excel. L’exemple de code suivant montre comment établir l’association à l’aide de la CustomFunctions.associate() fonction . L’exemple définit la fonction personnalisée add et associe à l’objet dans le fichier de métadonnées JSON où la valeur de la propriétéidestAJOUTER.

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

Le code JSON suivant montre les métadonnées JSON associées au code JavaScript de la fonction personnalisée précédente.

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

N’oubliez pas les meilleures pratiques suivantes lors de la création de fonctions personnalisées dans votre fichier JavaScript et spécifiez les informations correspondantes dans le fichier de métadonnées JSON.

  • Dans le fichier de métadonnées JSON, vérifiez que la valeur de chaque id propriété contient uniquement des points et des caractères alphanumériques.

  • Dans le fichier de métadonnées JSON, vérifiez que la valeur de chaque id propriété est unique dans l’étendue du fichier. Autrement dit, aucun objet fonction dans le fichier de métadonnées ne doit pas avoir la mêmeidvaleur.

  • Ne modifiez pas la valeur d’uneid propriété dans le fichier de métadonnées JSON après qu’elle ait été mappée à un nom de fonction JavaScript correspondante. Vous pouvez modifier le nom de fonction que voient les utilisateurs finaux dans Excel en mettant à jour la name propriété dans le fichier de métadonnées JSON, mais vous ne devez jamais changer la valeur d’une id propriété après qu’elle a été établie.

  • Dans le fichier JavaScript, spécifiez une association de fonction personnalisée à l’aide de CustomFunctions.associate après chaque fonction.

L’exemple suivant montre les métadonnées JSON qui correspondent aux fonctions définies dans l’exemple de code JavaScript précédent. Les id valeurs de propriété et name sont en majuscules, ce qui est une bonne pratique lors de la description de vos fonctions personnalisées. Vous devez uniquement ajouter ce fichier JSON si vous préparez votre propre fichier JSON manuellement et que vous n’utilisez pas la génération automatique. Pour plus d’informations sur la génération automatique, consultez Générer automatiquement des métadonnées JSON pour les fonctions personnalisées.

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

Étapes suivantes

Découvrez les meilleures pratiques pour nommer votre fonction ou découvrez comment localiser votre fonction à l’aide de la méthode JSON manuscrite décrite précédemment.

Voir aussi