Nommage et localisation des fonctions personnalisées

  • Article

Cet article décrit les recommandations et les meilleures pratiques pour nommer des fonctions personnalisées. Il montre également comment localiser des noms de fonctions personnalisées dans des langues autres que l’anglais.

Règles de noms des fonctions personnalisées

Une fonction personnalisée est identifiée par une id propriété et name dans le fichier de métadonnées JSON.

  • La fonction id est utilisée pour identifier de manière unique les fonctions personnalisées dans votre code JavaScript.
  • La fonction name est utilisée comme nom d’affichage qui apparaît à un utilisateur dans Excel.

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

Une fonction name peut différer de la fonction id, par exemple à des fins de localisation. En général, une fonction name doit rester la même que si id elle n’a aucune raison de différer.

Une fonction name et id partagent certaines exigences communes.

  • Une fonction ne id peut utiliser que des caractères de A à Z, des nombres de zéro à neuf, des traits de soulignement et des points.

  • Les fonctions name peuvent utiliser des caractères alphabétiques Unicode, des traits de soulignement et des points.

  • Les deux fonctions name et id doivent commencer par une lettre et avoir une limite minimale de trois caractères.

Excel utilise des lettres majuscules pour les noms de fonction intégrés (tels que SUM). Utilisez des lettres majuscules pour les fonctions personnalisées name et id comme meilleure pratique.

Une fonction ne name doit pas être identique à :

Conflits d’affectation de noms

Si votre fonction name est identique à une fonction name dans un complément qui existe déjà, l’erreur #REF ! s’affiche dans votre classeur.

Pour résoudre un conflit de nommage, modifiez le name dans votre complément et réessayez la fonction. Vous pouvez également désinstaller le complément avec le nom en conflit. Ou, si vous testez votre complément dans différents environnements, essayez d’utiliser un autre espace de noms pour différencier votre fonction (par NAMESPACE_NAMEOFFUNCTIONexemple).

Meilleures pratiques

  • Envisagez d’ajouter plusieurs arguments à une fonction plutôt que de créer plusieurs fonctions avec le même nom ou des noms similaires.
  • Évitez les abréviations ambiguës dans les noms de fonction. Clarity est plus important que la concision. Choisissez un nom comme =INCREASETIME plutôt que =INC.
  • Les noms de fonction doivent indiquer l’action de la fonction, par exemple =GETZIPCODE au lieu de ZIPCODE.
  • Utilisez systématiquement les mêmes verbes pour les fonctions qui effectuent des actions similaires. Par exemple, utilisez =DELETEZIPCODE et =DELETEADDRESS, plutôt que =DELETEZIPCODE et =REMOVEADDRESS.
  • Lorsque vous nommez une fonction de diffusion en continu, ajoutez une note à cet effet dans la description de la fonction ou ajoutez STREAM à la fin du nom de la fonction.

Conseil

Si vous allez tester votre complément dans plusieurs environnements (par exemple, dans le développement, la gestion intermédiaire, la version de démonstration, etc.), nous vous recommandons de maintenir un autre fichier manifeste XML pour chaque environnement. Dans chaque fichier manifeste, vous pouvez :

  • Spécifier les URL qui correspondent à l’environnement.
  • Personnaliser des valeurs de métadonnée telles que DisplayName et les étiquettes dans Resources pour indiquer l’environnement pour que les utilisateurs finaux puissent identifier un environnement correspondant du complément chargé indépendamment.
  • Personnaliser les fonctions namespace personnalisées pour indiquer l’environnement si votre complément définit des fonctions personnalisées.

En suivant ces conseils, vous simplifiez le processus de test et éviter des problèmes qui se produisent lorsqu’un complément est chargé indépendamment en même temps dans de nombreux environnements.

Localiser des fonctions personnalisées

Vous pouvez localiser à la fois votre complément et les noms de vos fonctions personnalisées. Pour ce faire, fournissez des noms de fonctions localisés dans le fichier JSON des fonctions et des informations de paramètres régionaux dans le fichier manifeste XML.

Importante

Les métadonnées générées automatiquement ne fonctionnent pas pour la localisation. Vous devez donc mettre à jour le fichier JSON manuellement. Pour savoir comment procéder, consultez Créer manuellement des métadonnées JSON pour des fonctions personnalisées.

Localiser les noms des fonctions

Pour localiser vos fonctions personnalisées, créez un fichier de métadonnées JSON pour chaque langage. Dans chaque fichier JSON de langage, ajoutez name les propriétés et description dans la langue cible. Le fichier par défaut pour l’anglais est nommé functions.json. Utilisez les paramètres régionaux dans le nom de fichier pour chaque fichier JSON supplémentaire, par exemple functions-de.json pour les identifier.

Les name et description apparaissent dans Excel et sont localisés. Toutefois, le id de chaque fonction n’est pas localisé. La id propriété est la façon dont Excel identifie votre fonction comme unique et ne doit pas être modifiée une fois qu’elle est définie.

Importante

Évitez de donner à vos fonctions un id ou name qui est une fonction Excel intégrée dans un autre langage, car cela est en conflit avec les fonctions localisées.

Le code JSON suivant montre comment définir une fonction avec la id propriété « MULTIPLY ». La name propriété et description de la fonction est localisée pour l’allemand. Chaque paramètre name et description est également localisé pour l’allemand.

{
    "id": "MULTIPLY",
    "name": "SUMME",
    "description": "Summe zwei Zahlen",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "eins",
            "description": "Erste Nummer",
            "dimensionality": "scalar"
        },
        {
            "name": "zwei",
            "description": "Zweite Nummer",
            "dimensionality": "scalar"
        },
    ],
}

Comparez le code JSON précédent avec le code JSON suivant pour l’anglais.

{
    "id": "MULTIPLY",
    "name": "Multiply",
    "description": "Multiplies two numbers",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "one",
            "description": "first number",
            "dimensionality": "scalar"
        },
        {
            "name": "two",
            "description": "second number",
            "dimensionality": "scalar"
        },
    ],
}

Localiser votre complément

Après avoir créé un fichier JSON pour chaque langage, mettez à jour votre fichier manifeste XML avec une valeur de remplacement pour chaque paramètre régional qui spécifie l’URL de chaque fichier de métadonnées JSON. Le fichier XML de manifeste suivant affiche des paramètres régionaux par défaut en-us avec une URL de fichier JSON de remplacement pour de-de (Allemagne). Le fichier functions-de.json contient les id et noms des fonctions allemandes localisées.

<DefaultLocale>en-us</DefaultLocale>
...
<Resources>
     <bt:Urls>
        <bt:Url id="Contoso.Functions.Metadata.Url" DefaultValue="https://localhost:3000/dist/functions.json"/>
          <bt:Override Locale="de-de" Value="https://localhost:3000/dist/functions-de.json" />
        </bt:url>
        
     </bt:Urls>
</Resources>

Pour plus d’informations sur le processus de localisation d’un complément, voir Localisation des compléments Office.

Prochaines étapes

Découvrez les meilleures pratiques en matière de gestion des erreurs.

Voir aussi