Date

Esta tradução está incompleta. Ajude atraduzir este artigo.

Resumo

Cria uma instância JavaScript de Date que representa um único momento no tempo. Objetos Date são baseados no valor de tempo que é o número de milisegundos desde 1 de Janeiro de 1970 (UTC).

Construtor

new Date();
new Date(valor);
new Date(dataString);
new Date(ano, mês, dia, hora, minuto, segundo, milissegundo);

Note: Note que objetos JavaScript Date só podem ser instanciados chamando JavaScript Date como um construtor: chamá-lo como uma função regular (ou seja, sem o operador new) irá retornar uma string ao invés de um objeto Date; ao contrário de outros tipos de objetos JavaScript, objetos JavaScript Date não têm sintaxe literal.

Parâmetros para o constructor Date

Nota: Quando Date for chamado como um construtor com mais de um argumento, se os valores forem maiores do que seu limite lógico (e.g. se 13 for fornecido como um valor para mês ou 70 for o valor para minuto), o valor adjacente será ajustado. E.g. new Date(2013, 13, 1) é equivalente a new Date(2014, 1, 1), ambos criam uma data para 2014-02-01 (note que o mês começa em 0). Similarmente para outros valores: new Date(2013, 2, 1, 0, 70) é equivalente a new Date(2013, 2, 1, 1, 10), pois ambos criam uma data para 2013-03-01T01:10:00.

valor
Um valor inteiro representando o número de milisegundos desde 1 de Janeiro de 1970 00:00:00 UTC (Era Unix ou Marco Zero).
dataString
Um valor do tipo String que representa uma data. A string deverá estar uma formato reconhecido pelo método Date.parse() (IETF-compliant RFC 2822 timestamps e também uma versão da ISO8601).
ano
Um valor inteiro que representa o ano. Valores de 0 a 99 correspondem aos anos de 1900 a 1999. Veja o exemplo abaixo.
mês
Um valor inteiro que representa o mês, começando com 0 para Janeiro até 11 para Dezembro.
dia
Um valor inteiro que representa o dia do mês.
hora
Um valor inteiro que representa a hora do dia.
minuto
Um valor inteiro que representa o segmento de um minuto de tempo.
segundo
Um valor inteiro que representa o segmento de segundo do tempo.
milisegundo
Um valor inteiro que representa o segmento de milisegundo do tempo.

Descrição

  • Se nenhum argumento for fornecido, o construtor criará um objeto JavaScript Date com a data e hora corrente de acordo com as configurações do sistema.
  • Se ao menos 2 argumentos forem fornecidos, os argumentos ausentes serão configurados como 1 (se o dia estiver ausente) ou 0 para todos os outros.
  • A data do JavaScript é baseada no valor de tempo em milisegundos desde a meia noite de 01 de Janeiro de 1970, UTC. Um dia corresponde a 86.400,000 milisegundos. O intervalo do objeto Date no JavaScript é de -100.000,000 dias a 100.000,000 dias relativo a 01 de Janeiro de 1970, UTC.
  • O objeto Date no JavaScript tem um comportamento uniforme nas plataformas. O valor do tempo pode ser transmitido entre sistemas para representar o mesmo instante no tempo e se for usado para criar um objeto de data local, ele refletirá o tempo local equivalente.
  • O objeto Date JavaScript suporta vários métodos UTC (universal), assim como métodos de tempo locais. UTC, também conhecido como Tempo Médio de Greenwich (Greenwich Mean Time, GMT), refere-se ao tempo como definido pelo Padrão de Tempo Mundial (World Time Standard). O tempo local é o tempo conhecido pelo computador onde o JavaScript é executado.
  • Invocar o objeto Date no JavaScript como uma função (i.e., sem o operador new) retornatá uma string representando a data e hora corrente.

Propriedades

For properties available on Date instances, see Properties of Date instances.

Date.prototype
Permite adicionar propriedades a um objeto javaScript Date.
Date.length
O valor de Date.length é 7. Esse é o número de argumentos manipulados pelo construtor.

Properties inherited from Function:

Métodos

For methods available on Date instances, see Methods of Date instances.

Date.now()
Retorna o valor numérico correspondente ao tempo corrente - o número de milisegundos passados desde 1 de Janeiro de 1970 00:00:00 UTC.
Date.parse()
Analisa uma string que representa uma data e retorna o número de milisegundos desde 1 de Janeiro, 1970, 00:00:00, hora local.
Date.UTC()
Aceita os mesmos parâmetros como a forma mais longa do construtor (i.e. 2 até 7) e retorna o número de milisegundos desde 1 de Janeiro, 1970, 00:00:00 UTC. 

Methods inherited from Function:

Instâncias JavaScript de Date 

Todas as instâncias Date são herdadas de Date.prototype. O objeto protótipo do construtor Date pode ser modificado para afetar todas as instâncias de Date.

Métodos

Getter

Date.prototype.getDate()
Returns the day of the month (1-31) for the specified date according to local time.
Date.prototype.getDay()
Returns the day of the week (0-6) for the specified date according to local time.
Date.prototype.getFullYear()
Returns the year (4 digits for 4-digit years) of the specified date according to local time.
Date.prototype.getHours()
Returns the hour (0-23) in the specified date according to local time.
Date.prototype.getMilliseconds()
Returns the milliseconds (0-999) in the specified date according to local time.
Date.prototype.getMinutes()
Returns the minutes (0-59) in the specified date according to local time.
Date.prototype.getMonth()
Returns the month (0-11) in the specified date according to local time.
Date.prototype.getSeconds()
Returns the seconds (0-59) in the specified date according to local time.
Date.prototype.getTime()
Returns the numeric value of the specified date as the number of milliseconds since January 1, 1970, 00:00:00 UTC (negative for prior times).
Date.prototype.getTimezoneOffset()
Returns the time-zone offset in minutes for the current locale.
Date.prototype.getUTCDate()
Returns the day (date) of the month (1-31) in the specified date according to universal time.
Date.prototype.getUTCDay()
Returns the day of the week (0-6) in the specified date according to universal time.
Date.prototype.getUTCFullYear()
Returns the year (4 digits for 4-digit years) in the specified date according to universal time.
Date.prototype.getUTCHours()
Returns the hours (0-23) in the specified date according to universal time.
Date.prototype.getUTCMilliseconds()
Returns the milliseconds (0-999) in the specified date according to universal time.
Date.prototype.getUTCMinutes()
Returns the minutes (0-59) in the specified date according to universal time.
Date.prototype.getUTCMonth()
Returns the month (0-11) in the specified date according to universal time.
Date.prototype.getUTCSeconds()
Returns the seconds (0-59) in the specified date according to universal time.
Date.prototype.getYear()
Returns the year (usually 2-3 digits) in the specified date according to local time. Use getFullYear() instead.

Setter

Date.prototype.setDate()
Sets the day of the month for a specified date according to local time.
Date.prototype.setFullYear()
Sets the full year (e.g. 4 digits for 4-digit years) for a specified date according to local time.
Date.prototype.setHours()
Sets the hours for a specified date according to local time.
Date.prototype.setMilliseconds()
Sets the milliseconds for a specified date according to local time.
Date.prototype.setMinutes()
Sets the minutes for a specified date according to local time.
Date.prototype.setMonth()
Sets the month for a specified date according to local time.
Date.prototype.setSeconds()
Sets the seconds for a specified date according to local time.
Date.prototype.setTime()
Sets the Date object to the time represented by a number of milliseconds since January 1, 1970, 00:00:00 UTC, allowing for negative numbers for times prior.
Date.prototype.setUTCDate()
Sets the day of the month for a specified date according to universal time.
Date.prototype.setUTCFullYear()
Sets the full year (e.g. 4 digits for 4-digit years) for a specified date according to universal time.
Date.prototype.setUTCHours()
Sets the hour for a specified date according to universal time.
Date.prototype.setUTCMilliseconds()
Sets the milliseconds for a specified date according to universal time.
Date.prototype.setUTCMinutes()
Sets the minutes for a specified date according to universal time.
Date.prototype.setUTCMonth()
Sets the month for a specified date according to universal time.
Date.prototype.setUTCSeconds()
Sets the seconds for a specified date according to universal time.
Date.prototype.setYear()
Sets the year (usually 2-3 digits) for a specified date according to local time. Use setFullYear() instead.

Conversion getter

Date.prototype.toDateString()
Returns the "date" portion of the Date as a human-readable string.
Date.prototype.toISOString()
Converts a date to a string following the ISO 8601 Extended Format.
Date.prototype.toJSON()
Returns a string representing the Date using toISOString(). Intended for use by JSON.stringify().
Date.prototype.toGMTString()
Returns a string representing the Date based on the GMT (UT) time zone. Use toUTCString() instead.
Date.prototype.toLocaleDateString()
Returns a string with a locality sensitive representation of the date portion of this date based on system settings.
Date.prototype.toLocaleFormat()
Converts a date to a string, using a format string.
Date.prototype.toLocaleString()
Returns a string with a locality sensitive representation of this date. Overrides the Object.prototype.toLocaleString() method.
Date.prototype.toLocaleTimeString()
Returns a string with a locality sensitive representation of the time portion of this date based on system settings.
Date.prototype.toSource()
Returns a string representing the source for an equivalent Date object; you can use this value to create a new object. Overrides the Object.prototype.toSource() method.
Date.prototype.toString()
Returns a string representing the specified Date object. Overrides the Object.prototype.toString() method.
Date.prototype.toTimeString()
Returns the "time" portion of the Date as a human-readable string.
Date.prototype.toUTCString()
Converts a date to a string using the UTC timezone.
Date.prototype.valueOf()
Returns the primitive value of a Date object. Overrides the Object.prototype.valueOf() method.

Exemplos

Exemplo: Várias formas de se criar um objeto Date

Os seguintes exemplos mostram várias formas de se criar datas em JavaScript: 

var today = new Date();
var birthday = new Date("December 17, 1995 03:24:00");
var birthday = new Date("1995-12-17T03:24:00");
var birthday = new Date(1995,11,17);
var birthday = new Date(1995,11,17,3,24,0);

Exemplo: Anos com dois dígitos mapeados para 1900 - 1999

De forma a criar e recuperar datas entre os anos 0 e 99 os métodos Date.prototype.setFullYear()Date.prototype.getFullYear() devem ser usados.

var date = new Date(98, 1); // Dom Fev 01 1998 00:00:00 GMT+0000 (GMT)

// Métodos em desuso, 98 mapeia para 1998 aqui também
date.setYear(98);           // Dom Fev 01 1998 00:00:00 GMT+0000 (GMT)

date.setFullYear(98);       // Sab Fev 01 0098 00:00:00 GMT+0000 (BST)

Exemplo: Calculando tempo decorrido

Os seguintes exemplos mostram como determinar o tempo decorrido entre duas datas no JavaScript:

// usando objetos Date
var inicio = Date.now();

// o evento para o tempo vai aqui:
facaAlgoPorUmLongoTempo();
var fim = Date.now();
var decorrido = fim - inicio; // tempo decorrido em milisegundos
// utilizando métodos embutidos
var inicio = new Date();

// o evento para o tempo vai aqui:
facaAlgoPorUmLongoTempo();
var fim = new Date();
var decorrido = fim.getTime() - inicio.getTime(); // tempo decorrido em milisegundos
// para testar uma função e pegar o seu retorno
function imprimirTempoDecorrido (fTeste) {
	var nTempoInicial = Date.now(), 
            vRetorno = fTeste(),
            nTempoFinal = Date.now();

	alert("Tempo decorrido: " + String(nTempoFinal - nTempoInicial) + " milisegundos");
	return vRetorno;
}

retornoDaSuaFuncao = imprimirTempoDecorrido(suaFuncao);

Nota: Em navegadores que suportam a API de Desempenho Web (Web Performance API's) com o recurso de tempo de alta resolução, window.performance.now pode fornecer medidas de tempo decorrido mais confiáveis e precisas do que Date.now.

Especificações

Especificação Estado Comentário
ECMAScript 1º Edição. Implementado em  JavaScript 1.1 Padrão Definição Inicial.
ECMAScript 5.1 (ECMA-262)
The definition of 'Date' in that specification.
Standard  
ECMAScript 6 (ECMA-262)
The definition of 'Date' in that specification.
Release Candidate  

Compatibilidade dos navegadores

Recurso Chrome Firefox (Gecko) Internet Explorer Opera Safari
Suporte Básico (Yes) (Yes) (Yes) (Yes) (Yes)
Recurso Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Suporte Básico (Yes) (Yes) (Yes) (Yes) (Yes) (Yes)

Relatórios de compatibilidade dos navegadores

Etiquetas do documento e colaboradores

Etiquetas: 
Contributors to this page: fnsc.luis, daniloazevedo, teoli, BargaoRobalo
Última atualização por: fnsc.luis,
Esconder painel