Extensão do Planilhas Google

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O Google Apps Script permite que você faça coisas novas e legais com o Planilhas Google. Você pode usar o Apps Script para adicionar menus personalizados, caixas de diálogo e barras laterais ao Planilhas Google. Com ele, você também pode escrever funções personalizadas para o Planilhas e integrá-lo a outros serviços do Google, como o Agenda, o Drive e o Gmail.

A maioria dos scripts criados para o Planilhas Google manipula matrizes para interagir com as células, linhas e colunas em uma planilha. Se você não tiver familiaridade com matrizes no JavaScript, o Codecademy oferece um ótimo módulo de treinamento para matrizes. Este curso não foi desenvolvido e não está associado ao Google.

Para uma introdução rápida sobre como usar o 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 criar, ler e editar programaticamente o Planilhas Google. 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 e um script também puder ser vinculado a uma planilha, o que proporciona ao script recursos 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 Planilhas trata o Planilhas Google como uma grade, que opera com matrizes bidimensionais. Para recuperar os dados da planilha, você precisa ter acesso à planilha em que os dados estão armazenados, obter o intervalo na planilha que contém os dados e, em seguida, receber os valores das células. O Apps Script facilita o acesso aos dados ao ler dados estruturados na planilha e criar objetos JavaScript para eles.

Como ler dados

Imagine que você tenha uma lista de nomes e números de produtos armazenados em uma planilha, como 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]);
  }
}

Ver registros

Para ver 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 de produto e número na planilha, adicione o seguinte código ao fim 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. Ao executar essa função, você verá uma nova linha adicionada à planilha.

Menus personalizados e interfaces do usuário

Você pode personalizar o Planilhas Google adicionando menus, caixas de diálogo e barras laterais personalizadas. Para aprender os conceitos básicos da criação de menus, consulte o guia de menus. Para saber como personalizar o 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. Saiba mais em Imagens e desenhos no Planilhas Google.

Se você planeja publicar a 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.

Conectar-se ao Formulários Google

O Apps Script permite conectar arquivos do Formulários ao Planilhas Google usando os serviços do Formulários e Planilhas. Esse recurso pode criar automaticamente um arquivo do Formulários Google com base nos dados de uma planilha. O Apps Script também permite que você use acionadores, como onFormSubmit, para executar uma ação específica após um usuário responder ao formulário. Para saber mais sobre como conectar o Planilhas Google ao Formulários Google, consulte o guia de início rápido de Gerenciar respostas para o Formulários Google de cinco minutos.

Formatação

A classe Range tem métodos como setBackground(color) para acessar e modificar o formato de uma célula ou um 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ê pode acessar regras de validação de dados no Planilhas Google ou criar novas. Veja no exemplo a seguir como definir uma regra de validação de dados que permita 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

Com o Apps Script, você pode incorporar gráficos em uma planilha que representa os dados de um intervalo específico. No exemplo a seguir, um gráfico de barras incorporado é gerado, 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 específicos de gráficos, como EmbeddedPieChartBuilder.

Funções personalizadas no Planilhas Google

Uma função personalizada é semelhante a uma função de planilha integrada, como =SUM(A1:A5), exceto pelo fato de 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 a milímetros e, em seguida, usar a fórmula na sua planilha digitando =in2mm(A1) ou =in2mm(10) em uma célula.

Para saber mais sobre funções personalizadas, veja o guia de início rápido de Menus e funções personalizadas de cinco minutos ou consulte o guia mais detalhado para funções personalizadas.

Macros

As macros são outra forma de executar código do Apps Script na IU do Planilhas Google. Ao contrário das funções personalizadas, você as ativa com um atalho no teclado ou pelo menu do Planilhas Google. Para mais informações, consulte Macros do Planilhas Google.

Complementos para o Planilhas Google

Os complementos são projetos do Apps Script empacotados especialmente para serem executados no Planilhas Google e que podem ser instalados na loja de complementos do Planilhas Google. Se você desenvolveu um script para o 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 do Planilhas Google podem usar acionadores simples, como as funções onOpen() e onEdit(), para responder automaticamente quando um usuário com acesso para editar a planilha abrir ou editar a planilha.

Assim como os acionadores simples, os acionadores instaláveis permitem que o Planilhas Google execute uma função automaticamente quando ocorre um determinado evento. Os gatilhos instaláveis, no entanto, oferecem mais flexibilidade do que os acionadores simples e oferecem suporte aos seguintes eventos: abrir, editar, alterar, enviar formulário e baseado em tempo (relógio).