Planilhas do Google Curso de Capacitação de Servidores
Início do conteúdo
Traçando um Gráfico e Apresentando Dados nos Slides

Configurando

Antes de continuar, você precisa de uma planilha com alguns dados. Como antes, fornecemos uma folha de dados que você pode copiar para esses exercícios. Execute as seguintes etapas:

  1. Clique neste link para copiar a planilha de dados e, em seguida, clique no botão Fazer uma cópia . A nova planilha é colocada em sua pasta inicial do Google Drive e é chamada de “Cópia de datas e taxas de câmbio do dólar americano”.
  2. Clique no título da planilha e altere de “Cópia de datas e taxas de câmbio do USD” para “Datas e taxas de câmbio do USD”. Sua planilha deve ser semelhante a esta, com algumas informações básicas sobre as diferentes taxas de câmbio do dólar americano em datas diferentes:

  1. Selecione Ferramentas> Editor de scripts para abrir o editor de scripts:

    Para economizar seu tempo, incluímos um pouco de código para configurar um menu personalizado nesta planilha. Você deve ter visto o menu aparecer quando sua cópia da planilha foi aberta:

 

Observação : se precisar de uma atualização, você pode aprender mais sobre menus personalizados e onOpen()no codelab Trabalhando com dados .

 

 

 

Com esta planilha e projeto, você está pronto para iniciar o laboratório! Passe para a próxima seção para começar a aprender sobre gráficos e gatilhos baseados em tempo.

 

 

Crie um gráfico no Planilhas com o Apps Script

Suponha que você queira criar um gráfico específico para visualizar um conjunto de dados. Você pode realmente usar o Apps Script para criar, editar e colocar gráficos no Planilhas Google! Quando um gráfico é criado e colocado no Planilhas Google, ele é chamado de gráfico incorporado.

Os gráficos incorporados são gráficos contidos em uma planilha. Os gráficos são usados ​​para visualizar uma ou mais séries de dados; para gráficos incorporados, os dados que eles apresentam geralmente vêm de dados de formulário dentro da própria planilha. Na maioria dos casos, a atualização dos dados na planilha fará com que o Planilhas Google também atualize automaticamente o gráfico.

Você pode usar o Apps Script para criar gráficos incorporados personalizados do zero ou atualizar gráficos existentes. Esta seção apresenta os fundamentos da construção de gráficos incorporados no Planilhas com Apps Script e o Spreadsheet serviço .

 

 

Implementação

Em sua cópia da planilha de dados, o conjunto de dados “Datas e taxas de câmbio” mostra as taxas de câmbio (para 1 dólar americano) de moedas diferentes em datas diferentes. Você implementará uma função do Apps Script que cria um novo gráfico para visualizar parte desses dados.

Execute as seguintes etapas:

  1. No editor do Apps Script, adicione a seguinte função ao final do script do seu projeto de Code.gsscript, após a onOpen()função:
/**
 * Creates and inserts an embedded
 * line chart into the active sheet.
 */
function createEmbeddedLineChart() {
  var sheet = SpreadsheetApp.getActiveSheet();
  var chartDataRange = sheet.getRange(
    'Dates and USD Exchange Rates dataset!A2:F102');
  var hAxisOptions = {
    slantedText: true,
    slantedTextAngle: 60,
    gridlines: {
      count: 12
    }
  };
  
  var lineChartBuilder = sheet.newChart().asLineChart();
  var chart = lineChartBuilder
    .addRange(chartDataRange)
    .setPosition(5, 8, 0, 0)
    .setTitle('USD Exchange rates')
    .setNumHeaders(1)
    .setLegendPosition(Charts.Position.RIGHT)
    .setOption('hAxis', hAxisOptions)
    .build();
 
  sheet.insertChart(chart);  
}
  1. Salve seu projeto de script.

 

Revisão de código

O código que você adicionou implementa a função chamada pelo item de menu Gráfico “Datas e taxas de câmbio do USD” . Ele cria um gráfico de linha básico. Vamos revisar o código!

As primeiras linhas configuram as seguintes três variáveis:

  • sheet: uma referência à planilha ativa atual.
  • chartDataRange: uma variação dos dados que queremos visualizar. O código usa a notação A1 para especificar que o intervalo abrange as células de A2 a F102 na planilha denominada datas e conjunto de dados de taxas de câmbio do USD . Ao nomear a planilha especificamente, garantimos que o item de menu funcionará mesmo se uma planilha diferente estiver ativa no momento – o intervalo sempre cobre onde os dados estão. Incluir a linha 2 neste intervalo significa que estamos incluindo os cabeçalhos das colunas. Decidimos representar graficamente apenas as 100 datas (linhas) mais recentes.
  • hAxisOptions: um objeto JavaScript básico que inclui algumas informações de configuração que o código usa para configurar a aparência do eixo horizontal. Especificamente, essas configurações definem os rótulos de texto do eixo horizontal em uma inclinação de 60 graus e define o número de linhas de grade verticais para 12.

A próxima linha cria um objeto construtor de gráfico de linha . Os gráficos incorporados no Apps Script são construídos usando um padrão de design Builder . Uma explicação completa desse padrão de design está fora do escopo deste codelab, então, por enquanto, apenas entenda que o Spreadsheet serviço fornece várias EmbeddedChartBuilder classes. Para criar um gráfico, seu código primeiro cria um objeto construtor de gráfico integrado, usa seus métodos para definir as configurações do gráfico e, em seguida, chama um build() método para criar o EmbeddedChart objeto final . Seu código nunca modifica o EmbeddedChart objeto diretamente; toda a configuração do gráfico é feita por meio das classes construtoras.

O Spreadsheet serviço fornece uma EmbeddedChartBuilder classe pai e várias classes de construtor filho (como EmbeddedLineChartBuilder) que herdam dela. As classes filhas permitem que o Apps Script forneça os métodos de configuração de gráficos de construtores que são aplicáveis ​​apenas a determinados tipos de gráficos. Por exemplo, a EmbeddedPieChartBuilder classe fornece um set3D() método que só faz sentido para gráficos de pizza.

Em seu código, esta linha está criando uma variável de objeto builder lineChartBuilder:

var lineChartBuilder = sheet.newChart().asLineChart();

O código chama o Sheet.newChart() método para criar um novo EmbeddedChartBuilder objeto e, em seguida, usa EmbeddedChartBuilder.asLineChart() para definir o tipo de construtor como EmbeddedLineChartBuilder.

O código então cria o gráfico usando lineChartBuilder. Esta parte do código é apenas uma série de chamadas de método que definem as configurações do gráfico, seguidas por uma build() chamada para criar o gráfico. Como você viu em codelabs anteriores, o código faz uso do encadeamento de métodos para manter o código legível por humanos. Aqui está o que as chamadas de método estão fazendo:

  • addRange(range): Define um intervalo de dados que o gráfico exibirá.
  • setPosition(anchorRowPos, anchorColPos, offsetX, offsetY): Determina onde o gráfico é colocado na folha. Aqui, o código está colocando o canto superior esquerdo do gráfico na célula H5.
  • setTitle(title): Define o título do gráfico.
  • setNumHeaders(headers): Determine quantas linhas ou colunas no intervalo de dados devem ser tratadas como cabeçalhos. Aqui, o código diz para usar a primeira linha no intervalo de dados como cabeçalhos, o que significa que o texto nessa linha será usado como rótulos para as séries de dados individuais no gráfico.
  • setLegendPosition(position): Move a legenda do gráfico para o lado direito do gráfico. Este método usa o enum Charts.Position como parâmetro.
  • setOption(option, value): Define opções de gráfico complexas. Aqui, o código define a hAxis opção para o hAxisOptions objeto. Existem muitas opções que você pode definir usando este método, mas você precisa saber as opções e os valores possíveis para cada tipo de gráfico. Tudo isso está documentado na Charts API Charts Gallery. Por exemplo, as opções que você pode definir para gráficos de linha estão documentadas em Opções de configuração do gráfico de linha . Usar setOption(option, value) métodos é um uso avançado do Apps Script, portanto, convém evitar usá-los até se sentir mais familiarizado com a criação de gráficos no Apps Script.
  • build(): Cria e retorna um EmbeddedChart objeto usando as configurações acima.

Finalmente, o código chama Sheet.insertChart(chart) para colocar o gráfico construído na planilha ativa.

 

Resultados

Você pode ver sua função de formatação em ação fazendo o seguinte:

  1. Salve seu projeto de script no editor do Apps Script, caso ainda não tenha feito isso.
  2. Clique no item de menu Conjunto de dados presente> Gráfico “Datas e taxas de câmbio do USD” .

 

 

Seu script agora coloca um novo gráfico à direita de seus dados!

Parabéns! Você construiu um gráfico de linha incorporado com o Apps Script. A próxima seção ensina como exportar seu gráfico para o Slides!

 

 

Exporte seus gráficos para slides

Um dos grandes pontos fortes do Apps Script é que ele permite que você mova dados facilmente de um aplicativo do G Suite para outro. A maioria dos aplicativos do G Suite tem um serviço Apps Script dedicado, semelhante ao serviço Spreadsheet : por exemplo, o Gmail tem o serviço Gmail , o Google Docs tem o serviço Document e o Google Slides tem o serviço Slides . Com todos esses serviços integrados, você pode extrair rapidamente os dados de um aplicativo, processá-los e gravar o resultado em outro.

Nesta seção, você verá como exportar todos os gráficos incorporados em uma planilha do Google para uma nova apresentação do Google Slides. Você também verá duas maneiras de mostrar as mensagens personalizadas do usuário no Planilhas!

 

 

Implementação

Aqui, você implementará a função chamada pelo item de menu Apresentar conjunto de dados> Exportar gráficos para slides . Execute as seguintes etapas:

  1. No editor do Apps Script, adicione a seguinte função ao final do script do seu projeto de Code.gs script, após a createEmbeddedLineChart() função:
/**
 * Creates a new Slides presentation and exports
 * all the embedded charts in this spreadsheet
 * to it, one chart per slide.
 */
function exportChartsToSlides() {
  var ss = SpreadsheetApp.getActiveSpreadsheet();
  
  // Fetch a list of all embedded charts in this
  // spreadsheet.
  var charts = [];
  var sheets = ss.getSheets();
  for (var i = 0; i < sheets.length; i++) {
    charts = charts.concat(sheets[i].getCharts());
  }
  
  // If there aren't any charts, display a toast
  // message and return without doing anything
  // else.
  if (charts.length == 0) {
    ss.toast('No charts to export!');
    return;
  }
  
  // Create a new Slides presentation, removing the default
  // title slide.
  var presentationTitle =
    ss.getName() + " Presentation";
  var slides = SlidesApp.create(presentationTitle);
  slides.getSlides()[0].remove();  
  
  // Add charts to the presentation, one chart per slide.
  var position = {left: 40, top: 30};
  var size = {height: 340, width: 430};
  for (var i = 0; i < charts.length; i++) {
    var newSlide = slides.appendSlide();
    newSlide.insertSheetsChart(
      charts[i],
      position.left,
      position.top,
      size.width,
      size.height);   
  }
  
  // Create and display a dialog that tells the user where to
  // find the new presentation.
  var slidesUrl = slides.getUrl();
  var html = "<p>Find it in your home Drive folder:</p>"
      + "<p><a href=\"" + slidesUrl + "\" target=\"_blank\">"
      + presentationTitle + "</a></p>";
  
  SpreadsheetApp.getUi().showModalDialog(
    HtmlService.createHtmlOutput(html)
      .setHeight(120)
      .setWidth(350),
      "Created a presentation!"
  );
}
  1. Salve seu projeto de script.

 

Revisão de código

Este código pode ser mais curto do que você esperava! Vamos revisar o que está fazendo dividindo o código em seções:

 

1: Obtenha os gráficos

As primeiras linhas pesquisam a planilha ativa para encontrar todos os gráficos incorporados, reunindo-os no array charts. Essas linhas usam o Spreadsheet.getSheets()método e o Sheet.getCharts()método para obter listas de planilhas e gráficos. O Array.concat()método JavaScript é usado para anexar a lista de gráficos de cada folha ao charts.

 

2: Verifique se há gráficos para exportar

O código então verifica se há realmente algum gráfico para exportar. Queremos evitar fazer uma apresentação em branco; portanto, se não houver gráficos, o código em vez disso cria uma mensagem brinde usando Spreadsheet.toast(message). Esta é uma pequena caixa de diálogo “espiada” que aparece no canto inferior direito do Planilhas, permanece por alguns segundos e depois desaparece:

 

 

Se não houver gráficos para exportar, o código cria a mensagem do sistema e sai sem fazer mais nada. Se houver gráficos para exportar, o código continuará a criar uma apresentação nas próximas linhas.

 

3: Crie uma apresentação

A variável presentationTitle é criada como o nome do arquivo da nova apresentação. Ele é definido como o nome da planilha, com ” Presentation” concatenado no final. O código então chama o método de serviço Slides SlidesApp.create(name) para criar uma nova apresentação.

 

 

Novas apresentações são criadas com um único slide em branco. Não queremos isso em nossa apresentação, então o cod remove com Presentation.getSlides() e Slide.remove().

 

4: Exportar os gráficos

Na próxima seção, o código define os objetos JavaScript position e size descreve onde os gráficos importados serão colocados no slide e o tamanho do gráfico (em pixels).

 

 

O código faz um loop em cada gráfico na lista de gráficos. Para cada gráfico, newSlide é criado um Presentation.appendSlide(), adicionando esse slide ao final da apresentação. O Slide.insertSheetsChart(sourceChart, left, top, width, height) método é então usado para importar o gráfico para o slide com o size e position.

 

5: Diga ao usuário onde está a apresentação

Por fim, o código precisa permitir que o usuário saiba onde está a nova apresentação, de preferência com um link no qual ele possa clicar para abri-la. Para fazer isso, o código usa o Apps Script HtmlService para criar uma caixa de diálogo modal personalizada . As caixas de diálogo modais (também conhecidas como caixas de diálogo personalizadas no Apps Script) são janelas que aparecem na interface do Planilhas; enquanto eles estão presentes, o usuário é impedido de interagir com o Planilhas.

 

 

Para criar uma caixa de diálogo personalizada, o código precisa do HTML que define seu conteúdo. Isso é fornecido na html variável. O conteúdo consiste em um texto de parágrafo curto e um hiperlink. O hiperlink é o presentationTitle, vinculado ao URL da apresentação fornecido por Presentation.getUrl(). O hiperlink também usa o target="_blank" atributo para que a apresentação seja aberta em uma nova guia do navegador, em vez de na própria caixa de diálogo.

O HTML é analisado em um HtmlOutput objeto pelo HtmlService.createHtmlOutput(html) método. O HtmlOutput objeto permite que o código defina o tamanho da caixa de diálogo personalizada com HtmlOutput.setHeight(height) e HtmlOutput.setWidth(width).

Depois de htmlOutput criado, o código usa o Ui.showModalDialog(htmlOutput, title) método para exibir a caixa de diálogo com o título fornecido.

 

Resultados

Agora que implementou o segundo item de menu, você pode vê-lo em ação! Faça o seguinte para testar a exportChartsToSlides()função:

  1. Se ainda não o fez, abra sua planilha e selecione o item de menu Conjunto de dados atual> Gráfico “Conjunto de dados de datas e taxas de câmbio do dólar americano” para criar um gráfico para exportar. Ele aparecerá ancorado na célula H5 na planilha ativa.
  2. Selecione o item de menu Apresentar conjunto de dados> Exportar gráficos para slides . Você pode ser solicitado a reautorizar o script.
  3. Você deve ver seu script processar a solicitação e, em seguida, exibir a caixa de diálogo personalizada. Clique no link Apresentação de Datas e Taxas de Câmbio do USD para abrir a nova apresentação:

    Se desejar, você também pode adicionar mais gráficos à planilha e selecionar novamente o item de menu para criar uma nova apresentação com vários slides.

 

 

Agora você pode exportar gráficos criados no Planilhas para uma apresentação do Google Slides! Você também pode escrever código para criar um diálogo personalizado!

 

O que você aprendeu?

  • Como construir um gráfico de linha incorporado com o Apps Script.
  • Como exportar um gráfico para um novo arquivo no Apresentações.
  • Como apresentar mensagens de notificação e caixas de diálogo personalizadas para o usuário no Planilhas.