L'objet JavaScript Date

L'objet Date de QML étend l'objet Date de JavaScript avec des fonctions tenant compte des paramètres régionaux.

Les fonctions qui acceptent un argument « format » prennent soit les valeurs d’énumération Locale.LongFormat, Locale.ShortFormat, Locale.NarrowFormat, soit une chaîne de caractères spécifiant le format.

La syntaxe des chaînes de format prises en charge est celle décrite dans la documentation des fonctions QDate::toString(), QTime::toString() et QDateTime::toString().

Si la date n’est pas valide, une chaîne vide est renvoyée.

Valeurs de l'énumération Format

Utilisez les valeurs d’énumération lorsque vous souhaitez un format correspondant aux préférences régionales.

Le format représenté par les énumérations dépendra de vos paramètres régionaux, mais aussi de la méthode pour laquelle l'énumération est utilisée.

Par exemple, pour la locale en_US, les chaînes de format suivantes sont utilisées :

Remarques supplémentaires

L'utilisation des fonctions tenant compte des paramètres régionaux pour le formatage de la date ou de l'heure peut entraîner des formats d'heure incorrects, en raison d'une incohérence entre les spécifications de Qt et celles de JS. La norme ECMA-262 spécifie que les dates historiques doivent être interprétées en appliquant les règles actuelles relatives à l'heure d'été aux années passées, tandis que Qt utilise les données historiques (lorsqu'elles sont disponibles) pour déterminer si l'heure d'été était en vigueur à une date donnée. Par conséquent, la création d’une valeur Date en JS et sa conversion en chaîne à l’aide des fonctions tenant compte des paramètres régionaux peuvent donner un résultat erroné d’une heure, si l’heure d’été est actuellement en vigueur alors qu’elle ne l’était pas à la date spécifiée, ou inversement.

Il existe différents formats de date avec des interprétations différentes des années négatives. Le langage courant ne connaît pas d’année 0. L’année suivant 1 av. J.-C. est 1 apr. J.-C. Cette interprétation se reflète lors de l’affichage ou de l’analyse de dates dans l’un des formats non normalisés par ECMAScript. À savoir : toString(), toLocaleString(), toUTCString() et autres fonctions similaires. ECMAScript normalise un seul format : ISO 8601. C’est ce que l’on obtient en appelant toISOString(). Ce format inclut une année 0, qui correspond à 1 av. J.-C. dans d’autres formats. On obtient donc des années différentes lors de l’affichage de dates négatives avec toISOString() et toString().

Lorsque vous définissez l’année à l’aide du constructeur Date ou de la méthode set(UTC)FullYear(), la convention établie par la norme ISO 8601 est utilisée et 0 est une année valide. Cela signifie que les années négatives définies avec le constructeur ou la méthode set(UTC)FullYear() sont basées sur zéro et présentent donc un décalage d’une année par rapport à ce qui est affiché avec toString() et ses méthodes apparentées. L'analyse de la sortie de n'importe laquelle des méthodes to*String() donnera la même valeur de date que celle à partir de laquelle vous avez effectué l'affichage. Date.parse() reconnaîtra les différents formats et leur convention concernant l'existence de l'année 0.

Notez que tout cela diffère de ce que vous obtenez dans d’autres implémentations de JavaScript, qui traitent généralement l’année 0 comme valide dans toutes les représentations sous forme de chaîne. Cependant, comme les formats de date sont « dépendants de l’implémentation » dans la norme ECMAScript, cela reste valable.

chaîne Date::toLocaleString(locale, format)

Convertit l’objet Date en une chaîne de caractères contenant la date et l’heure adaptées à l’ locale spécifiée dans l’ format spécifiée.

Si format n’est pas spécifié, Locale.LongFormat sera utilisé.

Si locale n’est pas spécifiée, la locale par défaut sera utilisée.

L'exemple suivant affiche la date et l'heure actuelles formatées selon les paramètres régionaux allemands :

import QtQuick 2.0

Text {
    text: "The date is: " + new Date().toLocaleString(Qt.locale("de_DE"))
}

string Date::toLocaleDateString(locale, format)

Convertit la date en une chaîne de caractères contenant la date adaptée à l’ locale spécifiée dans l’ format spécifiée.

Si l'format n'est pas spécifiée, l'Locale.LongFormat sera utilisée.

Si locale n'est pas spécifié, la locale par défaut sera utilisée.

L'exemple suivant montre la date du jour formatée selon les paramètres régionaux allemands :

import QtQuick 2.0

Text {
    text: "The date is: " + new Date().toLocaleDateString(Qt.locale("de_DE"))
}

string Date::toLocaleTimeString(locale, format)

Convertit la date en une chaîne de caractères contenant l'heure adaptée à l'locale spécifiée dans l'format spécifiée.

Si l'format n'est pas spécifiée, l'Locale.LongFormat sera utilisée.

Si locale n'est pas spécifiée, la locale par défaut sera utilisée.

L'exemple suivant montre l'heure actuelle formatée selon la locale allemande :

import QtQuick 2.0

Text {
    text: "The date is: " + new Date().toLocaleTimeString(Qt.locale("de_DE"))
}

string Date::fromLocaleString(locale, dateTimeString, format)

Convertit la chaîne de date et d'heure dateTimeString en un objet Date à l'aide de locale et format.

Si format n’est pas spécifié, Locale.LongFormat sera utilisé.

Si locale n’est pas spécifié, les paramètres régionaux par défaut seront utilisés.

L'exemple suivant montre comment analyser une date-heure à partir d'une chaîne de caractères au format spécifié en utilisant la locale par défaut :

import QtQml 2.0

QtObject {
    property var locale: Qt.locale()
    property string dateTimeString: "Tue 2013-09-17 10:56:06"

    Component.onCompleted: {
        print(Date.fromLocaleString(locale, dateTimeString, "ddd yyyy-MM-dd hh:mm:ss"));
    }
}

string Date::fromLocaleDateString(locale, dateString, format)

Convertit la chaîne de date dateString en un objet Date à l'aide de locale et format.

Si format n’est pas spécifié, Locale.LongFormat sera utilisé.

Si locale n’est pas spécifié, les paramètres régionaux par défaut seront utilisés.

L'exemple suivant montre comment la date actuelle est d'abord formatée sous forme de chaîne de date à l'aide de la locale et du format par défaut, puis analysée à nouveau de la même manière :

import QtQml 2.0

QtObject {
    property var locale: Qt.locale()
    property date currentDate: new Date()
    property string dateString

    Component.onCompleted: {
        dateString = currentDate.toLocaleDateString();
        print(Date.fromLocaleDateString(dateString));
    }
}

string Date::fromLocaleTimeString(locale, timeString, format)

Convertit la chaîne de temps timeString en un objet Date à l’aide de locale et format.

Si format n’est pas spécifié, Locale.LongFormat sera utilisé.

Si locale n’est pas spécifié, la locale par défaut sera utilisée.

L'exemple suivant montre comment l'heure actuelle est d'abord formatée sous forme de chaîne de caractères à l'aide de la locale par défaut et d'un format court, puis analysée à nouveau de la même manière :

import QtQml 2.2

QtObject {
    property var locale: Qt.locale()
    property date currentTime: new Date()
    property string timeString

    Component.onCompleted: {
        timeString = currentTime.toLocaleTimeString(locale, Locale.ShortFormat);
        print(Date.fromLocaleTimeString(locale, timeString, Locale.ShortFormat));
    }
}

string Date::timeZoneUpdated()

Indique au moteur JS que le fuseau horaire du système a été modifié, ce qui est nécessaire pour la manipulation correcte des données de date et d’heure.

JS stocke les objets Date en heure UTC ; tout accès aux composants Date en heure locale implique l’application du décalage actuel par rapport à l’UTC. Si le décalage actuel change en raison d’une mise à jour du fuseau horaire, le moteur JS doit en être informé afin de pouvoir recalculer ce décalage.

Cette fonction doit être appelée une fois que le fuseau horaire du système a été mis à jour.

Par exemple, une application qui modifie le fuseau horaire appellerait timeZoneUpdated() après avoir défini le nouveau fuseau horaire :

property string selectedTimeZone

onSelectedTimeZoneChanged: {
    MyFunctions.setSystemTimeZone(selectedTimeZone)
    Date.timeZoneUpdated()
}