Como estender o uso do Planilhas Google com complementos

O Planilhas Google é uma solução de planilhas baseada na nuvem com colaboração em tempo real e ferramentas eficientes para visualizar, processar e comunicar dados.

É possível estender as Planilhas com complementos que criam melhorias personalizadas no fluxo de trabalho, estabelecem conectividade a sistemas de terceiros e integram seus dados com outros aplicativos do Google Workspace, como as Apresentações Google.

Confira os complementos de Planilhas criados por outras pessoas no Google Workspace Marketplace.

O que você pode fazer

Confira algumas coisas que você pode fazer com um complemento que estende as Planilhas Google:

Os complementos do Planilhas são criados usando o Apps Script. Para saber mais sobre como acessar e gerenciar as Planilhas Google com o Apps Script, consulte Como estender as Planilhas Google.

Estrutura da planilha

Uma planilha do Google Sheets consiste em uma ou mais páginas. Cada planilha é essencialmente uma grade 2D de células em que texto, números, links ou outros valores podem ser armazenados. Um grupo de uma ou mais células adjacentes é chamado de intervalo.

O serviço de planilhas do Apps Script oferece várias classes para representar estruturas organizacionais nas Planilhas, como Sheet e Range. É possível usar essas classes para ler e modificar os dados e o comportamento das Planilhas.

Gatilhos

Os gatilhos do Apps Script permitem que um projeto de script execute uma função especificada quando determinadas condições são atendidas, como quando uma planilha é aberta ou quando um complemento é instalado.

Consulte gatilhos de complementos para mais informações sobre quais gatilhos podem ser usados com os complementos do Planilhas e quais restrições se aplicam a eles.

Funções personalizadas

As Planilhas Google têm várias funções integradas, como SUM e AVERAGE, que podem ser invocadas em uma célula das Planilhas Google. Os complementos do Planilhas podem definir outras funções personalizadas para complementar essas funções integradas. Quando um usuário instala o complemento, todas as funções personalizadas definidas incluídas no complemento ficam disponíveis imediatamente. É possível que um complemento consista apenas de definições de função personalizadas. As definições de função personalizadas são compartilhadas principalmente com outras pessoas ao publicar um complemento que contém as definições.

Como criar funções personalizadas de complemento

Qualquer função definida em um projeto de script complementar pode ser usada como uma função personalizada. Depois que a função for implementada e o complemento for instalado, você poderá chamar a função personalizada como qualquer outra função integrada do Planilhas: em uma célula da planilha, insira = seguido pelo nome da função e todos os parâmetros necessários. Se não houver erros, o resultado retornado pela função será colocado na célula da planilha, transbordando para as células vizinhas conforme necessário.

Ao criar funções personalizadas em um complemento, siga as diretrizes gerais de função personalizada:

Além disso, as funções personalizadas definidas em complementos têm algumas considerações especiais:

  • Ao nomear a função, tente criar um nome exclusivo, talvez relacionado ao nome do complemento. Se dois ou mais complementos instalados definirem funções personalizadas com o mesmo nome, os usuários só poderão usar um deles.
  • O complemento precisa comunicar claramente quais funções personalizadas ele oferece. Forneça comentários JSDoc precisos para suas funções personalizadas para que o Apps Script possa apresentar informações de preenchimento automático ao usuário. Além disso, considere fornecer mais documentação das funções personalizadas no próprio complemento ou em uma página da Web de suporte a complementos.
  • As funções personalizadas que não são concluídas em menos de 30 segundos falham com um erro Internal error executing the custom function. Crie uma boa experiência do usuário limitando a quantidade de processamento que você faz em uma função personalizada. Otimize a função sempre que possível.
  • As funções personalizadas não podem usar serviços do Apps Script que exigem autorização. Se isso acontecer, uma falha com um erro You do not have permission to call X service será gerada. Use apenas os serviços permitidos na função personalizada.
  • Cada função personalizada em uma planilha resulta em uma chamada separada para os servidores do Apps Script. Se um usuário tentar usar funções personalizadas em muitas células, elas poderão ser executadas lentamente. Para evitar isso, mantenha as funções personalizadas o mais simples possível. Se você precisar que a função execute um processamento complexo ou estendido, não use uma função personalizada. Forneça essa funcionalidade por meio de um item de menu, diálogo ou interação da barra lateral.

Macros das Planilhas

Com as macros, você pode gravar ações realizadas nas Planilhas Google e repeti-las mais tarde com um atalho de teclado. Quando uma macro é criada em uma planilha, ela é adicionada como uma função de macro em um projeto do Apps Script vinculado a essa planilha. Para mais informações sobre macros, consulte Macros das Planilhas Google.

Infelizmente, as macros do app Planilhas não podem ser distribuídas com complementos. Se você incluir uma definição de macro no manifesto de um complemento, ela não estará disponível para os usuários desse complemento.