Appeler des API JavaScript Excel à partir d’une fonction personnalisée

Appeler des API JavaScript Excel à partir d’une fonction personnalisée lorsque son calcul nécessite des données de classeur qui ne sont pas transmises en tant que paramètre. Par exemple, une fonction personnalisée peut lire les propriétés d’un document, les valeurs ou formats de plage, les parties XML personnalisées ou le nom du classeur.

Conservez ces appels en lecture seule. Une fonction personnalisée qui modifie d’autres cellules ou l’environnement Excel peut entraîner des performances médiocres, des délais d’expiration ou des boucles de calcul infinies.

Avant de commencer

Votre complément doit utiliser un environnement d’exécution partagé avant qu’une fonction personnalisée puisse appeler des API JavaScript Excel. Créez un projet de fonctions personnalisées Excel avec Microsoft 365 Agents Toolkit ou configurez un complément existant pour utiliser un runtime partagé.

Obtenir une valeur à partir d’un classeur

Créez un objet Excel.RequestContext pour accéder au classeur. Chargez les propriétés dont la fonction a besoin, appelez context.sync(), puis renvoyez le résultat.

La fonction personnalisée suivante utilise Worksheet.getRange pour lire une valeur de cellule. Le address paramètre doit être une chaîne. Par exemple, entrez =CONTOSO.GETRANGEVALUE("A1") dans une cellule pour renvoyer la valeur de la cellule A1.

/**
 * @customfunction
 * @param {string} address The address of the cell from which to retrieve the value.
 * @returns The value of the cell at the input address.
 **/
async function getRangeValue(address) {
    // Retrieve the context object.
    const context = new Excel.RequestContext();

    // Use the context object to access the cell at the input address.
    const range = context.workbook.worksheets.getActiveWorksheet().getRange(address);
    range.load("values");
    await context.sync();

    // Return the value of the cell at the input address.
    return range.values[0][0];
}

Limitations de l’appel d’API JavaScript Excel via une fonction personnalisée

Un complément de fonctions personnalisées peut appeler des API JavaScript Excel, mais vous devez être prudent quant aux API qu’il appelle. N’appelez pas d’API JavaScript Excel à partir d’une fonction personnalisée qui modifient des cellules en dehors de la cellule exécutant la fonction personnalisée. La modification d’autres cellules ou de l’environnement Excel peut entraîner des performances médiocres, des délais d’expiration et des boucles infinies dans l’application Excel. Cela signifie que vos fonctions personnalisées ne doivent pas effectuer les opérations suivantes :

  • Insérez, supprimez ou mettez en forme des cellules dans la feuille de calcul.
  • Modifier la valeur d’une autre cellule.
  • Déplacer, renommer, supprimer ou ajouter des feuilles à un classeur.
  • Ajouter des noms à un classeur.
  • Définissez les propriétés.
  • Modifiez les options d’environnement d’Excel, telles que le mode de calcul ou les affichages d’écran.

Votre complément de fonctions personnalisées peut lire des informations provenant de cellules situées en dehors de la cellule où elle exécute la fonction personnalisée, mais il ne doit pas effectuer d’opérations d’écriture dans d’autres cellules. Au lieu de cela, apportez des modifications à d’autres cellules ou à l’environnement Excel à partir du contexte d’un bouton de ruban ou d’un volet Office. En outre, les calculs de fonction personnalisée ne doivent pas s’exécuter pendant un recalcul Excel, car ce scénario crée des résultats imprévisibles.

Étapes suivantes

Voir aussi

  • Last updated on