Criar interfaces do Google Drive

Os complementos do Google Workspace podem oferecer interfaces personalizadas quando um usuário abre o Drive. Assim, você pode fornecer ao usuário mais informações relevantes, automatizar tarefas e conectar sistemas de terceiros ao Drive.

Acessar a interface do complemento do Google Workspace

Abra o complemento no Drive se o ícone dele aparecer na coluna de ícones no lado direito da interface do usuário do Drive. Um complemento pode definir uma interface de página inicial, uma interface de seleção de itens ou ambas:

  • Se um usuário clicar no ícone do complemento enquanto estiver no Drive, o complemento vai executar a função drive.homepageTrigger correspondente (se houver). Essa função cria e retorna um card da página inicial para exibição no Drive. Se nenhuma função drive.homepageTrigger for definida, um card genérico da página inicial será exibido.
  • Se o usuário selecionar um ou mais itens no Drive e clicar no ícone do complemento ou selecionar itens enquanto o complemento estiver aberto, ele vai executar a função contextual drive.onItemsSelectedTrigger correspondente (se houver). Essa função cria a interface contextual "itens selecionados" do Drive do complemento e a retorna ao Drive para exibição.

Criar a interface do complemento do Drive

Para criar interfaces que estendem o Drive, siga estas etapas gerais:

  1. Decida se você quer que seu complemento tenha uma página inicial específica do Drive. Decida também se você quer fornecer uma interface contextual para quando o usuário selecionar itens do Drive.
  2. Adicione os campos addOns.common e addOns.drive ao manifesto do projeto de script do complemento, incluindo os escopos do Drive necessários.
  3. Se você estiver fornecendo uma página inicial específica do Drive, implemente a função drive.homepageTrigger para criar essa interface. Você também pode usar a interface common.homepageTrigger para vários hosts do Google Workspace.
  4. Se você estiver fornecendo uma interface de seleção de itens contextuais do Drive, implemente uma função de acionamento contextual drive.onItemsSelectedTrigger para criar essa interface. Consulte Interface contextual do Drive para itens selecionados para mais detalhes.
  5. Implemente as funções de callback associadas necessárias para responder às interações do usuário na interface, como cliques em botões.

Páginas iniciais do Drive

O Drive é compatível com a exibição de páginas iniciais de complementos. Para mostrar a página inicial comum do complemento no Drive, verifique se há um campo addOns.drive no manifesto do complemento.

Como alternativa, adicione um drive.homepageTrigger ao manifesto do complemento para fornecer uma página inicial específica do Drive.

Em qualquer um dos casos, forneça 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 acionamento da página inicial recebe um objeto de evento como parâmetro que contém algumas informações gerais, como a plataforma do cliente. Use os dados do objeto de evento para criar a página inicial.

Interface contextual do Drive para itens selecionados

O Drive usa um gatilho contextual para determinar qual interface (se houver) mostrar quando o usuário seleciona um ou mais itens do Drive. Quando o gatilho é disparado, ele executa a função de gatilho contextual especificada pelo campo drive.onItemsSelectedTrigger.runFunction no manifesto do complemento.

Para criar uma interface de seleção de itens contextuais para o Drive, faça o seguinte:

  1. Confira se o manifesto do complemento inclui o https://www.googleapis.com/auth/drive.addons.metadata.readonly escopo.

  2. Verifique se o manifesto inclui uma seção drive.onItemsSelectedTrigger.

  3. Implemente a função nomeada no campo drive.onItemsSelectedTrigger. Essa função aceita um objeto de evento como argumento e precisa retornar um único objeto Card ou uma matriz de objetos Card.

  4. Como em qualquer card, implemente as funções de callback usadas para fornecer interatividade de widget para a interface. Por exemplo, se você incluir um botão na interface, ele precisará ter uma ação 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 à função de acionamento drive.homepageTrigger ou drive.onItemsSelectedTrigger quando essas funções são chamadas. A função de gatilho usa as informações desse objeto de evento para determinar como criar cards de complemento ou controlar o comportamento do complemento.

A estrutura completa dos objetos de evento é descrita em Objetos de evento. Quando o Drive é o app host do complemento, os objetos de evento contextual incluem o campo objeto de evento do Drive, que contém informações específicas do cliente do Drive.

Os objetos de evento contextuais do Drive para acionadores de seleção de itens incluem informações sobre os itens que o usuário selecionou quando o acionador é ativado. Quando um usuário seleciona mais de um item no Drive, um deles é considerado de interesse principal, chamado de item de cursor ativo.

Se o comportamento do complemento for aplicado a vários itens selecionados, use as informações fornecidas na matriz drive.selectedItems do objeto de evento para identificar todos eles.

Quando o comportamento de um complemento precisar ser aplicado apenas a um único item selecionado, use as informações fornecidas no campo drive.activeCursorItem do objeto de evento para identificar o item na seleção completa. Não tente inferir qual item usar da matriz drive.selectedItems.

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"
      },
      ...
    ]
  },
  ...
}