Boîtes de dialogue et barres latérales pour les modules complémentaires d'éditeurs

Pour la plupart des modules complémentaires d'éditeur, les fenêtres de boîte de dialogue et les panneaux de barre latérale sont les principales interfaces utilisateur des modules complémentaires. Les deux sont entièrement personnalisables à l'aide de HTML et CSS standards. Vous pouvez utiliser le modèle de communication client-serveur d'Apps Script pour exécuter des fonctions Apps Script lorsque l'utilisateur interagit avec la barre latérale ou la boîte de dialogue. Votre module complémentaire peut définir plusieurs barres latérales et boîtes de dialogue, mais il ne peut en afficher qu'une à la fois.

Lorsque vous souhaitez empêcher l'utilisateur d'interagir avec l'éditeur tant qu'il n'a pas fait un choix dans l'interface du module complémentaire, utilisez une boîte de dialogue. Sinon, utilisez une barre latérale.

Boîtes de dialogue

Les boîtes de dialogue sont des panneaux de fenêtre qui se superposent au contenu principal de l'éditeur. Les boîtes de dialogue Apps Script sont modales. Lorsqu'elles sont ouvertes, l'utilisateur ne peut pas interagir avec les autres éléments de l'interface de l'éditeur. Vous pouvez personnaliser le contenu et la taille des boîtes de dialogue.

Vous créez des boîtes de dialogue de module complémentaire de la même manière que les boîtes de dialogue personnalisées Apps Script. La procédure générale recommandée est la suivante:

  1. Créez un fichier de projet de script qui définit la structure HTML, le CSS et le comportement JavaScript côté client de votre boîte de dialogue. Lorsque vous définissez la boîte de dialogue, consultez les consignes de style pour les modules complémentaires de l'éditeur.
  2. Dans le code côté serveur où vous souhaitez ouvrir la boîte de dialogue, appelez HtmlService.createHtmlOutputFromFile(filename) pour créer un objet HtmlOutput représentant la boîte de dialogue. Si vous utilisez du code HTML avec modèle, vous pouvez également appeler HtmlService.createTemplateFromFile(filename) pour générer un modèle, puis HtmlTemplate.evaluate() pour le convertir en objet HtmlOutput.
  3. Appelez Ui.showModalDialog(htmlOutput, dialogTitle) pour afficher la boîte de dialogue à l'aide de HtmlOutput.

Les boîtes de dialogue ne suspendent pas le script côté serveur lorsqu'elles sont ouvertes. Le code JavaScript côté client peut effectuer des appels asynchrones côté serveur à l'aide de google.script.run() et des fonctions de gestionnaire associées. Pour en savoir plus, consultez la section Communication client-serveur.

Boîtes de dialogue d'ouverture de fichiers

Les boîtes de dialogue d'ouverture de fichier sont des boîtes de dialogue prédéfinies qui permettent à vos utilisateurs de sélectionner des fichiers dans leur Google Drive. Vous pouvez ajouter une boîte de dialogue d'ouverture de fichier à votre module complémentaire sans avoir à la concevoir, mais cela nécessite une configuration supplémentaire. Vous devez également disposer d'un accès au projet Cloud Platform du module complémentaire pour activer l'API Google Picker.

Pour en savoir plus, consultez Boîtes de dialogue d'ouverture de fichier.

Les barres latérales sont des panneaux qui s'affichent à droite de l'interface de l'éditeur. Il s'agit du type d'interface de module complémentaire le plus courant. Contrairement aux boîtes de dialogue, vous pouvez continuer à interagir avec les autres éléments de l'interface de l'éditeur lorsqu'une barre latérale est ouverte. Les barres latérales ont une largeur fixe, mais vous pouvez personnaliser leur contenu.

Vous créez des barres latérales de modules complémentaires de la même manière que les barres latérales personnalisées Apps Script. La procédure générale recommandée est la suivante:

  1. Créez un fichier de projet de script qui définit la structure HTML, le CSS et le comportement JavaScript côté client de votre barre latérale. Lorsque vous définissez la barre latérale, consultez les consignes de style pour les modules complémentaires de l'éditeur.

  2. Dans le code côté serveur où vous souhaitez ouvrir la barre latérale, appelez HtmlService.createHtmlOutputFromFile(filename) pour créer un objet HtmlOutput représentant la barre latérale. Si vous utilisez du code HTML avec modèle, vous pouvez également appeler HtmlService.createTemplateFromFile(filename) pour générer un modèle, puis HtmlTemplate.evaluate() pour le convertir en objet HtmlOutput.

  3. Appelez Ui.showSidebar(htmlOutput) pour afficher la barre latérale à l'aide de HtmlOutput.

Les barres latérales ne suspendent pas le script côté serveur lorsqu'elles sont ouvertes. Le code JavaScript côté client peut effectuer des appels asynchrones côté serveur à l'aide de google.script.run() et des fonctions de gestionnaire associées. Pour en savoir plus, consultez la section Communication client-serveur.