O Google Apps Script permite que você faça coisas novas e interessantes com o Planilhas Google. É possível usar o Apps Script para adicionar menus personalizados, caixas de diálogo e barras laterais às Planilhas Google. Ele também permite criar funções personalizadas para o Planilhas, bem como integrar o Planilhas a outros serviços do Google, como Agenda, Drive e Gmail.
A maioria dos scripts do Planilhas Google manipula matrizes para interagir com as células, linhas e colunas da planilha. Se você não tem familiaridade com matrizes em JavaScript, o Codecademy oferece um ótimo módulo de treinamento para matrizes (em inglês). Este curso não foi desenvolvido nem está associado ao Google.
Para uma introdução rápida ao uso do Apps Script com o Planilhas Google, consulte o guia de início rápido de cinco minutos sobre Macros, menus e funções personalizadas.
Começar
O Apps Script inclui APIs especiais para você criar, ler e editar Planilhas Google de maneira programática. O Apps Script pode interagir com o Planilhas Google de duas maneiras amplas: qualquer script pode criar ou modificar uma planilha se o usuário do script tiver as permissões apropriadas para a planilha, e um script também pode ser vinculado a uma planilha, o que dá ao script capacidades especiais de alterar a interface do usuário ou responder quando a planilha for aberta. Para criar um script vinculado, selecione Extensões > Apps Script no Planilhas Google.
O serviço Planilhas trata as Planilhas Google como uma grade, operando com matrizes bidimensionais. Para recuperar os dados da planilha, você precisa acessar a planilha em que os dados estão armazenados, o intervalo que contém os dados na planilha e, em seguida, os valores das células. Para facilitar o acesso aos dados, o Apps Script lê os dados estruturados na planilha e cria objetos JavaScript para eles.
Como ler dados
Suponha que você armazene uma lista de nomes e números de produtos em uma planilha, conforme mostrado na imagem abaixo.
O exemplo abaixo mostra como recuperar e registrar os nomes e números de produtos.
function logProductInfo() {
var sheet = SpreadsheetApp.getActiveSheet();
var data = sheet.getDataRange().getValues();
for (var i = 0; i < data.length; i++) {
Logger.log('Product name: ' + data[i][0]);
Logger.log('Product number: ' + data[i][1]);
}
}
ver registros
Para visualizar os dados que foram registrados, clique em Registro de execução na parte superior do editor de script.
Como gravar dados
Para armazenar dados, como um novo nome e número de produto na planilha, adicione o código a seguir ao final do script.
function addProduct() {
var sheet = SpreadsheetApp.getActiveSheet();
sheet.appendRow(['Cotton Sweatshirt XL', 'css004']);
}
O código acima anexa uma nova linha na parte inferior da planilha com os valores especificados. Se você executar essa função, verá uma nova linha adicionada à planilha.
Menus e interfaces do usuário personalizados
Você pode personalizar o Planilhas Google adicionando menus, caixas de diálogo e barras laterais personalizados. Para aprender os conceitos básicos da criação de menus, consulte o guia de menus. Para saber mais sobre como personalizar o conteúdo de uma caixa de diálogo, consulte o guia do serviço HTML.
Também é possível anexar uma função de script a uma imagem ou desenho em uma planilha. A função será executada quando um usuário clicar na imagem ou desenho. Para saber mais, consulte Imagens e desenhos no Planilhas Google.
Se você planeja publicar sua interface personalizada como parte de um complemento, siga o guia de estilo para manter a consistência com o estilo e o layout do editor das Planilhas Google.
Conectando ao app Formulários Google
Com o Apps Script, você conecta os Formulários Google às Planilhas Google pelos serviços Formulários e Planilhas. Esse recurso pode criar automaticamente um Formulário Google com base nos dados de uma planilha.
O Apps Script também permite usar acionadores, como onFormSubmit, para realizar uma ação específica depois que um usuário responder ao formulário.
Para saber mais sobre como conectar o Planilhas Google aos Formulários Google, consulte o guia de início rápido de cinco minutos Como gerenciar respostas nos Formulários Google.
Formatação
A classe Range tem métodos como
setBackground(color)
para acessar e modificar o formato de uma célula ou intervalo de células. O exemplo a seguir mostra como definir o estilo da fonte de um intervalo:
function formatMySpreadsheet() {
// Set the font style of the cells in the range of B2:C2 to be italic.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var cell = sheet.getRange('B2:C2');
cell.setFontStyle('italic');
}
Validação de dados
Com o Apps Script, é possível acessar regras de validação de dados existentes nas Planilhas Google ou criar novas regras. Por exemplo, o exemplo a seguir mostra como definir uma regra de validação de dados que permite apenas números entre 1 e 100 em uma célula.
function validateMySpreadsheet() {
// Set a rule for the cell B4 to be a number between 1 and 100.
var cell = SpreadsheetApp.getActive().getRange('B4');
var rule = SpreadsheetApp.newDataValidation()
.requireNumberBetween(1, 100)
.setAllowInvalid(false)
.setHelpText('Number must be between 1 and 100.')
.build();
cell.setDataValidation(rule);
}
Para ver mais detalhes sobre como trabalhar com regras de validação de dados, consulte
SpreadsheetApp.newDataValidation(),
DataValidationBuilder
e Range.setDataValidation(rule)
Diagramas
Com o Apps Script, é possível incorporar gráficos em uma planilha que representam os dados em um intervalo específico. O exemplo a seguir gera um gráfico de barras incorporado, supondo que você tenha dados gráficos nas células A1:B15:
function newChart() {
// Generate a chart representing the data in the range of A1:B15.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var chart = sheet.newChart()
.setChartType(Charts.ChartType.BAR)
.addRange(sheet.getRange('A1:B15'))
.setPosition(5, 5, 0, 0)
.build();
sheet.insertChart(chart);
}
Para saber mais sobre como incorporar um gráfico à sua planilha, consulte EmbeddedChart e criadores de gráficos específicos, como EmbeddedPieChartBuilder.
Funções personalizadas no app Planilhas Google
Uma função personalizada é semelhante a uma função de planilha integrada, como =SUM(A1:A5), mas você define o comportamento das funções com o Apps Script. Por exemplo, você pode criar uma função
personalizada, in2mm(), que converte um valor de polegadas para milímetros e, em seguida, usar
a fórmula na planilha digitando =in2mm(A1) ou =in2mm(10) em uma
célula.
Para saber mais sobre funções personalizadas, consulte o guia de início rápido de cinco minutos Menus e funções personalizadas ou consulte o guia para funções personalizadas mais detalhado.
Macros
As macros são outra forma de executar o código do Apps Script na interface do Planilhas Google. Ao contrário das funções personalizadas, você as ativa com um atalho do teclado ou pelo menu das Planilhas Google. Para mais informações, consulte Macros do Planilhas Google.
Complementos para o Planilhas Google
Os complementos são projetos do Apps Script em pacotes especialmente executados no Planilhas Google. Eles podem ser instalados na loja de complementos desse programa. Se você desenvolveu um script para as Planilhas Google e quer compartilhá-lo com o mundo, o Apps Script permite publish o script como um complemento para que outros usuários possam instalá-lo da loja de complementos.
Gatilhos
Os scripts vinculados a um arquivo das Planilhas Google podem usar acionadores simples, como as funções onOpen() e onEdit(), para responder automaticamente quando um usuário com acesso para edição abre ou edita a planilha.
Assim como os acionadores simples, os acionadores instaláveis permitem que as Planilhas Google executem uma função automaticamente quando ocorre um determinado evento. Já os acionadores instaláveis oferecem mais flexibilidade do que os acionadores simples e aceitam os seguintes eventos: abertos, editar, alterar, envio de formulário e orientados por tempo (relógio).