CKTIS / JavaScript
Leggere e cambiare l’anno UTC di un oggetto Date
`getUTCFullYear()` legge l’anno in UTC. `setUTCFullYear()` modifica lo stesso oggetto `Date` e restituisce il nuovo timestamp. Omettere un argomento non equivale a passare `undefined`.
Versione: ECMAScript 2024 and the current web platform; runtime support varies
Sintassi
date.getUTCFullYear()
date.setUTCFullYear(year)
date.setUTCFullYear(year, monthIndex)
date.setUTCFullYear(year, monthIndex, dayOfMonth)getUTCFullYear() non accetta argomenti e restituisce l’anno di calendario in UTC come intero, non come stringa di quattro cifre. Se la data non è valida, restituisce NaN. Invece getFullYear() e setFullYear() usano il fuso orario locale dell’ambiente di esecuzione. A cavallo del nuovo anno, lo stesso istante può appartenere ad anni diversi in UTC e nell’ora locale.
setUTCFullYear(year, monthIndex, dayOfMonth) modifica l’oggetto Date esistente e restituisce il nuovo timestamp in millisecondi dall’epoca Unix. L’anno è obbligatorio; l’indice facoltativo del mese va da 0 (gennaio) a 11 (dicembre) e il giorno del mese parte da 1. Per indicare il giorno bisogna indicare anche il mese. I componenti omessi e l’ora del giorno provengono dalla data UTC esistente. I valori fuori dall’intervallo abituale vengono normalizzati: il 29 febbraio diventa il 1º marzo quando si passa a un anno non bisestile.
Gli argomenti vengono convertiti in numeri. Passare esplicitamente undefined non è come omettere l’argomento: il valore diventa NaN. Se un argomento diventa NaN o il timestamp risultante esce dall’intervallo di Date, il metodo memorizza e restituisce NaN. Se la data non era già valida, il metodo parte da 1970-01-01T00:00:00.000Z, quindi una chiamata valida può ripristinarla.
A differenza di Date.UTC(), setUTCFullYear() non aggiunge 1900 agli anni da 0 a 99. Entrambi i metodi del prototipo richiedono un vero oggetto Date come this; una chiamata con un ricevitore incompatibile genera un TypeError.
Esempi
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());Risultato
2024 1677674096789 2023-03-01T12:34:56.789Z NaN NaN 0007-01-01T00:00:00.000Z
Passando al 2023, il 29 febbraio diventa il 1º marzo senza cambiare l’ora UTC. Passare esplicitamente `undefined` invalida la data; impostare l’anno a `7` ripristina una data valida: il 1º gennaio dell’anno 7 a mezzanotte UTC.
Lezioni correlate
- JavaScript · Lezione 5 · Avanzato · Versione: 4
Fonti
- 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