O Google Apps Script permite fazer coisas novas e legais com as Planilhas Google. Você pode usar o Apps Script para adicionar menus personalizados, caixas de diálogo e barras laterais às Planilhas Google. Também é possível escrever funções personalizadas para as Planilhas e integrá-las a outros serviços do Google, como o Agenda, o Drive e o Gmail.
A maioria dos scripts criados para as Planilhas Google manipula matrizes para interagir com as células, linhas e colunas em uma planilha. Se você não conhece as matrizes em JavaScript, a Codecademy oferece um ótimo módulo de treinamento sobre matrizes. Este curso não foi desenvolvido nem está associado ao Google.
Para uma introdução rápida sobre como usar o Apps Script com as Planilhas Google, consulte o guia de início rápido de cinco minutos sobre Macros, menus e funções personalizadas.
Primeiros passos
O Apps Script inclui APIs especiais para criar, ler e editar planilhas Google de maneira programática. O Apps Script pode interagir com as Planilhas Google de duas maneiras: qualquer script pode criar ou modificar uma planilha se o usuário do script tiver as permissões adequadas para ela. Além disso, um script também pode ser vinculado a uma planilha, o que dá a ele habilidades especiais para alterar a interface do usuário ou responder quando a planilha é aberta. Para criar um script vinculado, selecione Extensões > Apps Script nas Planilhas Google.
O serviço de planilhas trata as Planilhas Google como uma grade, operando com matrizes bidimensionais. Para recuperar os dados da planilha, você precisa ter acesso à planilha em que os dados estão armazenados, extrair o intervalo na planilha que contém os dados e, em seguida, extrair os valores das células. O Apps Script facilita o acesso aos dados lendo dados estruturados na planilha e criando objetos JavaScript para eles.
Como ler dados
Suponha que você tenha uma lista de nomes e números de produtos armazenados em uma planilha, como mostrado na imagem abaixo.
O exemplo abaixo mostra como extrair 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 conferir os dados registrados, clique em Registro de execução na parte de cima do editor de script.
Como gravar dados
Para armazenar dados, como um novo nome e número de produto na planilha, adicione o seguinte código 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 de baixo da planilha com os valores especificados. Se você executar essa função, uma nova linha será adicionada à planilha.
Menus e interfaces do usuário personalizados
É possível personalizar o app Planilhas Google adicionando menus, caixas de diálogo e barras laterais personalizados. Para saber o básico sobre a criação de menus, consulte o guia de menus. Para saber mais sobre a personalização do 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 no desenho. Para saber mais, consulte Imagens e desenhos nas 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.
Como se conectar ao Google Forms
O Apps Script permite conectar o Formulários Google às Planilhas Google usando os 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 gatilhos, como
onFormSubmit, para realizar uma ação específica depois que um usuário responde ao formulário.
Para saber mais sobre como conectar as Planilhas Google aos Formulários Google, confira o tutorial Gerenciamento de respostas para os 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 de um intervalo de células. O exemplo
a seguir mostra como definir o estilo de 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, você pode 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 mais detalhes sobre como trabalhar com regras de validação de dados, consulte
SpreadsheetApp.newDataValidation(),
DataValidationBuilder
e Range.setDataValidation(rule).
Gráficos
O Apps Script permite 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 em tabela 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 nas Planilhas Google
Uma função personalizada é semelhante a uma função de planilha integrada, como =SUM(A1:A5), exceto que você define o comportamento das funções com o Apps Script. Por exemplo, é possível 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, tente o Guia introdutório de cinco minutos sobre menus e funções personalizadas ou confira o guia mais detalhado sobre funções personalizadas.
Macros
As macros são outra forma de executar o código do Apps Script na interface das Planilhas Google. Ao contrário das funções personalizadas, você as ativa com um atalho de teclado ou pelo menu das Planilhas Google. Para mais informações, consulte Macros das Planilhas Google.
Complementos para as Planilhas Google
Os complementos são projetos do Apps Script empacotados especialmente que são executados no Planilhas Google e podem ser instalados na loja de complementos do app. Se você desenvolveu um script para as Planilhas Google e quer compartilhá-lo com o mundo, o Apps Script permite publicar seu script como um complemento para que outros usuários possam instalá-lo na loja de complementos.
Gatilhos
Os scripts vinculados a um arquivo das Planilhas Google
podem usar gatilhos simples, como as funções
onOpen() e onEdit(), para responder automaticamente quando um usuário com acesso de edição
à planilha abrir ou editar a planilha.
Assim como os gatilhos simples, os instaláveis permitem que as Planilhas Google executem uma função automaticamente quando um determinado evento ocorre. No entanto, os gatilhos instaláveis oferecem mais flexibilidade do que os simples e oferecem suporte a estes eventos: abertura, edição, mudança, envio de formulário e baseado em tempo (relógio).