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

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.

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.

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 <Resources> section, 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": "GETPLANETS", 
      "name": "GETPLANETS", 
      "description": "A function that uses the custom enum as a parameter.", 
      "parameters": [ 
        { 
          "name": "planetName", 
          "type": "string", 
          "customEnumId": "PLANETS" 
        }
      ]
    }
  ],
  "enums": [ 
    { 
      "id": "PLANETS", 
      "type": "string", 
      "values": [ 
        { 
          "name": "Mercury", 
          "stringValue": "mercury", 
          "tooltip": "Mercury is the first planet from the sun." 
        }, 
        { 
          "name": "Venus", 
          "stringValue": "venus", 
          "tooltip": "Venus is the second planet from the sun." 
        }
      ] 
    }
  ]
}

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.

Si votre fonction personnalisée utilise le cellValueTypeparamètre , la définition de n’est pas nécessaire pour accepter les allowCustomDataForDataTypeAny types de données comme paramètres et retourner des valeurs.

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.

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.

Enums

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

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.

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.

"parameters": [
    {
        "name": "range",
        "description": "the input range",
        "type": "any",
            "cellValueType": "webimagecellvalue"
    }
]

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.

Associer des noms de fonctions à des 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",
      ...
    }
  ]
}

Modifier des énumérations personnalisées dans les métadonnées JSON

Créez ou modifiez des métadonnées d’énumération directement avec la enums propriété . Chaque énumération personnalisée doit avoir une valeur d’ID unique et une valeur de type de string ou number. Les énumérations de type mixte ne sont pas prises en charge.

Si vous créez manuellement les métadonnées JSON pour votre énumération personnalisée, vous pouvez associer ces énumérations à des fonctions personnalisées TypeScript ou JavaScript. Pour en savoir plus sur la création d’énumérations personnalisées, consultez Créer des énumérations personnalisées pour vos fonctions personnalisées.

L’extrait de code JSON suivant montre les métadonnées de deux énumérations : un PLANETS enum qui contient les planètes Mercure et Vénus, et un DAYS enum qui inclut les jours lundi et mardi.

"enums": [ 
  { 
    "id": "PLANETS", 
    "type": "string", 
    "values": [ 
      { 
        "name": "Mercury", 
        "stringValue": "mercury", 
        "tooltip": "Mercury is the first planet from the sun." 
      }, 
      { 
        "name": "Venus", 
        "stringValue": "venus", 
        "tooltip": "Venus is the second planet from the sun." 
      }
    ] 
  },
  {
    "id": "DAYS", 
    "type": "number", 
    "values": [ 
      { 
        "name": "Monday",
        "numberValue": 1,
        "tooltip": "Monday is the first working day of a week."
      },
      { 
        "name": "Tuesday",
        "numberValue": 2,
        "tooltip": "Tuesday is the second working day of a week."
      }
    ] 
  }
]

Chaque constante dans le values tableau de l’énumération est un objet avec les propriétés suivantes.

• stringValue ou numberValue : valeur de chaîne ou de nombre de la constante. Si le type enum est number, est numberValue obligatoire. Si le type enum est string, est stringValue obligatoire.
• name : brève description de la constante.
• info-bulle (facultatif) : informations supplémentaires sur la constante qui peut être affichée sous forme d’info-bulle dans les interfaces utilisateur.

Pour associer l’énumération personnalisée à une fonction, ajoutez la propriété customEnumId à l’objet parameters . La customEnumId valeur doit correspondre au id de l’énumération. Notez que la valeur ne respecte pas la customEnumId casse. L’extrait de code JSON suivant montre un functions objet associé à l’énumération PLANETS .

"functions": [ 
  {
    "description": "A function that uses the custom enum as a parameter.", 
    "id": "GETPLANETS", 
    "name": "GETPLANETS", 
    "parameters": [ 
      { 
        "name": "planetName", 
        "type": "string", 
        "customEnumId": "PLANETS" 
      }
    ], 
    "result": {} 
  } 
]

É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

• Générer automatiquement des métadonnées JSON pour des fonctions personnalisées
• Options des paramètres des fonctions personnalisées
• Créer des fonctions personnalisées dans Excel