CKTIS / JavaScript
Zonas horarias y ciclos horarios en Intl.DateTimeFormat
`timeZone` elige qué hora local se muestra para un instante. `hourCycle` controla cómo se numeran las horas, por ejemplo, si la medianoche aparece como `00` o `24`.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
new Intl.DateTimeFormat(locales, { timeZone, hourCycle, hour: "2-digit" })timeZone selecciona la zona usada para mostrar un instante, sin modificar el objeto Date ni su valor. Si se omite, se usa la zona predeterminada del entorno de ejecución. Una zona con nombre como "America/New_York" aplica las reglas vigentes en ese instante, incluidos los cambios de horario de verano. Un desplazamiento fijo como "-05:00" no sigue esas reglas. Es posible que los entornos antiguos no admitan identificadores de desplazamiento. timeZoneName controla la etiqueta visible, no la zona seleccionada.
hourCycle fija el intervalo de horas: "h11" es 0–11, "h12" es 1–12, "h23" es 0–23 y "h24" es 1–24. En "h24", 24 identifica la hora que empieza a medianoche; no desplaza el instante al día siguiente. hourCycle no añade una hora por sí solo: solicítala con hour o timeStyle, pero no combines ambas opciones.
hour12: true y hour12: false tienen prioridad sobre hourCycle y sobre la extensión Unicode hc de la configuración regional. true elige un ciclo de 12 horas y false, uno de 24 horas. Para imponer un ciclo concreto, omite hour12 y establece hourCycle, que tiene prioridad sobre hc. Sin estos ajustes, el ciclo predeterminado depende de la configuración regional.
Un hourCycle no válido o un identificador timeZone no reconocido produce un RangeError al crear el formateador, aunque un hour12 válido vaya a prevalecer sobre hourCycle. Consulta los ajustes efectivos con resolvedOptions(); el ciclo no aparece si el formato no incluye la hora. Para extraer solo la hora, usa la parte hour de formatToParts() en vez de analizar toda la cadena localizada.
Ejemplos
const instant = new Date("2024-01-15T05:00:00Z");
function showHour(timeZone, hourCycle) {
const formatter = new Intl.DateTimeFormat("en-US", {
timeZone,
hourCycle,
hour: "2-digit",
numberingSystem: "latn",
formatMatcher: "basic",
});
const hour = formatter.formatToParts(instant).find(part => part.type === "hour");
const displayHour = hour.value.padStart(2, "0");
console.log(`${timeZone} ${formatter.resolvedOptions().hourCycle}: ${displayHour}`);
}
showHour("UTC", "h23");
showHour("America/New_York", "h23");
showHour("America/New_York", "h24");Resultado
UTC h23: 05 America/New_York h23: 00 America/New_York h24: 24
Las dos primeras líneas solo cambian la zona: al mismo instante le corresponden la hora `05` en UTC y la medianoche en Nueva York. La última línea solo cambia el ciclo, así que esa misma hora local se muestra como `24` en vez de `00`.
Lecciones relacionadas
- JavaScript · Lección 25 · Avanzado · Versión: 4
Fuentes
- ECMAScript® 2024 Internationalization API Specification — CreateDateTimeFormat
- ECMAScript Internationalization API Specification — CreateDateTimeFormat (living specification)
- Intl.DateTimeFormat() constructor — MDN
- Intl.DateTimeFormat.prototype.resolvedOptions() — MDN
- Intl.DateTimeFormat.prototype.formatToParts() — MDN