diff options
Diffstat (limited to 'files/fr/web/javascript/reference/global_objects/date/index.html')
| -rw-r--r-- | files/fr/web/javascript/reference/global_objects/date/index.html | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/files/fr/web/javascript/reference/global_objects/date/index.html b/files/fr/web/javascript/reference/global_objects/date/index.html new file mode 100644 index 0000000000..e38ef84b9b --- /dev/null +++ b/files/fr/web/javascript/reference/global_objects/date/index.html @@ -0,0 +1,258 @@ +--- +title: Date +slug: Web/JavaScript/Reference/Objets_globaux/Date +tags: + - Date + - JavaScript + - Reference +translation_of: Web/JavaScript/Reference/Global_Objects/Date +--- +<div>{{JSRef}}</div> + +<p><span class="seoSummary">Les objets JavaScript <strong><code>Date</code></strong> représentent un instant donné sur l'axe du temps dans un format indépendant de la plateforme utilisée.</span> Les objets <code>Date</code> contiennent un nombre (<code>Number</code>) qui représente le nombre de millisecondes écoulées depuis le premier janvier 1970 sur l'échelle <a href="https://fr.wikipedia.org/wiki/Temps_universel_coordonn%C3%A9">UTC</a>.</p> + +<div class="blockIndicator note"> +<p>TC39 travaille actuellement sur <a href="https://tc39.es/proposal-temporal/docs/index.html">Temporal</a>, une nouvelle API pour la gestion des dates, heures et données temporelles.<br> + Pour en savoir plus, consultez le <a href="https://blogs.igalia.com/compilers/2020/06/23/dates-and-times-in-javascript/">blog d'Igalia</a> et n'hésitez pas à répondre <a href="https://forms.gle/iL9iZg7Y9LvH41Nv8">au sondage</a>. Les retours concrets de développeurs web sont importants pour affiner cette API. Attention, elle n'est pas encore prête à être utilisée en production !</p> +</div> + +<h2 id="Description">Description</h2> + +<h3 id="Lepoch_ECMAScript">L'epoch ECMAScript</h3> + +<p>D'un point de vue technique, une date JavaScript correspond au nombre de millisecondes écoulées depuis le premier janvier 1970, minuit UTC. Cette date et cette heure sont les mêmes que <strong>l'<a href="https://fr.wikipedia.org/wiki/Epoch">epoch</a> UNIX</strong>, qui est l'instant de référence principalement utilisé pour manipuler les dates/heures dans les systèmes informatiques.</p> + +<p><strong>Note :</strong> Bien que les valeurs temporelles des objets dates soient relatives à UTC, certaines des méthodes simples pour obtenir les composantes d'une date/heure fonctionnent relativement au fuseau horaire du système.</p> + +<p>On notera également que la représentation maximale d'un objet <code>Date</code> n'est pas la même que le plus grand entier représentable en JavaScript (<code>Number.MAX_SAFE_INTEGER</code> vaut 9,007,199,254,740,991). En effet, ECMA-262 définit un maximum de ±100 000 000 (cent millions) jours relatifs au premier janvier 1970 UTC (ce qui correspond au 20 avril 271 821 avant notre ètre d'une part et au 13 septembre 275 760 de notre ère) pouvant être représentés par un objet <code>Date</code> standard (soit un intervalle de ±8 640 000 000 000 000 millisecondes).</p> + +<h3 id="Les_formats_de_date_et_les_conversions_entre_les_fuseaux_horaires">Les formats de date et les conversions entre les fuseaux horaires</h3> + +<p>Il existe différentes méthodes pour obtenir une date sous différents formats ou effectuer une conversion entre différents fuseaux. On distingue notamment les fonctions qui manipulent les dates relativement au temps universal coordonné (UTC). Le temps local est celui utilisé par l'appareil de l'utilisateur.</p> + +<p>Ainsi, on dispose de méthodes permettant d'obtenir ou de définir les différentes composantes d'une date selon le temps local (ex. {{jsxref("Date.getDay", "getDay()")}}, {{jsxref("Date.setHours", "setHours()")}}) et de méthodes équivalentes pour la manipulation en UTC (ex. {{jsxref("Date.getUTCDay()", "getUTCDay()")}} et {{jsxref("Date.setUTCHours", "setUTCHours()")}} respectivement).</p> + +<h2 id="Constructeur">Constructeur</h2> + +<dl> + <dt>{{jsxref("Date/Date", "Date()")}}</dt> + <dd>Cette fonction permet de créer un nouvel objet <code>Date</code>.</dd> +</dl> + +<h2 id="Méthodes_statiques">Méthodes statiques</h2> + +<dl> + <dt>{{jsxref("Date.now()")}}</dt> + <dd>Renvoie la valeur numérique correspondant au moment présent sous la forme du nombre de millisecondes écoulées depuis le premier janvier 1970 00:00:00 UTC (les secondes intercalaires (<em>leap seconds</em>) sont ignorées).</dd> + <dt>{{jsxref("Date.parse()")}}</dt> + <dd>Analyse la représentation textuelle d'une date et renvoie le nombre de millisecondes écoulées entre cette date et le premier janvier 1970, 00:00:00 UTC (les secondes intercalaires (<em>leap seconds</em>) sont ignorées). + <div class="note"> + <p><strong>Note :</strong> L'analyse de chaînes de caractères à l'aide de <code>Date.parse</code> est fortement déconseillée en raison des incohérences qui existent entre les navigateurs.</p> + </div> + </dd> + <dt>{{jsxref("Date.UTC()")}}</dt> + <dd>Accepte les mêmes paramètres que la forme longue du constructeur (c'est-à-dire entre 2 et 7) et renvoie le nombre de millisecondes entre cette date et le premier janvier 1970, 00:00:00 UTC (les secondes intercalaires (<em>leap seconds</em>) sont ignorées).</dd> +</dl> + +<h2 id="Méthodes_des_instances">Méthodes des instances</h2> + +<dl> + <dt>{{jsxref("Date.prototype.getDate()")}}</dt> + <dd>Renvoie le jour du mois (entre <code>1</code> et <code>31</code>) pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.getDay()")}}</dt> + <dd>Renvoie le jour de la semaine (entre <code>0</code> et <code>6</code>) pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.getFullYear()")}}</dt> + <dd>Renvoie l'année (sans chiffre implicite, <code>1999</code> sera renvoyé et pas <code>99</code> par exemple) pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.getHours()")}}</dt> + <dd>Renvoie l'heure (entre <code>0</code> et <code>23</code>) pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.getMilliseconds()")}}</dt> + <dd>Renvoie les millisecondes (entre <code>0</code> et <code>999</code>) pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.getMinutes()")}}</dt> + <dd>Renvoie les minutes (entre <code>0</code> et <code>59</code>) pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.getMonth()")}}</dt> + <dd>Renvoie le mois (entre <code>0</code> et <code>11</code>) pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.getSeconds()")}}</dt> + <dd>Renvoie les secondes (entre <code>0</code> et <code>59</code>) pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.getTime()")}}</dt> + <dd>Renvoie la valeur numérique de la date donnée, exprimée en nombre de millisecondes écoulées depuis le premier janvier 1970, 00:00:00 UTC (pour les temps antérieurs, ce sont des valeurs négatives qui seront renvoyées).</dd> + <dt>{{jsxref("Date.prototype.getTimezoneOffset()")}}</dt> + <dd>Renvoie le décalage horaire, exprimé en minutes, pour la locale courante.</dd> + <dt>{{jsxref("Date.prototype.getUTCDate()")}}</dt> + <dd>Renvoie le jour du mois (entre <code>1</code> et <code>31</code>) pour la date donnée, selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.getUTCDay()")}}</dt> + <dd>Renvoie le jour de la semaine (entre <code>0</code> et <code>6</code>) pour la date donnée, selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.getUTCFullYear()")}}</dt> + <dd>Renvoie l'année (sans chiffre implicite, <code>1999</code> sera renvoyé plutôt que <code>99</code>) pour la date donnée, selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.getUTCHours()")}}</dt> + <dd>Renvoie l'heure (entre <code>0</code> et <code>23</code>) pour la date donnée, selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.getUTCMilliseconds()")}}</dt> + <dd>Renvoie les millisecondes (entre <code>0</code> et <code>999</code>) pour la date donnée, selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.getUTCMinutes()")}}</dt> + <dd>Renvoie les minutes (entre <code>0</code> et <code>59</code>) pour la date donnée, selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.getUTCMonth()")}}</dt> + <dd>Renvoie le mois (entre <code>0</code> et <code>11</code>) pour la date donnée, selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.getUTCSeconds()")}}</dt> + <dd>Renvoie les secondes (entre <code>0</code> et <code>59</code>) pour la date donnée, selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.getYear()")}}</dt> + <dd>Renvoie l'année (généralement exprimée sur 2 ou 3 chiffres) pour la date donnée selon le temps local. <strong>On utilisera plutôt {{jsxref("Date.prototype.getFullYear()", "getFullYear()")}}</strong>.</dd> + <dt>{{jsxref("Date.prototype.setDate()")}}</dt> + <dd>Définit le jour du mois pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.setFullYear()")}}</dt> + <dd>Définit l'année (sans chiffre implicite, on utilisera <code>1999</code> et pas <code>99</code>) pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.setHours()")}}</dt> + <dd>Définit les heures pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.setMilliseconds()")}}</dt> + <dd>Définit les millisecondes pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.setMinutes()")}}</dt> + <dd>Définit les minutes pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.setMonth()")}}</dt> + <dd>Définit le mois pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.setSeconds()")}}</dt> + <dd>Définit les secondes pour la date donnée, selon le temps local.</dd> + <dt>{{jsxref("Date.prototype.setTime()")}}</dt> + <dd>Définit le nombre de millisecondes écoulées depuis le premier janvier 1970, 00:00:00 UTC et la date donnée. On utilisera des nombres négatifs pour les moments antérieurs à cette date.</dd> + <dt>{{jsxref("Date.prototype.setUTCDate()")}}</dt> + <dd>Définit le jour du mois pour la date donnée selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.setUTCFullYear()")}}</dt> + <dd>Définit l'année (exprimée sans chiffres implicites, ex. <code>1999</code> et pas <code>99</code>) pour la date donnée selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.setUTCHours()")}}</dt> + <dd>Définit l'heure pour la date donnée selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.setUTCMilliseconds()")}}</dt> + <dd>Définit les millisecondes pour la date donnée selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.setUTCMinutes()")}}</dt> + <dd>Définit les minutes pour la date donnée selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.setUTCMonth()")}}</dt> + <dd>Définit le mois pour la date donnée selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.setUTCSeconds()")}}</dt> + <dd>Définit les secondes pour la date donnée selon le temps universel.</dd> + <dt>{{jsxref("Date.prototype.setYear()")}}</dt> + <dd>Définit l'année (avec 2 à 3 chiffres) pour la date courante selon le temps local. <strong>On privilégiera la méthode {{jsxref("Date.prototype.setFullYear()", "setFullYear()")}} à la place.</strong></dd> + <dt>{{jsxref("Date.prototype.toDateString()")}}</dt> + <dd>Renvoie la partie "date" (jour, mois, année) de l'objet {{jsxref("Date")}} en une chaîne de caractères compréhensible par un humain (anglophone) (ex. <code>'Thu Apr 12 2018'</code>).</dd> + <dt>{{jsxref("Date.prototype.toISOString()")}}</dt> + <dd>Convertit une date en une chaîne de caractères selon le format ISO 8601 Étendu.</dd> + <dt>{{jsxref("Date.prototype.toJSON()")}}</dt> + <dd>Renvoie une chaîne de caractères représentant l'objet {{jsxref("Date")}} avec {{jsxref("Date.prototype.toISOString()", "toISOString()")}}. Cette méthode est utilisée par {{jsxref("JSON.stringify()")}}.</dd> + <dt>{{jsxref("Date.prototype.toGMTString()")}}</dt> + <dd>Renvoie une chaîne de caractères représentant l'objet {{jsxref("Date")}} d'après le fuseau GMT (UTC). <strong>On utilisera plutôt {{jsxref("Date.prototype.toUTCString()", "toUTCString()")}}</strong>.</dd> + <dt>{{jsxref("Date.prototype.toLocaleDateString()")}}</dt> + <dd>Renvoie une chaîne de caractères représentant les jours / mois / années de la date courante avec une représentation propre à la locale courante (déduite des paramètres systèmes utilisés).</dd> + <dt>{{jsxref("Date.prototype.toLocaleFormat()")}}</dt> + <dd>Convertit la date courante en une chaîne de caractères avec un format décrit en paramètre via une chaîne de caractères.</dd> + <dt>{{jsxref("Date.prototype.toLocaleString()")}}</dt> + <dd>Renvoie une chaîne de caractères représentant la date sous le forme de la locale courante. Cette méthode surcharge la méthode {{jsxref("Object.prototype.toLocaleString()")}}.</dd> + <dt>{{jsxref("Date.prototype.toLocaleTimeString()")}}</dt> + <dd>Renvoie une chaîne de caractères représentant les heures / minutes / secondes de la date courante avec une représentation propre à la locale courante (déduite des paramètres systèmes utilisés).</dd> + <dt>{{jsxref("Date.prototype.toString()")}}</dt> + <dd>Renvoie une chaîne de caractères représentant l'objet {{jsxref("Date")}} courant. Cette méthode surcharge la méthode {{jsxref("Object.prototype.toString()")}}.</dd> + <dt>{{jsxref("Date.prototype.toTimeString()")}}</dt> + <dd>Renvoie l'heure (avec les minutes et les secondes) d'une date sous la forme d'une chaîne de caractères compréhensible par un humain.</dd> + <dt>{{jsxref("Date.prototype.toUTCString()")}}</dt> + <dd>Convertit une date en chaîne de caractère en utilisant le temps universel comme référentiel.</dd> + <dt>{{jsxref("Date.prototype.valueOf()")}}</dt> + <dd>Renvoie la valeur primitive d'un objet {{jsxref("Date")}}. Cette méthode surcharge la méthode {{jsxref("Object.prototype.valueOf()")}}.</dd> +</dl> + +<h2 id="Exemples">Exemples</h2> + +<h3 id="Différentes_façons_de_créer_un_objet_Date">Différentes façons de créer un objet <code>Date</code></h3> + +<p>Les exemples qui suivent illustrent différentes méthodes permettant de créer des dates JavaScript :</p> + +<div class="note"> +<p><strong>Note :</strong> L'analyse de chaîne de caractères représentant des dates avec le constructeur <code>Date</code> (ou <code>Date.parse</code> qui est équivalent) est fortement déconseillée en raison des différences de comportement existant entre les navigateurs.</p> +</div> + +<pre class="brush: js notranslate">let aujourdhui = new Date() +let anniversaire = new Date('September 22, 2018 15:00:00') +let anniversaire = new Date('2018-09-22T15:00:00') +let anniversaire = new Date(2018, 8, 22) // the month is 0-indexed +let anniversaire = new Date(2018, 8, 22, 15, 0, 0) +</pre> + +<h3 id="Les_années_sur_deux_chiffres_correspondent_à_la_période_1900_–_1999">Les années sur deux chiffres correspondent à la période 1900 – 1999</h3> + +<p>Afin de créer et de manipuler des dates sur les années <code>0</code> à <code>99</code> de notre ère, on doit utiliser les méthodes {{jsxref("Date.prototype.setFullYear()")}} and {{jsxref("Date.prototype.getFullYear()")}}.</p> + +<pre class="brush: js notranslate">let date = new Date(98, 1) // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT) + +// Méthode dépréciée, 98 correspond également ici à 1998 +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) +</pre> + +<h3 id="Calculer_le_temps_écoulé">Calculer le temps écoulé</h3> + +<p>Dans les exemples suivants, on illustre comment calculer le temps écoulé entre deux dates JavaScript en millisecondes.</p> + +<p>En raison de durées différentes pour les jours (heure d'été / heure d'hiver), les mois et les années, il faudra faire attention et étudier le sujet avant d'exprimer des durées en unités supérieures à des heures / minutes / secondes.</p> + +<pre class="brush: js notranslate">// Utiliser des objets Date +let debut = Date.now() + +// Ici, l'évènement dont on veut mesurer la durée : +faireQuelqueChosePendantLongtemps() +let fin = Date.now() +let duree = fin - debut // La durée écoulée, en millisecondes +</pre> + +<pre class="brush: js notranslate">// En utilisant les méthodes natives +let debut = new Date() + +// Ici, l'évènement dont on veut mesurer la durée : +faireQuelqueChosePendantLongtemps() +let fin = new Date() +let duree = fin.getTime() - debut.getTime() // La durée écoulée, en millisecondes +</pre> + +<pre class="brush: js notranslate">// Pour tester le temps d'exécution d'une fonction +function afficheDureeEcoulee(fTest) { + let debut = Date.now(), + valRetour = fTest(), + fin = Date.now() + + console.log(`Durée écoulée : ${ String(fin - debut) } millisecondes`) + return valRetour +} + +let valeurDeRetour = afficheDureeEcoulee(maFonctionATester) +</pre> + +<div class="note"> +<p><strong>Note :</strong> Pour les navigateurs qui prennent en charge l'{{domxref("Window.performance", "API Web Performance", "", 1)}}, la méthode {{domxref("Performance.now()")}} peut fournir un outil de mesure des durées écoulées plus fiable et précis que {{jsxref("Date.now()")}}.</p> +</div> + +<h3 id="Obtenir_le_nombre_de_secondes_écoulées_depuis_lepoch_ECMAScript">Obtenir le nombre de secondes écoulées depuis l'epoch ECMAScript</h3> + +<pre class="brush: js notranslate">let secondes = Math.floor(Date.now() / 1000) +</pre> + +<p>Dans ce cas, on renvoie un entier et c'est pour ça qu'on utilise {{jsxref("Math.floor()")}}. Par ailleurs, on n'utilise pas {{jsxref("Math.round()")}} afin d'avoir le nombre de secondes effectivement écoulées.</p> + +<h2 id="Spécifications">Spécifications</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Spécification</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('ESDraft', '#sec-date-objects', 'Date')}}</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilité_des_navigateurs">Compatibilité des navigateurs</h2> + +<div class="hidden">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 à consulter <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> et à nous envoyer une <em>pull request</em>.</div> + +<p>{{Compat("javascript.builtins.Date", 3)}}</p> + +<h2 id="Voir_aussi">Voir aussi</h2> + +<ul> + <li>Le constructeur {{jsxref("Date/Date", "Date()")}}</li> +</ul> |