Didacticiel : créer des fonctions personnalisées dans Excel

Créez un complément Excel qui fournit des fonctions personnalisées JavaScript ainsi que des fonctions intégrées telles que SUM. Vous allez créer des fonctions qui effectuent un calcul, récupèrent des données à partir du web et diffusent des mises à jour en temps réel dans une feuille de calcul.

Dans ce tutoriel, vous allez :

  • Créez un complément de fonction personnalisé à l’aide du générateur Yeoman pour les compléments Office.
  • Utiliser une fonction personnalisée prédéfinie pour effectuer un calcul simple.
  • Créer une fonction personnalisée qui demande les données à partir du web.
  • Créer une fonction personnalisée qui diffuse les données en temps réel à partir du web.

Conditions préalables

  • Node.js (dernière version d’Active LTS). Visitez le siteNode.js pour télécharger et installer la version appropriée pour votre système d’exploitation.

  • La dernière version deYeoman et du Générateur Yeoman Générateur de compléments Office. Pour installer ces outils globalement, exécutez la commande suivante via l’invite de commande.

    npm install -g yo generator-office

    Remarque

    Même si vous avez précédemment installé le générateur Yeoman, nous vous recommandons de mettre à jour votre package vers la dernière version de npm.

  • Office connecté à un abonnement Microsoft 365 (y compris Office on the web).

    Remarque

    Si vous n’avez pas encore Office, vous pouvez bénéficier d’un abonnement Microsoft 365 E5 développeur par le biais du Programme pour les développeurs Microsoft 365. Pour plus d’informations, consultez le FAQ. Vous pouvez également vous inscrire à un essai gratuit de 1 mois ou acheter un plan Microsoft 365.

Créer un projet de fonctions personnalisées

Créez le projet de code pour votre complément de fonction personnalisée. Le générateur Yeoman pour les compléments Office configure le projet avec des fonctions personnalisées prédéfinies à essayer. Si vous avez déjà généré un projet dans le guide de démarrage rapide des fonctions personnalisées, utilisez ce projet et continuez dans Créer une fonction personnalisée qui demande des données à partir du web.

Remarque

Si vous recréez le projet Yo Office, vous risquez d’obtenir une erreur, car le cache Office a déjà un instance d’une fonction portant le même nom. Pour éviter cette erreur, effacez le cache Office avant d’exécuter npm run start.

  1. Exécutez la commande suivante pour créer un projet de complément à l’aide du générateur Yeoman. Un dossier qui contient le projet est ajouté au répertoire actif.

    yo office

    Remarque

    Lorsque vous exécutez la commande yo office, il est possible que vous receviez des messages d’invite sur les règles de collecte de données de Yeoman et les outils CLI de complément Office. Utilisez les informations fournies pour répondre aux invites comme vous l’entendez.

    Lorsque vous y êtes invité, fournissez les informations suivantes pour créer votre projet de complément.

    • Choisissez un type de projet :Excel Custom Functions using a Shared Runtime
    • Choisissez un type de script :JavaScript
    • Que voulez-vous nommer votre complément ?My custom functions add-in

    L’interface de ligne de commande du générateur de compléments Office Yeoman invite à entrer des projets de fonctions personnalisées.

    Le générateur Yeoman crée les fichiers projet et installe les composants Node de prise en charge.

  2. Accédez au dossier racine du projet.

    cd "My custom functions add-in"

  3. Créez le projet.

    npm run build

    Remarque

    Les compléments web Office doivent utiliser le protocole HTTPS, et non HTTP, même lorsque vous développez. Si vous êtes invité à installer un certificat après avoir exécuté npm run build, acceptez l’invite pour installer le certificat fourni par le générateur Yeoman.

  4. Démarrez le serveur web local qui est exécuté dans Node.js. Vous pouvez essayer le complément de fonction personnalisée dans Excel.

La commande permettant de tester votre complément dans Excel sur Windows ou Mac dépend du moment où vous avez créé le projet. Si la "scripts" section du fichier package.json du projet comporte un start:desktop script, exécutez npm run start:desktop. Sinon, exécutez npm run start. Le serveur web local démarre et Excel s’ouvre avec votre complément chargé.

Remarque

  • Les compléments Office doivent utiliser HTTPS, et non HTTP, même lorsque vous développez. Si vous êtes invité à installer un certificat après avoir exécuté l’une des commandes suivantes, acceptez l’invite pour installer le certificat fourni par le générateur Yeoman. Il se peut également que vous deviez exécuter votre invite de commande ou votre terminal en tant qu'administrateur pour que les modifications soient effectuées.

  • Si c’est la première fois que vous développez un complément Office sur votre ordinateur, vous pouvez être invité dans la ligne de commande à accorder à Microsoft Edge WebView une exemption de bouclage (« Autoriser le bouclage localhost pour Microsoft Edge WebView ? »). Lorsque vous y êtes invité, entrez Y pour autoriser l’exemption. Notez que vous aurez besoin de privilèges d’administrateur pour autoriser l’exemption. Une fois autorisé, vous ne devez pas être invité à bénéficier d’une exemption lorsque vous chargez une version test des compléments Office à l’avenir (sauf si vous supprimez l’exemption de votre ordinateur). Pour plus d’informations, consultez « Nous ne pouvons pas ouvrir ce complément à partir de localhost » lors du chargement d’un complément Office ou de l’utilisation de Fiddler.

    Invite dans la ligne de commande pour autoriser Microsoft Edge WebView à bénéficier d’une exemption de bouclage.

  • Lorsque vous utilisez le générateur Yeoman pour la première fois pour développer un complément Office, votre navigateur par défaut ouvre une fenêtre dans laquelle vous êtes invité à vous connecter à votre compte Microsoft 365. Si aucune fenêtre de connexion n’apparaît et que vous rencontrez une erreur de chargement indépendant ou de délai d’expiration de connexion, exécutez atk auth login m365.

Essayer une fonction personnalisée prédéfinie

Le projet contient des fonctions personnalisées prédéfinies dans ./src/functions/functions.js. Le fichier ./manifest.xml les affecte à l’espace CONTOSO de noms, que vous utilisez pour accéder aux fonctions dans Excel.

Ensuite, essayez la ADD fonction personnalisée en effectuant les étapes suivantes.

  1. Dans Excel, accédez à n’importe quelle cellule et entrez =CONTOSO. Notez que le menu de saisie semi-automatique affiche la liste de toutes les fonctions dans l’espace de noms CONTOSO.

  2. Entrez =CONTOSO.ADD(10,200) dans la cellule, puis sélectionnez Entrée.

La ADD fonction personnalisée retourne 210.

Si l’espace de noms CONTOSO n’est pas disponible dans le menu de saisie semi-automatique, procédez comme suit pour inscrire le complément dans Excel.

  1. Sélectionnez Compléments d’accueil>, puis Autres paramètres.

  2. Dans la boîte de dialogue Compléments Office , sélectionnez Charger mon complément.

  3. Sélectionnez Parcourir... et accédez au répertoire racine du projet créé par le Générateur de Yo Office.

  4. Sélectionnez le fichiermanifest.xml puis sélectionnezOuvrir, puis sélectionnez Télécharger.

  5. Essayez la nouvelle fonction. Dans la cellule B1, tapez le texte =CONTOSO. GETSTARCOUNT(« OfficeDev », « Excel-Custom-Functions ») et appuyez sur Entrée. Le résultat dans la cellule B1 doit correspondre au nombre d’étoiles actuellement attribuées au référentiel GitHub Excel-Custom-Functions.

Remarque

Consultez la section Résolution des problèmes de cet article si vous rencontrez des erreurs lors du chargement indépendant du complément.

Créer une fonction personnalisée qui demande les données à partir du web

L’intégration de données à partir du web est un excellent moyen d’étendre Excel via des fonctions personnalisées. Créez une getStarCount fonction personnalisée qui récupère le nombre d’étoiles d’un dépôt GitHub.

  1. Dans le projet de complément Mes fonctions personnalisées , ouvrez ./src/functions/functions.js dans votre éditeur de code.

  2. Dans functions.js, ajoutez le code suivant.

    /**
 * Gets the star count for a GitHub repository.
 * @customfunction
 * @param {string} userName GitHub user or organization name.
 * @param {string} repoName GitHub repository name.
 * @returns {number} Number of stars given to the GitHub repository.
 */
async function getStarCount(userName, repoName) {
  try {
    const url = `https://api.github.com/repos/${userName}/${repoName}`;
    const response = await fetch(url);

    if (!response.ok) {
      throw new Error(response.statusText);
    }

    const jsonResponse = await response.json();
    return jsonResponse.stargazers_count;
  } catch (error) {
    throw new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable, String(error));
  }
}

  3. Exécutez la commande suivante pour régénérer le projet.

    npm run build

  4. Enregistrez de nouveau le complément dans Excel en procédant comme suit (pour Excel sur le web, Windows ou Mac). Vous devez effectuer ces étapes avant que la nouvelle fonction soit disponible.

  1. Fermez Excel, puis rouvrez-le.

  2. Dans le ruban Excel, sélectionnezCompléments d’accueil>.

  3. Dans la section Compléments développeur , sélectionnez Le complément Mes fonctions personnalisées pour l’inscrire .

    Boîte de dialogue Mes compléments qui affiche les compléments actifs, avec le bouton Mon complément de fonction personnalisée mis en évidence.

  4. Dans la cellule B1, entrez =CONTOSO.GETSTARCOUNT("OfficeDev", "Office-Add-in-Samples"), puis sélectionnez Entrée. La cellule affiche le nombre actuel d’étoiles pour le dépôt Office-Add-in-Samples.

Remarque

Consultez la section Résolution des problèmes de cet article si vous rencontrez des erreurs lors du chargement indépendant du complément.

Créer une fonction personnalisée asynchrone de diffusion en continu

La getStarCount fonction retourne le nombre d’étoiles à un moment spécifique. En revanche, une fonction de diffusion en continu peut mettre à jour une cellule à plusieurs reprises. Il inclut un invocation paramètre qui représente la cellule qui a appelé la fonction .

L’exemple suivant contient deux fonctions. currentTime retourne l’heure actuelle sous forme de chaîne. La fonction de streaming clock appelle invocation.setResult pour mettre à jour la cellule toutes les secondes et utilise invocation.onCanceled pour arrêter le minuteur quand Excel annule la fonction.

Le projet de complément Mes fonctions personnalisées contient déjà ces fonctions dans ./src/functions/functions.js.

/**
 * Returns the current time
 * @returns {string} String with the current time formatted for the current locale.
 */
function currentTime() {
  return new Date().toLocaleTimeString();
}

/**
 * Displays the current time once a second.
 * @customfunction
 * @param {CustomFunctions.StreamingInvocation<string>} invocation Custom function invocation
 */
function clock(invocation) {
  const timer = setInterval(() => {
    const time = currentTime();
    invocation.setResult(time);
  }, 1000);

  invocation.onCanceled = () => {
    clearInterval(timer);
  };
}

Pour essayer la fonction de diffusion en continu, entrez =CONTOSO.CLOCK() dans la cellule C1, puis sélectionnez Entrée. La cellule affiche l’heure actuelle et se met à jour toutes les secondes. Vous pouvez utiliser le même modèle de minuteur avec des fonctions qui demandent des données en temps réel à partir du web.

Résolution des problèmes

Vous pouvez rencontrer des problèmes si vous exécutez le didacticiel plusieurs fois. Votre complément retourne une erreur lors de son chargement si le cache d'Office contient déjà une instance d'une fonction qui porte le même nom.

Pour éviter ce conflit, effacez le cache Office avant d’exécuter npm run start. Si votre processus npm est déjà en cours d’exécution, entrez npm run stop, effacez le cache Office, puis redémarrez npm.

Message d’erreur Excel intitulé « Erreur lors de l’installation des fonctions ». Il contient le texte « Ce complément n’a pas été installé car une fonction personnalisée du même nom existe déjà ».

Étapes suivantes

Vous avez créé un projet de fonctions personnalisées, essayé une fonction prédéfinie, créé une fonction personnalisée qui demande des données à partir du web et créé une fonction personnalisée qui diffuse des données. Découvrez ensuite comment partager des données de fonction personnalisées avec le volet Office.

  • Last updated on