Date

Ce constructeur permet de créer des instances Date qui représentent un moment précis dans le temps. Les objets Date se basent sur une valeur de temps qui est le nombre de millisecondes depuis 1^er janvier 1970 minuit UTC.

Le code source de cet exemple interactif est disponible dans un dépôt GitHub. Si vous souhaitez contribuez à ces exemples, n'hésitez pas à cloner https://github.com/mdn/interactive-examples et à envoyer une pull request !

Syntaxe

new Date(); // heure courante dans le fuseau horaire locale
new Date(valeur); // heure basée sur l'epoch Unix
new Date(chaîneDate);
new Date(année, indexMois[, jour[, heures[, minutes[, secondes[, millisecondes]]]]]);

Paramètres

valeur

Un entier représentant le nombre de millisecondes depuis le 1 janvier 1970 00:00:00 UTC (Unix Epoch, attention ici, de nombreuses fonctions Unix comptent en secondes) sans compter les secondes intercalaires.

chaîneDate

Une chaîne de caractère représentant une date. La chaîne doit être dans un format reconnu par la méthode Date.parse() (conforme à la RFC 1123 de l'IETF ou à l'ISO8601).

Note : L'analyse de chaînes via le constructeur Date (ou via la méthode Date.parse()) est déconseillée car il existe différentes incohérences entre les différents navigateurs. La prise en charge des chaînes de format de la RFC 2822 est une simple convention. La norme ISO 8601 n'est pas complètement respectée car les chaînes qui décrivent uniquement des dates (ex. "1970-01-01") sont considérées en UTC et non en heure locale.

Note : Une chaîne invalide passée dans le constructeur Date  (par exemple let noDate = new Date('is it a date ?') va créer une instance de cette classe pour laquelle la méthode toString() retourne la chaîne "Invalid Date". Les méthodes telles que getFullYear() retournent NaN.

année

Un entier représentant l'année. Les valeurs 0 à 99 correspondent aux années 1900 à 1999. Voir l'exemple ci-après pour plus d'informations.

indexMois

Valeur d'un entier représentant le mois, commençant à partir de 0 pour janvier jusqu'à 11 pour Décembre.

jour Facultatif

Un entier représentant le jour du mois (1-31).

heures Facultatif

Un entier représentant l'heure d'un jour (0-23).

minutesFacultatif

Un entier représentant le segment de minute (0-59) du temps lu.

secondesFacultatif

Un entier représentant le segment de secondes (0-59) du temps lu.

millisecondesFacultatif

Un entier représentant le segment de millisecondes (0-999) du temps lu.

Description

Origine des temps : epoch Unix

La date est mesurée en millisecondes depuis minuit le 01 janvier 1970 UTC (« epoch Unix »). Une journée contient 86 400 000 millisecondes. Les limites de l'objet Date sont -100 000 000 jours à 100 000 000 jours par rapport au 01 janvier 1970 UTC.

Si vous ne fournissez pas d'arguments, le constructeur crée un objet Date pour la date du jour et l'heure selon l'heure locale du système. Si vous fournissez des arguments, au moins l'année et le mois, arguments obligatoires, doivent être spécifiés. Les autres sont optionnels et leur valeur par défaut, s'ils ne sont pas fournis, sera 1 pour le jour et 0 pour les autres. Quand un argument optionnel est spécifié, tous les arguments situés à sa gauche doivent l'être également.

Format de date et gestion des fuseaux horaires

Il existe plusieurs méthodes qui permettent d'obtenir une date selon différents formats et d'autres qui permettent d'effectuer des conversions entre fuseaux horaires. On pourra ainsi convertir/récupérer une valeur en temps universel coordonné (UTC) pour l'échanger avec d'autres systèmes.

En plus des méthodes qui permettent de lire et de modifier les composantes individuelles liées à la date et à l'heure (ex. getDay() et setHours()), il existe des méthodes analogues pour lire et manipuler les composantes selon le fuseau UTC (ex. getUTCDay() et setUTCHours()).

Propriétés

Date.prototype

Permet l'ajout de propriétés à l'objet Date.

Date.length

La valeur de Date.length est 7. Il s'agit du nombre d'arguments pris en charge par le constructeur.

Méthodes

Date.now()

Retourne la valeur numérique correspondant au temps courant. Le nombre de millisecondes depuis le 1 janvier 1970, 00:00:00 UTC (Unix Epoch) sans compter les secondes intercalaires.

Date.parse()

Analyse une représentation textuelle d'une date, et retourne le nombre de millisecondes depuis le 1 janvier 1970, 00:00:00, UTC sans compter les secondes intercalaires. Note : se référer à la page de la méthode quant aux différences de comportement liées à l'implémentation.

Note : L'analyse de chaînes via le constructeur Date (ou via la méthode Date.parse()) est déconseillée car il existe différentes incohérences entre les différents navigateurs.

Date.UTC()

Accepte les mêmes paramètres sous la forme la plus longue du constructeur (2 à 7), et retourne le nombre de millisecondes dans l'objet Date depuis le 1er janvier 1970, 00:00:00, UTC sans compter les secondes intercalaires.

Instances de Date

Toutes les instances de Date héritent de Date.prototype. L'objet prototype du constructeur Date peut être modifié pour modifier l'ensemble des instances de Date.

Méthodes de Date.prototype

Lecture (getters)

Date.prototype.getDate()

Renvoie le jour du mois (1-31) pour la date spécifiée selon l'heure locale.

Date.prototype.getDay()

Renvoie le jour de la semaine (0-6) pour la date spécifiée selon l'heure locale.

Date.prototype.getFullYear()

Renvoie l'année (avec 4 chiffres pour une année à 4 chiffres) pour la date spécifiée selon l'heure locale.

Date.prototype.getHours()

Renvoie l'heure (0-23) pour la date spécifiée selon l'heure locale.

Date.prototype.getMilliseconds()

Renvoie les millièmes de secondes (0-999) pour la date spécifiée selon l'heure locale.

Date.prototype.getMinutes()

Renvoie les minutes (0-59) pour la date spécifiée selon l'heure locale.

Date.prototype.getMonth()

Renvoie le mois (0-11) pour la date spécifiée selon l'heure locale.

Date.prototype.getSeconds()

Renvoie les secondes (0-59) pour la date spécifiée selon l'heure locale.

Date.prototype.getTime()

Renvoie la valeur numérique de la date spécifiée sous la forme du nombre de millisecondes depuis le 1^er janvier 1970, 00:00:00 UTC (les valeurs renvoyées pour les dates antérieures seront négatives).

Date.prototype.getTimezoneOffset()

Renvoie le décalage de fuseau horaire en minutes pour l'heure locale courante.

Date.prototype.getUTCDate()

Renvoie le jour (date) du mois (1-31) pour la date spécifiée selon le temps universel.

Date.prototype.getUTCDay()

Renvoie le jour de la semaine (0-6) pour la date spécifiée selon le temps universel.

Date.prototype.getUTCFullYear()

Renvoie l'année (avec 4 chiffres pour une année à 4 chiffres) pour la date spécifiée selon le temps universel.

Date.prototype.getUTCHours()

Renvoie les heures (0-23) pour la date spécifiée selon le temps universel.

Date.prototype.getUTCMilliseconds()

Renvoie les millièmes de seconde (0-999) pour la date spécifiée selon le temps universel.

Date.prototype.getUTCMinutes()

Renvoie les minutes (0-59) pour la date spécifiée selon le temps universel.

Date.prototype.getUTCMonth()

Renvoie le mois (0-11) pour la date spécifiée selon le temps universel.

Date.prototype.getUTCSeconds()

Renvoie les secondes (0-59) pour la date spécifiée selon le temps universel

Date.prototype.getYear()

Renvoie l'année (habituellement avec 2 ou 3 chiffres) pour la date spécifiée selon l'heure locale. Utilisez plutôt getFullYear().

Écriture (setters)

Date.prototype.setDate()

Définit le jour du mois pour la date spécifiée selon l'heure locale.

Date.prototype.setFullYear()

Définit l'année complète (4 chiffres pour une année à 4 chiffres) pour la date spécifiée selon l'heure locale.

Date.prototype.setHours()

Définit les heures pour la date spécifiée selon l'heure locale.

Date.prototype.setMilliseconds()

Définit les millièmes de seconde pour la date spécifiée selon l'heure locale.

Date.prototype.setMinutes()

Définit les minutes pour la date spécifiée selon l'heure locale.

Date.prototype.setMonth()

Définit le mois pour la date spécifiée selon l'heure locale.

Date.prototype.setSeconds()

Définit les secondes pour la date spécifiée selon l'heure locale.

Date.prototype.setTime()

Règle l'objet Date sur le temps représenté par un nombre de millisecondes depuis le 1^er janvier 1970, 00:00:00 UTC.

Date.prototype.setUTCDate()

Définit le jour du mois pour la date spécifiée selon le temps universel.

Date.prototype.setUTCFullYear()

Définit l'année complète (4 chiffres pour une année à 4 chiffres) pour la date spécifiée selon le temps universel.

Date.prototype.setUTCHours()

Définit les heures pour la date spécifiée selon le temps universel.

Date.prototype.setUTCMilliseconds()

Définit les millièmes de seconde pour la date spécifiée selon le temps universel.

Date.prototype.setUTCMinutes()

Définit les minutes pour la date spécifiée selon le temps universel.

Date.prototype.setUTCMonth()

Définit le mois pour la date spécifiée selon le temps universel.

Date.prototype.setUTCSeconds()

Définit les secondes pour la date spécifiée selon le temps universel.

Date.prototype.setYear()

Définit l'année (habituellement avec 2 ou 3 chiffres) pour une date spécifiée selon le temps universel. Utilisez plutôt setFullYear().

Lecture avec conversion

Date.prototype.toDateString()

Renvoie la partie « date » de l'objet Date sous la forme d'une chaîne de caractères lisible par un humain (autrement dit quelque chose comme "Thu Apr 12 2018").

Date.prototype.toISOString()

Convertit une date en chaîne de caractère respectant la norme ISO 8601 Format Étendu.

Date.prototype.toJSON()

Renvoie une chaîne de caractère représentant la date en utilisant toISOString(). Pour une utilisation avec JSON.stringify().

Date.prototype.toGMTString()

Convertit une date en une chaîne de caractères, en utilisant les conventions GMT. Utilisez plutôt toUTCString().

Date.prototype.toLocaleDateString()

Renvoie la partie « date » de l'objet Date sous la forme d'une chaîne de caractères adaptée selon la locale en utilisant les réglages du système pour déterminer la locale à utiliser.

Date.prototype.toLocaleFormat()

Convertit une date en une chaîne de caractères, en utilisant une chaîne de formatage.

Date.prototype.toLocaleString()

Convertit une date en une chaîne de caractères, en utilisant les conventions locales courantes. Remplace la méthode Object.prototype.toLocaleString().

Date.prototype.toLocaleTimeString()

Renvoie la partie « heure » de l'objet Date sous la forme d'une chaîne, en utilisant les conventions locales courantes.

Date.prototype.toSource()

Renvoie une chaîne de caractères représentant le code source pour un objet Date équivalent ; cette valeur peut être utilisée pour créer un nouvel objet. Remplace la méthode Object.prototype.toSource().

Date.prototype.toString()

Renvoie une chaîne de caractères représentant l'objet Date spécifié. Remplace la méthode Object.prototype.toString().

Date.prototype.toTimeString()

Renvoie la partie « heure » de l'objet Date sous la forme d'une chaîne de caractères lisible par humain.

Date.prototype.toUTCString()

Convertit une date en une chaîne de caractères, en utilisant le fuseau horaire UTC.

Date.prototype.valueOf()

Renvoie la valeur primitive d'un objet Date. Remplace la méthode Object.prototype.valueOf().

Exemples

Différentes façons de créer un objet Date

Les exemples suivants montrent différentes façon pour créer des Date :

var aujourdhui = new Date();
var anniversaire = new Date("December 17, 1995 03:24:00");
var anniversaire = new Date("1995-12-17T03:24:00");
var anniversaire = new Date(1995,11,17);
var anniversaire = new Date(1995,11,17,3,24,0);

Années à deux chiffres correspondent à 1900 - 1999

Pour créer et obtenir des dates entre les années 0 et 99, les méthodes Date.prototype.setFullYear() et Date.prototype.getFullYear() doivent être utilisées.

var date = new Date(98, 1); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)

// Méthode obsolète, 98 correspond à 1998 ici aussi
date.setYear(98);           // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)

date.setFullYear(98);       // Sat Feb 01 0098 00:00:00 GMT+0000 (BST)

Calculer le temps écoulé

Les exemples suivants montrent comment déterminer le temps écoulé entre deux dates.

// en utilisant les objets Date
var debut = Date.now();

// l'évènement à mesurer se trouve ici :
traitementQuiPrendBeaucoupDeTemps();
var fin = Date.now();
var tempsEcoule = fin - debut; // temps écoulé en millisecondes

// en utilisant les méthodes natives
var debut = new Date();

// l'évènement à mesurer se trouve ici :
traitementQuiPrendBeaucoupDeTemps();
var fin = new Date();
var tempsEcoule = fin.getTime() - debut.getTime(); // temps écoulé en millisecondes

// pour tester le temps d'exécution d'une fonction et obtenir son résultat
function afficherTempsEcoule (fTest) {
  var nTempsDebut = Date.now(), 
      vRetour = fTest(),
      nTempsFin = Date.now();

  console.log("Temps écoulé : " + String(nTempsFin - nTempsDebut) + " millisecondes");
  return vRetour;
}

var retourVotreFonction = afficherTempsEcoule(votreFonction);

Obtenir le nombre de secondes depuis l'époque Unix

var seconds = Math.floor(Date.now() / 1000);

Dans ce cas il est important de ne retourner qu'un nombre entier de secondes (c'est pourquoi une simple division ne peut convenir), et aussi de ne retourner que le nombre des secondes effectivement écoulées (c'est pourquoi ce code utilise Math.floor() et non Math.round()).

Calculer le nombre de jours dans un mois

// Prend en paramètre deux entiers
function getNumberOfDays(year, month) {
    var days = 31;
    var currentDate = new Date(year, month, days);
    var itsOk = false;

    do {
        if (currentDate.getDate() < 28) {
            // La date est passée au mois suivant
            days--;
            currentDate = new Date(year, month, days);
        } else {
            itsOk = true;
        }
    }  while (!itsOk);
    return currentDate.getDate();
}

Spécifications

Compatibilité des navigateurs

Le tableau de compatibilité de cette page a été généré à partir de données structurées. Si vous souhaitez contribuer à ces données, n'hésitez pas à envoyer une pull request sur https://github.com/mdn/browser-compat-data.