Créer des interfaces d'éditeur Google

Grâce aux modules complémentaires Google Workspace, vous pouvez fournir des interfaces personnalisées dans les éditeurs, y compris Google Docs, Google Sheets et Google Slides. Cela vous permet de fournir à l'utilisateur des informations pertinentes, d'automatiser des 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 s'affiche dans le panneau latéral d'accès rapide Google Workspace des interfaces utilisateur Docs, Sheets et Slides.

Un module complémentaire Google Workspace peut présenter 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 dans lequel l'utilisateur ouvre le module complémentaire, celui-ci crée et renvoie une fiche de page d'accueil spécifique à cet éditeur. Si le fichier manifeste du module complémentaire n'inclut pas le EDITOR_NAME.homepageTrigger pour l'éditeur dans lequel l'utilisateur l'ouvre, une fiche de page d'accueil générique s'affiche à la place.
Interfaces d'API REST : si le module complémentaire utilise des API REST, vous pouvez inclure des déclencheurs qui demandent un accès par fichier à un document à l'aide du champ d'application drive.file. Une fois l'accès 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 affichent un aperçu du contenu des URL de votre service.

Créer des interfaces pour les modules complémentaires d'éditeur

Pour créer des interfaces de module complémentaire d'éditeur pour les éditeurs, procédez comme suit :

Ajoutez les champs appropriés addOns.common, addOns.docs, addOns.sheets, et addOns.slides au fichier manifestedu projet de script du module complémentaire.
Ajoutez tous les champs d'application d'éditeur requis à votre fichier manifeste de projet de script.
Si vous fournissez une page d'accueil spécifique à l'éditeur, implémentez la EDITOR_NAME.homepageTrigger fonction pour créer l'interface. Sinon, utilisez l' common.homepageTrigger interface pour créer une page d'accueil commune pour vos applications hôtes.
Si vous utilisez des API REST, implémentez le drive.file flux d'autorisation du champ d'application et EDITOR_NAME.onFileScopeGrantedTrigger fonction de déclencheur pour afficher une interface spécifique au fichier ouvert. Pour en savoir plus, consultez la section Interfaces d'API REST.
Si vous configurez des aperçus de liens à partir d'un service tiers, implémentez le champ d'applicationhttps://www.googleapis.com/auth/workspace.linkpreviewflux d'autorisation et linkPreviewTriggers fonction. 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 des boutons.

Pages d'accueil de l'éditeur

Vous devez fournir une fonction de déclencheur de page d'accueil dans le projet de script de votre module complémentaire qui crée et renvoie une seule Card ou un tableau d'Card objets qui composent la page d'accueil du module complémentaire.

La fonction de déclencheur de 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 création de la page d'accueil.

Vous pouvez présenter une page d'accueil commune ou une page d'accueil 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 à l'éditeur

Pour présenter une page d'accueil spécifique à un éditeur, ajoutez le EDITOR_NAME.homepageTrigger au 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 est activé pour Docs, Sheets et Slides. Il 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 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 d'API REST

Si votre module complémentaire utilise des API REST, telles que l' API Google Sheets, vous pouvez utiliser la onFileScopeGrantedTrigger fonction pour afficher une nouvelle interface spécifique au fichier ouvert dans l'application hôte de l'éditeur.

Vous devez inclure le flux d'autorisation du champ d'application drive.file pour utiliser la fonction onFileScopeGrantedTrigger. Pour savoir comment demander le drive.file champ d'application, consultez Demander l'accès aux fichiers du document actuel.

Lorsqu'un utilisateur accorde le drive.file champ d'application, le EDITOR_NAME.onFileScopeGrantedTrigger.runFunction se déclenche. Lorsque le déclencheur se déclenche, il exécute la fonction de déclencheur contextuel spécifiée par le EDITOR_NAME.onFileScopeGrantedTrigger.runFunction champ dans le fichier manifeste du module complémentaire.

Pour créer une interface d'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 le EDITOR_NAME.onFileScopeGrantedTrigger dans la section appropriée de l'éditeur de votre fichier manifeste. Par exemple, si vous souhaitez créer cette interface dans Google Sheets, ajoutez le déclencheur à la "sheets" section.
Implémentez la fonction nommée dans la EDITOR_NAME.onFileScopeGrantedTrigger section. Cette fonction accepte un objet d' événement comme argument et doit renvoyer un seul Card objet ou un tableau d' Card objets.
Comme pour n'importe quelle fiche, vous devez implémenter les fonctions de rappel utilisées pour fournir une interactivité de widget à l'interface. Par exemple, si vous incluez un bouton dans l'interface, il doit être associé à une action et à une fonction de rappel implémentée qui s'exécute lorsque l'utilisateur clique sur le bouton.

L'exemple suivant montre la partie addons d'un fichier manifeste de module complémentaire Google Workspace. Le module complémentaire utilise des API REST. Par conséquent, onFileScopeGrantedTrigger est 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 des liens pour les services tiers

Pour activer les aperçus de liens pour un service tiers, vous devez configurer les aperçus de liens dans le fichier manifeste de votre module complémentaire et créer une fonction qui renvoie une fiche d'aperçu. Pour les services qui nécessitent une autorisation de l'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 les chips intelligents.

Objets d'événement

Un objet d'événement est créé et transmis aux fonctions de déclencheur, telles que EDITOR_NAME.homepageTrigger ou EDITOR_NAME.onFileScopeGrantedTrigger. La fonction de déclencheur utilise les informations de l'objet d'événement pour déterminer comment créer des fiches de module complémentaire ou contrôler le comportement du module complémentaire.

La structure complète des objets d'événement est décrite dans Event objects.

Lorsqu'un éditeur est l'application hôte active du module complémentaire, les objets d'événement incluent Docs, Sheets, ou Slides champs d'objet d'événement qui contiennent des informations sur le client.

Si le module complémentaire ne dispose pas de l'autorisation du champ d'application drive.file pour l'utilisateur ou le document actuel, l'objet d'événement ne contient que le champ docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission ou slides.addonHasFileScopePermission. Si le module complémentaire dispose de l'autorisation, l'objet d'événement contient tous les champs d'objet d'événement de l'éditeur.

L'exemple suivant montre un objet d'événement d'éditeur transmis à une fonction sheets.onFileScopeGrantedTrigger. Ici, le module complémentaire dispose de l'autorisation du champ d'application drive.filepour le document actuel :

{
  "commonEventObject": { ... },
  "sheets": {
    "addonHasFileScopePermission": true,
    "id":"A_24Q3CDA23112312ED52",
    "title":"How to get started with Sheets"
  },
  ...
}

Créer des interfaces d'éditeur Google Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.