Você pode criar um botão no Google Sheets para executar uma função do Apps Script com um clique. Isso é útil para atualizar o status de pedidos, limpar dados, gerar relatórios ou rodar uma rotina que seria repetitiva se dependesse de menus e fórmulas.
O caminho mais simples é desenhar um botão com uma imagem ou desenho, criar uma função sem parâmetros no Apps Script e atribuir o nome dessa função ao objeto. O script fica vinculado à própria planilha, então a pessoa trabalha em uma interface mais parecida com um pequeno aplicativo.
O que você precisa antes de começar
- Uma planilha do Google Sheets com permissão para editar;
- um projeto do Apps Script vinculado à planilha;
- uma função que possa ser executada sem receber argumentos;
- um desenho ou uma imagem para usar como botão.
O projeto precisa ser aberto por Extensões > Apps Script dentro do próprio arquivo. Esse detalhe importa: a documentação do Google informa que atribuir uma função a uma imagem ou desenho no Sheets exige um script vinculado à planilha, não um projeto independente.
Como criar a função que será executada
Para ter um exemplo concreto, imagine uma aba chamada Pedidos com esta estrutura:
| A | B | C | D | E |
|---|---|---|---|---|
| Pedido | Cliente | Valor | Status | Atualizado em |
| 001 | Ana | 89,90 | Pendente |
A função abaixo usa a linha atualmente selecionada, muda o status para Conferido e registra a data na coluna E:
function atualizarPedido() {
const planilha = SpreadsheetApp.getActiveSpreadsheet();
const aba = planilha.getSheetByName('Pedidos');
const linha = aba.getActiveCell().getRow();
// Evita alterar o cabeçalho da tabela.
if (linha < 2) {
throw new Error('Selecione uma linha de pedido antes de clicar no botão.');
}
aba.getRange(linha, 4).setValue('Conferido');
aba.getRange(linha, 5).setValue(new Date());
}Salve o projeto com Ctrl + S ou pelo botão de salvar. Na primeira execução, o Google pode pedir autorização para que o script acesse e altere a planilha. Leia a tela de permissões e autorize somente se você reconhecer o projeto e o código.
Como inserir um botão no Google Sheets
1. Crie um desenho
Na planilha, abra Inserir > Desenho. Use a ferramenta de forma, escreva algo como Atualizar pedido e escolha uma cor que contraste com o fundo. Depois, clique em Salvar e fechar.
O desenho aparecerá sobre as células. Você pode arrastá-lo e redimensioná-lo para deixá-lo próximo da tabela. Não o coloque em cima dos dados que precisam ser selecionados: o botão deve ser fácil de encontrar sem esconder a planilha.
2. Atribua a função ao desenho
Clique nos três pontos do desenho, escolha Atribuir script e informe apenas o nome da função:
atualizarPedidoNão coloque parênteses e não escreva atualizarPedido(). O Sheets espera o nome da função que deverá chamar quando o objeto for clicado.
3. Faça o primeiro teste
- Selecione uma célula da linha 2 ou de outra linha de pedido.
- Clique no desenho.
- Confirme se a coluna D mudou para Conferido.
- Confira se a coluna E recebeu data e hora.
Se o Google mostrar uma mensagem de autorização, conclua o processo e repita o clique. O teste deve ser feito com uma linha de exemplo antes de usar o botão em uma planilha que contenha dados importantes.
Como criar um menu para ter mais de uma ação
Um único botão resolve tarefas simples. Quando a planilha precisa de várias ações, um menu personalizado costuma ser mais organizado. A função onOpen abaixo cria o menu Automação sempre que o arquivo é aberto:
function onOpen() {
SpreadsheetApp.getUi()
.createMenu('Automação')
.addItem('Atualizar pedido selecionado', 'atualizarPedido')
.addToUi();
}Depois de salvar, recarregue a planilha. O menu aparecerá na barra superior e chamará a mesma função atribuída ao desenho. A documentação do Google também permite criar itens de menu, imagens e desenhos que acionam funções do Apps Script, então você pode escolher entre uma interface mais visível ou uma barra de ações mais compacta.
Erros comuns e como corrigir
O nome da função não aparece
Confira se o desenho está na mesma planilha em que o script foi criado. Verifique também se a função está no nível principal do arquivo, com o nome exatamente igual ao informado em Atribuir script. Ela não deve estar dentro de outra função.
O botão altera a linha errada
Esse exemplo usa a célula ativa para descobrir a linha. Antes de clicar, selecione uma célula da linha desejada. Se várias pessoas usam a planilha ao mesmo tempo, substitua essa lógica por um campo de pedido ou por uma tela de seleção; depender da célula ativa pode causar confusão.
A planilha fica com a data em formato estranho
Selecione a coluna E, abra Formatar > Número > Data e hora e escolha o formato desejado. O Apps Script grava um objeto de data; a forma como ele aparece depende da formatação da coluna e das configurações regionais da planilha.
A função falha por falta de permissão
Execute a função pelo editor uma vez e confira se a autorização foi concluída. Se o arquivo pertencer a uma organização, o administrador também pode restringir o acesso a determinados serviços. Não copie código de origem desconhecida para contornar uma tela de permissão.
Limites que você precisa considerar
Um botão não transforma o Google Sheets em um sistema multiusuário completo. A função ainda está sujeita às cotas e ao tempo máximo de execução do Apps Script. A página oficial de cotas informa, por exemplo, limite de 6 minutos por execução e limites diários que variam conforme o tipo de conta. Consulte a tabela atual antes de colocar uma rotina pesada em produção.
Também vale lembrar que o desenho é uma camada de interface, não uma barreira de segurança. Quem puder editar o projeto poderá alterar o código, e quem tiver permissão para editar a planilha poderá modificar os dados. Para processos financeiros, informações pessoais ou aprovações importantes, controle o compartilhamento e mantenha um histórico de alterações.
Se o seu objetivo for avisar clientes ou a equipe depois de uma mudança, você pode combinar esse botão com o fluxo explicado no nosso guia sobre como enviar e-mails automáticos pelo Google Sheets usando Apps Script. O botão inicia a ação manual; o script pode registrar a alteração e enviar a mensagem.
Quando usar botão, menu ou gatilho automático?
- Botão: melhor quando alguém precisa revisar a linha antes de executar a ação.
- Menu personalizado: útil quando existem várias funções relacionadas no mesmo arquivo.
- Gatilho automático: indicado quando a ação deve acontecer ao editar a planilha ou em um horário programado, sem depender de um clique.
Comece pelo botão se a tarefa exigir decisão humana. Assim você evita que uma alteração incompleta dispare um e-mail, mude um status ou crie um registro antes da hora.
Perguntas frequentes
Posso atribuir qualquer função a um desenho no Google Sheets?
Não. A função precisa estar no projeto vinculado à planilha e deve ser chamada pelo nome, sem parênteses. Funções que dependem de argumentos não são adequadas para esse tipo de clique.
O botão funciona no celular?
Segundo a documentação do Google, a função atribuída à imagem ou ao desenho é disparada quando o objeto é clicado em um navegador. No aplicativo móvel, não conte com esse botão; para uma rotina usada no celular, prefira um formulário ou uma interface web própria.
Por que o Apps Script pede autorização?
O script está tentando acessar ou alterar dados da sua conta Google. A autorização permite que a função use os serviços necessários, como a planilha ativa. Revise o projeto e as permissões antes de aceitar.
Posso criar vários botões na mesma planilha?
Sim. Cada desenho pode chamar uma função diferente, e vários desenhos podem chamar a mesma função. Use nomes claros e teste cada ação com dados de exemplo para evitar alterações acidentais.