Com os complementos do Google Workspace, você pode fornecer interfaces personalizadas nos Editores, incluindo Documentos, Planilhas e Apresentações Google. Isso permite fornecer ao usuário informações relevantes, automatizar tarefas e conectar sistemas de terceiros aos editores.
Como acessar a IU do complemento
Você pode abrir um complemento do Google Workspace nos Editores se o ícone dele aparecer no painel lateral de acesso rápido do Google Workspace, no lado direito das interfaces do usuário dos Documentos, Planilhas e Apresentações.
Um complemento do Google Workspace pode apresentar as seguintes interfaces:
Interfaces da página inicial: se o manifesto do complemento incluir o gatilho
EDITOR_NAME.homepageTrigger
para o editor em que o usuário o abre, o complemento cria e retorna um card da página inicial especificamente para esse editor. Se o manifesto do complemento não incluir oEDITOR_NAME.homepageTrigger
para o editor em que o usuário o abre, um card genérico da página inicial será exibido.Interfaces da API REST: se o complemento usar APIs REST, será possível incluir acionadores que solicitam acesso por arquivo a um documento usando o escopo
drive.file
. Depois de concedido, outro gatilho chamadoEDITOR_NAME.onFileScopeGrantedTrigger
é executado e mostra uma interface específica para o arquivo.Interfaces de visualização de links: se o complemento se integrar a um serviço de terceiros, você poderá criar cards que mostrem uma prévia do conteúdo dos URLs do serviço.
Como criar interfaces para complementos do Editor
Crie interfaces de complementos do editor para os editores seguindo estas etapas:
- Adicione os campos
addOns.common
,addOns.docs
,addOns.sheets
eaddOns.slides
adequados ao manifesto do projeto de script de complemento. - Adicione os escopos do editor necessários ao manifesto do projeto de script.
- Se você estiver fornecendo uma página inicial específica do editor,
implemente a função
EDITOR_NAME.homepageTrigger
para criar a interface. Caso contrário, use a interfacecommon.homepageTrigger
para criar uma página inicial comum para seus apps de host. - Se você usar APIs REST, implemente o fluxo de autorização do escopo
drive.file
e a função de acionamentoEDITOR_NAME.onFileScopeGrantedTrigger
para exibir uma interface específica para o arquivo aberto. Para mais informações, consulte Interfaces da API REST. - Se você estiver configurando visualizações de links de um serviço de terceiros, implemente o fluxo de autorização do escopo
https://www.googleapis.com/auth/workspace.linkpreview
e a funçãolinkPreviewTriggers
. Para saber mais, consulte Interfaces de visualização de links. - Implemente as funções de callback associadas e necessárias para responder às interações da IU do usuário, como cliques em botões.
Páginas iniciais dos editores
Forneça uma função de gatilho da página inicial no projeto de script do complemento
que crie e retorne um único Card
ou uma matriz de objetos Card
que compõem a página inicial do complemento.
A função de acionador da página inicial recebe um objeto de evento como um parâmetro que contém informações, como a plataforma do cliente. É possível 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 uma página inicial específica para o Editor em que o usuário abre o complemento.
Exibir a página inicial comum
Para mostrar a página inicial comum do complemento nos Editores, inclua os campos
do Editor apropriados, como addOns.docs
,
addOns.sheets
ou addOns.slides
,
no manifesto do complemento.
O exemplo a seguir mostra a parte addons
de um manifesto de complemento do Google Workspace. O complemento estende os Documentos, as Planilhas e as Apresentações e mostra a página inicial
comum 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": {} } }
Exibir uma página inicial específica para o editor
Para apresentar uma página inicial específica para um editor, adicione o EDITOR_NAME.homepageTrigger
ao manifesto do
complemento.
O exemplo a seguir mostra a parte addons
de um manifesto de complemento do Google Workspace.
O complemento está ativado para os Documentos, as Planilhas e as Apresentações. Ele exibe a página inicial comum no Documentos e no Apresentações e uma página inicial exclusiva no Planilhas. A função de callback onSheetsHomepage
cria o card da página inicial específico do app Planilhas.
"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 usa APIs REST, como a API Google Sheets,
você pode usar a função onFileScopeGrantedTrigger
para exibir uma nova interface
específica para o arquivo que está aberto no app host do Editor.
É necessário incluir o fluxo de autorização do escopo drive.file
para usar a
função onFileScopeGrantedTrigger
. Para saber como solicitar o escopo drive.file
, consulte Solicitar acesso ao arquivo para o documento atual.
Quando um usuário concede o escopo drive.file
, o
EDITOR_NAME.onFileScopeGrantedTrigger.runFunction
é disparado. Quando o acionador é disparado, ele executa a função do acionador contextual
especificada pelo campo EDITOR_NAME.onFileScopeGrantedTrigger.runFunction
no
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ê quer
usar, por exemplo, sheets.onFileScopeGrantedTrigger
.
- Inclua o
EDITOR_NAME.onFileScopeGrantedTrigger
na seção do editor adequada do manifesto. Por exemplo, se você quiser criar essa interface nas Planilhas Google, adicione o gatilho à seção"sheets"
. - Implemente a função nomeada na seção
EDITOR_NAME.onFileScopeGrantedTrigger
. Essa função aceita um objeto de evento como argumento e precisa retornar um único objetoCard
ou uma matriz de objetosCard
. - Como acontece com qualquer card, é necessário implementar as funções de callback usadas para oferecer interatividade do widget para a interface. Por exemplo, se você incluir um botão na interface, ele precisará ter uma Action anexada e uma função de callback implementada, que será executada quando o botão for clicado.
O exemplo a seguir mostra a parte addons
de um manifesto de complemento do Google Workspace.
O complemento usa APIs REST, então o onFileScopeGrantedTrigger
está incluído nas 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 links em um serviço de terceiros, configure essas visualizações no manifesto do complemento e crie uma função que retorne um card de visualização. Para serviços que exigem autorização do usuário, sua função também precisa invocar o fluxo de autorização.
Confira as etapas para ativar as visualizações de links em Visualizar links com ícones inteligentes.
Objetos de evento
Um objeto de evento é criado e transmitido para acionar funções, como
EDITOR_NAME.homepageTrigger
ou EDITOR_NAME.onFileScopeGrantedTrigger
. A função de acionamento usa as informações no
objeto de evento para determinar como criar cartões de complementos ou controlar o
comportamento do complemento.
A estrutura completa dos objetos de evento é descrita em Objetos de evento.
Quando um Editor é o app host de atuação do complemento, os objetos de evento incluem campos do objeto de evento Documentos, Planilhas ou Apresentações que transportam informações do cliente.
Se o complemento não tiver autorização de escopo drive.file
para o usuário
ou documento atual, o objeto de evento conterá apenas o campo
docs.addonHasFileScopePermission
, sheets.addonHasFileScopePermission
ou
slides.addonHasFileScopePermission
. Se o complemento tiver autorização, o objeto de evento conterá todos os campos do objeto de evento do Editor.
O exemplo a seguir mostra um objeto de evento do Editor que é transmitido para uma função sheets.onFileScopeGrantedTrigger
. Aqui, o complemento tem a
autorização do escopo drive.file
para o documento atual:
` { "commonEventObject": { ... }, "sheets": { "addonHasFileScopePermission": true, "id":"A_24Q3CDA23112312ED52", "title":"How to get started with Sheets" }, ... }