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 1er Janvier 1970 minuit UTC.
Syntaxe
new Date(); new Date(valeur); new Date(chaîneDate); new Date(année, mois[, jour[, heures[, minutes[, secondes[, millisecondes]]]]]);
Date ne peuvent être instanciés qu'en appelant Date comme un constructeur : l'appeler comme une fonction normale (sans l'opérateur new) retournera une chaîne de caractère au lieu de l'objet Date ; contrairement aux autres objets en JavaScript, il n'existe pas de littéral pour représenter « simplement » des objets Date).Paramètres
Note : Quand Date est appelé en tant que constructeur avec plus d'un argument, si les valeurs sont supérieures aux limites logiques (par exemple, 13 est fourni comme valeur pour le mois, ou 70 pour la valeur des minutes), les valeurs adjacentes seront ajustées. Exemple : new Date(2013,13,1) est équivalent à new Date(2014,1,1), les deux créent une date pour 2014-02-01 (notez que le mois démarre à 0). De même avec d'autres valeurs : new Date(2013,2,1,0,70) est équivalent à new Date(2013,2,1,1,10) créent tous les deux la date 2013-03-01T01:10:00.
Note : Quand Date est appelé en tant que constructeur avec plus d'un argument, les arguments fournis représentent l'heure et la date locales. Si on souhaite exprimer cet instant en UTC, on pourra utiliser new Date( avec les mêmes arguments.Date.UTC(...))
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).
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éthodeDate.parse()) est déconseillée car il existe différentes incohérences entre les différents navigateurs.
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.
mois- Valeur d'un entier représentant le mois, commençant à partir de 0 pour Janvier jusqu'à 11 pour Décembre.
jour- Paramètre optionnel. Un entier représentant le jour du mois (1-31).
heures- Paramètre optionnel. Un entier représentant l'heure d'un jour (0-23).
minutes- Paramètre optionnel. Un entier représentant le segment de minute (0-59) du temps lu.
secondes- Paramètre optionnel. Un entier représentant le segment de secondes (0-59) du temps lu.
millisecondes- Paramètre optionnel. Un entier représentant le segment de millisecondes (0-999) du temps lu.
Description
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.
La date est mesurée en millisecondes depuis minuit le 01 janvier 1970 UTC. 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.
L'objet Date fournit un comportement uniforme à travers les plates-formes. Une valeur peut être échangée entre les différents systèmes afin de représenter le même instant et si la date est utilisée pour créer une date locale, elle correspondra à l'équivalent local.
L'objet Date soutient un certain nombre de méthodes UTC (Universal), ainsi que des méthodes d'heure locale. UTC, également connu sous le nom de Greenwich Mean Time (GMT), se réfère au temps fixé par la norme de temps du monde (World Time Standard). L'heure locale est l'heure connue sur l'ordinateur quand JavaScript est exécuté.
L'invocation de Date dans un contexte non-constructeur (c'est-à-dire sans new) renverra une chaîne de caractère représentant la date et l'heure courante.
Propriétés
Date.prototype- Permet l'ajout de propriétés à l'objet
Date. - Date.length
- La valeur de
Date.lengthest 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).
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. 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éthodeDate.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
Datedepuis le 1er Janvier 1970, 00:00:00, UTC.
Les instances d'objet 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 1er 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
Datesur le temps représenté par un nombre de millisecondes depuis le 1er 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
Datesous la forme d'une chaîne de caractères lisible par un humain. 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 avecJSON.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
Datesous 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
Datesous 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éthodeObject.prototype.toSource(). Date.prototype.toString()- Renvoie une chaîne de caractères représentant l'objet
Datespécifié. Remplace la méthodeObject.prototype.toString(). Date.prototype.toTimeString()- Renvoie la partie « heure » de l'objet
Datesous 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éthodeObject.prototype.valueOf().
Exemples
Différentes façon 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.
Note : Attention aux effets de l'heure d'été (DST) et aux autres élément perturbateurs lorsqu'on souhaite exprimer une durée sur une unité plus grande que les heures les minutes ou les secondes.
// 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);
Note : Pour les navigateurs qui supportent la fonctionnalité de haute précision temporelle de l'API Web Performance, Performance.now() peut fournir des mesures plus précises et sûres que Date.now().
Spécifications
| Spécification | Statut | Commentaires |
|---|---|---|
| ECMAScript 1st Edition (ECMA-262) | Standard | Définition initiale. Implémentée avec JavaScript 1.1. |
| ECMAScript 5.1 (ECMA-262) La définition de 'Date' dans cette spécification. |
Standard | |
| ECMAScript 2015 (6th Edition, ECMA-262) La définition de 'Date' dans cette spécification. |
Standard | |
| ECMAScript 2017 Draft (ECMA-262) La définition de 'Date' dans cette spécification. |
Projet |
Compatibilité des navigateurs
| Fonctionnalité | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
|---|---|---|---|---|---|
| Support simple | (Oui) [1] | (Oui) [1] | (Oui) [2] | (Oui) [1] | (Oui) [1] |
| Fonctionnalité | Android | Chrome pour Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
|---|---|---|---|---|---|---|
| Support simple | (Oui) | (Oui) | (Oui) | (Oui) | (Oui) | (Oui) |
[1] Billet de danvk en date du 14 mars 2012 sur la comparaison entre FF/IE/Chrome sur l'analyse des chaînes de caractères pour les dates (en anglais)
[2] Note relative à Internet Explorer 8 : Le format de date ISO 8601 n'est pas supporté par ce navigateur.