Criar interfaces do editor do Google

Com os complementos do Google Workspace, você pode oferecer interfaces personalizadas nos editores, incluindo o Documentos, o Planilhas e o Apresentações. Isso permite que você forneça informações relevantes ao usuário, automatize tarefas e conecte sistemas de terceiros aos editores.

Acessar a interface do complemento

Você pode abrir o complemento do Google Workspace nos editores se o ícone dele aparecer no painel lateral de acesso rápido do Google Workspace nas interfaces do usuário do 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 acionador EDITOR_NAME.homepageTrigger para o editor em que o usuário abre o complemento, ele vai criar e retornar um card da página inicial especificamente para esse editor. Se o manifesto do complemento não incluir o EDITOR_NAME.homepageTrigger para o editor em que o usuário o abre, um card genérico da página inicial será exibido em vez disso.
Interfaces da API REST: se o complemento usar APIs REST, você poderá incluir acionadores que solicitam acesso por arquivo a um documento usando o escopo drive.file. Depois de concedido, outro acionador chamado EDITOR_NAME.onFileScopeGrantedTrigger é executado e mostra uma interface específica para o arquivo.
Interfaces de visualização de links: se o complemento for integrado a um serviço de terceiros, você poderá criar cards que mostram uma prévia do conteúdo dos URLs do serviço.

Criar interfaces para complementos do editor

Para criar interfaces de complementos do editor, siga estas etapas:

Adicione os campos addOns.common, addOns.docs, addOns.sheets, e addOns.slides adequados ao manifesto do projeto de script do 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 EDITOR_NAME.homepageTrigger função para criar a interface. Caso contrário, use a common.homepageTrigger interface para criar uma página inicial comum para seus apps host.
Se você usar APIs REST, implemente o fluxo de autorização do escopo drive.file e a função de acionador EDITOR_NAME.onFileScopeGrantedTrigger para mostrar 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 escopohttps://www.googleapis.com/auth/workspace.linkpreviewfluxo de autorização e linkPreviewTriggers função. Para mais informações, consulte Interfaces de visualização de links.
Implemente as funções de callback associadas necessárias para responder às interações da interface do usuário, como cliques em botões.

Páginas iniciais do editor

É necessário fornecer uma função de acionador de página inicial no projeto de script do complemento que cria e retorna um único Card ou uma matriz de Card objetos 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. 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 uma página inicial específica do editor em que o usuário abre o complemento.

Mostrar a página inicial comum

Para mostrar a página inicial comum do complemento nos editores, inclua os campos do editor adequados, 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 o Documentos, o Planilhas e o 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": {}
  }
}

Mostrar uma página inicial específica do editor

Para apresentar uma página inicial específica de 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 o Documentos, o Planilhas e o Apresentações. Ele mostra 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 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 usar APIs REST, como a API Google Sheets, você poderá usar a onFileScopeGrantedTrigger função para mostrar uma nova interface específica para o arquivo 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 drive.file escopo, consulte Solicitar acesso ao arquivo do documento.

Quando um usuário concede o escopo drive.file, o EDITOR_NAME.onFileScopeGrantedTrigger.runFunction é acionado. Quando o acionador é disparado, ele executa a função de acionador contextual especificada pelo EDITOR_NAME.onFileScopeGrantedTrigger.runFunction campo no manifesto do complemento.

Para criar uma interface da API REST para um dos editores, conclua as etapas a seguir. Substitua EDITOR_NAME pelo app host do editor que você escolher usar, por exemplo, sheets.onFileScopeGrantedTrigger:

Inclua o EDITOR_NAME.onFileScopeGrantedTrigger na seção apropriada do editor do manifesto. Por exemplo, se você quiser criar essa interface no Google Planilhas, adicione o acionador à seção "sheets".
Implemente a função nomeada na EDITOR_NAME.onFileScopeGrantedTrigger seção. Essa função aceita um objeto de evento como argumento e precisa retornar um único Card objeto ou uma matriz de Card objetos.
Como em qualquer card, é necessário implementar 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 Action 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 no Google Planilhas. 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 de um serviço de terceiros, é necessário configurar as visualizações de links no manifesto do complemento e criar uma função que retorne um card de visualização. Para serviços que exigem autorização do usuário, a função também precisa invocar o fluxo de autorização.

Para conferir as etapas de ativação das visualizações de links, consulte Visualizar links com ícones inteligentes.

Objetos de evento

Um objeto de evento é criado e transmitido para funções de acionador, como EDITOR_NAME.homepageTrigger ou EDITOR_NAME.onFileScopeGrantedTrigger. A função de acionador usa as informações no objeto de evento para determinar como construir cards 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 do complemento, os objetos de evento incluem campos de objeto de evento do Documentos, Planilhas ou Apresentações que contêm 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 vai conter apenas o campo docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission ou slides.addonHasFileScopePermission. Se o complemento tiver autorização, o objeto de evento vai conter todos os campos de 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 de escopo drive.file para o documento atual:

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

Criar interfaces do editor do Google Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.