Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

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