Datas e horas

  1. Visão geral
  2. Datas e horas usando o construtor de data
  3. Datas, horas e fusos horários
  4. Datas e horas usando a representação de string de data
  5. Como trabalhar com Timeofday
  6. Formatar rótulos de eixo, linha de grade e marcação
  7. Mais informações sobre datas do JavaScript

Visão geral

Os tipos de dados da coluna date e datetime da coluna DataTable usam a classe de data JavaScript integrada.

Importante: em objetos JavaScript Date, os meses são indexados a partir de zero e vão até onze, sendo janeiro o mês 0 e dezembro o mês 11.

Datas e horas usando o construtor de data

Datas usando o construtor de data

Para criar um novo objeto Date, chame o construtor Date() com a palavra-chave new, com argumentos para especificar os componentes da data. Esses argumentos assumem a forma de vários números correspondentes às diferentes propriedades da data. 

new Date(Year, Month, Day, Hours, Minutes, Seconds, Milliseconds)

Ao usar o construtor de data com o tipo de dados date, você só precisa especificar o ano, o mês e o dia.

O construtor Date também pode assumir o seguinte formato: new Date(Milliseconds), em que milissegundos é a distância em milissegundos da data desejada a partir de 1o de janeiro de 1970 00:00:00 UTC. Para datas e horas anteriores a essa data, um número negativo de milissegundos seria fornecido.

O uso do construtor de data é útil ao criar manualmente seu DataTable usando os métodos addColumn(), addRow() e addRows(), bem como o método arrayToDataTable(). No entanto, se você estiver usando JSON para especificar dados, a representação de string precisará ser usada.

O construtor JavaScript Date também pode aceitar uma representação de string da data como um argumento. Essa string pode assumir várias formas diferentes. Os formulários mais confiáveis estão em conformidade com a especificação RFC 2822 ou a especificação ISO 8601 (links em inglês). Estes são os formatos disponíveis:

  • RFC 2822: 'MMM DD, YYYY' ou 'DD MMM, YYYY' (por exemplo: new Date('Jan 1, 2015') ou new Date('1 Jan, 2015'))
  • ISO 8601 - 'YYYY-MM-DD' (exemplo: new Date('2015-01-01'))

Aviso:a representação de string no construtor "Date" pode ser analisada de maneira diferente por navegadores e versões diferentes dos navegadores, retornando assim datas diferentes para a mesma string. Dessa forma, não é recomendado transmitir strings para o construtor Date. Em vez disso, recomendamos o uso de números apenas para os argumentos do construtor de Data.

A linha do tempo abaixo mostra o campeão do Super Bowl de cada temporada da NFL desde o ano de 2000.


Confira abaixo o código para criar essa linha do tempo. Observe o uso dos construtores new Date() e os números fornecidos para cada data usando meses com base no valor zero, conforme mencionado anteriormente. 

    google.charts.load('current', {'packages':['timeline']});
    google.charts.setOnLoadCallback(drawChart);

    function drawChart() {
      var data = new google.visualization.DataTable();
      data.addColumn('string', 'Team');
      data.addColumn('date', 'Season Start Date');
      data.addColumn('date', 'Season End Date');

      data.addRows([
        ['Baltimore Ravens',     new Date(2000, 8, 5), new Date(2001, 1, 5)],
        ['New England Patriots', new Date(2001, 8, 5), new Date(2002, 1, 5)],
        ['Tampa Bay Buccaneers', new Date(2002, 8, 5), new Date(2003, 1, 5)],
        ['New England Patriots', new Date(2003, 8, 5), new Date(2004, 1, 5)],
        ['New England Patriots', new Date(2004, 8, 5), new Date(2005, 1, 5)],
        ['Pittsburgh Steelers',  new Date(2005, 8, 5), new Date(2006, 1, 5)],
        ['Indianapolis Colts',   new Date(2006, 8, 5), new Date(2007, 1, 5)],
        ['New York Giants',      new Date(2007, 8, 5), new Date(2008, 1, 5)],
        ['Pittsburgh Steelers',  new Date(2008, 8, 5), new Date(2009, 1, 5)],
        ['New Orleans Saints',   new Date(2009, 8, 5), new Date(2010, 1, 5)],
        ['Green Bay Packers',    new Date(2010, 8, 5), new Date(2011, 1, 5)],
        ['New York Giants',      new Date(2011, 8, 5), new Date(2012, 1, 5)],
        ['Baltimore Ravens',     new Date(2012, 8, 5), new Date(2013, 1, 5)],
        ['Seattle Seahawks',     new Date(2013, 8, 5), new Date(2014, 1, 5)],
      ]);

      var options = {
        height: 450,
        timeline: {
          groupByRowLabel: true
        }
      };

      var chart = new google.visualization.Timeline(document.getElementById('chart_div'));

      chart.draw(data, options);
    }

Data e hora usando o construtor Date

O tipo de dados da coluna datetime do DataTable usa o mesmo construtor Date que o tipo de dados date, mas agora usa todos os argumentos para preencher o horário.

Como alternativa, uma representação de string de datetime também pode ser transmitida para o construtor de data. Uma representação de string de datetime consiste em adicionar as horas, os minutos e os segundos, além da diferença do fuso horário de quatro dígitos. Por exemplo, o horário padrão do Pacífico (PST, na sigla em inglês) é -0800. Para a especificação RFC 2822, a hora e o fuso horário são adicionados com espaços entre a data, a hora, a hora e o fuso horário. Na especificação ISO 8601, não há espaços. Em vez disso, a data é seguida por um "T" maiúsculo para indicar um componente de hora. Também não há espaço entre a hora e o deslocamento de fuso horário. A string datetime completa da data de 6 de dezembro de 2014 às 10h30 PST seria:

  • RFC 2822 — Dec 6, 2014 10:30:00 -0800.
  • ISO 8601 — 2014-12-06T10:30:00-0800

Aviso:novamente, a representação da string pode ser analisada de maneira diferente por navegadores/versões diferentes. É importante ressaltar que, ao lidar com horas e fusos horários, há diferenças no retorno da data e hora com um fuso horário UTC (GMT) ou uma diferença e retorno na hora local. Esse é outro motivo pelo qual o uso de strings de data e hora não é recomendado.

A linha do tempo abaixo detalha um dia médio usando o tipo de dados datetime. 

    google.charts.load('current', {'packages':['timeline']});
    google.charts.setOnLoadCallback(drawChart);

    function drawChart() {
      var data = google.visualization.arrayToDataTable([
        ['Activity', 'Start Time', 'End Time'],
        ['Sleep',
         new Date(2014, 10, 15, 0, 30),
         new Date(2014, 10, 15, 6, 30)],
        ['Eat Breakfast',
         new Date(2014, 10, 15, 6, 45),
         new Date(2014, 10, 15, 7)],
        ['Get Ready',
         new Date(2014, 10, 15, 7, 4),
         new Date(2014, 10, 15, 7, 30)],
        ['Commute To Work',
         new Date(2014, 10, 15, 7, 30),
         new Date(2014, 10, 15, 8, 30)],
        ['Work',
         new Date(2014, 10, 15, 8, 30),
         new Date(2014, 10, 15, 17)],
        ['Commute Home',
         new Date(2014, 10,  15, 17),
         new Date(2014, 10,  15, 18)],
        ['Gym',
         new Date(2014, 10, 15, 18),
         new Date(2014, 10,  15, 18, 45)],
        ['Eat Dinner',
         new Date(2014, 10,  15, 19),
         new Date(2014, 10,  15, 20)],
        ['Get Ready For Bed',
         new Date(2014, 10,  15, 21),
         new Date(2014, 10,  15, 22)]
      ]);

      var options = {
        height: 450,
      };

      var chart = new google.visualization.Timeline(document.getElementById('chart_div'));

      chart.draw(data, options);
    }

Datas, horas e fusos horários

O uso do construtor Date, seja para date ou datetime, retornará a data ou data e hora desejadas no fuso horário definido pelo navegador do usuário. Há algumas maneiras de configurar o objeto Date em um fuso horário específico. Primeiro, o Google Charts fornece um formatador de data em que você pode especificar um timeZone. Isso vai fornecer um valor formatado para cada um dos valores date e datetime no DataTable. Você também pode transmitir uma string como argumento para o construtor new Date() ou unir os argumentos no método Date.UTC(), por exemplo: 

new Date(Date.UTC(Year, Month, Day, Hours, Minutes, Seconds, Milliseconds))

Isso definirá um objeto "Date" como a data e a hora especificadas no fuso horário UTC (GMT). A partir daí, você pode calcular a compensação de fuso horário e definir as datas e os horários conforme desejado.

Datas e horas usando a representação de string de data

Ao serializar dados usando a notação literal do objeto DataTable do JavaScript para criar o DataTable, não é possível usar o construtor new Date(). Em vez disso, o Google Charts fornece uma representação de string de data que permite que date ou datetime sejam serializados e analisados corretamente ao criar um DataTable. Esse formato de string de data simplesmente descarta a palavra-chave new e une a expressão restante entre aspas: 

"Date(Year, Month, Day, Hours, Minutes, Seconds, Milliseconds)"

Importante:ao usar essa representação de string de data, assim como ao usar o construtor new Date(), os meses são indexados a partir de zero (janeiro é o mês 0, dezembro é o mês 11).

Veja abaixo a mesma linha do tempo do Super Bowl de antes, mas agora usando a notação literal de objeto JavaScript e o formato de string Date. 

    google.charts.load('current', {'packages':['timeline']});
    google.charts.setOnLoadCallback(drawChart);

    function drawChart() {
      var data = new google.visualization.DataTable({

        cols: [
          {id: 'team', label: 'Team', type: 'string'},
          {id: 'start', label: 'Season Start Date', type: 'date'},
          {id: 'end', label: 'Season End Date', type: 'date'}
        ],

        rows: [
          {c: [{v: 'Baltimore Ravens'},     {v: 'Date(2000, 8, 5)'}, {v: 'Date(2001, 1, 5)'}]},
          {c: [{v: 'New England Patriots'}, {v: 'Date(2001, 8, 5)'}, {v: 'Date(2002, 1, 5)'}]},
          {c: [{v: 'Tampa Bay Buccaneers'}, {v: 'Date(2002, 8, 5)'}, {v: 'Date(2003, 1, 5)'}]},
          {c: [{v: 'New England Patriots'}, {v: 'Date(2003, 8, 5)'}, {v: 'Date(2004, 1, 5)'}]},
          {c: [{v: 'New England Patriots'}, {v: 'Date(2004, 8, 5)'}, {v: 'Date(2005, 1, 5)'}]},
          {c: [{v: 'Pittsburgh Steelers'},  {v: 'Date(2005, 8, 5)'}, {v: 'Date(2006, 1, 5)'}]},
          {c: [{v: 'Indianapolis Colts'},   {v: 'Date(2006, 8, 5)'}, {v: 'Date(2007, 1, 5)'}]},
          {c: [{v: 'New York Giants'},      {v: 'Date(2007, 8, 5)'}, {v: 'Date(2008, 1, 5)'}]},
          {c: [{v: 'Pittsburgh Steelers'},  {v: 'Date(2008, 8, 5)'}, {v: 'Date(2009, 1, 5)'}]},
          {c: [{v: 'New Orleans Saints'},   {v: 'Date(2009, 8, 5)'}, {v: 'Date(2010, 1, 5)'}]},
          {c: [{v: 'Green Bay Packers'},    {v: 'Date(2010, 8, 5)'}, {v: 'Date(2011, 1, 5)'}]},
          {c: [{v: 'New York Giants'},      {v: 'Date(2011, 8, 5)'}, {v: 'Date(2012, 1, 5)'}]},
          {c: [{v: 'Baltimore Ravens'},     {v: 'Date(2012, 8, 5)'}, {v: 'Date(2013, 1, 5)'}]},
          {c: [{v: 'Seattle Seahawks'},     {v: 'Date(2013, 8, 5)'}, {v: 'Date(2014, 1, 5)'}]}
        ]
      });

      var options = {
        height: 450,
        timeline: {
          groupByRowLabel: true
        }
      };

      var chart = new google.visualization.Timeline(document.getElementById('chart_div'));

      chart.draw(data, options);
    }

Esse formato também pode ser usado no método arrayToDataTable(), desde que na primeira matriz, em que os rótulos de coluna são especificados, você declare a coluna necessária como type: 'date' ou type: 'datetime'. 

var data = google.visualization.arrayToDataTable([
  ["Team", {type: 'date', label: 'Season Start Date'}, {type: 'date', label: 'Season End Date'}],
  ["Baltimore Ravens",     "Date(2000, 8, 5)", "Date(2001, 1, 5)"],
  ["New England Patriots", "Date(2001, 8, 5)", "Date(2002, 1, 5)"],
  ["Tampa Bay Buccaneers", "Date(2002, 8, 5)", "Date(2003, 1, 5)"],
  ["New England Patriots", "Date(2003, 8, 5)", "Date(2004, 1, 5)"],
  ["New England Patriots", "Date(2004, 8, 5)", "Date(2005, 1, 5)"],
  ["Pittsburgh Steelers",  "Date(2005, 8, 5)", "Date(2006, 1, 5)"],
  ["Indianapolis Colts",   "Date(2006, 8, 5)", "Date(2007, 1, 5)"],
  ["New York Giants",      "Date(2007, 8, 5)", "Date(2008, 1, 5)"],
  ["Pittsburgh Steelers",  "Date(2008, 8, 5)", "Date(2009, 1, 5)"],
  ["New Orleans Saints",   "Date(2009, 8, 5)", "Date(2010, 1, 5)"],
  ["Green Bay Packers",    "Date(2010, 8, 5)", "Date(2011, 1, 5)"],
  ["New York Giants",      "Date(2011, 8, 5)", "Date(2012, 1, 5)"],
  ["Baltimore Ravens",     "Date(2012, 8, 5)", "Date(2013, 1, 5)"],
  ["Seattle Seahawks",     "Date(2013, 8, 5)", "Date(2014, 1, 5)"]
]);

Como trabalhar com Timeofday

O tipo de dados da coluna timeofday do DataTable usa uma matriz de três ou quatro números, representando horas, minutos, segundos e, opcionalmente, milissegundos, respectivamente. Usar timeofday é diferente de usar date e datetime, porque os valores não são específicos de uma data, enquanto date e datetime sempre especificam uma data.

Por exemplo, o horário 8:30 seria: [8, 30, 0, 0], com o quarto valor opcional ([8, 30, 0] produziria o mesmo valor timeofday). 

    google.charts.load('current', {'packages':['bar']});
    google.charts.setOnLoadCallback(drawChart);

    function drawChart() {

      var data = new google.visualization.DataTable();
      data.addColumn('timeofday', 'Time of Day');
      data.addColumn('number', 'Emails Received');

      data.addRows([
        [[8, 30, 45], 5],
        [[9, 0, 0], 10],
        [[10, 0, 0, 0], 12],
        [[10, 45, 0, 0], 13],
        [[11, 0, 0, 0], 15],
        [[12, 15, 45, 0], 20],
        [[13, 0, 0, 0], 22],
        [[14, 30, 0, 0], 25],
        [[15, 12, 0, 0], 30],
        [[16, 45, 0], 32],
        [[16, 59, 0], 42]
      ]);

      var options = {
        title: 'Total Emails Received Throughout the Day',
        height: 450
      };

      var chart = new google.charts.Bar(document.getElementById('chart_div'));

      chart.draw(data, google.charts.Bar.convertOptions(options));
    }

Formatar rótulos de eixo, linha de grade e marcação

Ao trabalhar com datas, datetime e timeofday, você pode formatar os rótulos dos eixos, das linhas de grade ou das marcações de uma determinada maneira. Isso pode ser feito de algumas maneiras.

Primeiro, use a opção hAxis.format ou vAxis.format. Essa opção se aplica quando a opção gridlines.count é omitida. Nesse caso, o padrão do gráfico é a contagem de 5, bem como quando é definido como um número diferente de -1. Isso permite especificar uma string de formato em que você usa letras de marcador para diferentes partes da data/hora/hora. Consulte a referência do formatador de data, especificamente a seção pattern, para mais informações sobre os marcadores de posição e como eles funcionam. 

      google.charts.load('current', {'packages':['corechart']});
      google.charts.setOnLoadCallback(drawChart);

      function drawChart() {

        var data = new google.visualization.DataTable();
        data.addColumn('date', 'Time of Day');
        data.addColumn('number', 'Rating');

        data.addRows([
          [new Date(2015, 0, 1), 5],  [new Date(2015, 0, 2), 7],  [new Date(2015, 0, 3), 3],
          [new Date(2015, 0, 4), 1],  [new Date(2015, 0, 5), 3],  [new Date(2015, 0, 6), 4],
          [new Date(2015, 0, 7), 3],  [new Date(2015, 0, 8), 4],  [new Date(2015, 0, 9), 2],
          [new Date(2015, 0, 10), 5], [new Date(2015, 0, 11), 8], [new Date(2015, 0, 12), 6],
          [new Date(2015, 0, 13), 3], [new Date(2015, 0, 14), 3], [new Date(2015, 0, 15), 5],
          [new Date(2015, 0, 16), 7], [new Date(2015, 0, 17), 6], [new Date(2015, 0, 18), 6],
          [new Date(2015, 0, 19), 3], [new Date(2015, 0, 20), 1], [new Date(2015, 0, 21), 2],
          [new Date(2015, 0, 22), 4], [new Date(2015, 0, 23), 6], [new Date(2015, 0, 24), 5],
          [new Date(2015, 0, 25), 9], [new Date(2015, 0, 26), 4], [new Date(2015, 0, 27), 9],
          [new Date(2015, 0, 28), 8], [new Date(2015, 0, 29), 6], [new Date(2015, 0, 30), 4],
          [new Date(2015, 0, 31), 6], [new Date(2015, 1, 1), 7],  [new Date(2015, 1, 2), 9]
        ]);


        var options = {
          title: 'Rate the Day on a Scale of 1 to 10',
          width: 900,
          height: 500,
          hAxis: {
            format: 'M/d/yy',
            gridlines: {count: 15}
          },
          vAxis: {
            gridlines: {color: 'none'},
            minValue: 0
          }
        };

        var chart = new google.visualization.LineChart(document.getElementById('chart_div'));

        chart.draw(data, options);

        var button = document.getElementById('change');

        button.onclick = function () {

          // If the format option matches, change it to the new option,
          // if not, reset it to the original format.
          options.hAxis.format === 'M/d/yy' ?
          options.hAxis.format = 'MMM dd, yyyy' :
          options.hAxis.format = 'M/d/yy';

          chart.draw(data, options);
        };
      }

Também é possível fornecer regras de formatação para unidades específicas de valores de data e hora incluindo uma opção units em gridlines e minorGridlines para os dois eixos. Essa opção só vai ser usada se gridlines.count for definida como -1.

A opção gridlines.units é um objeto em que você especifica o formato dos diferentes aspectos de data/hora/hora da linha de grade calculada, e seu gráfico vai calcular as linhas de grade com base no primeiro formato que se encaixa no espaço do rótulo da linha de grade. É possível definir os formatos para anos, meses, dias, horas, minutos, segundos e milissegundos.

A opção de formato aceita uma matriz de formatos de string e os usa em ordem até que um formato se encaixe na área do rótulo. Por esse motivo, é recomendável listar os formatos em ordem, do maior para o mais curto. Os formatos de string usam os mesmos padrões que a referência do formatador de data mencionada anteriormente.


No gráfico acima, ao alterar a janela de visualização, o formato da unidade hours muda, já que as horas mudam de linhas de grade secundárias para as principais, e o formato das opções muda com elas. Além disso, menoresGridlines estão usando o segundo formato mais curto, já que os primeiros formatos não cabem no espaço em cada instância. 

        hAxis: {
          viewWindow: {
            min: new Date(2014, 11, 31, 18),
            max: new Date(2015, 0, 3, 1)
          },
          gridlines: {
            count: -1,
            units: {
              days: {format: ['MMM dd']},
              hours: {format: ['HH:mm', 'ha']},
            }
          },
          minorGridlines: {
            units: {
              hours: {format: ['hh:mm:ss a', 'ha']},
              minutes: {format: ['HH:mm a Z', ':mm']}
            }
          }
        }

Mais informações sobre datas do JavaScript

Se você quiser saber mais sobre o objeto Date() JavaScript, a Mozilla Developer Network é um ótimo recurso. Lá você aprende tudo sobre objetos de data JavaScript.