Esta página foi traduzida pela API Cloud Translation.

Como criar interfaces dos Editores do Google

Com os complementos do Google Workspace, você tem interfaces personalizadas nos Editores, incluindo Documentos, Planilhas e Apresentações Google. Isso permite que você forneça ao usuário informações relevantes, automatizar tarefas e conectar sistemas de terceiros ao Editores.

Como acessar a interface do complemento

Você pode abrir um complemento do Google Workspace nos Editores se o ícone aparecer no menu rápido do Google Workspace acessar o painel lateral no lado direito do usuário do Documentos, Planilhas e Apresentações. do Google Cloud.

Um complemento do Google Workspace pode apresentar as seguintes interfaces:

Interfaces da página inicial: se o manifesto do complemento inclui o gatilho EDITOR_NAME.homepageTrigger para o editor em que o usuário abre o complemento dos complementos e retorna uma card da página inicial especificamente para desse Editor. Se o manifesto do complemento não incluir o EDITOR_NAME.homepageTrigger para o editor que o usuário abre um card de página inicial genérica será exibido.
Interfaces da API REST: se o complemento usa REST APIs, é possível incluir gatilhos que solicitam acesso por arquivo a um documento usando o escopo drive.file. Depois de concedido, outro gatilho chamado EDITOR_NAME.onFileScopeGrantedTrigger executa e exibe uma interface específica para o arquivo.
Interfaces de visualização de links: se o complemento integra-se com um serviço de terceiros, é possível criar cartões que pré- conteúdo dos URLs do seu serviço.

Como criar interfaces para complementos do Editor

Crie interfaces do complemento do editor para os editores seguindo estas etapas:

Adicione o addOns.common, addOns.docs, addOns.sheets, e addOns.slides no manifesto do projeto de script de complementos.
Adicione os escopos do Editor necessários ao manifesto do projeto de script.
Se você fornecer uma página inicial específica do editor, implementar EDITOR_NAME.homepageTrigger para criar a interface. Caso contrário, use o método common.homepageTrigger do aplicativo para criar uma página inicial comum para seus apps host.
Se você usa APIs REST, implemente o fluxo de autorização do escopo drive.file. e EDITOR_NAME.onFileScopeGrantedTrigger função gatilho para exibir uma interface específica para o arquivo aberto. Para mais Para mais informações, consulte Interfaces da API REST.
Se você estiver configurando visualizações de links de um serviço de terceiros, implemente no fluxo de autorização do escopo https://www.googleapis.com/auth/workspace.linkpreview linkPreviewTriggers função. Para mais informações, consulte Vincular interfaces de visualização.
Implementar as funções de callback associadas necessárias para responder ao comando Interações da interface, como cliques em botões.

Páginas iniciais do editor

Você precisa fornecer uma função de gatilho de página inicial no projeto de script do seu complemento que cria e retorna uma única Card ou uma matriz de objetos Card que compõem a página inicial do complemento.

A função do acionador da página inicial recebe um objeto de evento. como um parâmetro que contém informações como a plataforma do cliente. Você pode usar os dados do objeto de evento para personalizar a construção da página inicial.

Você pode apresentar uma página inicial comum ou específica do Editor. quando o usuário abrir o complemento.

Mostrar a página inicial comum

Para mostrar a página inicial comum do seu complemento nos Editores, inclua as informações Campos do editor, como addOns.docs, addOns.sheets, ou addOns.slides, no manifesto do complemento.

O exemplo a seguir mostra a parte addons de um complemento do Google Workspace manifesto do aplicativo. O complemento estende o Documentos, o Planilhas e o Apresentações e mostra os recursos comuns em cada app host.

 "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": {}
  }
}

Mostrar uma página inicial específica do editor

Para apresentar uma página inicial específica a um editor, adicione o EDITOR_NAME.homepageTrigger ao complemento manifesto do aplicativo.

O exemplo a seguir mostra a parte addons de um manifesto de complementos do Google Workspace. O complemento está ativado para os apps Documentos, Planilhas e Apresentações. Ele mostra as vulnerabilidades uma página inicial nos apps Documentos e Apresentações e uma página inicial exclusiva no Planilhas. A chamada de retorno onSheetsHomepage cria o card da página inicial específico do Planilhas Google.

 "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 da API REST

Se o complemento usar APIs REST, como a API Google Sheets, use a função onFileScopeGrantedTrigger para mostrar uma nova interface específico para o arquivo aberto no aplicativo host Editor.

É necessário incluir o fluxo de autorização do escopo drive.file para usar o função onFileScopeGrantedTrigger. Para saber como solicitar a drive.file escopo, consulte Solicitar acesso ao arquivo para o documento atual.

Quando um usuário concede o escopo drive.file, o EDITOR_NAME.onFileScopeGrantedTrigger.runFunction fogueiras Quando o gatilho é disparado, ele executa a função de gatilho contextual especificado pelo campo EDITOR_NAME.onFileScopeGrantedTrigger.runFunction na manifesto do complemento.

Para criar uma interface da API REST para um dos editores, siga as etapas abaixo. Substitua EDITOR_NAME pelo app host do Editor que você escolher. use, por exemplo, sheets.onFileScopeGrantedTrigger.

Inclua o EDITOR_NAME.onFileScopeGrantedTrigger na seção "Editor" apropriada do manifesto. Por exemplo, se você quiser criar esta interface no Planilhas Google, adicione o gatilho a seção "sheets".
Implemente a função nomeada no EDITOR_NAME.onFileScopeGrantedTrigger. nesta seção. Essa função aceita um objeto de evento como argumento e precisa retornar um único Card objeto ou uma matriz de objetos Card.
Como acontece com qualquer cartão, é necessário implementar as funções de callback usadas para fornecer com interatividade de widgets na interface. Por exemplo, se você incluir um botão na interface, ela deve ter uma Action anexada e uma função de callback implementada que é executada quando o botão é clicado.

O exemplo a seguir mostra a parte addons de um manifesto de complementos do Google Workspace. O complemento usa APIs REST, então o onFileScopeGrantedTrigger é incluído para Planilhas Google. Quando um usuário concede o escopo drive.file, a função de callback onFileScopeGrantedSheets cria uma interface específica do arquivo.

"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 de visualização de links para serviços de terceiros

Para ativar as visualizações de link em um serviço de terceiros, configure o link visualizações no manifesto do seu complemento e criar uma função que retorne uma visualização carda. Para serviços que exigem autorização do usuário, sua função também precisa invocar no fluxo de autorização.

Para conferir as etapas para ativar as visualizações de links, consulte Acesse a prévia de links com ícones inteligentes.

Objetos de evento

Um objeto de evento é criado e passado para acionar funções, como EDITOR_NAME.homepageTrigger ou EDITOR_NAME.onFileScopeGrantedTrigger. A função de gatilho usa as informações objeto de evento para determinar como construir cartões complementares ou de outra forma controlar o do complemento.

A estrutura completa dos objetos de evento é descrita em Objetos de evento.

Quando um Editor é o aplicativo host de ação do complemento, os objetos de evento incluem Documentos, Planilhas ou Apresentações campos de objeto de evento que transportam as informações do cliente.

Se o complemento não tiver a autorização do escopo drive.file para o usuário atual ou documento, o objeto de evento terá apenas o docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission ou slides.addonHasFileScopePermission. Se o complemento tiver autorização, o objeto de evento contém todos os campos de objeto de evento do Editor.

O exemplo a seguir mostra um objeto de evento Editor que é passado para um função sheets.onFileScopeGrantedTrigger. Aqui, o complemento tem Autorização do escopo do drive.file para o documento atual:

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