Temporal.PlainYearMonth : méthode add()

Disponibilité limitée

Cette fonctionnalité n'est pas Compatible car elle ne fonctionne pas dans certains des navigateurs les plus utilisés.

La méthode add() des instances de Temporal.PlainYearMonth retourne un nouvel objet Temporal.PlainYearMonth représentant cette année et ce mois avancés d'une durée donnée (sous une forme convertible par Temporal.Duration.from()).

Syntaxe

add(duration)
add(duration, options)

Paramètres

duration

Une chaîne de caractères, un objet, ou une instance de Temporal.Duration représentant la durée à ajouter à ce PlainYearMonth. Elle est convertie en Temporal.Duration en utilisant le même algorithme que Temporal.Duration.from().

options Facultatif

Un objet contenant la propriété suivante :

overflow Facultatif

Une chaîne de caractères définissant le comportement lorsque un composant de date est hors plage. Valeurs possibles :

"constrain" (par défaut): Le composant de date est contraint à la plage valide.
"reject": Un objet RangeError est levé si le composant de date est hors plage.

Valeur de retour

Un nouvel objet Temporal.PlainYearMonth représentant cette année et ce mois définis par le PlainYearMonth d'origine, plus la durée.

Exceptions

RangeError: Levée si le résultat n'est pas dans la plage représentable, qui est ±(10⁸ + 1) jours, ou environ ±273 972,6 ans, à partir de l'époque Unix.

Description

La valeur de duration est traitée de la manière suivante :

Avancer du nombre d'années indiqué, en conservant le même monthCode. Si le monthCode est invalide dans l'année résultante (impossible pour le calendrier grégorien et ISO 8601, mais possible pour les calendriers avec des mois intercalaires), nous ajustons en fonction de l'option overflow : pour constrain, nous choisissons un autre mois selon les conventions culturelles des utilisateurs de ce calendrier. Par exemple, comme le mois intercalaire est généralement considéré comme un doublon d'un autre mois, nous pouvons choisir le mois dont il est un doublon.
Avancer du nombre de mois indiqué, en ajustant l'année si nécessaire.
Pour toutes les unités inférieures à months (semaines, jours, heures, minutes, secondes, millisecondes, microsecondes, nanosecondes), elles sont converties en nombre de jours. Tous les calendriers couramment pris en charge utilisent des semaines de longueur fixe, donc le nombre de semaines est simplement converti en nombre de jours. Si la règle est plus complexe, nous pouvons adopter une approche similaire au décalage des mois. Ensuite, nous avançons de ce nombre de jours, en commençant par le premier jour du mois, en ajustant le mois et l'année si nécessaire. Les durées inférieures à la longueur du mois en cours n'ont donc aucun effet.

Le jour de référence interne est ensuite choisi comme étant le premier jour valide du mois, indépendamment du jour de référence d'origine ou du nombre de jours dans la durée. Pour le calendrier grégorien, un dépassement ne peut pas se produire car chaque année a toujours 12 mois, et tout incrément inférieur à un mois est simplement ignoré.

Ajouter une durée est équivalent à soustraire sa négation.

Exemples

Ajouter une durée dans le calendrier ISO 8601

const start = Temporal.PlainYearMonth.from("2021-01");
const end = start.add({ years: 1, months: 2, weeks: 3, days: 4 });
console.log(end.toString()); // 2022-03

const end2 = start.add({ years: -1, months: -2, weeks: -3, days: -4 });
console.log(end2.toString()); // 2019-11

const distance = Temporal.PlainYearMonth.from("2020-01").until("2021-01"); // 366 days
const end3 = start.add(distance);
console.log(end3.toString()); // 2022-01

Ajouter une durée dans un calendrier non ISO

const start = Temporal.PlainYearMonth.from("2021-02-01[u-ca=chinese]");
console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 12/2020
console.log(start.toString()); // 2021-01-13[u-ca=chinese]
const end = start.add({ months: 1 });
console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 1/2021
console.log(end.toString()); // 2021-02-12[u-ca=chinese]

// Ajouter un jour supplémentaire n'a aucun effet
const end2 = start.add({ months: 1, days: 1 });
console.log(end2.toLocaleString("en-US", { calendar: "chinese" })); // 1/2021
// Le jour de référence ne change pas, car c'est toujours le premier jour du mois chinois
console.log(end2.toString()); // 2021-02-12[u-ca=chinese]

// Début dans un mois intercalaire
const start2 = Temporal.PlainYearMonth.from({
  year: 5730,
  monthCode: "M05L",
  calendar: "hebrew",
});
console.log(start2.toLocaleString("en-US", { calendar: "hebrew" })); // Adar I 5730
// Fin dans un autre mois intercalaire
const end3 = start2.add({ years: 3 });
console.log(end3.toLocaleString("en-US", { calendar: "hebrew" })); // Adar I 5733

Ajouter une durée avec dépassement

Si nous avançons de quelques années et que le mois correspondant est invalide dans cette année, nous ajustons le mois en fonction de l'option overflow.

// Début dans un mois intercalaire
const start = Temporal.PlainYearMonth.from({
  year: 5730,
  monthCode: "M05L",
  calendar: "hebrew",
});
// Les années bissextiles hébraïques se produisent tous les 2 ou 3 ans, et 5731 n'est pas une année bissextile
const end = start.add({ years: 1 });
console.log(end.toLocaleString("en-US", { calendar: "hebrew" })); // Adar 5731
console.log(end.monthCode); // M06
console.log(end.toString()); // 1971-02-26[u-ca=hebrew]

// Toute addition de mois supplémentaire est basée sur l'année-mois ajustée
const end2 = start.add({ years: 1, months: 2 });
console.log(end2.monthCode); // M08
console.log(end2.toString()); // 1971-04-26[u-ca=hebrew]

// Comparer avec la même addition dans un ordre différent qui ne provoque pas de dépassement :
const end3 = start.add({ months: 2 }).add({ years: 1 });
console.log(end3.monthCode); // M07
console.log(end3.toString()); // 1971-03-27[u-ca=hebrew]

Notez que ce qui suit n'est pas un dépassement, car l'année peut simplement augmenter :

const start = Temporal.PlainYearMonth.from("2021-01");
const end = start.add({ months: 100 });
console.log(end.toString()); // 2029-05

Vous pouvez également générer une erreur si le composant de date est hors de portée :

const start = Temporal.PlainYearMonth.from({
  year: 5730,
  monthCode: "M05L",
  calendar: "hebrew",
});
const end = start.add({ years: 1 }, { overflow: "reject" }); // RangeError: invalid "monthCode" calendar field: M05L

Spécifications

Spécification
Temporal # sec-temporal.plainyearmonth.prototype.add

Compatibilité des navigateurs

Voir aussi

L'objet Temporal.PlainYearMonth
L'objet Temporal.Duration
La méthode Temporal.PlainYearMonth.prototype.subtract()

Aider à améliorer MDN

Apprendre à contribuer

Cette page a été modifiée le 29 mars 2026 par les contributeur·ice·s du MDN.

Voir cette page sur GitHub • Signaler un problème avec ce contenu