L'objet JavaScript Date

L'objet QML Date étend l'objet JS Date avec des fonctions tenant compte de la locale.

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

La forme des chaînes de format prises en charge est décrite dans la documentation de 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 des formats

Utilisez les valeurs de l'énumération lorsque vous souhaitez obtenir un format correspondant aux préférences locales.

Le format que les énumérations représentent dépend de votre locale, mais aussi de la méthode pour laquelle l'énumération est utilisée.

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

Remarques complémentaires

L'utilisation des fonctions locales pour formater la date ou l'heure peut entraîner un formatage incorrect des heures, en raison d'une incohérence dans les spécifications entre Qt et JS. L'ECMA-262 spécifie que les dates historiques doivent être interprétées en projetant les règles actuelles de l'heure d'été sur les années passées, alors 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 construction d'une valeur Date en JS et sa conversion en une chaîne de caractères à l'aide des fonctions sensibles aux paramètres locaux peut donner un résultat incorrect d'une heure si l'heure d'été est actuellement en vigueur, alors qu'elle ne l'était pas à l'heure spécifiée, ou vice versa.

Il existe différents formats de date avec différentes interprétations des années négatives. Le langage humain courant n'a pas d'année 0. L'année qui suit 1BC est 1AD. Cette compréhension se reflète lors de l'impression ou de l'analyse de dates dans l'un des formats non standardisés par ECMAScript. C'est-à-dire : toString(), toLocaleString(), toUTCString() et ses amis. ECMAScript standardise un format : ISO 8601. C'est ce que vous obtenez lorsque vous appelez toISOString(). Ce format inclut l'année 0, qui est 1BC dans les autres formats. Vous obtenez donc des années différentes lorsque vous imprimez des dates négatives avec toISOString() et toString().

Lors de la définition de l'année à l'aide du constructeur de la date ou de set(UTC)FullYear(), la convention établie par 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 set(UTC)FullYear() sont basées sur zéro et donc décalées d'une année par rapport à ce qui est imprimé avec toString() et friends. L'analyse de la sortie de n'importe quelle méthode to*String() donnera la même valeur de date que celle que vous avez imprimée. Date.parse() reconnaîtra les différents formats et leur convention sur l'existence de l'année 0.

Notez que tout ceci est différent de ce que vous obtenez dans d'autres implémentations JavaScript qui traitent généralement l'année 0 comme valide dans toutes les représentations de chaînes de caractères. Comme les formats de date sont "dépendants de l'implémentation" dans le standard ECMAScript, cela reste valable.

string Date::toLocaleString(locale, format)

Convertit la date en une chaîne de caractères contenant la date et l'heure correspondant à la locale locale dans la locale 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 la date et l'heure actuelles formatées pour la locale allemande :

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 correspondant à l'adresse locale spécifiée dans l'adresse format spécifiée.

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 la date actuelle formatée pour la locale allemande :

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 correspondant à l'adresse locale spécifiée dans l'adresse format spécifiée.

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 l'heure actuelle formatée pour 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 datetime dateTimeString en un objet Date en utilisant 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 une datetime analysée à partir d'une chaîne datetime dans un certain format 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 en utilisant 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 que la date actuelle est d'abord formatée comme une chaîne de date en utilisant la locale et le 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 en utilisant 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 que l'heure actuelle est d'abord formatée comme une chaîne de temps en utilisant la locale par défaut et 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()

Informe le moteur JS que le fuseau horaire du système a été modifié, ce qui est nécessaire pour la manipulation correcte des données temporelles.

JS stocke les objets Date en heure UTC ; tous les accès aux composants Date en heure locale impliquent l'application du décalage actuel par rapport à l'heure UTC. Si le décalage actuel change en raison de la mise à jour du fuseau horaire, le moteur JS doit en être informé afin qu'il puisse recalculer le décalage.

Cette fonction doit être appelée après la mise à jour du fuseau horaire du système.

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

property string selectedTimeZone

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