Partager via

Nommage et localisation des fonctions personnalisées

Cet article fournit des instructions et des bonnes pratiques pour nommer des fonctions personnalisées et explique comment les localiser.

Règles de noms des fonctions personnalisées

Une fonction personnalisée est identifiée par un id et un name dans les métadonnées JSON.

  • id: identificateur unique utilisé dans le code.
  • name: nom d’affichage affiché aux utilisateurs. Il peut être localisé.

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
    • Office 2021 perpétuel/LTSC sous licence en volume 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 sous licence en volume de Office 2021 ou antérieures sur Windows

Remarque

Actuellement, le manifeste unifié pour Microsoft 365 ne prend pas en charge les projets de fonctions personnalisées. Vous devez utiliser le manifeste de complément uniquement pour les projets de fonctions personnalisées. Pour plus d’informations, voir Manifeste des compléments Office.

Une fonction name peut différer de pour la id localisation. Si vous n’avez pas besoin de localisation, il est préférable d’utiliser la même valeur pour les deux.

Une fonction name et id partagent des règles similaires.

  • Les deux doivent commencer par une lettre et comporter au moins trois caractères.
  • id: seuls les caractères A à Z, 0 à 9, le trait de soulignement et le point sont autorisés.
  • name: tous les caractères alphabétiques Unicode, traits de soulignement et points sont autorisés.

Excel affiche les noms de fonction intégrés en majuscules (par exemple, SUM). Utilisez des majuscules pour vos fonctions personnalisées afin de les aider à se fondre naturellement.

Évitez les noms qui correspondent :

Conflits d’affectation de noms

Si votre fonction name est en conflit avec l’une d’un autre complément, Excel affiche l’erreur #REF ! .

Corrigez les conflits en renommant votre fonction ou en désinstallant l’autre complément. Pour les tests dans plusieurs environnements, utilisez un préfixe d’espace de noms court (tel que ADDINNAME_FUNCTIONNAME).

Meilleures pratiques

  • Utilisez des arguments de fonction supplémentaires au lieu de créer plusieurs noms de fonction similaires. Par exemple, GETNAME(firstName, middleName, lastName) est plus efficace que d’avoir des fonctions distinctes comme GETFIRSTNAME, GETMIDDLENAMEet GETLASTNAME.
  • Évitez les abréviations qui ne sont pas claires. Par exemple, INCREASETIME est plus facile à comprendre que INC.
  • Choisissez des verbes d’action pour les noms de fonction. Utilisez GETZIPCODE au lieu de .ZIPCODE
  • Soyez cohérent. Utilisez le même verbe pour des actions similaires, telles que DELETEZIPCODE et DELETEADDRESS.
  • Pour les fonctions de diffusion en continu, ajoutez STREAM au nom ou incluez une note dans la description.
  • Utilisez un préfixe fournisseur court dans les noms de vos fonctions pour éviter les conflits avec d’autres compléments. Par exemple, utilisez CONTOSO_GETPRICE ou CONTOSO_TAX_CALC.

Conseil

Si vous souhaitez tester votre complément dans plusieurs environnements (par exemple, en développement, en préproduction, en démonstration, etc.), nous vous recommandons de conserver un fichier manifeste différent pour chaque environnement. Dans chaque fichier manifeste, vous pouvez :

  • Spécifier les URL qui correspondent à l’environnement.

  • Personnalisez les valeurs de métadonnées afin que les utilisateurs finaux puissent identifier l’environnement correspondant d’un complément chargé de manière indépendante. Par exemple :

    • Dans le manifeste unifié pour Microsoft 365, personnalisez la "name" propriété du complément et les "label" propriétés de différents contrôles d’interface utilisateur pour indiquer l’environnement.
    • Dans le manifeste du complément uniquement, personnalisez les DisplayName étiquettes d’élément et et dans l’élément Resources pour indiquer l’environnement.

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

Informations de référence rapides sur les contraintes d’affectation de noms

Guideline id name Notes
Caractères autorisés A–Z 0–9 _. Caractères alphabétiques Unicode _. Restez id simple. Localisez name.
Doit commencer par une lettre Oui Oui Évite la confusion des références de cellule.
Longueur minimale 3 3 Les noms courts réduisent la clarté.
Majuscules Toutes les majuscules recommandées Toutes les majuscules recommandées Correspond au style Excel.
Localisables Non Oui Restez id stable. Localisez en name fonction des besoins.
Peut imiter l’adresse de la cellule Non Non Empêcher les erreurs d’analyse d’adresse.
Noms des macros réservées Rejeté Rejeté Quelques exemples : RUN, ECHO.

Localiser des fonctions personnalisées

Vous pouvez localiser à la fois votre complément et les noms de vos fonctions personnalisées. Ajoutez des noms de fonction localisés dans votre fichier JSON et définissez des remplacements de paramètres régionaux dans le manifeste du complément uniquement.

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 distinct pour chaque langage. Dans chaque fichier, ajoutez les name propriétés et description dans la langue cible. Utilisez functions.json pour l’anglais et incluez les paramètres régionaux dans le nom de fichier pour d’autres langues, telles que functions-de.json pour l’allemand.

Excel localise uniquement les name propriétés et description . Le id n’est pas localisé et doit rester inchangé une fois qu’il est défini.

Importante

Évitez un id ou name qui correspond à une fonction Excel intégrée dans n’importe quelle langue.

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 json pour chaque langage, ajoutez un remplacement au manifeste de votre complément uniquement qui pointe vers le fichier correct. Le fichier XML de manifeste suivant montre les paramètres régionaux par défaut en-us ainsi qu’une URL de fichier JSON de remplacement pour de-de (Allemagne).

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

Étapes suivantes

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

Voir aussi

  • Last updated on