CKTIS / JavaScript
Lire et modifier l’année UTC d’un objet Date
`getUTCFullYear()` lit l’année en UTC. `setUTCFullYear()` modifie le même objet `Date` et renvoie son nouvel horodatage. Omettre un argument n’équivaut pas à passer `undefined`.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
date.getUTCFullYear()
date.setUTCFullYear(year)
date.setUTCFullYear(year, monthIndex)
date.setUTCFullYear(year, monthIndex, dayOfMonth)getUTCFullYear() ne prend aucun argument et renvoie l’année civile en UTC sous forme d’entier, et non de chaîne à quatre chiffres. Si la date est invalide, la méthode renvoie NaN. À l’inverse, getFullYear() et setFullYear() utilisent le fuseau horaire local de l’environnement d’exécution. Au passage à la nouvelle année, un même instant peut appartenir à des années différentes en UTC et en heure locale.
setUTCFullYear(year, monthIndex, dayOfMonth) modifie l’objet Date existant et renvoie son nouvel horodatage en millisecondes depuis l’époque Unix. L’année est obligatoire. L’indice de mois, facultatif, va de 0 (janvier) à 11 (décembre), et le jour du mois commence à 1. Pour préciser le jour, il faut aussi préciser le mois. Les composantes omises et l’heure proviennent de la date UTC existante. Les valeurs calendaires hors de leur plage habituelle sont normalisées : le 29 février devient le 1er mars si l’année choisie n’est pas bissextile.
Les arguments sont convertis en nombres. Passer explicitement undefined n’est pas une omission : la valeur devient NaN. Si un argument devient NaN ou si l’horodatage calculé sort de la plage de Date, la méthode stocke et renvoie NaN. Si la date était déjà invalide, la méthode part de 1970-01-01T00:00:00.000Z : un appel valide peut donc la rétablir.
Contrairement à Date.UTC(), setUTCFullYear() n’ajoute pas 1900 aux années de 0 à 99. Les deux méthodes du prototype exigent un véritable objet Date comme valeur de this ; sinon, l’appel déclenche une TypeError.
Exemples
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());Résultat
2024 1677674096789 2023-03-01T12:34:56.789Z NaN NaN 0007-01-01T00:00:00.000Z
En passant à 2023, le 29 février devient le 1er mars sans changer l’heure UTC. Passer explicitement `undefined` invalide la date ; fixer l’année à `7` rétablit une date valide : le 1er janvier de l’an 7 à minuit UTC.
Leçons associées
- JavaScript · Leçon 5 · Avancé · Version : 4
Sources
- 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