Ampliar arquivos do Planilhas Google com complementos

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

É possível estender os arquivos do Planilhas com complementos que criam melhorias personalizadas no fluxo de trabalho, estabelecer conectividade com sistemas de terceiros e integrar os dados do Planilhas a outros Google Workspace aplicativos (como o Apresentações Google).

É possível ver os complementos do Planilhas que outras pessoas criaram no Google Workspace Marketplace.

O que você pode fazer

Veja o que você pode fazer com um complemento que amplia o Planilhas Google:

• Você pode ler, editar, visualizar e formatar dados nas Planilhas Google usando o serviço integrado Planilhas do Apps Script. O serviço também permite criar e modificar a formatação condicional e as regras de validação de dados.
• Você pode usar o serviço avançado do Planilhas do Apps Script para acessar a API REST do Planilhas.
• É possível criar menus personalizados e definir várias interfaces de diálogo e barras laterais personalizadas usando HTML e CSS padrão.
• Você pode incluir definições de função personalizada no seu complemento.
• Você pode usar acionadores de complementos que executam funções especificadas quando determinados eventos de acionamento ocorrem.

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

Estrutura da planilha

O arquivo do Planilhas Google tem uma ou mais planilhas. Basicamente, cada página é uma grade 2D de células em que é possível armazenar textos, números, links ou outros valores. Um grupo de uma ou mais células adjacentes é chamado de intervalo.

O serviço de planilhas do Apps Script fornece várias classes para representar estruturas organizacionais no Planilhas (como Sheet e Range). Você pode usar essas classes para ler e modificar os dados e o comportamento do app Planilhas.

Acionadores

Os acionadores 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 um complemento é instalado.

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

Funções personalizadas

O app Planilhas Google tem várias funções integradas, como SUM e AVERAGE, que podem ser usadas 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 nele ficam disponíveis imediatamente. É possível que um complemento consista apenas em definições de função personalizadas. As definições das funções personalizadas são principalmente compartilhadas com outras pessoas, publicando um complemento que contém as definições.

Criar funções personalizadas de complementos

Qualquer função definida em um projeto de script de complementos 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 o = seguido pelo nome da função e dos parâmetros necessários. Se não houver erros, o resultado retornado pela função vai ser colocado na célula da planilha, transbordando para células vizinhas conforme necessário.

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

• Diretrizes de nomeação da função
• Como definir argumentos de função
• Como definir o valor de retorno da função
• Tipos de dados de função personalizada
• Ativar o preenchimento automático usando o JSDoc
• Funções personalizadas dos serviços
• Como otimizar funções personalizadas

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

• Ao nomear sua 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.
• Seu complemento precisa comunicar claramente quais funções personalizadas ele oferece. Forneça comentários precisos sobre o JSDoc para suas funções personalizadas. Assim, o Apps Script pode apresentar informações de preenchimento automático ao usuário. Além disso, considere fornecer documentação adicional das funções personalizadas no próprio complemento ou em uma página da Web de suporte.
• 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 quando possível.
• As funções personalizadas não podem usar os serviços do Apps Script que exigem autorização e falharão com um erro You do not have permission to call X service se isso for tentado. Use apenas os serviços permitidos na sua 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 atenuar isso, mantenha suas funções personalizadas o mais simples possível. Se você precisar que a função realize processamento complexo ou estendido, não use uma função personalizada. Forneça essa funcionalidade por um item de menu, caixa de diálogo ou interação na barra lateral.

Macros do Planilhas

As macros permitem gravar ações realizadas no 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 página. Para mais informações sobre macros, consulte Macros do Planilhas Google.

Infelizmente, as macros do 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.