Extensão das Planilhas Google

O Google Apps Script permite fazer coisas novas e interessantes com o Planilhas Google. Você pode usar o Apps Script para adicionar menus personalizados, caixas de diálogo e barras laterais ao Planilhas Google. Ele também permite que você escreva funções personalizadas para as Planilhas e integre-as a outros Serviços do Google, como Agenda, Drive e Gmail.

A maioria dos scripts criados para o Planilhas Google manipula matrizes para interagir com células, linhas e colunas em uma planilha. Para quem não conhece bem as matrizes em JavaScript, o Codecademy oferece um ótimo módulo de treinamento para matrizes. Este curso não foi desenvolvido pelo Google nem está associado a ele.

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.

Primeiros passos

O Apps Script inclui APIs especiais para permitir a criação, leitura e edição programática de planilhas do Google. O Apps Script pode interagir com o Planilhas Google de duas maneiras amplas: qualquer script poderá criar ou modificar uma planilha se o usuário tiver as permissões adequadas para a planilha, e um script também poderá ser vinculado a uma planilha, o que dá ao script habilidades especiais para 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 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, acessar o intervalo na planilha que contém os dados e, em seguida, obter 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, conforme mostrado na imagem abaixo.

No exemplo abaixo, mostramos 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]);
  }
}

Ler registros

Para visualizar os dados que foram registrados, clique em Execution log na parte superior do editor de scripts.

Como gravar dados

Para armazenar dados, como um novo nome e número de produto à 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 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 as 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 a personalização do conteúdo de uma caixa de diálogo, consulte o guia do serviço HTML.

Você também pode 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 no Planilhas Google.

Se você está planejando 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 do Planilhas Google.

Conexão com o app Formulários Google

O Apps Script permite conectar o Formulários Google ao Planilhas Google usando os serviços Formulários e Planilhas. Com esse recurso, você cria um arquivo do Formulários Google automaticamente com base nos dados de uma planilha. O Apps Script também permite usar acionadores, como onFormSubmit, para executar uma ação específica depois que um usuário responde ao formulário. Para saber mais sobre como conectar as Planilhas Google ao 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 abaixo 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, você acessa regras de validação de dados nas Planilhas Google ou cria regras novas. 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)

Paradas

Com o Apps Script, é possível incorporar gráficos que representam os dados em um determinado intervalo a uma planilha. 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 à 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), mas 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, consulte o guia de início rápido 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 códigos do Apps Script na interface do Planilhas Google. Ao contrário das funções personalizadas, você as ativa com um atalho de teclado ou pelo menu do Planilhas Google. Para mais informações, consulte Macros do Planilhas Google (em inglês).

Complementos para o Planilhas Google

Os complementos são projetos do Apps Script empacotados especialmente para serem executados no Planilhas Google e instalados na loja de complementos do Planilhas Google. Se você desenvolveu um script para as Planilhas Google e quer compartilhá-lo com outras pessoas, o Apps Script permite publish um 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 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.

Como acionadores simples, os acionadores instaláveis permitem que as Planilhas Google executem uma função automaticamente quando um determinado evento ocorre. No entanto, os acionadores instaláveis oferecem mais flexibilidade do que acionadores simples e oferecem suporte aos seguintes eventos: abrir, editar, alterar, envio de formulário e orientado por tempo (relógio).