Créer des interfaces Google Editor

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Les modules complémentaires Google Workspace vous permettent de 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 Google Workspace situé à droite des interfaces utilisateur Docs, Sheets et Slides.

Un module complémentaire Google Workspace peut présenter les interfaces suivantes:

  • Interfaces de la 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 est compilé et renvoie une fiche de page d'accueil spécifique à cet éditeur. Si le fichier manifeste du module complémentaire n'inclut pas 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 de l'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 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 (aperçu développeur): si votre module complémentaire s'intègre à un service tiers, vous pouvez créer des fiches qui prévisualisez le contenu à partir des URL de votre service.

Créer des interfaces pour les modules complémentaires Editor

Pour créer des interfaces complémentaires pour les éditeurs, procédez comme suit:

  1. Ajoutez les champs addOns.common, addOns.docs, addOns.sheets et addOns.slides appropriés au projet de script du module complémentaire manifest.
  2. Ajoutez les champs d'application d'éditeur requis au fichier manifeste de votre projet de script.
  3. Si vous fournissez une page d'accueil spécifique à Editor, implémentez la fonction EDITOR_NAME.homepageTrigger pour créer l'interface. Si ce n'est pas le cas, utilisez l'interface common.homepageTrigger afin de créer une page d'accueil commune pour vos applications hôtes.
  4. Si vous utilisez les API REST, implémentez le flux d'autorisation du champ d'application drive.file et la fonction de déclenchement EDITOR_NAME.onFileScopeGrantedTrigger pour afficher une interface spécifique au fichier ouvert. Pour en savoir plus, consultez la section Interfaces de l'API REST.
  5. Si vous configurez les aperçus de lien à partir d'un service tiers, implémentez le flux d'autorisation du champ d'application https://www.googleapis.com/auth/documents.readonly et la fonction linkPreviewTriggers. Pour en savoir plus, consultez la section Interfaces d'aperçu des liens.
  6. Implémentez les fonctions de rappel associées requises pour répondre aux interactions de l'UI de l'utilisateur, telles que les clics sur un bouton.

Pages d'accueil des éditeurs

Vous devez fournir une fonction de déclenchement de la page d'accueil dans le projet de script de votre module complémentaire, qui compile et renvoie un seul objet Card ou un tableau d'objets Card qui constituent la page d'accueil du module complémentaire.

La fonction du 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 d'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 courante

Pour afficher la page d'accueil courante de votre module complémentaire dans les éditeurs, incluez les champs appropriés de l'éditeur, 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 les fonctionnalités de Docs, Sheets et Slides, et affiche la page d'accueil courante 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 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 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.

Vous devez inclure le flux d'autorisation du champ d'application drive.file pour utiliser la fonction onFileScopeGrantedTrigger. Pour savoir comment demander le champ d'application drive.file, consultez Demander l'accès au 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 activé, il exécute la fonction de déclenchement 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, suivez les étapes ci-dessous. Remplacez EDITOR_NAME par l'application hôte Editor que vous choisissez d'utiliser, par exemple sheets.onFileScopeGrantedTrigger.

  1. 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 section "sheets".
  2. Implémentez la fonction nommée dans la section EDITOR_NAME.onFileScopeGrantedTrigger. Cette fonction accepte un objet événement en tant qu'argument et doit renvoyer un seul objet Card ou un tableau d'objets Card.
  3. Comme pour toute fiche, vous devez implémenter les fonctions de rappel permettant d'interagir avec les widgets. 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 montre la partie addons d'un fichier manifeste de module complémentaire Google Workspace. Le module complémentaire utilise les API REST. Le fichier onFileScopeGrantedTrigger est donc inclus pour 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"
     }
   }

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 fiche 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 des liens, consultez Prévisualiser les liens dans Google Docs (aperçu pour les développeurs).

Objets d'événement

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

La structure complète des objets d'événement est décrite dans la section Objets d'événement.

Lorsqu'un éditeur est l'application hôte 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 sur les clients.

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 Editor qui est 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"
          },
          ...
        }