Présentation des API JavaScript Office
Dans cette unité, vous allez découvrir le modèle de programmation des Compléments Office, les outils de développement et les fonctionnalités des API JavaScript Office pour Excel, Outlook et Word.
Présentation des concepts de base du modèle de programmation de Compléments Office
Le modèle de programmation de compléments Office repose sur deux modèles d’objets JavaScript :
- API JavaScript spécifique à l'hôte – Les API spécifiques à l'hôte pour Excel et Word fournissent des objets typés que vous pouvez utiliser pour accéder à des éléments spécifiques de l'application hôte. Par exemple, l’API Excel contient des objets qui représentent des feuilles de calcul, des plages, des tableaux, des graphiques et bien plus encore..
- API commune : présentée avec Office 2013, l’API commune vous permet d’accéder à des fonctionnalités telles que :
- Interface utilisateur
- Boîtes de dialogue
- Paramètres client communs à différents types d’applications Office
Les fonctions personnalisées utilisent un modèle de programmation légèrement différent et sont traitées dans une unité ultérieure.
Ensembles de conditions requises de l’API JavaScript pour Office
Vous n’avez pas toujours le contrôle sur la version Office que vos utilisateurs ont installée. Selon la version Office et de plateforme sur laquelle il s’exécute, plusieurs API et fonctionnalités sont prises en charge pour votre complément. Par exemple, Office 2016 prend en charge davantage de fonctionnalités qu’Office 2013. Pour gérer cette situation, nous fournissons des ensembles de conditions requises pour vous aider à déterminer si un hôte Office prend en charge les fonctionnalités dont vous avez besoin dans votre complément Office.
Les ensembles de conditions peuvent être spécifiques aux hôtes Office, tels qu’un ExcelApi 1.7 défini, ou communs à plusieurs hôtes, tels que l’API de boîte de dialogue. La prise en charge de l’ensemble des conditions requises varie selon l’hôte et la version de ce dernier.
Il est possible de vérifier par programmation si les ensembles de conditions sont pris en charge par l’hôte Office de votre complément, à l’aide de isSetSupported. Si l'ensemble d'exigences est pris en charge, isSetSupportedles retourstrue et votre complément peuvent exécuter le code supplémentaire qui utilise les membres de l' API de cet ensemble d'exigences. Si l'hôte de l'Office ne prend pas en charge l'ensemble des exigences, isSetSupportedles retoursfalseet le code supplémentaire ne fonctionneront pas. Le code suivant indique la syntaxe à utiliser avec isSetSupported
if (Office.context.requirements.isSetSupported(RequirementSetName, MinimumVersion)) {
// Code that uses API members from RequirementSetName.
}
Remarque
Programme Office Insider
Pour obtenir les modifications les plus anciennes ou mensuelles apportées à tous les hôtes Office, vous pouvez participer au programme Office Insider. Ce programme est destiné uniquement aux PC Windows et nécessite un abonnement Microsoft 365. Dans n’importe quelle application Office, sélectionnez Fichier>Compte>Office Insider pour rejoindre rapidement le programme.
Utilisation de l’API JavaScript pour Office
Pour utiliser ces API, faites référence à celles-ci sur le réseau de diffusion de contenu (CDN) Office.js, généralement en ajoutant l’une des instructions de code suivantes à la balise de <head> de votre page.
<!-- Reference the production APIs on the CDN -->
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>
<!-- Reference the beta/preview APIs on the CDN -->
<script src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js" type="text/javascript"></script>
Outre l’ajout de votre lien de CDN favori, tous les compléments Office nécessitent un appel Office.onReady(). Vous avez placé votre code de complément dans cette méthode, lequel est appelé une fois la bibliothèque Office.js initialisée. Dans la méthode onReady(), vous pouvez déterminer l’hôte dans lequel votre complément s’exécute en vérifiant la valeur d’énumération Office.HostType (par exemple, Excel ou Word). Vous pouvez vérifier la plateforme sur laquelle votre complément est exécuté avec une valeur d’énumération Office.PlatformType (par exemple, PC ou Mac).
Si vous utilisez d’autres frameworks JavaScript qui incluent leur propre gestionnaire d’initialisation ou tests, ils doivent être placés dans la réponse à Office.onReady(). Par exemple, vous devez référencer $(document).ready() la fonction JQuery comme illustré dans l’exemple de code suivant.
Office.onReady(function() {
// Office is ready.
$(document).ready(function () {
// The document is ready.
});
});
Effectuer des appels asynchrones avec des objets proxy
Lorsque vous travaillez avec un document, les actions de lecture ou d'écriture demandées sont regroupées à l'aide d'un objet proxy. Vos appels d’API ne lisent ni ne mettent à jour le document sous-jacent tant que vous n’avez pas appelé la méthode sync().
Pour améliorer la sécurité, votre complément s’exécute dans un environnement JavaScript sandbox qui ne peut pas accéder directement au document ou à d’autres compléments. La plateforme de Compléments Office fournit un objet RequestContext qui, à son tour, fournit des objets proxy pour représenter le document (par exemple, des feuilles de calcul, des plages et des tableaux). Le RequestContext est généralement transmis à votre code sous la forme d’un paramètre nommé context. Vous pouvez utiliser l’objet context pour récupérer les objets proxy dont vous avez besoin pour travailler sur le document.
Avant que vous puissiez lire les propriétés d’un objet proxy, vous devez charger les propriétés pour remplir l’objet proxy avec des données à partir du document Office. Pour ce faire, appelez la méthode load() sur l’objet proxy pour les propriétés dont vous avez besoin. Appelez ensuite la méthode context.sync(), qui charge toutes les propriétés demandées. Par exemple, si vous créez un objet de plage de proxy pour fonctionner avec une plage sélectionnée d’utilisateur dans une feuille de calcul Excel, puis que vous voulez lire la propriété address de la plage sélectionnée, vous devez charger la propriété address avant de pouvoir la lire. Pour demander le chargement de propriétés d’un objet, appelez la méthode load() sur l’objet et spécifiez les propriétés à charger.
L’exemple suivant montre une fonction qui définit un objet proxy local (selectedRange), charge la propriété address de cet objet, puis appelle context.sync(). Lorsque la promesse de context.sync() est résolue, le code peut lire la propriété address. Excel.run est nécessaire pour cet hôte spécifique, pour charger propriétés qui ont une incidence sur le comportement de la plateforme lorsque la fonction est en cours d’exécution. Tous les hôtes ne contiennent pas d’appel d’exécution.
Excel.run(function (context) {
var selectedRange = context.workbook.getSelectedRange();
selectedRange.load('address');
return context.sync()
.then(function () {
console.log('The selected range is: ' + selectedRange.address);
});
}).catch(function (error) {
console.log('error: ' + error);
if (error instanceof OfficeExtension.Error) {
console.log('Debug info: ' + JSON.stringify(error.debugInfo));
}
});
Présentation des concepts de base des outils de développement des Compléments Office
Vous pouvez utiliser les outils de développement des Compléments Office pour créer un complément Office, explorer les API JavaScript Office et valider un fichier manifeste de complément Office. Les outils développés dans cette unité sont les suivants :
- Générateur Yeoman pour compléments Office
- Visual Studio
- Script Lab
- Validateur de manifeste
Création d’un complément Office
Vous pouvez créer un complément Office à l’aide du générateur Yeoman pour les compléments Office ou de Visual Studio.
Conseil
Installez et apprenez-en davantage sur le générateur Yeoman pour compléments Office auprès de github.com/OfficeDev/generator-office.
Générateur Yeoman pour compléments Office
LeGénérateur Yeoman pour les compléments Office peut être utilisé pour créer un projet de complément Office Node.js qui peut être géré à l’aide de Visual Studio Code ou de tout autre éditeur. Le générateur peut créer des modules complémentaires Office pour :
- Excel
- OneNote
- Outlook
- PowerPoint
- Project
- Word
- Fonctions personnalisées dans Excel
Vous pouvez choisir de créer le projet à l’aide de HTML, CSS et JavaScript, ou d’utiliser Angular ou React. TypeScript est une autre option possible.
Pour créer un projet de complément Office avec le générateur Yeoman, effectuez les étapes suivantes.
Pour désinstaller globalement Yeoman et le générateur Yeoman pour compléments Office à l’aide du gestionnaire de package de nœud (npm), exécutez la commande suivante.
npm install -g yo generator-officePour créer un projet de complément à l’aide du générateur Yeoman, exécutez la commande suivante.
yo office
Visual Studio
Visual Studio peut être utilisé pour créer des compléments Office pour Excel, Word, PowerPoint ou Outlook. Un projet de complément Office est créé dans le cadre d’une solution Visual Studio, ce qui signifie que vous pouvez utiliser les fonctionnalités de Visual Studio comme le bouton Démarrer ou appuyer surF5 pour exécuter automatiquement votre complément localement sur IIS. Les projets de complément Office que vous créez avec Visual Studio utilisent html, CSS et JavaScript.
Pour créer un complément Office avec Visual Studio, créez un projet C# ou Visual Basic et choisissez l’un des types de projets suivants.
- Complément web Excel
- Complément web Outlook
- Complément web PowerPoint
- Complément web Word
Explorer les API avec Script Lab
Script Lab est un complément qui vous permet d’exécuter des extraits de code JavaScript Office lorsque vous travaillez dans un programme Office tel qu’Excel ou Word. Il est disponible gratuitement via AppSource. Il s’agit d’un outil utile pour inclure votre kit de ressources de développement pendant que vous testez et vérifiez les fonctionnalités de votre complément. Dans Script Lab, vous pouvez accéder à une bibliothèque d'exemples intégrés pour essayer rapidement des API ou même utiliser un exemple comme point de départ pour votre propre code.
La vidéo suivante illustre Script Lab en action.
Validation du fichier manifeste d’un complément Office
Le validateur de fichier manifeste de Complément Office examine le fichier manifeste de votre complément pour déterminer s’il est correct et complet. Si vous avez créé votre projet de complément à l’aide du générateur Yeoman pour compléments Office (version 1.1.17 ou ultérieure), vous pouvez valider le fichier manifeste en exécutant la commande suivante dans le répertoire racine du projet.
npm run validate
Si vous n’avez pas utilisé le générateur Yeoman pour créer votre projet de complément, vous pouvez valider le fichier manifeste de votre complément en procédant comme suit.
Installez Node.js.
Exécutez la commande suivante dans le répertoire racine de votre projet.
Importante
Remplacez
{{MANIFEST_FILE}}par le nom de votre fichier manifeste.npx office-addin-manifest validate {{MANIFEST_FILE}}
Présentation des fonctionnalités de l’API JavaScript pour Excel
Les API JavaScript pour Excel permettent à vos compléments d’accéder à des documents Excel. Vos compléments Excel peuvent ainsi gérer le contenu, la mise en forme et la structure d’un classeur ou d’une feuille de calcul.
Présentation des fonctionnalités de l’API JavaScript pour Outlook
Les API JavaScript pour Outlook permettent aux compléments d’accéder à la boîte aux lettres, aux messages et aux rendez-vous de l’utilisateur dans Outlook. Un complément Outlook peut obtenir le contenu et les propriétés d’un message ou d’un rendez-vous. Un complément peut également gérer le contenu, la mise en forme et la structure d’un message ou d’un rendez-vous composé.
Modèle d’objet
Pour comprendre les API Outlook, commencez par déterminer la relation entre les principaux composants d’une boîte aux lettres.
- L’objet boîte aux lettres vous permet de gérer l’authentification, de gérer un élément sélectionné et d’afficher les détails du profil utilisateur.
- L'objet élément représente le message ou le rendez-vous sélectionné que l'utilisateur lit ou rédige.
À l’aide des API Outlook, vous pouvez gérer de nombreuses propriétés d’un e-mail ou d’un rendez-vous. De nombreuses API sont organisées autour du mode dans lequel se trouve l’utilisateur. Le tableau suivant présente les types et modes d’éléments.
| Type d’élément | Modes |
|---|---|
| Message | Lecture Composition |
| Rendez-vous/réunion | Participant (lecture) Organisateur (composer) |
Principales fonctionnalités
Outre les compléments du volet Office, vous pouvez créer des compléments contextuels et de module. Dans cette section, vous allez découvrir quelques fonctionnalités clés des API Outlook.
- Options d’authentification
- Compléments contextuels
- Compléments de module
Authentification
Votre complément Outlook peut accéder aux informations à partir de n’importe quel emplacement sur Internet. Quelques exemples incluent le serveur qui héberge le complément, votre réseau interne ou un autre emplacement dans le Cloud. Si ces informations sont protégées, votre complément doit trouver un moyen d’authentifier votre utilisateur. Les compléments d'Outlook offrent de nombreuses méthodes d'authentification différentes, en fonction de votre scénario spécifique.
Jeton d’identité d’utilisateur Exchange
Les jetons d’identité d’utilisateur Exchange permettent à votre complément d’établir l’identité de l’utilisateur. En vérifiant l'identité de l'utilisateur, vous pouvez authentifier un utilisateur dans votre système une fois, puis accepter le jeton d'identité d'utilisateur comme autorisation pour les demandes futures. Envisagez d’utiliser des jetons d’identité d’utilisateur si votre complément est principalement utilisé par des utilisateurs locaux Exchange ou si vous avez besoin d’accéder à un service non Microsoft que vous contrôlez. Votre complément peut appeler la méthode getUserIdentityTokenAsync() pour obtenir des jetons d’identité d’utilisateur Exchange.
Obtenir des jetons d’accès avec des flux OAuth2
Les compléments peuvent également accéder à des services tiers qui prennent en charge les flux OAuth2 pour l’autorisation. Envisagez d’utiliser des jetons Oauth2 ne si votre complément a besoin d’accéder à un service tiers en dehors de votre contrôle. À l’aide de cette méthode, votre complément invite l’utilisateur à se connecter au service à l’aide de la méthode displayDialogAsync() pour initialiser le flux Oauth2, par exemple.
Jetons de rappel
Les jetons de rappel permettent à votre complément d’accéder à la boîte aux lettres de l’utilisateur à partir de votre serveur à l’aide d’Exchange Web Services (EWS) ou de l’API REST Outlook. Les compléments obtiennent des jetons de rappel à l’aide d’une méthode getCallbackTokenAsync(). Le niveau d’accès est contrôlé par les autorisations spécifiées dans le manifeste du complément.
Résumé de l’authentification
Le tableau suivant récapitule les situations dans lesquelles vous devez utiliser chaque type de jeton d’accès.
| Access token (Jeton d’accès) | Utilisez si votre complément... |
|---|---|
| Jetons d’identité d’utilisateur Exchange | Est utilisé principalement par les utilisateurs locaux Exchange. Doit accéder à un service non-Microsoft que vous contrôlez. |
| Jetons d'accès OAuth2 | Doit accéder à un service tiers en dehors de votre contrôle. |
| Jetons de rappel | Doit accéder à la boîte aux lettres de l’utilisateur à partir de votre serveur. |
Compléments contextuels
Les compléments contextuels sont des compléments Outlook qui s’activent sur la base du texte d’un message ou d’un rendez-vous. Vous avez peut-être déjà vu les compléments contextuels par défaut dans Outlook, tels que Bing Cartes ou Suggested Meetings. À l'aide de compléments contextuels, un utilisateur peut lancer des tâches liées à un message sans laisser le message lui-même pour faciliter et enrichir l'expérience utilisateur.
Le tableau suivant répertorie quelques exemples de tâche basés sur la sélection d’un utilisateur.
| L'utilisateur choisit... | Action de complément contextuelle |
|---|---|
| Adresse | Ouvrir une carte de l'emplacement. |
| Chaîne | Ouvrir un complément de proposition de réunion. |
| Numéro de téléphone | Ajouter un numéro à vos contacts. |
Remarque
Pour l’instant, les compléments contextuels ne sont pas disponibles actuellement dans Outlook pour Android et iOS.
L’image suivante montre un complément contextuel affiché dans Outlook.
Complément contextuel affiché dans Outlook
Le manifeste d’un complément contextuel doit inclure un élément ExtensionPoint avec une attribut xsi:type défini sur DetectedEntity. Au sein de l’élément ExtensionPoint, le complément spécifie les entités ou l’expression régulière qui peuvent l’activer. Si une entité est spécifiée, il peut s’agir d’une des propriétés de l’objet Entities.
Ainsi, le manifeste de complément doit contenir une règle de type ItemHasKnownEntity ou ItemHasRegularExpressionMatch. L’exemple suivant montre comment spécifier qu’un complément doit s’activer sur les messages lorsqu'il détecte un numéro de téléphone.
<ExtensionPoint xsi:type="DetectedEntity">
<Label resid="contextLabel" />
<SourceLocation resid="detectedEntityURL" />
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="ItemIs" ItemType="Message" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="PhoneNumber" Highlight="all" />
</Rule>
</ExtensionPoint>
Une fois qu’un complément contextuel est associé à un compte, il démarre automatiquement lorsque l’utilisateur sélectionne sur une expression régulière ou une entité mise en surbrillance.
Un utilisateur lance un complément contextuel par le biais du texte, une entité connue ou une expression régulière du développeur. En règle générale, un utilisateur identifie un complément contextuel car l’entité est mise en surbrillance.
Compléments de module
Les compléments de module figurent dans la barre de navigation Outlook, en regard des onglets Courrier, Tâches et Calendriers. Vous pouvez utiliser toutes les fonctionnalités de l’interface API JavaScript pour Outlook dans votre complément et créer des boutons de commande dans le ruban Outlook pour ue l’utilisateur puisse interagir avec le contenu du complément.
Remarque
Les compléments de module sont uniquement prises en charge dans Outlook 2016 ou version ultérieure sous Windows.
L’image suivante montre un exemple de complément d'extension de module.
Exemple de complément de module dans Outlook sur Windows
Pour créer un complément de module, incluez le point d’extension du module dans le fichier manifeste de votre complément. L’exemple suivant montre un extrait de fichier manifeste ajusté pour définir une extension de module.
...
<!-- Add Outlook module extension point. -->
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides"
xsi:type="VersionOverridesV1_0">
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1"
xsi:type="VersionOverridesV1_1">
<!-- Begin override of existing elements. -->
<Description resid="residVersionOverrideDesc" />
<Requirements>
<bt:Sets DefaultMinVersion="1.3">
<bt:Set Name="Mailbox" />
</bt:Sets>
</Requirements>
<!-- End override of existing elements. -->
<Hosts>
<Host xsi:type="MailHost">
<DesktopFormFactor>
<!-- Set the URL of the file that contains the
JavaScript function that controls the extension. -->
<FunctionFile resid="residFunctionFileUrl" />
<!-- Module extension point for a ModuleApp -->
<ExtensionPoint xsi:type="Module">
<SourceLocation resid="residExtensionPointUrl" />
<Label resid="residExtensionPointLabel" />
<CommandSurface>
<CustomTab id="idTab">
<Group id="idGroup">
<Label resid="residGroupLabel" />
<Control xsi:type="Button" id="group.changeToAssociate">
<Label resid="residChangeToAssociateLabel" />
<Supertip>
<Title resid="residChangeToAssociateLabel" />
<Description resid="residChangeToAssociateDesc" />
</Supertip>
<Icon>
<bt:Image size="16" resid="residAssociateIcon16" />
<bt:Image size="32" resid="residAssociateIcon32" />
<bt:Image size="80" resid="residAssociateIcon80" />
</Icon>
<Action xsi:type="ExecuteFunction">
<FunctionName>changeToAssociateRate</FunctionName>
</Action>
</Control>
</Group>
<Label resid="residCustomTabLabel" />
</CustomTab>
</CommandSurface>
</ExtensionPoint>
</DesktopFormFactor>
</Host>
</Hosts>
<Resources>
...
</Resources>
</VersionOverrides>
</VersionOverrides>
Commencer à développer des compléments Outlook
Pour développer un complément Outlook, utilisez :
- Le générateur Yeoman pour compléments Office
- Visual Studio
Vous pouvez utiliser un modèle comme base, puis ajouter votre fonctionnalité.
Présentation des fonctionnalités de l’API JavaScript pour Word
Les API JavaScript pour Word donnent à vos compléments l’accès aux documents Word. Un complément Word peut gérer le contenu, la mise en forme et la structure d’un document.
Modèle d’objet
Pour comprendre les API Word, vous devez déterminer la relation entre les principaux composants d’un document.
- Un Document contient un Corps et au moins une Section.
- Un Corps peut contenir les éléments suivants :
- Paragraphe (un ou plusieurs)
- Tableau (un ou plusieurs)
- Liste (une ou plusieurs)
- Texte
- Objets tels que des images et des listes
- Une Section donne accès à ses corps, en-têtes et pieds de page.
Scénarios clés
Dans cette section, vous allez découvrir quelques scénarios clés pour les API Word.
- Utiliser le texte d’un document
- Recherche
Remarque
Vous pouvez appliquer une mise en forme simple à l’ensemble d’un document existant à l’aide des API Office.js. Toutefois, si vous voulez appliquer une mise en forme complexe ou utiliser des objets de contenu enrichi, vous pouvez utiliser Office Open XML (OOXML) pour créer ces effets. Les exemples de fonctionnalités de OOXML incluent l’application d’ombres à du texte ou des images, la contrainte de zones de texte en formes, et l’insertion de graphiques Excel en tant que graphiques dynamiques dans des documents Word. Comme il s’agit d’une compétence plus avancée, nous ne traiterons pas de ce sujet dans son intégralité, mais nous le mentionnerons pour les développeurs pour les développeurs habitués à OOXML.
Utilisation du texte du document
Les compléments Word utilisent le gestionnaire d’événements Office.onReady() pour démarrer. Si le complément cible Word 2016 ou version ultérieure, il appelle la méthode Word.run() pour exécuter les API JavaScript Word. Le complément doit transmettre une fonction à Word.run() qui attend qu’un objet de contexte soit transmis comme paramètre. L’objet de contexte permet au complément d’interagir avec le document Word. Vous pouvez utiliser l’objet de contexte pour créer les objets proxy nécessaires pour le document Word et charger les proxies avec toutes les propriétés que vous souhaitez utiliser. Vous pouvez également programmer des actions à exécuter à l’aide de ces propriétés. Comme toujours, une commande context.sync() synchronise l’état entre les objets proxy et objets dans le document Word.
L’exemple suivant illustre du code qui insère du texte après le corps de texte d’un document Word. Pour simplifier, cet exemple omet le code Office.onReady() et se concentre sur le code inclus dans un bloc de code Word.run().
// Run a batch operation against the Word JavaScript API.
Word.run(function (context) {
// Create a proxy object for the document body.
var body = context.document.body;
// Queue a command to load the text property of the proxy body object.
body.load("text");
// Queue a command to insert text into the end of the Word document body.
body.insertText('This is text inserted after loading the body.text property',
Word.InsertLocation.end);
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync().then(function () {
console.log("Body contents: " + body.text);
});
})
Recherche
Vous pouvez utiliser les API pour rechercher du texte conforme à vos critères dans le document. Vous pouvez également étendre la recherche à certains types de contenu, par exemple, des paragraphes ou des tableaux.
L’exemple de code suivant recherche le texte « vidéo » et ignore la ponctuation. Si le texte est trouvé, les correspondances sont mises en gras, mises en surbrillance en jaune et la couleur de police est le plus clair.
// Run a batch operation against the Word object model.
Word.run(function (context) {
// Queue a command to search the document and ignore punctuation.
var searchResults = context.document.body.search('video you', {ignorePunct: true});
// Queue a command to load the search results and get the font property values.
context.load(searchResults, 'font');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync().then(function () {
console.log('Found count: ' + searchResults.items.length);
// Queue a set of commands to change the font for each found item.
for (var i = 0; i < searchResults.items.length; i++) {
searchResults.items[i].font.color = 'purple';
searchResults.items[i].font.highlightColor = '#FFFF00'; // Yellow
searchResults.items[i].font.bold = true;
}
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync();
});
})
.catch(function (error) {
console.log('Error: ' + JSON.stringify(error));
if (error instanceof OfficeExtension.Error) {
console.log('Debug info: ' + JSON.stringify(error.debugInfo));
}
});
Commencer à développer des compléments Word
Pour développer un complément Word, utilisez :
- Le générateur Yeoman pour compléments Office
- Visual Studio
Pour explorer les API, nous vous recommandons d’utiliser le complément Script Lab. Vous y trouvez de nombreux extraits de code TypeScript et JavaScript et pouvez expérimenter des documents Word sans créer de complément entier.
Présentation des fonctionnalités des fonctions personnalisées
Les fonctions personnalisées possèdent plusieurs fonctionnalités et restrictions uniques, car elles s’exécutent dans un runtime distinct des autres interactions de compléments, comme les volets Office.
Fonctionnalités des fonctions personnalisées
Vous pouvez créer des fonctions JavaScript ou TypeScript personnalisées pouvant être utilisées comme des fonctions Excel intégrées telles que SUM(). Vous pouvez également créer des fonctions personnalisées de diffusion en continu, qui renvoient une valeur basée sur un minuteur. Par exemple, vous pouvez mettre à jour la valeur d’heure actuelle dans une cellule toutes les secondes. Vous pouvez également effectuer des appels réseau à partir de fonctions personnalisées.
Exemple de fonction personnalisée JavaScript
L’exemple de code suivant définit la fonction personnalisée add() qui accepte deux nombres puis renvoie leur somme.
/**
* 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;
}
Description des commentaires du code JSDoc
Les balises JSDoc présentes dans les commentaires du code sont utilisées pour générer un fichier de métadonnées JSON décrivant la fonction personnalisée pour Excel. Le fichier de métadonnées JSON permet à Excel de présenter correctement les informations à un utilisateur et de transmettre les paramètres attendus à votre fonction personnalisée.
@customfunction: est déclaré en premier et indique qu’il s’agit d’une fonction personnalisée. Obligatoire.@param: décrit le paramètre. Inclus pour chaque paramètre défini par la fonction.@returns: décrit le résultat de la fonction.
Remarque
La description de commentaire « Ajoute deux nombres. » est également ajoutée au fichier de métadonnées JSON pour qu’Excel indique quand l’utilisateur affiche votre fonction personnalisée.
Restrictions du runtime des fonctions personnalisées
Le runtime de fonction personnalisée exécute uniquement JavaScript. Il n’existe pas de modèle d’objet de document (DOM) ou de stockage local, à l’inverse d’un environnement d’exécution JavaScript basé sur un navigateur. Cela signifie que vous ne pouvez pas charger de bibliothèques qui utilisent le modèle DOM, comme jQuery. Vous ne pouvez pas non plus accéder à l’API Office.js pour interagir avec le document comme vous le feriez à partir d’un volet Office. Le runtime des fonctions personnalisées est en fait optimisé pour les tâches telles que les calculs rapides, et n’a généralement pas besoin d’utiliser les API Office.js telles que les outils de mise en forme dans Excel.
Les fonctions personnalisées ont une page web qui charge le runtime des fonctions personnalisées. Le runtime des fonctions personnalisés ne possédant pas d’interface utilisateur, il n’y a rien à afficher dans la page web. La balise de script suivante apparaît dans la page web qui charge la bibliothèque pour le runtime des fonctions personnalisées.
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/custom-functions-runtime.js" type="text/javascript"></script>
En règle générale, les fonctions personnalisées sont associées à un volet Office dans le même complément. Si vous créez un projet de complément à l’aide du générateur Yeoman pour compléments Office, le projet aura une page web pour les fonctions personnalisées et une page web avec interface utilisateur pour le volet Office.
Utilisation de l’API de stockage pour communiquer avec le volet Office
Le code de fonction personnalisée et le code de volet Office (qui utilise Office.js) ne peuvent pas s’appeler ou communiquer directement entre eux. Vous pouvez cependant utiliser une API de stockage qui leur permet de partager des données. On utilise par exemple l’API de stockage lorsque le complément doit partager un jeton de sécurité pour accéder à une ressource réseau sécurisée. L’utilisateur peut d’abord appeler une fonction personnalisée qui exige une connexion. Une fois l’utilisateur authentifié, la fonction reçoit le jeton de sécurité. Elle le partage ensuite à l’aide de l’API de stockage pour que l’utilisateur, lorsqu’il ouvre le volet Office ultérieurement, n’ait pas besoin de se reconnecter.
Au lieu de cela, l’utilisateur peut commencer par ouvrir le volet Office. Dans ce cas, le volet Office connecte l’utilisateur et partage le jeton de sécurité via l’API de stockage. Lorsqu’une fonction personnalisée est utilisée ultérieurement, celle-ci peut obtenir le jeton de sécurité via l’API de stockage.
Exemple d’API de stockage
L’exemple de code suivant illustre comment stocker et récupérer une valeur créée par l’utilisateur.
/**
* @customfunction
* @description Stores a value in OfficeRuntime.storage.
* @param {any} key Key in the key-value pair you will store.
* @param {any} value Value in the key-value pair you will store.
*/
function storeValue(key, value) {
return OfficeRuntime.storage.setItem(key, value).then(function (result) {
return "Success: Item with key '" + key + "' saved to storage.";
}, function (error) {
return "Error: Unable to save item with key '" + key + "' to storage. " + error;
});
}
/**
* @customfunction
* @description Gets value from OfficeRuntime.storage.
* @param {any} key Key of item you intend to get.
*/
function getValue(key) {
return OfficeRuntime.storage.getItem(key);
}
API de boîte de dialogue
Les fonctions personnalisées possèdent leur propre API de boîte de dialogue, étant donné qu’elles ne peuvent pas accéder à l’API Office.js. Toutefois, la fonctionnalité est similaire. Le scénario le plus courant consiste à ouvrir une boîte de dialogue pour connecter un utilisateur et recevoir un jeton de sécurité.
L’exemple de code suivant montre comment afficher une boîte de dialogue web à partir d’une fonction personnalisée.
OfficeRuntime.displayWebDialog('https://myDomain/myDialog.html', {height: 30, width: 20});
Création d’un projet de fonctions personnalisées
Vous pouvez créer un projet de fonctions personnalisées en utilisant le générateur Yeoman pour compléments Office. Exécutez yo office pour démarrer le générateur, puis choisissez l’option Projet de complément Fonctions personnalisées Excel. Une fois créé, votre projet contient un dossier /src/taskpane/ pour les fichiers sources du volet Office et un dossier /src/functions pour les fichiers sources des fonctions personnalisées.
Remarque
Vous ne pouvez pas créer de projet de fonctions personnalisées dans Visual Studio.
Résumé
Dans cette unité, vous avez découvert le modèle de programmation des Compléments Office, les outils de développement et les fonctionnalités des API JavaScript Office pour Excel, Outlook et Word.