CKTIS / JavaScript
Leer y cambiar el año UTC de un objeto Date
`getUTCFullYear()` lee el año en UTC. `setUTCFullYear()` modifica el mismo objeto `Date` y devuelve la nueva marca de tiempo. Omitir un argumento no equivale a pasar `undefined`.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
date.getUTCFullYear()
date.setUTCFullYear(year)
date.setUTCFullYear(year, monthIndex)
date.setUTCFullYear(year, monthIndex, dayOfMonth)getUTCFullYear() no recibe argumentos y devuelve el año natural en UTC como un entero, no como una cadena de cuatro dígitos. Si la fecha no es válida, devuelve NaN. En cambio, getFullYear() y setFullYear() usan la zona horaria local del entorno de ejecución. Cerca del cambio de año, un mismo instante puede pertenecer a años distintos en UTC y en hora local.
setUTCFullYear(year, monthIndex, dayOfMonth) modifica el objeto Date existente y devuelve su nueva marca de tiempo en milisegundos desde la época Unix. El año es obligatorio; el índice de mes es opcional y va de 0 (enero) a 11 (diciembre), y el día del mes empieza en 1. Para indicar el día, también hay que indicar el mes. Los componentes omitidos y la hora del día se toman de la fecha UTC existente. Los valores fuera de su intervalo habitual se normalizan: el 29 de febrero pasa al 1 de marzo al cambiar a un año no bisiesto.
Los argumentos se convierten en números. Pasar undefined explícitamente no equivale a omitir el argumento: se convierte en NaN. Si un argumento se convierte en NaN o la marca de tiempo resultante queda fuera del intervalo de Date, el método almacena y devuelve NaN. Si la fecha ya era inválida, el punto de partida es 1970-01-01T00:00:00.000Z, por lo que una llamada válida puede recuperarla.
A diferencia de Date.UTC(), setUTCFullYear() no suma 1900 a los años del 0 al 99. Ambos métodos del prototipo requieren que this sea un objeto Date auténtico; llamarlos con un receptor incompatible lanza un TypeError.
Ejemplos
const date = new Date('2024-02-29T12:34:56.789Z');
console.log(date.getUTCFullYear());
console.log(date.setUTCFullYear(2023));
console.log(date.toISOString());
console.log(date.setUTCFullYear(2023, undefined));
console.log(date.getUTCFullYear());
date.setUTCFullYear(7);
console.log(date.toISOString());Resultado
2024 1677674096789 2023-03-01T12:34:56.789Z NaN NaN 0007-01-01T00:00:00.000Z
Al cambiar a 2023, el 29 de febrero pasa al 1 de marzo sin cambiar la hora UTC. Pasar `undefined` explícitamente invalida la fecha; fijar el año en `7` recupera una fecha válida: el 1 de enero del año 7 a medianoche UTC.
Lecciones relacionadas
- JavaScript · Lección 5 · Avanzado · Versión: 4
Fuentes
- ECMAScript® 2024 Language Specification — Date.prototype.getUTCFullYear
- ECMAScript® 2024 Language Specification — Date.prototype.setUTCFullYear
- ECMAScript® 2024 Language Specification — Date.UTC
- ECMAScript® 2024 Language Specification — TimeClip
- Date.prototype.getUTCFullYear() - JavaScript | MDN
- Date.prototype.setUTCFullYear() - JavaScript | MDN