JavaScript 的 Date 对象

QML 的 Date 对象在JS Date 对象的基础上扩展了支持区域设置的函数。

接受 `format ` 参数的函数可以接受 `Locale.LongFormat`、`Locale.ShortFormat`、`Locale.NarrowFormat` 枚举值，或者指定格式的字符串。

支持的格式字符串形式如QDate::toString()、QTime::toString() 和QDateTime::toString() 的文档中所述。

如果日期无效，则返回一个空字符串。

格式枚举值

若需使用与区域设置偏好相匹配的格式，请使用这些枚举值。

枚举所表示的格式不仅取决于您的区域设置，还取决于使用该枚举的方法。

例如，对于en_US 区域设置，将使用以下格式字符串：

补充说明

由于 Qt 和 JS 之间的规范不一致，使用支持区域设置的函数进行日期或时间格式化可能会导致时间格式不正确。 ECMA-262 规定，历史日期应通过将当前的夏令时规则投影到过去几年中来解释，而 Qt 则使用历史数据（如有）来确定给定日期是否实行夏令时。 因此，如果在 JS 中构建一个 Date 值，并使用支持区域设置的函数将其转换为字符串，当当前夏令时生效，而指定时间未生效时，或者反之，结果可能会出现一小时的误差。

不同的日期格式对负年的理解各不相同。 日常语言中并不存在公元0年。公元前1年之后是公元1年。这种理解体现在使用ECMAScript未标准化的日期格式（如 toString()、toLocaleString()、toUTCString() 及其相关函数）打印或解析日期时。 ECMAScript 确实标准化了一种格式：ISO 8601。调用 toISOString() 时返回的正是该格式。该格式包含 0 年，而在其他格式中 0 年对应于公元前 1 年。因此，使用 toISOString() 和 toString() 打印负年份时，会得到不同的年份结果。

当使用 Date 构造函数或 set(UTC)FullYear() 设置年份时，会采用 ISO 8601 规定的约定，其中 0 被视为有效年份。这意味着通过构造函数或 set(UTC)FullYear() 设置的负年份采用零基制，因此与 toString() 及其相关方法打印的结果存在一年之差。 解析任何 to*String() 方法的输出结果，将得到与打印时相同的日期值。Date.parse() 会识别不同的格式及其关于 0 年的约定。

请注意，这与其他 JavaScript 实现中的情况不同——其他实现通常在所有字符串表示中都将 0 年视为有效。不过，由于 ECMAScript 标准中日期格式属于“实现依赖型”，因此这种做法仍然有效。

string Date::toLocaleString(locale, format)

将 Date 转换为一个字符串，该字符串包含适合指定 `locale ` 且符合指定 `format` 的日期和时间。

如果未指定format ，则使用Locale.LongFormat 。

如果未指定locale ，则将使用 。

以下示例展示了按德语区域设置格式化的当前日期和时间：

import QtQuick 2.0

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

string Date::toLocaleDateString(locale, format)

将 Date 转换为字符串，该字符串包含符合指定locale 且符合指定format 的日期格式。

如果未指定format ，则使用Locale.LongFormat 。

如果未指定locale ，则使用 。

以下示例展示了按德语区域设置格式化的当前日期：

import QtQuick 2.0

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

string Date::toLocaleTimeString(locale, format)

将 Date 转换为一个字符串，其中包含符合指定locale 且符合指定format 的时间格式。

如果未指定format ，则将使用Locale.LongFormat 。

如果未指定locale ，则将使用 。

以下示例展示了按德语区域设置格式化的当前时间：

import QtQuick 2.0

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

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

使用 `locale ` 和 `format` 将日期时间字符串 `dateTimeString ` 转换为`Date` 对象。

如果未指定format ，则将使用Locale.LongFormat 。

如果未指定locale ，则将使用默认区域设置。

以下示例展示了如何使用默认区域设置，从特定格式的日期时间字符串中解析出日期时间：

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)

使用locale 和format 将日期字符串dateString 转换为Date对象。

如果未指定format ，则将使用Locale.LongFormat 。

如果未指定locale ，则将使用默认区域设置。

以下示例首先使用默认区域设置和格式将当前日期格式化为日期字符串，然后以相同的方式将其解析回来：

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)

使用locale 和format 将时间字符串timeString 转换为Date对象。

如果未指定format ，则将使用Locale.LongFormat 。

如果未指定locale ，则将使用默认区域设置。

以下示例展示了如何先使用默认区域设置和简短格式将当前时间格式化为时间字符串，然后以相同方式将其解析回来：

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()

该方法通知 JS 引擎系统时区已发生变更，这是正确处理日期和时间数据所必需的。

JS 以 UTC 时间存储 Date 对象；所有以本地时间访问 Date 组件或从其获取数据的行为，都涉及应用当前相对于 UTC 的偏移量。如果因时区更新导致当前偏移量发生变化，则需要通知 JS 引擎，以便其重新计算偏移量。

应在系统时区更新完成后调用此函数。

例如，一个更改时区的应用程序会在设置新时区后调用 timeZoneUpdated()：

property string selectedTimeZone

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