Afficher ou masquer le volet des tâches de votre complément Office
Importante
Le runtime partagé est pris en charge uniquement dans certaines applications Office. Pour plus d’informations, consultez Ensembles de conditions requises pour le runtime partagé.
Vous pouvez afficher le volet Office de votre complément Office en appelant la Office.addin.showAsTaskpane() méthode .
function onCurrentQuarter() {
Office.addin.showAsTaskpane()
.then(function() {
// Code that enables task pane UI elements for
// working with the current quarter.
});
}
Le code précédent suppose un scénario où il existe une feuille de calcul Excel nommée CurrentQuarterSales. Le complément rend le volet Office visible chaque fois que cette feuille de calcul est activée. La méthode onCurrentQuarter est un gestionnaire pour l’événement Office.Worksheet.onActivated qui a été inscrit pour la feuille de calcul.
Vous pouvez également masquer le volet Office en appelant la Office.addin.hide() méthode .
function onCurrentQuarterDeactivated() {
Office.addin.hide();
}
Le code précédent est un gestionnaire inscrit pour l’événement Office.Worksheet.onDeactivated .
Détails supplémentaires sur l’affichage du volet Office
Lorsque vous appelez Office.addin.showAsTaskpane(), Office affiche dans un volet Office le fichier que vous avez affecté en tant que valeur d’ID de ressource (resid) du volet Office. Cette resid valeur peut être affectée ou modifiée en ouvrant votre fichier manifest.xml et en localisant <SourceLocation> à l’intérieur de l’élément <Action xsi:type="ShowTaskpane"> .
(Pour plus d’informations, voir Configurer votre complément Office pour utiliser un runtime partagé .)
Étant donné que Office.addin.showAsTaskpane() est une méthode asynchrone, votre code continue à s’exécuter jusqu’à ce que la méthode soit terminée. Attendez cette fin avec le await mot clé ou une then() méthode, en fonction de la syntaxe JavaScript que vous utilisez.
Configurer votre complément pour utiliser le runtime partagé
Pour utiliser les showAsTaskpane() méthodes et hide() , votre complément doit utiliser le runtime partagé. Pour plus d’informations, voir Configurer votre complément Office pour utiliser un runtime partagé.
Conservation des écouteurs d’état et d’événements
Les hide() méthodes et showAsTaskpane() modifient uniquement la visibilité du volet Office. Ils ne le déchargent pas ou ne le rechargent pas (ou ne réinitialisent pas son état).
Considérez le scénario suivant : un volet Office est conçu avec des onglets. L’onglet Accueil est ouvert lors du premier lancement du complément. Supposons qu’un utilisateur ouvre l’onglet Paramètres et, plus tard, que du code dans le volet Office appelle hide() en réponse à un événement. Appels de code showAsTaskpane() encore plus tard en réponse à un autre événement. Le volet Office réapparaît et l’onglet Paramètres est toujours sélectionné.
En outre, tous les écouteurs d’événements inscrits dans le volet Office continuent de s’exécuter même lorsque le volet Office est masqué.
Prenons l’exemple suivant : le volet Office dispose d’un gestionnaire inscrit pour Excel Worksheet.onActivated et Worksheet.onDeactivated d’événements pour une feuille nommée Sheet1. Le gestionnaire activé fait apparaître un point vert dans le volet Office. Le gestionnaire désactivé transforme le point en rouge (qui est son état par défaut). Supposons que le code appelle hide() quand Sheet1 n’est pas activé et que le point est rouge. Lorsque le volet Office est masqué, Sheet1 est activé. Appels de code showAsTaskpane() ultérieurs en réponse à un événement. Lorsque le volet Office s’ouvre, le point est vert, car les écouteurs et gestionnaires d’événements ont été exécutés même si le volet Office était masqué.
Gérer l’événement de changement de visibilité
Lorsque votre code modifie la visibilité du volet Office avec showAsTaskpane() ou hide(), Office déclenche l’événement VisibilityModeChanged . Il peut être utile de gérer cet événement. Par exemple, supposons que le volet Office affiche une liste de toutes les feuilles d’un classeur. Si une nouvelle feuille de calcul est ajoutée alors que le volet Office est masqué, le fait de le rendre visible ne permet pas, en soi, d’ajouter le nouveau nom de feuille de calcul à la liste. Mais votre code peut répondre à l’événement VisibilityModeChanged pour recharger la propriété Worksheet.name de toutes les feuilles de calcul de la collection Workbook.worksheets , comme illustré dans l’exemple de code ci-dessous.
Pour inscrire un gestionnaire pour l’événement, vous n’utilisez pas de méthode « ajouter un gestionnaire » comme vous le feriez dans la plupart des contextes JavaScript Office. Au lieu de cela, il existe une fonction spéciale à laquelle vous transmettez votre gestionnaire : Office.addin.onVisibilityModeChanged. Voici un exemple. Notez que la args.visibilityMode propriété est de type VisibilityMode.
Office.addin.onVisibilityModeChanged(function(args) {
if (args.visibilityMode == "Taskpane") {
// Code that runs whenever the task pane is made visible.
// For example, an Excel.run() that loads the names of
// all worksheets and passes them to the task pane UI.
}
});
La fonction retourne une autre fonction qui annule l’inscription du gestionnaire. Voici un exemple simple, mais pas robuste.
const removeVisibilityModeHandler =
Office.addin.onVisibilityModeChanged(function(args) {
if (args.visibilityMode == "Taskpane") {
// Code that runs whenever the task pane is made visible.
}
});
// In some later code path, deregister with:
removeVisibilityModeHandler();
La onVisibilityModeChanged méthode est asynchrone et retourne une promesse, ce qui signifie que votre code doit attendre la réalisation de la promesse avant de pouvoir appeler le gestionnaire de désinscription .
// await the promise from onVisibilityModeChanged and assign
// the returned deregister handler to removeVisibilityModeHandler.
const removeVisibilityModeHandler =
await Office.addin.onVisibilityModeChanged(function(args) {
if (args.visibilityMode == "Taskpane") {
// Code that runs whenever the task pane is made visible.
}
});
La fonction de désinscription est également asynchrone et retourne une promesse. Par conséquent, si vous avez du code qui ne doit pas s’exécuter tant que la désinscription n’est pas terminée, vous devez attendre la promesse retournée par la fonction de désinscription.
// await the promise from the deregister handler before continuing
await removeVisibilityModeHandler();
// subsequent code here