Os complementos do Google Workspace podem fornecer interfaces personalizadas quando o usuário está usando o Google Drive. Isso permite que você forneça ao usuário mais informações relevantes, automatize tarefas e conecte sistemas de terceiros ao Google Drive.
Como acessar a IU do complemento
Você poderá abrir um complemento do Google Workspace no Google Drive se o ícone dele aparecer na coluna de ícones no lado direito da interface do usuário do Drive. Um complemento do Google Workspace pode definir uma interface de página inicial, uma interface de seleção de item ou ambas:
- Se um usuário clicar no ícone do complemento no Google Drive,
o complemento executará
a função
drive.homepageTrigger
correspondente (se houver). Essa função cria e retorna um card da página inicial ao Google Drive para exibição. Se nenhuma funçãodrive.homepageTrigger
for definida, um card genérico de página inicial vai ser mostrado. - Se o usuário selecionar um ou mais itens no Google Drive e clicar no ícone de complemento
ou selecionar itens enquanto o complemento estiver aberto, o complemento executará a função contextual
drive.onItemsSelectedTrigger
correspondente (se houver). Essa função cria a interface contextual "itens selecionados" do Google Drive do complemento e a retorna ao Google Drive para exibição.
Como criar a interface do complemento do Drive
Você pode criar interfaces que ampliem o Google Drive seguindo estas etapas gerais:
- Decida se você quer que seu complemento tenha uma página inicial específica do Drive. Decida também se você quer oferecer uma interface contextual para quando o usuário selecionar itens do Drive.
- Adicione os campos
addOns.common
eaddOns.drive
apropriados ao manifesto do projeto de script de complemento, incluindo todos os escopos do Drive necessários. - Se você estiver fornecendo uma página inicial específica do Drive, implemente a função
drive.homepageTrigger
para criar essa interface. Também é possível usar a interfacecommon.homepageTrigger
para vários hosts do Google Workspace. - Se você estiver fornecendo uma interface de seleção de itens contextuais do Drive, será necessário
implementar uma função de gatilho contextual
drive.onItemsSelectedTrigger
para criar essa interface. Consulte a página Interface contextual do Drive para os itens selecionados para ver mais detalhes. - 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 do Drive
O Google Drive permite a exibição de páginas iniciais
do complemento do Google Workspace.
Para mostrar a página inicial comum do complemento no Google Drive, verifique se há
um campo addOns.drive
no manifesto do complemento.
Se preferir, adicione um
drive.homepageTrigger
ao manifesto do complemento para fornecer uma página inicial específica do Drive.
Em ambos os casos, é necessário fornecer o nome de uma função de gatilho da página inicial no
projeto de script do complemento. Essa função é chamada automaticamente para criar a
página inicial do Drive quando necessário. Implemente essa função para criar e
retornar um único
Card
ou uma matriz de
objetos Card
que compõem a página inicial. A função de acionador da página inicial recebe um
objeto de evento
como um parâmetro que contém algumas informações gerais, como a plataforma
do cliente. Use os dados do objeto de evento para personalizar a construção da página inicial.
Interface contextual do Drive para itens selecionados
O Google Drive usa um acionador contextual para determinar qual interface
(se houver) será exibida quando o usuário selecionar um ou mais itens do Google Drive. Quando o
acionador é disparado, ele executa a função de acionador contextual especificada pelo campo
drive.onItemsSelectedTrigger.runFunction
no manifesto do complemento.
Para criar uma interface de seleção contextual de itens para o Drive, faça o seguinte:
Verifique se o manifesto do complemento inclui o escopo
https://www.googleapis.com/auth/drive.addons.metadata.readonly
Verifique se o manifesto inclui uma seção
drive.onItemsSelectedTrigger
.Implemente a função nomeada no campo
drive.onItemsSelectedTrigger
. 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 qualquer função de callback usada para fornecer 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.
Objetos de evento
Um objeto de evento é criado e transmitido
para a função de gatilho drive.homepageTrigger
ou drive.onItemsSelectedTrigger
quando essas funções são chamadas. A função de acionamento pode usar as informações nesse 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 o Drive é o app host de ação do complemento, os objetos de evento contextuais incluem o campo Objeto de evento do Drive que carrega informações do cliente específicas do Drive.
Os objetos de evento do Drive contextuais para acionadores de seleção de itens incluem informações sobre os itens que o usuário selecionou quando o acionador é disparado. Quando um usuário seleciona mais de um item no Drive, um deles é considerado um dos principais interesses. Esse item é chamado de item de cursor ativo.
O exemplo a seguir mostra um
objeto de evento do Drive
que é transmitido para uma
função
drive.onItemsSelectedTrigger
:
{
"commonEventObject": { ... },
"drive": {
"activeCursorItem":{
"addonHasFileScopePermission": true,
"id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
"iconUrl": "https://drive-thirdparty.googleusercontent.com...",
"mimeType":"application/pdf",
"title":"How to get started with Drive"
},
"selectedItems": [
{
"addonHasFileScopePermission": true,
"id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
"iconUrl":"https://drive-thirdparty.googleusercontent.com...",
"mimeType":"application/pdf",
"title":"How to get started with Drive"
},
...
]
},
...
}