Avec les modules complémentaires Google Workspace, vous pouvez fournir des interfaces personnalisées dans les éditeurs, y compris Google Docs, Sheets et Slides. Cela vous permet de fournir à l'utilisateur des informations pertinentes, d'automatiser les tâches et de connecter des systèmes tiers aux éditeurs.
Accéder à l'interface utilisateur du module complémentaire
Vous pouvez ouvrir un module complémentaire Google Workspace dans les éditeurs si son icône apparaît dans le panneau latéral d'accès rapide de Google Workspace, à droite des interfaces utilisateur de Docs, Sheets et Slides.
Un module complémentaire Google Workspace peut utiliser les interfaces suivantes:
Interfaces de page d'accueil: si le fichier manifeste du module complémentaire inclut le déclencheur
EDITOR_NAME.homepageTrigger
pour l'éditeur, l'utilisateur ouvre le module complémentaire, le module complémentaire crée et renvoie une fiche d'accueil propre à cet éditeur. Si le fichier manifeste du module complémentaire n'inclut pas leEDITOR_NAME.homepageTrigger
de l'éditeur dans lequel l'utilisateur l'ouvre, une fiche générique de la page d'accueil s'affiche.Interfaces API REST: si le module complémentaire utilise des API REST, vous pouvez inclure des déclencheurs qui demandent l'accès par fichier à un document à l'aide du champ d'application
drive.file
. Une fois accordé, un autre déclencheur appeléEDITOR_NAME.onFileScopeGrantedTrigger
s'exécute et affiche une interface spécifique au fichier.Interfaces d'aperçu des liens: si votre module complémentaire s'intègre à un service tiers, vous pouvez créer des fiches qui prévisualisent le contenu à partir des URL de votre service.
Créer des interfaces pour les modules complémentaires des éditeurs
Créez des interfaces de module complémentaire de l'éditeur pour les éditeurs en procédant comme suit:
- Ajoutez les champs
addOns.common
,addOns.docs
,addOns.sheets
etaddOns.slides
appropriés au fichier manifeste du script de module complémentaire. - Ajoutez les champs d'application d'éditeur requis au fichier manifeste de votre projet de script.
- Si vous fournissez une page d'accueil spécifique à l'éditeur, implémentez la fonction
EDITOR_NAME.homepageTrigger
pour créer l'interface. Si ce n'est pas le cas, utilisez l'interfacecommon.homepageTrigger
pour créer une page d'accueil commune pour vos applications hôtes. - Si vous utilisez des API REST, implémentez le flux d'autorisation du champ d'application
drive.file
et la fonction de déclencheurEDITOR_NAME.onFileScopeGrantedTrigger
pour afficher une interface spécifique au fichier ouvert. Pour en savoir plus, consultez la section Interfaces API REST. - Si vous configurez des aperçus de lien à partir d'un service tiers, implémentez le flux d'autorisation du champ d'application
https://www.googleapis.com/auth/workspace.linkpreview
et la fonctionlinkPreviewTriggers
. Pour en savoir plus, consultez la section Interfaces d'aperçu des liens. - Implémentez les fonctions de rappel associées nécessaires pour répondre aux interactions de l'utilisateur avec l'interface utilisateur, telles que les clics sur les boutons.
Pages d'accueil de l'éditeur
Dans le projet de script de votre module complémentaire, vous devez fournir une fonction de déclencheur de page d'accueil. Celle-ci compile et renvoie un seul Card
ou un tableau d'objets Card
qui constituent la page d'accueil du module complémentaire.
La fonction de déclenchement de la page d'accueil reçoit un objet d'événement en tant que paramètre contenant des informations telles que la plate-forme du client. Vous pouvez utiliser les données de l'objet d'événement pour personnaliser la construction de la page d'accueil.
Vous pouvez présenter une page d'accueil commune ou spécifique à l'éditeur dans lequel l'utilisateur ouvre votre module complémentaire.
Afficher la page d'accueil commune
Pour afficher la page d'accueil commune de votre module complémentaire dans les éditeurs, incluez les champs d'éditeur appropriés, tels que addOns.docs
, addOns.sheets
ou addOns.slides
, dans le fichier manifeste du module complémentaire.
L'exemple suivant montre la partie addons
d'un fichier manifeste de module complémentaire Google Workspace. Le module complémentaire étend Docs, Sheets et Slides, et affiche la page d'accueil commune dans chaque application hôte.
"addOns": { "common": { "name": "Translate", "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png", "layoutProperties": { "primaryColor": "#2772ed" }, "homepageTrigger": { "runFunction": "onHomepage" } }, "docs": {}, "sheets": {}, "slides": {} } }
Afficher une page d'accueil spécifique à Editor
Pour présenter une page d'accueil spécifique à un éditeur, ajoutez EDITOR_NAME.homepageTrigger
au fichier manifeste du module complémentaire.
L'exemple suivant présente la partie addons
d'un fichier manifeste de module complémentaire Google Workspace.
Le module complémentaire est activé pour Docs, Sheets et Slides. Elle affiche la page d'accueil commune dans Docs et Slides, et une page d'accueil unique dans Sheets. La fonction de rappel onSheetsHomepage
crée la fiche de la page d'accueil spécifique à Sheets.
"addOns": { "common": { "name": "Translate", "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png", "layoutProperties": { "primaryColor": "#2772ed" }, "homepageTrigger": { "runFunction": "onHomepage" } }, "docs": {}, "slides": {}, "sheets": { "homepageTrigger": { "runFunction": "onSheetsHomepage" }, } }
Interfaces de l'API REST
Si votre module complémentaire utilise des API REST, telles que l'API Google Sheets, vous pouvez utiliser la fonction onFileScopeGrantedTrigger
pour afficher une nouvelle interface spécifique au fichier ouvert dans l'application hôte Editor.
Pour utiliser la fonction onFileScopeGrantedTrigger
, vous devez inclure le flux d'autorisation du champ d'application drive.file
. Pour savoir comment demander le champ d'application drive.file
, consultez Demander l'accès à un fichier pour le document actuel.
Lorsqu'un utilisateur accorde le champ d'application drive.file
, EDITOR_NAME.onFileScopeGrantedTrigger.runFunction
se déclenche. Lorsque le déclencheur est exécuté, il exécute la fonction de déclencheur contextuel spécifiée par le champ EDITOR_NAME.onFileScopeGrantedTrigger.runFunction
du fichier manifeste du module complémentaire.
Pour créer une interface API REST pour l'un des éditeurs, procédez comme suit :
Remplacez EDITOR_NAME
par l'application hôte de l'éditeur que vous choisissez d'utiliser, par exemple sheets.onFileScopeGrantedTrigger
.
- Incluez
EDITOR_NAME.onFileScopeGrantedTrigger
dans la section de l'éditeur appropriée de votre fichier manifeste. Par exemple, si vous souhaitez créer cette interface dans Google Sheets, ajoutez le déclencheur à la section"sheets"
. - Implémentez la fonction nommée dans la section
EDITOR_NAME.onFileScopeGrantedTrigger
. Cette fonction accepte un objet d'événement comme argument et doit renvoyer un seul objetCard
ou un tableau d'objetsCard
. - Comme pour toute fiche, vous devez implémenter les fonctions de rappel utilisées pour fournir l'interactivité des widgets à l'interface. Par exemple, si vous incluez un bouton dans l'interface, celui-ci doit être associé à une action et à une fonction de rappel implémentée qui s'exécute lorsque l'utilisateur clique dessus.
L'exemple suivant présente la partie addons
d'un fichier manifeste de module complémentaire Google Workspace.
Le module complémentaire utilise des API REST. onFileScopeGrantedTrigger
est donc inclus pour Google Sheets. Lorsqu'un utilisateur accorde le champ d'application drive.file
, la fonction de rappel onFileScopeGrantedSheets
crée une interface spécifique au fichier.
"addOns": { "common": { "name": "Productivity add-on", "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png", "layoutProperties": { "primaryColor": "#669df6", "secondaryColor": "#ee675c" } }, "sheets": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedSheets" } }
Interfaces d'aperçu d'association pour des services tiers
Pour activer les aperçus des liens pour un service tiers, vous devez configurer les aperçus des liens dans le fichier manifeste de votre module complémentaire et créer une fonction qui renvoie une carte d'aperçu. Pour les services qui nécessitent une autorisation utilisateur, votre fonction doit également appeler le flux d'autorisation.
Pour savoir comment activer les aperçus de liens, consultez Prévisualiser les liens avec des chips intelligents.
Objets événement
Un objet événement est créé et transmis à des fonctions de déclenchement, telles que EDITOR_NAME.homepageTrigger
ou EDITOR_NAME.onFileScopeGrantedTrigger
. La fonction de déclencheur utilise les informations de l'objet événement pour déterminer comment créer des cartes complémentaires ou contrôler leur comportement.
La structure complète des objets d'événement est décrite dans la section Objets événement.
Lorsqu'un éditeur est l'application hôte en cours d'exécution du module complémentaire, les objets d'événement incluent des champs d'objet d'événement Docs, Sheets ou Slides, qui contiennent des informations client.
Si le module complémentaire ne dispose pas d'une autorisation de champ d'application drive.file
pour l'utilisateur ou le document actuel, l'objet événement ne contient que le champ docs.addonHasFileScopePermission
, sheets.addonHasFileScopePermission
ou slides.addonHasFileScopePermission
. Si le module complémentaire dispose d'une autorisation, l'objet événement contient tous les champs d'objet d'événement Editor.
L'exemple suivant montre un objet d'événement Éditeur transmis à une fonction sheets.onFileScopeGrantedTrigger
. Ici, le module complémentaire dispose de l'autorisation de champ d'application drive.file
pour le document actuel:
` { "commonEventObject": { ... }, "sheets": { "addonHasFileScopePermission": true, "id":"A_24Q3CDA23112312ED52", "title":"How to get started with Sheets" }, ... }