Créer des fonctions personnalisées dans ExcelCreate custom functions in Excel

Les fonctions personnalisées permettent aux développeurs d’ajouter de nouvelles fonctions dans Excel en définissant ces fonctions dans JavaScript dans le cadre d’un complément.Custom functions enable developers to add new functions to Excel by defining those functions in JavaScript as part of an add-in. Les utilisateurs d’Excel peuvent accéder aux fonctions personnalisées comme ils le feraient pour n’importe quelle fonction native d’Excel, telle que SUM().Users within Excel can access custom functions just as they would any native function in Excel, such as SUM(). Cet article explique comment créer des fonctions personnalisées dans Excel.This article describes how to create custom functions in Excel.

Important

Notez que les fonctions personnalisées Excel sont disponibles sur les plateformes suivantes.Note that Excel custom functions are available on the following platforms.

  • Office sur Windows (version 1904 ou ultérieure, connexion à l’abonnement Office 365)Office on Windows (version 1904 or later, connected to Office 365 subscription)
  • Office sur Mac (version 16,24 ou ultérieure, connexion à l’abonnement Office 365)Office on Mac (version 16.24 or later, connected to Office 365 subscription)
  • Office sur le WebOffice on the web

Les fonctions personnalisées d’Excel ne sont actuellement pas prises en charge sur iPad ou dans les versions à usage unique d’Office 2019 ou version antérieure.Excel custom functions are currently not supported on iPad or in one-time purchase versions of Office 2019 or earlier.

L’image animée suivante montre votre classeur appelant une fonction que vous avez créée avec JavaScript ou Typescript.The following animated image shows your workbook calling a function you've created with JavaScript or Typescript. Dans cet exemple, la fonction personnalisée =MYFUNCTION.SPHEREVOLUME calcule le volume d’une sphère.In this example, the custom function =MYFUNCTION.SPHEREVOLUME calculates the volume of a sphere.

animated image showing an end user inserting the MYFUNCTION.SPHEREVOLUME custom function into a cell of an Excel worksheet

Le code suivant définit la fonction personnalisée =MYFUNCTION.SPHEREVOLUME.The following code defines the custom function =MYFUNCTION.SPHEREVOLUME.

/**
 * Returns the volume of a sphere. 
 * @customfunction
 * @param {number} radius
 */
function sphereVolume(radius) {
  return Math.pow(radius, 3) * 4 * Math.PI / 3;
}

Notes

La section problèmes connusplus loin dans cet article indique les limitations en cours de fonctions personnalisées.The Known issues section later in this article specifies current limitations of custom functions.

Comment une fonction personnalisée est définie dans le codeHow a custom function is defined in code

Si vous utilisez le générateur de Yo Office pour créer un projet de complément de fonctions personnalisées Excel, vous constaterez qu’il crée des fichiers qui contrôlent totalement vos fonctions, votre volet des tâches et votre complément.If you use the Yo Office generator to create an Excel custom functions add-in project, you'll find that it creates files which control your functions, your task pane, and your add-in overall. Nous allons vous concentrer sur les fichiers importants pour les fonctions personnalisées :We'll concentrate on the files that are important to custom functions:

FileFile Format de fichierFile format DescriptionDescription
./src/functions/functions.js./src/functions/functions.js
ouor
./src/functions/functions.ts./src/functions/functions.ts
JavaScriptJavaScript
ouor
TypeScriptTypeScript
Contient le code qui définit les fonctions personnalisées.Contains the code that defines custom functions.
./src/functions/functions.html./src/functions/functions.html HTMLHTML Fournit une référence<script> au fichier JavaScript qui définit les fonctions personnalisées.Provides a <script> reference to the JavaScript file that defines custom functions.
./manifest.xml./manifest.xml XMLXML Spécifie l’espace de noms pour toutes les fonctions personnalisées dans le complément et l’emplacement des fichiers JavaScript et HTML qui figurent plus haut dans ce tableau.Specifies the namespace for all custom functions within the add-in and the location of the JavaScript and HTML files that are listed previously in this table. Répertorie également les emplacements des autres fichiers que votre complément pourrait utiliser, tels que les fichiers du volet des tâches et les fichiers de commande.It also lists the locations of other files your add-in might make use of, such as the task pane files and command files.

Fichier de scriptScript file

Le fichier de script (./src/functions/functions.js ou ./src/functions/functions.ts) contient le code qui définit des fonctions personnalisées et des commentaires qui définissent la fonction.The script file (./src/functions/functions.js or ./src/functions/functions.ts) contains the code that defines custom functions and comments which define the function.

Le code suivant définit la fonction personnalisée add.The following code defines the custom function add. Les commentaires du code sont utilisés pour générer un fichier de métadonnées JSON décrivant la fonction personnalisée pour Excel.The code comments are used to generate a JSON metadata file that describes the custom function to Excel. Le commentaire obligatoire @customfunction est déclaré en premier, pour indiquer qu’il s’agit d’une fonction personnalisée.The required @customfunction comment is declared first, to indicate that this is a custom function. Vous pouvez également constater que deux paramètres sont déclarés, first et second, qui sont suivis de leurs propriétés description.Additionally, you'll notice two parameters are declared, first and second, which are followed by their description properties. Enfin, une description returns est fournie.Finally, a returns description is given. Pour plus d’informations sur les commentaires requis pour votre fonction personnalisée, voir Créer des métadonnées JSON pour des fonctions personnalisées.For more information about what comments are required for your custom function, see Create JSON metadata for custom functions.

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number.
 * @param second Second number.
 * @returns The sum of the two numbers.
 */

function add(first, second){
  return first + second;
}

Notez que le fichier functions.html qui régit le chargement du runtime de fonctions personnalisées doit créer un lien vers le CDN actuel pour les fonctions personnalisées.Note that the functions.html file, which governs the loading of the custom functions runtime, must link to the current CDN for custom functions. Les projets préparés avec la version actuelle du générateur Yo Office font référence au CDN correct.Projects prepared with the current version of the Yo Office generator reference the correct CDN. Si vous mettez à niveau un projet de fonction personnalisée de mars 2019 ou antérieur, vous devez copier le code ci-dessous dans la page ** functions.html**.If you are retrofitting a previous custom function project from March 2019 or earlier, you need to copy in the code below to the functions.html page.

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/custom-functions-runtime.js" type="text/javascript"></script>

Fichier manifesteManifest file

Le fichier manifeste XML pour un complément qui définit les fonctions personnalisées (./manifest.xml du projet créé par le Générateur de Yo Office) spécifie l’espace de noms pour toutes les fonctions personnalisées dans le complément et l’emplacement des fichiers HTML, JavaScript et JSON.The XML manifest file for an add-in that defines custom functions (./manifest.xml in the project that the Yo Office generator creates) specifies the namespace for all custom functions within the add-in and the location of the JavaScript, JSON, and HTML files.

Le marquage XML suivant présente un exemple des éléments<ExtensionPoint> et <Resources> que vous devez inclure dans le manifeste d’un complément pour activer les fonctions personnalisées.The following basic XML markup shows an example of the <ExtensionPoint> and <Resources> elements that you must include in an add-in's manifest to enable custom functions. Si vous utilisez le générateur de Yo Office, vos fichiers de fonction personnalisée générés contiennent un fichier manifeste plus complexe que vous pouvez comparer sur ce dépôt Github.If using the Yo Office generator, your generated custom function files will contain a more complex manifest file, which you can compare on this Github repository.

Notes

Les URL spécifiées dans le fichier manifeste pour les fonctions personnalisées de fichiers HTML, JavaScript et JSON doivent avoir le même sous-domaine et être accessibles publiquement.The URLs specified in the manifest file for the custom functions JavaScript, JSON, and HTML files must be publicly accessible and have the same subdomain.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="TaskPaneApp">
  <!--IMPORTANT! Id must be unique for each add-in. If you copy this manifest ensure that you change this id to your own GUID. -->
  <Id>6f4e46e8-07a8-4644-b126-547d5b539ece</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="helloworld"/>
  <Description DefaultValue="Samples to test custom functions"/>
  <SupportUrl DefaultValue="[Insert the URL of a page that provides support information for the app]" />
  <Hosts>
    <Host Name="Workbook"/>
  </Hosts>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://localhost:8081/index.html"/>
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Hosts>
      <Host xsi:type="Workbook">
        <AllFormFactors>
          <ExtensionPoint xsi:type="CustomFunctions">
            <Script>
              <SourceLocation resid="JS-URL"/>
            </Script>
            <Page>
              <SourceLocation resid="HTML-URL"/>
            </Page>
            <Metadata>
              <SourceLocation resid="JSON-URL"/>
            </Metadata>
            <Namespace resid="namespace"/>
          </ExtensionPoint>
        </AllFormFactors>
      </Host>
    </Hosts>
    <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>
  </VersionOverrides>
</OfficeApp>

Notes

Les fonctions dans Excel sont précédées par l’espace de noms spécifié dans votre fichier manifeste XML.Functions in Excel are prepended by the namespace specified in your XML manifest file. L’espace de noms d’une fonction vient avant le nom de fonction et les deux sont séparés par un point.A function's namespace comes before the function name and they are separated by a period. Par exemple, pour appeler la fonction ADD42 dans la cellule de feuille de calcul Excel, vous saisiriez =CONTOSO.ADD42, car CONTOSO est l’espace de noms et ADD42 est le nom de la fonction spécifié dans le fichier JSON.For example, to call the function ADD42 in the cell of an Excel worksheet, you would type =CONTOSO.ADD42, because CONTOSO is the namespace and ADD42 is the name of the function specified in the JSON file. L’espace de noms est destiné à être utilisé comme identificateur de votre entreprise ou du complément.The namespace is intended to be used as an identifier for your company or the add-in. Un espace de noms ne peut contenir que des points et des caractères alphanumériques.A namespace can only contain alphanumeric characters and periods.

Conseil

Si vous testez votre complément dans plusieurs environnements (par exemple, en cours de développement, de mise en œuvre, de démonstration, etc.), nous vous recommandons de conserver un fichier manifeste XML différent pour chaque environnement.If you'll be testing your add-in across multiple environments (for example, in development, staging, demo, etc.), we recommend that you maintain a different XML manifest file for each environment. Dans chaque fichier manifeste, vous pouvez :In each manifest file, you can:

  • Spécifiez les URL qui correspondent à l’environnement.Specify the URLs that correspond to the environment.
  • Personnalisez les valeurs DisplayName de métadonnées Resources telles que et les étiquettes au sein pour indiquer l’environnement, afin que les utilisateurs finals puissent identifier l’environnement correspondant d’un complément versions test chargées.Customize metadata values like DisplayName and labels within Resources to indicate the environment, so that end users will be able to identify a sideloaded add-in's corresponding environment.
  • Personnalisez les fonctions namespace personnalisées pour indiquer l’environnement, si votre complément définit des fonctions personnalisées.Customize the custom functions namespace to indicate the environment, if your add-in defines custom functions.

En suivant ce guide, vous allez rationaliser le processus de test et éviter les problèmes qui seraient normalement survenus lorsqu’un complément est simultanément versions test chargées pour plusieurs environnements.By following this guidance, you'll streamline the testing process and avoid issues that would otherwise occur when an add-in is simultaneously sideloaded for multiple environments.

Co-créationCoauthoring

Excel sur le web et Windows avec un abonnement Office 365 vous permettent de co-créer des documents et cette fonctionnalité est disponible avec les fonctions personnalisées.Excel on the web and Windows connected to an Office 365 subscription allow you to coauthor documents and this feature works with custom functions. Si votre classeur utilise une fonction personnalisée, votre collègue sera invité à charger le complément de la fonction personnalisée.If your workbook uses a custom function, your colleague will be prompted to load the custom function's add-in. Quand vous avez tous les deux chargé le complément, la fonction personnalisée peut partager les résultats via la co-création.Once you both have loaded the add-in, the custom function will share results through coauthoring.

Pour plus d’informations sur la co-création, voir À propos de la co-création dans Excel.For more information on coauthoring, see About coauthoring in Excel.

Problèmes connusKnown issues

Consulter les problèmes connus sur notrerepo GitHub Fonctions Excel Personnalisées.See known issues on our Excel Custom Functions GitHub repo.

Étapes suivantesNext steps

Vous voulez essayer les fonctions personnalisées ?Want to try out custom functions? Consultez la documentation sur le démarrage rapide de fonction personnalisée ou le didacticiel sur les fonctions personnalisées.Check out the simple custom functions quick start or the more in-depth custom functions tutorial if you haven't already.

Un autre moyen simple d’essayer des fonctions personnalisées consiste à utiliser Script Lab, un complément qui vous permet d’expérimenter des fonctions personnalisées directement dans Excel.Another easy way to try out custom functions is to use Script Lab, an add-in that allows you to experiment with custom functions right in Excel. Vous pouvez essayer de créer votre propre fonction personnalisée ou utiliser les exemples fournis.You can try out creating your own custom function or play with the provided samples.

Êtes-vous prêt à en apprendre davantage sur les capacités des fonctions personnalisées ?Ready to read more about the capabilities custom functions? Découvrez une vue d’ensemble de l’architecture des fonctions personnalisées.Learn about an overview of the custom functions architecture.

Voir aussiSee also