Date

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Los objetos Date representan en JavaScript un momento fijo en el tiempo en un formato independiente. El objeto Date contiene un Number que representa los milisegundos transcurridos desde el 1 de Enero de 1970 UTC.

Nota: TC39 está trabajando en Temporal, una nueva API de Date/Time. Lee más acerca de ello en el blog Igalia. Aún no está lista para su uso en producción.

Descripción

La época ECMAScript y la marca temporal

Una fecha en JavaScript es fundamentalmente especificada como el número de milisegundos que han pasado desde la Época ECMAScript la cuál está definida como el 1 de Enero de 1970, UTC. Esta fecha y hora no son los mismos que en la Época Unix (el número de segundos que han pasado desde la media noche del 1 de Enero de 1970, UTC), el cual es el valor predominante base para representar los valores de fecha y hora en los ordenadores.

Nota: Es importante tener en cuenta que mientras el valor de la hora en el núcleo del objeto Date está en UTC, los métodos básicos para recibir la fecha y la hora o sus derivados trabajan todos en la zona horaria local (por ejemplo: máquina huesped).

Se debe tener en cuenta que el valor máximo de Date no es el mismo que el valor del máximo entero seguro (Number.MAX_SAFE_INTEGER es 9,007,199,254,740,991). En su lugar, fue definido en ECMA-262 que un máximo de ±100,000,000 (cien millones) días relativos al 1 de Enero de 1970, UTC (que es, 20 de Abril de 271821 a. e. c. ~ 13 de Septiembre de 275760 a. e. c.) pueden ser representados por el objeto estandar Date (equivalente a ±8,640,000,000,000,000 milisegundos).

Formato de fecha y conversiones de zona horaria

Hay muchos métodos disponibles para obtener una fecha en distintos formatos, también para representar conversiones de zona horaria. Son particularmente útiles las funciones que retornan la fecha y la hora en Tiempo Universal Coordinado (UTC), la hora estandar global definida por la Hora Mundial Estandar. (Esta hora tambien es conocida como Hora media de Greenwich, ) así como UTC depende del meridiano que incluye London y zonas de Reino Unido cercanas a Greenwich. El dispositivo del usuario provee la hora local.

Sumado a los métodos para leer y manipular los componentes individuales de la fecha y la hora local (tales como getDay() y setHours()), hay también versiones de los mismos métodos que leen y manipulan la fecha y la hora usando UTC (tales como getUTCDay() y setUTCHours()).

Constructor

Date(): Cuando es llamado como una función, retorna una cadena que representa la fecha y hora actual, exactamente como lo hace new Date().toString().
new Date(): Cuando es llamado como un constructor, retorna un nuevo objeto Date.

Métodos estáticos

Date.now(): Devuelve el valor númerico correspondiente al actual número de milisegundos transcurridos desde el 1 de Enero de 1970, 00:00:00 UTC, ignorando los segundos intercalares.
Date.parse(): Transforma la cadena que representa una fecha y retorna el número de milisegundos transcurridos desde el 1 de Enero de 1970, 00:00:00 UTC, ignorando los segundos intercalares.

Nota: Transforma las cadenas con Date.parse es muy poco recomendado debido a diferencias e inconsistencias entre navegadores.
Date.UTC(): Acepta los mismos parámetros de la forma extendida del constructor (por ejemplo: del 2 al 7 ) y retorna el número de milisegundos transcurridos desde el 1 de Enero de 1970, 00:00:00 UTC, ignorando los segundos intercalares.

Métodos de instanciación

Date.prototype.getDate(): Retorna el día del mes (1–31) para la fecha especificada acorde a la hora local.
Date.prototype.getDay(): Retorna el día de la semana (0–6) para la fecha especificada acorde a la hora local.
Date.prototype.getFullYear(): Retorna el año (4 dígitos para años de 4 dígitos) para la fecha especificada acorde a la hora local.
Date.prototype.getHours(): Retorna la hora (0–23) para la fecha especificada acorde a la hora local.
Date.prototype.getMilliseconds(): Retorna los milisegundos (0–999) para la fecha especificada acorde a la hora local.
Date.prototype.getMinutes(): Retorna los minutos (0–59) para la fecha especificada acorde a la hora local.
Date.prototype.getMonth(): Retorna el mes (0–11) para la fecha especificada acorde a la hora local.
Date.prototype.getSeconds(): Retorna los segundos (0–59) para la fecha especificada acorde a la hora local.
Date.prototype.getTime(): Retorna el valor númerico de la fecha especificada como el número de milisegundos transcurridos desde el 1 de Enero de 1970, 00:00:00 UTC. (Retona valores negativos para fechas previas.)
Date.prototype.getTimezoneOffset(): Retona la diferencia horaria en minutos para la hora local.
Date.prototype.getUTCDate(): Retorna el día (fecha) del mes (1–31) para la fecha especificada acorde a la hora local.
Date.prototype.getUTCDay(): Retona el día de la semana (0–6) para la fecha especificada en hora universal.
Date.prototype.getUTCFullYear(): Retona el año (4 dígitos para años de 4 dígitos) para la fecha especificada acorde a la hora universal.
Date.prototype.getUTCHours(): Retona la hora (0–23) para la fecha especificada acorde a la hora universal.
Date.prototype.getUTCMilliseconds(): Retona los milisegundos (0–999) para la fecha especificada acorde a la hora universal.
Date.prototype.getUTCMinutes(): Retorna los minutos (0–59) para la fecha especificada acorde a la hora universal.
Date.prototype.getUTCMonth(): Retonar el mes (0–11) para la fecha especificada acorde a la hora universal.
Date.prototype.getUTCSeconds(): Retorna los segundos (0–59) para la fecha especificada acorde a la hora universal.
Date.prototype.getYear(): Retorna el año (usualmente de 2 a 3 dígitos) para la fecha especificada acorde a la hora local. Usa getFullYear() en su lugar.
Date.prototype.setDate(): Establece el día del mes para la fecha especificada acorde a la hora local.
Date.prototype.setFullYear(): Establece el año completo (ej. 4 dígitos para años de 4 dígitos) para una fecha espefica acorde a la hora local.
Date.prototype.setHours(): Establece la hora para una fecha especifica acorde a la hora local.
Date.prototype.setMilliseconds(): Establece los milisegundos para una fecha especifica acorde a la hora local.
Date.prototype.setMinutes(): Establece los minutos para una fecha especifica acorde a la hora local.
Date.prototype.setMonth(): Establece el mes para una fecha especifica acorde a la hora local.
Date.prototype.setSeconds(): Establece los segundos para una fecha especifica acorde a la hora local.
Date.prototype.setTime(): Establece el objeto Date al tiempo representado por un número de milisegundos desde el 1 de Enero de 1970, 00:00:00 UTC. Usa números negativos para fechas previas.
Date.prototype.setUTCDate(): Establece el día del mes para la fecha especificada acorde a la hora universal.
Date.prototype.setUTCFullYear(): Establece el año completo (ej. 4 dígitos para años de 4 dígitos) para una fecha espefica acorde a la hora universal.
Date.prototype.setUTCHours(): Establece la hora para una fecha especifica acorde a la hora universal.
Date.prototype.setUTCMilliseconds(): Establece los milisegundos para una fecha especifica acorde a la hora universal.
Date.prototype.setUTCMinutes(): Establece los minutos para una fecha especifica acorde a la hora universal.
Date.prototype.setUTCMonth(): Establece el mes para una fecha especifica acorde a la hora universal.
Date.prototype.setUTCSeconds(): Establece los segundos para una fecha especifica acorde a la hora universal.
Date.prototype.setYear(): Establece el año (usualmente de 2 a 3 dígitos) para una fecha especifica acorde a la hora local. Usa setFullYear() en su lugar.
Date.prototype.toDateString(): Retona la "fecha" del objeto Date como una cadena facil de leer por humanos 'Thu Apr 12 2018'.
Date.prototype.toISOString(): Convierte una fecha a una cadena siguiendo el ISO 8601 de Formato Extendido.
Date.prototype.toJSON(): Retorna una cadena representando el objeto Date usando toISOString(). Destinado a ser usado por JSON.stringify().
Date.prototype.toGMTString(): Retona una cadena representando el objeto Date basado en la zona horaria GMT (UTC). Usa toUTCString() en su lugar.
Date.prototype.toLocaleDateString(): Retorna una cadena con una representación sensible a la localización de la fecha basada en la configuración del sistema.
Date.prototype.toLocaleString(): Retorna una cadena con una representación sensible a la localización de esta fecha. Sobrescribe el método Object.prototype.toLocaleString().
Date.prototype.toLocaleTimeString(): Retorna una cadena con una representación sensible a la localización de la fecha basada en la configuración del sistema.
Date.prototype.toString(): Retorna una cadena representando el objeto especificado Date. Sobrescribe el método Object.prototype.toString().
Date.prototype.toTimeString(): Retona la porción de "tiempo" del objeto Date a una cadena legible para humanos.
Date.prototype.toUTCString(): Convierte una fecha a una cadena usando la zona horaria UTC.
Date.prototype.valueOf(): Retona el valor primitivo de un objeto Date. Sobrescribe el método Object.prototype.valueOf().

Ejemplos

Distintas maneras de crear un objeto Date

Los siguientes ejemplos muestran distintas maneras de crear fechas en JavaScript:

Nota: Transformar las cadenas de fechas con el constructor Date (y Date.parse, son equivalentes) es escasamente recomendado debido las diferencias e inconsistencias entre navegadores.

let today = new Date();
let birthday = new Date("December 17, 1995 03:24:00");
let birthday = new Date("1995-12-17T03:24:00");
let birthday = new Date(1995, 11, 17); // el mes es indexado como 0
let birthday = new Date(1995, 11, 17, 3, 24, 0);
let birthday = new Date(628021800000); // pasando la marca temporal de la época

Obtener fecha, mes y año u hora

const date = new Date();
const [month, day, year] = [
  date.getMonth(),
  date.getDate(),
  date.getFullYear(),
];
const [hour, minutes, seconds] = [
  date.getHours(),
  date.getMinutes(),
  date.getSeconds(),
];

Interpretación de los años de dos dígitos

new Date() hereda de forma no deseada, comportamiento inconsistente con años expresados en dos dígitos, cuando una llamada new Date() es dada a un año expresado en dos dígitos, ese valor del año no es tratado como un año literal y usado como tal si no que es interpretado como una diferencia desde el año 1900, pero en otros casos, como una diferencia desde el año 2000.

let date = new Date(98, 1); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
let date = new Date(22, 1); // Wed Feb 01 1922 00:00:00 GMT+0000 (GMT)
let date = new Date("2/1/22"); // Tue Feb 01 2022 00:00:00 GMT+0000 (GMT)

// Método heredado; siempre interpreta los años en dos digitos como relativos al 1900
date.setYear(98);
date.toString(); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
date.setYear(22);
date.toString(); // Wed Feb 01 1922 00:00:00 GMT+0000 (GMT)

Por lo tanto, crear y obtener fechas entre los años 0 y 99, preferiblemente usa los métodos setFullYear() y getFullYear().

// Método preferido; nunca interpreta ningun valor como una diferencia relativa,
// pero en su lugar valor del año tal y como está
date.setFullYear(98);
date.getFullYear(); // 98 (no 1998)
date.setFullYear(22);
date.getFullYear(); // 22 (no 1922, no 2022)

Calculando el tiempo transcurrido

Los siguientes ejemplos muestran como determinar el tiempo transcurrido entre dos fechas JavaScript en milisegundos.

Debido a las diferentes duraciones de los días (debido a los cambios horarios para aprovechar la luz del sol), meses, y años, expresar el tiempo transcurrido en unidades mayores a horas, minutos y segundos requiere abordar un número de inconvenientes, y deberia ser revisado minuciosamente antes de intentarse.

// Usando objetos Date
let start = Date.now();

// El tiempo a expresar va aquí:
doSomethingForALongTime();
let end = Date.now();
let elapsed = end - start; // tiempo transcurrido en milisegundos

// Usando métodos internos
let start = new Date();

// El tiempo a expresar va aquí:
doSomethingForALongTime();
let end = new Date();
let elapsed = end.getTime() - start.getTime(); // tiempo transcurrido en milisegundos

// Probar una función y regresar su valor
function printElapsedTime(fTest) {
  let nStartTime = Date.now(),
    vReturn = fTest(),
    nEndTime = Date.now();

  console.log(
    `Tiempo transcurrido: ${String(nEndTime - nStartTime)} milisegundos`,
  );
  return vReturn;
}

let yourFunctionReturn = printElapsedTime(yourFunction);

Nota: En los navegadores que soportan la funcionalidad de alta resolución temporal de Web Performance API, Performance.now() puede proveer una medida más precisa y confiable del tiempo transcurrido que Date.now().

Obtener el número de segundos desde la Época ECMAScript

let seconds = Math.floor(Date.now() / 1000);

En este caso, es más importante retornar únicamente un entero que una simple división no hará. Es también importante sólo retornar realmente el tiempo transcurrido. (Esa es la razón por la que este código usa Math.floor(), y no Math.round().)

Especificaciones

Specification
ECMAScript Language Specification # sec-date-objects

Compatibilidad con navegadores

BCD tables only load in the browser

Véase también

Date() constructor