Appeler des API JavaScript Excel à partir d’une fonction personnalisée
Appelez des API JavaScript Excel à partir de vos fonctions personnalisées pour obtenir des données de plage et obtenir plus de contexte pour vos calculs. L’appel des API JavaScript Excel via une fonction personnalisée peut être utile dans les cas suivants :
- Une fonction personnalisée doit obtenir des informations à partir d’Excel avant le calcul. Ces informations peuvent inclure des propriétés de document, des formats de plage, des parties XML personnalisées, un nom de classeur ou d’autres informations spécifiques à Excel.
- Une fonction personnalisée définit le format numérique de la cellule pour les valeurs renvoyées après le calcul.
Importante
Pour appeler des API JavaScript Excel à partir de votre fonction personnalisée, vous devez utiliser un runtime partagé. Utilisez le générateur Yeoman pour les compléments Office pour installer des fonctions personnalisées Excel à l’aide d’un projet d’exécution partagé ou consultez Configurer votre complément Office pour utiliser un runtime partagé pour en savoir plus.
Exemple de code
Pour appeler des API JavaScript Excel à partir d’une fonction personnalisée, vous avez d’abord besoin d’un contexte. Utilisez l’objet Excel.RequestContext pour obtenir un contexte. Utilisez ensuite le contexte pour appeler les API dont vous avez besoin dans le classeur.
L’exemple de code suivant montre comment utiliser Excel.RequestContext pour obtenir une valeur à partir d’une cellule du classeur. Dans cet exemple, le address paramètre est passé dans la méthode Excel JavaScript API Worksheet.getRange et doit être entré sous forme de chaîne. Par exemple, la fonction personnalisée entrée dans l’interface utilisateur Excel doit suivre le modèle =CONTOSO.GETRANGEVALUE("A1"), où "A1" est l’adresse de la cellule à partir de laquelle récupérer la valeur.
/**
* @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 des 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 les API JavaScript Excel à partir d’une fonction personnalisée qui modifie 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’attente et des boucles infinies dans l’application Excel. Cela signifie que vos fonctions personnalisées ne doivent pas effectuer l’une des opérations suivantes :
- Insérer, supprimer ou mettre 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éfinir les propriétés.
- Modifiez l’une des options de l’environnement Excel, telles que le mode de calcul ou les affichages d’écran.
Votre complément fonctions personnalisées peut lire des informations à partir de cellules situées à l’extérieur de la cellule exécutant 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 qu’un recalcul Excel est effectué, car ce scénario crée des résultats imprévisibles.