QTimeZone Class
QTimeZone 用于确定某种时间表示形式与 UTC 之间的关系。更多内容...
| 标题: | #include <QTimeZone> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
注意:本类中的所有函数均是线程安全的。
QTimeZone 比较
| 类别 | 可比较类型 |
|---|---|
| 相等性 | QTimeZone |
公共类型
| struct | OffsetData |
(since 6.5) enum | Initialization { LocalTime, UTC } |
| enum | NameType { DefaultName, LongName, ShortName, OffsetName } |
| OffsetDataList | |
| enum | TimeType { StandardTime, DaylightTime, GenericTime } |
公共函数
| QTimeZone() | |
(since 6.5) | QTimeZone(QTimeZone::Initialization spec) |
| QTimeZone(const QByteArray &ianaId) | |
| QTimeZone(int offsetSeconds) | |
| QTimeZone(const QByteArray &zoneId, int offsetSeconds, const QString &name, const QString &abbreviation, QLocale::Territory territory = QLocale::AnyTerritory, const QString &comment = QString()) | |
| QTimeZone(const QTimeZone &other) | |
| QTimeZone(QTimeZone &&other) | |
| ~QTimeZone() | |
| QString | abbreviation(const QDateTime &atDateTime) const |
(since 6.5) QTimeZone | asBackendZone() const |
| QString | comment() const |
| int | daylightTimeOffset(const QDateTime &atDateTime) const |
| QString | displayName(QTimeZone::TimeType timeType, QTimeZone::NameType nameType = DefaultName, const QLocale &locale = QLocale()) const |
| QString | displayName(const QDateTime &atDateTime, QTimeZone::NameType nameType = DefaultName, const QLocale &locale = QLocale()) const |
(since 6.5) int | fixedSecondsAheadOfUtc() const |
(since 6.8) bool | hasAlternativeName(QByteArrayView alias) const |
| bool | hasDaylightTime() const |
| bool | hasTransitions() const |
| QByteArray | id() const |
| bool | isDaylightTime(const QDateTime &atDateTime) const |
(since 6.5) bool | isUtcOrFixedOffset() const |
| bool | isValid() const |
| QTimeZone::OffsetData | nextTransition(const QDateTime &afterDateTime) const |
| QTimeZone::OffsetData | offsetData(const QDateTime &forDateTime) const |
| int | offsetFromUtc(const QDateTime &atDateTime) const |
| QTimeZone::OffsetData | previousTransition(const QDateTime &beforeDateTime) const |
| int | standardTimeOffset(const QDateTime &atDateTime) const |
| void | swap(QTimeZone &other) |
(since 6.2) QLocale::Territory | territory() const |
(since 6.5) Qt::TimeSpec | timeSpec() const |
| CFTimeZoneRef | toCFTimeZone() const |
| NSTimeZone * | toNSTimeZone() const |
| QTimeZone::OffsetDataList | transitions(const QDateTime &fromDateTime, const QDateTime &toDateTime) const |
| QTimeZone & | operator=(QTimeZone &&other) |
| QTimeZone & | operator=(const QTimeZone &other) |
静态公共成员
| const int | MaxUtcOffsetSecs |
| const int | MinUtcOffsetSecs |
| QList<QByteArray> | availableTimeZoneIds() |
| QList<QByteArray> | availableTimeZoneIds(QLocale::Territory territory) |
| QList<QByteArray> | availableTimeZoneIds(int offsetSeconds) |
| QTimeZone | fromCFTimeZone(CFTimeZoneRef timeZone) |
(since 6.5) QTimeZone | fromDurationAheadOfUtc(std::chrono::seconds offset) |
| QTimeZone | fromNSTimeZone(const NSTimeZone *timeZone) |
(since 6.5) QTimeZone | fromSecondsAheadOfUtc(int offset) |
(since 6.4) QTimeZone | fromStdTimeZonePtr(const std::chrono::time_zone *timeZone) |
| QByteArray | ianaIdToWindowsId(const QByteArray &ianaId) |
| bool | isTimeZoneIdAvailable(QByteArrayView ianaId) |
(since 6.5) bool | isUtcOrFixedOffset(Qt::TimeSpec spec) |
| QTimeZone | systemTimeZone() |
| QByteArray | systemTimeZoneId() |
| QTimeZone | utc() |
| QByteArray | windowsIdToDefaultIanaId(const QByteArray &windowsId) |
| QByteArray | windowsIdToDefaultIanaId(const QByteArray &windowsId, QLocale::Territory territory) |
| QList<QByteArray> | windowsIdToIanaIds(const QByteArray &windowsId) |
| QList<QByteArray> | windowsIdToIanaIds(const QByteArray &windowsId, QLocale::Territory territory) |
相关的非成员
| bool | operator!=(const QTimeZone &lhs, const QTimeZone &rhs) |
| bool | operator==(const QTimeZone &lhs, const QTimeZone &rhs) |
详细说明
当日期和时间结合时,结果的含义取决于时间的表示方式。 关于时间的表示方式,存在多种国际标准;其中之一是 UTC,它对应于格林尼治太阳平均时(又称 GMT)这一传统标准。Qt 支持的所有其他时间系统最终都是相对于 UTC 来定义的。该类的实例提供了一个无状态计算器,用于在 UTC 与其他时间表示法之间进行转换。
某些时间表示法仅通过相对于 UTC 的固定偏移量来定义。另一些则由各国政府定义,供其管辖范围内使用。后者通常被称为时区,但 QTimeZone(自 Qt 6.5 起)将其表示形式与通用时间系统的表示形式进行了统一。 大多数操作系统普遍支持的一个时区被指定为本地时间;该时区被假定对应于用户所居住的时区。
对于本地时间以外的时区、UTC 以及相对于 UTC 具有固定偏移量的时区,只有当操作系统提供某种方式来访问相关信息时,Qt 才能提供支持。在构建 Qt 时,timezone 功能控制此类信息是否可用。 如果未启用该功能,QTimeZone 的某些构造函数和方法将从其 API 中排除;这些内容在文档中被标记为依赖于timezone 功能。请注意,即使在构建 Qt 时启用了此功能,对于系统配置错误或未安装某些标准软件包(例如 Linux 上的tzdata 软件包)的用户,该功能也可能不可用。 当有时区信息可用时,此功能默认处于启用状态。
该类主要设计用于QDateTime ;大多数应用程序无需直接访问该类,而应在构造QDateTime 时使用其实例。
注意:为了 与QDateTime 保持一致,QTimeZone 不考虑闰秒。
备注
与QDateTime 一样,QTimeZone以秒为单位衡量与UTC的偏移量。这与其通常以毫秒为单位衡量时间的做法形成对比。 现实世界中的时区,其UTC偏移量通常是5分钟(300秒)的整数倍,至少自1970年之前便是如此。相对于UTC的正偏移量表示:某一天的正午时间早于该日UTC正午;负偏移量则表示该日正午时间晚于UTC正午。
轻量级时间表示法
即使禁用了timezone 功能,QTimeZone仍可表示UTC、本地时间以及相对于UTC的固定偏移量。该功能启用时,其表示形式同样可用;这是一种更轻量级的形式,使用它进行处理通常会更高效,除非正在调用仅在启用timezone 功能时才可用的方法。 有关如何构建这些表示形式,请参阅Initialization 和QTimeZone::fromSecondsAheadOfUtc(int)。
本文档区分了“时区”(用于描述由系统提供的或标准信息所描述的时间表示形式)和更普遍的时间表示形式(包括这些轻量级形式)。 仅在启用timezone 功能时才可用的方法,对于时区而言通常比对于轻量级时间表示形式更高效;对于后者,这些方法可能会构建一个合适的临时时区对象,并将查询转发至该对象。
IANA 时区 ID
QTimeZone 使用 IANA 时区数据库(http://www.iana.org/time-zones)中定义的 IANA 时区 ID。这是为了确保在所有受支持的平台上使用标准 ID。 大多数平台原生支持 IANA 标识符和 IANA 数据库,但在 Windows 系统上需要将其映射到本机标识符。更多详细信息请参见下文。
IANA 标识符会定期更新,且可能因主机系统数据的更新时间而有所不同。因此,您不能指望任何给定的标识符在任何主机系统上都存在。您必须使用availableTimeZoneIds() 来确定可用的 IANA 标识符。
IANA 标识符和数据库也被称为 Olson 标识符和数据库,该名称源自该数据库的最初编译者。
UTC 偏移时区
系统提供了一个默认的 UTC 时区后端,当启用timezone 功能时,该后端始终可用。它提供了一组通用“相对于 UTC 的偏移量”时区,范围从 UTC-16:00 到 UTC+16:00。 这些时区既可以使用availableTimeZoneIds() 中列出的标准 ISO 格式名称(例如“UTC+00:00”),也可以使用类似格式的名称结合偏移秒数来创建。
Windows 时区
与标准的 IANA TZ 数据库相比,Windows 原生时区支持非常有限。Windows 时区覆盖的地理范围更广,因此其转换精度较低。此外,它们不支持那么多的历史数据,因此可能仅对当前年度准确。 特别是,当微软的时区数据声称 1900 年之前曾实行夏令时(历史事实证明并非如此)时,该声明将被忽略,并认为 1900 年(据称)生效的标准时间一直有效。
QTimeZone 使用源自 Unicode CLDR 数据的转换表,在 IANA ID 与 Windows ID 之间进行映射。根据您所使用的 Windows 和 Qt 版本不同,该转换表可能无法提供有效的转换结果,此时将返回“UTC”。
QTimeZone 提供了一个用于使用此转换表的公共 API。所使用的 Windows ID 是该时区的 Windows 注册表项,它同时也是 MS Exchange 的 EWS ID,但与 2007 年之前版本的 MS Exchange 所使用的时区名称(TZID)和 COD 代码不同。
注意:当 Qt 使用 ICU 库构建时,系统会优先使用 ICU 库,而非 Windows 系统 API,从而避开了这些 API 因名称不一致而引发的所有问题。
WebAssembly
在 WebAssembly 环境中,当以后端形式表示时,QTimeZone 仅支持 UTC 以及固定 UTC 偏移量的时间区。由于无法访问 IANA 时区数据库,因此诸如 `availableTimeZoneIds()` 之类的函数仅返回具有 UTC 偏移量的时间区。 系统时区通过 JavaScript 的 `Date.getTimezoneOffset() ` 获取,并以固定偏移量(例如“UTC+02:00”)的形式表示,而非地理位置的 IANA ID。不过,`QTimeZone(QTimeZone::LocalTime)` 仍能准确反映本地时间,因为它依赖于平台的标准时间函数。
系统时区
方法systemTimeZoneId() 返回当前系统的 IANA 时区 ID,在类 Unix 系统上该值始终正确。 在 Windows 上,该 ID 是通过内部转换表和用户选择的国家/地区,从 Windows 系统 ID 转换而来的。因此,存在极小概率,某些 Windows 安装环境中的 ID 可能未被 Qt 识别,这种情况下将返回“UTC”。
使用系统时区 ID 创建新的 QTimeZone 实例只会生成该时区的固定命名副本,即使系统时区发生变化,该副本也不会随之改变。QTimeZone::systemTimeZone() 将返回一个代表该系统 ID 所指时区的实例。 请注意,使用该系统时区构建QDateTime 的行为可能与构建QDateTime (其将Qt::LocalTime 作为Qt::TimeSpec )的行为不同,因为后者直接使用系统API访问本地时间信息,其行为可能有所不同(特别是,当用户调整系统时区设置时,它可能会随之调整)。
时区偏移量
UTC 与某个时区当地时间之间的差异以相对于 UTC 的偏移量(单位为秒)表示,即获得当地时间时需加到 UTC 上的秒数。总偏移量由两个组成部分构成:标准时间偏移量和夏令时偏移量。 标准时间偏移量是指为获得该时区的标准时间,需加到 UTC 上的秒数。夏令时偏移量是指为获得该时区的夏令时(缩写为 DST,有时也称为“日光时间”或“夏季时间”),需加到标准时间偏移量上的秒数。 通常情况下,夏令时(冬季采用标准时间,夏季采用夏令时)的夏令时偏移量为正值。然而,某些时区在冬季采用负值夏令时偏移量,而夏季则采用标准时间。
请注意,随着各国修改夏令时法规甚至调整标准时间偏移量,某个时区的标准时间偏移量和夏令时偏移量可能会随时间变化。
许可
本类包含根据《Unicode数据文件和软件许可协议》条款从CLDR数据文件中获取的数据。详情请参阅Unicode通用区域设置数据存储库(CLDR)。
成员类型文档
[since 6.5] enum QTimeZone::Initialization
最简单的轻量级时间表示类型的类型。
此枚举用于标识一种轻量级时间表示类型,可将其传递给QTimeZone 构造函数,且无需额外数据。它们对应于Qt::TimeSpec 中同名的成员。
| 常量 | 值 | 描述 |
|---|---|---|
QTimeZone::LocalTime | 0 | 该时间表示形式对应于系统函数所隐式使用的表示形式,这些函数使用time_t 和struct tm 值在本地时间与协调世界时(UTC)之间进行映射。 |
QTimeZone::UTC | 1 | 这种时间表示形式——协调世界时(UTC)——是所有受支持的时间表示形式中民用时间所参照的基础表示形式。它由国际电信联盟定义。 |
该枚举类型在 Qt 6.5 中引入。
enum QTimeZone::NameType
时区名称的类型。
| 常量 | 值 | 描述 |
|---|---|---|
QTimeZone::DefaultName | 0 | 时区名称的默认形式,可以是 LongName、ShortName 或 OffsetName 之一 |
QTimeZone::LongName | 1 | 时区名称的长形式,例如“中欧时间” |
QTimeZone::ShortName | 2 | 时区名称的简短形式,通常为缩写(例如“CET”),若该时区在特定语言环境中设有缩写则采用缩写;否则采用紧凑的GMT偏移量形式,例如“GMT+1” |
QTimeZone::OffsetName | 3 | 时区名称的标准 ISO 偏移量形式,例如“UTC+01:00” |
此类型仅在启用timezone 功能时可用。
QTimeZone::OffsetDataList
QList<OffsetData> 的同义词。
只有在启用“timezone ”功能时,此类型才可用。
enum QTimeZone::TimeType
时区的名称可能会随季节变化而变化,以表明该时区是采用相对于协调世界时(UTC)的标准偏移量,还是对该偏移量进行了夏令时调整。在这种情况下,该时区通常还拥有一个无论季节如何都适用的通用名称。在请求时区的显示名称时,此类型用于确定应使用上述哪个名称。 在不实行夏令时的时区中,这三个值可能返回相同的结果。
| 常量 | 值 | 描述 |
|---|---|---|
QTimeZone::StandardTime | 0 | 该时区的标准时间名称。例如,“太平洋标准时间”。 |
QTimeZone::DaylightTime | 1 | 夏令时生效时该时区的名称。例如,“太平洋夏令时”。 |
QTimeZone::GenericTime | 2 | 该时区不考虑是否采用夏令时调整时的名称。例如,“太平洋时间”。 |
此类型仅在启用timezone 功能时可用。
成员函数文档
[noexcept] QTimeZone::QTimeZone()
创建一个空的/无效的时区实例。
[noexcept, since 6.5] QTimeZone::QTimeZone(QTimeZone::Initialization spec)
创建一个描述协调世界时(UTC)或本地时间的轻量级实例。
该函数在 Qt 6.5 中引入。
另请参阅 fromSecondsAheadOfUtc()、asBackendZone()、utc() 以及systemTimeZone()。
[explicit] QTimeZone::QTimeZone(const QByteArray &ianaId)
创建一个时间区实例,其 IANA ID 为ianaId 。
该 ID 必须是可用的系统 ID 之一,或是一个有效的带偏移量的 UTC ID,否则将返回一个无效的时区。对于带偏移量的 UTC ID,当它们实际上并非 IANA ID 时,生成的实例的id() 可能与传递给构造函数的 ID 不同。
仅当启用timezone 功能时,此构造函数才可用。
另请参阅 availableTimeZoneIds() 和id()。
[explicit] QTimeZone::QTimeZone(int offsetSeconds)
创建一个时区实例,其偏移量为offsetSeconds ,以UTC为基准。
该偏移量offsetSeconds 必须在-16小时到+16小时之间,否则将返回一个无效的时区。
只有在启用了timezone 功能时,此构造函数才可用。返回的实例等同于轻量级时间表示QTimeZone::fromSecondsAheadOfUtc(offsetSeconds) ,尽管它是作为时区实现的。
另请参阅 MinUtcOffsetSecs 、MaxUtcOffsetSecs 以及id()。
QTimeZone::QTimeZone(const QByteArray &zoneId, int offsetSeconds, const QString &name, const QString &abbreviation, QLocale::Territory territory = QLocale::AnyTerritory, const QString &comment = QString())
创建一个相对于UTC具有固定偏移量的自定义时区实例。
返回的时区 ID 为zoneId ,相对于 UTC 的偏移量为offsetSeconds 。name 将作为displayName() 函数中LongName 的名称,abbreviation 将用于displayName() 函数中的ShortName 以及abbreviation() 函数,而可选参数territory 将用于territory() 函数。comment 是一条可选注释,可在图形用户界面 (GUI) 中显示,以协助用户选择时区。
相对于 UTC 的offsetSeconds 必须在 -16 小时到 +16 小时的范围内。zoneId 不能是 isTimeZoneIdAvailable() 返回 true 的 ID,除非它是availableTimeZoneIds() 中未出现的 UTC 偏移量名称。
如果自定义时区没有特定的地域,则将其设置为默认值QLocale::AnyTerritory 。
只有在启用了timezone 功能时,此构造函数才可用。
另请参阅 id()、offsetFromUtc()、displayName()、abbreviation()、territory()、comment()、MinUtcOffsetSecs 以及MaxUtcOffsetSecs 。
[noexcept] QTimeZone::QTimeZone(const QTimeZone &other)
复制构造函数:将other 复制到this中。
[noexcept] QTimeZone::QTimeZone(QTimeZone &&other)
将此类的移动构造函数从other 移至此处。
[noexcept] QTimeZone::~QTimeZone()
破坏时区。
QString QTimeZone::abbreviation(const QDateTime &atDateTime) const
返回给定atDateTime 对应的时区缩写。
该缩写可能会因夏令时(DST)甚至历史事件而发生变化。
注意: 无法保证该缩写 在该时区内具有唯一性,因此不应将其用作 ID 或显示名称的替代。根据底层操作系统的不同,该缩写可能会被本地化。如需获得一致的本地化效果,请使用displayName(atDateTime, QTimeZone::ShortName, locale) 。
此方法仅在启用timezone 功能时可用。
另请参阅 displayName()。
[since 6.5] QTimeZone QTimeZone::asBackendZone() const
将此QTimeZone 转换为一个其timeSpec()结果为Qt::TimeZone 的对象。
在所有情况下,结果的timeSpec() 均为Qt::TimeZone 。当该QTimeZone 的timeSpec() 为Qt::TimeZone 时,返回此QTimeZone 本身。若timeSpec() 为Qt::LocalTime ,则返回systemTimeZone()。
如果timeSpec() 的返回值为Qt::UTC ,则返回QTimeZone::utc()。如果返回值为Qt::OffsetFromUTC ,则向QTimeZone(int) 传递其偏移量,并返回结果。
当使用轻量级时间表示形式(本地时间、UTC 时间或相对于 UTC 的固定偏移时间)时,若调用仅在启用timezone 功能时才支持的方法,其开销可能比使用相应时区更大。此方法将轻量级时间表示形式映射到相应的时区——即基于系统提供的或标准数据的实例。
此方法仅在启用timezone 功能时可用。
该函数在 Qt 6.5 中引入。
另请参阅 QTimeZone(QTimeZone::Initialization) 和fromSecondsAheadOfUtc()。
[static] QList<QByteArray> QTimeZone::availableTimeZoneIds()
返回该系统上可用时区 ID 的列表。
其中包括系统时区信息源所支持的每个时区的 IANA ID,以及这些时区的部分别名和一组常用的 UTC 偏移量 ID。
QTimeZone 构造函数还会接受一些未出现在所返回列表中的UTC偏移量ID——因为列出所有可能的UTC偏移量ID并不现实。它还接受受支持的IANA ID的已知别名,其中一些可能未出现在此列表中。此类ID也可由isTimeZoneIdAvailable()接受。
当 Unicode 联盟的通用区域设置数据存储库 (CLDR) 将某个受支持的 IANA ID 视为该时区稳定名称的别名时, 该时区的稳定名称也会被纳入列表(即使该名称可能已过时),此举既是为了确保稳定性,也是为了在不同系统时区信息源对同一时区使用不同别名的情况下,提供跨平台的共同基准。
此方法仅在启用timezone 功能时可用。
另请参阅 isTimeZoneIdAvailable() 和hasAlternativeName()。
[static] QList<QByteArray> QTimeZone::availableTimeZoneIds(QLocale::Territory territory)
返回给定territory 的所有可用IANA时区ID列表。
作为特例,当territory 的值为AnyTerritory 时,将选择那些不与特定地区关联的时区(如UTC);而当值为World 时,则选择那些具有全局默认IANA ID的时区。若需获取所有地区的全部时区ID列表,请使用标准的availableTimeZoneIds()方法。
此方法仅在启用timezone 功能时可用。
另请参阅 isTimeZoneIdAvailable() 和territory()。
[static] QList<QByteArray> QTimeZone::availableTimeZoneIds(int offsetSeconds)
返回所有具有给定标准时间偏移量offsetSeconds 的可用 IANA 时区 ID 列表。
如果支持该偏移量,则列表中会包含QTimeZone(offsetSeconds).id() ,即使它不是 IANA ID。这种情况仅在没有与给定偏移量对应的 IANA UTC 偏移量 ID 时才会发生。
仅当启用了timezone 功能时,此方法才可用。
另请参阅 isTimeZoneIdAvailable() 和QTimeZone(int)。
QString QTimeZone::comment() const
返回该时区的任何注释。
注释可能由主机平台提供,以帮助用户选择正确的时区。根据平台的不同,该注释可能未进行本地化处理。
仅当启用timezone 功能时,此方法才可用。
int QTimeZone::daylightTimeOffset(const QDateTime &atDateTime) const
返回给定atDateTime 的夏令时偏移量,即在标准时间偏移量基础上需加上的秒数,以获得当地夏令时。
例如,对于时区“Europe/Berlin”,夏令时偏移量为 +3600 秒。在标准时间期间,daylightTimeOffset() 将返回 0;而在夏令时生效期间,它将返回 +3600。
此方法仅在启用timezone 功能时可用。
另请参阅 offsetFromUtc() 和standardTimeOffset()。
QString QTimeZone::displayName(QTimeZone::TimeType timeType, QTimeZone::NameType nameType = DefaultName, const QLocale &locale = QLocale()) const
返回本地化的时区显示名称。
返回的名称是针对给定locale 的名称,在给定timeType 生效时适用,且符合nameType 所指定的格式。如果时区显示名称随时间变化,则将使用当前名称。如果没有可用且经过适当本地化的给定类型名称,则可能使用另一种名称类型,或者返回空字符串。
如果未提供locale ,则将使用应用程序的默认区域设置。 对于由客户端代码创建的自定义时区,将使用提供给构造函数的数据,因为对此类时区没有本地化数据可用。如果该时区无效,则返回空字符串。当无法确定系统时区时,本地时间的表示也可能出现这种情况。
此方法仅在启用timezone 功能时可用。
另请参阅 abbreviation()。
QString QTimeZone::displayName(const QDateTime &atDateTime, QTimeZone::NameType nameType = DefaultName, const QLocale &locale = QLocale()) const
返回本地化的时区显示名称。
返回的名称是针对给定的locale 、适用于给定的atDateTime ,且符合nameType 所指示格式的名称。显示名称可能会因夏令时或历史事件而发生变化。如果无法提供给定类型的合适本地化名称,则可能会使用另一种名称类型,或者返回空字符串。
如果未提供locale ,则将使用应用程序的默认区域设置。 对于由客户端代码创建的自定义时区,将使用提供给构造函数的数据,因为该时区没有可用的本地化数据。如果该时区无效,则返回空字符串。当无法确定系统时区时,本地时间的表示也可能出现这种情况。
此方法仅在启用timezone 功能时可用。
另请参阅 abbreviation()。
[constexpr noexcept, since 6.5] int QTimeZone::fixedSecondsAheadOfUtc() const
对于一种轻量级的时间表示法,其timeSpec() 返回值为Qt::OffsetFromUTC 时,该函数将返回该表示法所描述的相对于 UTC 的固定偏移量。对于任何其他时间表示法,该函数均返回 0,即使该时间表示法确实具有相对于 UTC 的常量偏移量。
该函数于 Qt 6.5 中引入。
[static] QTimeZone QTimeZone::fromCFTimeZone(CFTimeZoneRef timeZone)
创建一个新的QTimeZone 对象,其中包含CFTimeZonetimeZone 的副本。
另请参阅 toCFTimeZone()。
[static, since 6.5] QTimeZone QTimeZone::fromDurationAheadOfUtc(std::chrono::seconds offset)
[static, since 6.5] QTimeZone QTimeZone::fromSecondsAheadOfUtc(int offset)
返回一个以固定offset (相对于UTC的秒数)表示的时间值。
相对于 UTC 的offset 必须在 -16 小时到 +16 小时之间,否则将返回无效时区。返回的QTimeZone 是一个轻量级时间表示,而非时区(由系统提供的或标准数据支持)。
如果偏移量为 0,则返回实例的timeSpec() 结果为Qt::UTC 。否则,如果offset 有效,则timeSpec() 结果为Qt::OffsetFromUTC 。当返回无效时区时,其timeSpec() 结果为Qt::TimeZone 。
这些函数在 Qt 6.5 中引入。
另请参阅 QTimeZone(int)、asBackendZone()、fixedSecondsAheadOfUtc()、MinUtcOffsetSecs 以及MaxUtcOffsetSecs 。
[static] QTimeZone QTimeZone::fromNSTimeZone(const NSTimeZone *timeZone)
创建一个新的QTimeZone 对象,其中包含NSTimeZonetimeZone 的副本。
另请参阅 toNSTimeZone()。
[static, since 6.4] QTimeZone QTimeZone::fromStdTimeZonePtr(const std::chrono::time_zone *timeZone)
返回一个QTimeZone 对象,该对象表示与timeZone 相同的时区。timeZone 的IANA ID必须是可用系统ID之一,否则将返回一个无效的时区。
仅当启用了timezone 功能时,此方法才可用。
该函数于 Qt 6.4 中引入。
[since 6.8] bool QTimeZone::hasAlternativeName(QByteArrayView alias) const
如果alias 是该时区的别名,则返回true 。
IANA(原 Olson)数据库在其发展历程中曾对某些时区进行了重命名。此外,还有一些时区仅在 1970 年之前存在差异,但现在被视为同义项。 某些后端可能拥有可追溯至 1970 年前的数据,并在后一种情况下生成不同的时区。而另一些后端生成的时区可能仅通过id() 才能区分。此方法用于确定某个 ID 是否(至少自 1970 年以来)指向与该时区对象所描述的同一时区。
此方法仅在启用timezone 功能时可用。
该函数在 Qt 6.8 中引入。
另请参阅 isTimeZoneIdAvailable()。
bool QTimeZone::hasDaylightTime() const
如果该时区曾实施过夏令时,则返回“true ”。
仅当启用timezone 功能时,此方法才可用。
另请参阅 isDaylightTime() 和daylightTimeOffset()。
bool QTimeZone::hasTransitions() const
如果系统后端支持获取时区转换,则返回true 。
时区转换是指时区的变更:这些变更发生在夏令时开启或关闭时,以及主管部门调整时区偏移量时。
仅当启用timezone 功能时,此方法才可用。
注意:这不是 该对象所描述的时区属性,而是提供该时区数据的后端(通常来自系统库)的属性。它告诉您其他与转换相关的函数是否能提供相关信息。
另请参阅 nextTransition()、previousTransition() 和transitions()。
[static] QByteArray QTimeZone::ianaIdToWindowsId(const QByteArray &ianaId)
返回与给定的ianaId 相对应的Windows ID。
仅当启用了timezone 功能时,此方法才可用。
另请参阅 windowsIdToDefaultIanaId() 和windowsIdToIanaIds()。
QByteArray QTimeZone::id() const
返回该时区的 IANA 标识符。
所有平台均使用 IANA ID。在 Windows 系统上,这些 ID 会从 Windows ID 转换为与该时区和地区最匹配的 IANA ID。
如果该时区实例并非由 IANA ID 构建而成,则其 ID 由构建方式决定。在大多数情况下,会使用构建实例时传入的 ID。(自定义时区的构造函数会使用传入的 ID,该 ID 不能是 IANA ID。)有两种例外情况。
- 仅通过传递以秒为单位的 UTC 偏移量构建的实例,在构建时不会传递任何 ID。
- 仅接受 IANA 标识符的构造函数也会接受某些实际上并非 IANA 标识符的 UTC 偏移量标识符:其处理方式等同于传递相应的秒数偏移量,与第一个例外情况相同。
在这两种特殊情况下,如果存在一个具有指定偏移量的 IANA UTC 偏移时区,则生成的实例将使用该 IANA 时区的 ID,即使这可能与传递给构造函数的(非 IANA)UTC 偏移 ID 不同。 否则,该实例将使用根据其偏移量合成的 ID,格式为 UTC±hh:mm:ss,其中零秒或零分钟的尾部 :00 将被省略。同样,这可能与传递给构造函数的 UTC 偏移量 ID 不同。
此方法仅在启用timezone 功能时可用。
bool QTimeZone::isDaylightTime(const QDateTime &atDateTime) const
如果给定的atDateTime 期间实行了夏令时,则返回true 。
仅当功能timezone 已启用时,此方法才可用。
另请参阅 hasDaylightTime() 和daylightTimeOffset()。
[static] bool QTimeZone::isTimeZoneIdAvailable(QByteArrayView ianaId)
如果该系统上存在给定的时区ianaId ,则返回true 。
对于某些实际上并非 IANA ID 的文本,此情况可能成立,尤其是 UTC 偏移量 ID,以及未在availableTimeZoneIds() 中列出的受支持 IANA ID 的已知别名。
仅当启用了timezone 功能时,此方法才可用。
另请参阅 availableTimeZoneIds() 和hasAlternativeName()。
[constexpr noexcept, since 6.5] bool QTimeZone::isUtcOrFixedOffset() const
如果 `timeSpec()` 的返回值为 `Qt::UTC ` 或 `Qt::OffsetFromUTC`,则返回 `true `。
当该值为真时,时间描述随时间推移不会发生变化,例如不会出现本地时间或时区中可能出现的季节性夏令时调整。了解这一点可使调用代码免于进行其他各种检查。
该函数于 Qt 6.5 中引入。
[static constexpr noexcept, since 6.5] bool QTimeZone::isUtcOrFixedOffset(Qt::TimeSpec spec)
如果spec 为Qt::UTC 或Qt::OffsetFromUTC ,则返回true 。
该函数在 Qt 6.5 中引入。
bool QTimeZone::isValid() const
如果该时区有效,则返回true 。
QTimeZone::OffsetData QTimeZone::nextTransition(const QDateTime &afterDateTime) const
返回给定afterDateTime 之后的首个时区过渡。当您已知某个过渡时间,并希望查找其后的过渡时,此方法最为有用。
如果给定的afterDateTime 之后没有Transition,则会返回一个无效的OffsetData ,其atUtc 为无效的QDateTime 。
给定的afterDateTime 不包含该过渡。
仅当启用了timezone 功能时,此方法才可用。
另请参阅 hasTransitions()、previousTransition() 和transitions()。
QTimeZone::OffsetData QTimeZone::offsetData(const QDateTime &forDateTime) const
返回给定forDateTime 的实际偏移详情。
这相当于分别调用abbreviation() 以及三个偏移函数,但可能更高效,并且可能为该缩写词获得不同的本地化结果。如果给定的日期时间不存在此数据,则会返回一个无效的OffsetData ,其atUtc 为无效的QDateTime 。
此方法仅在启用timezone 功能时可用。
另请参阅 offsetFromUtc()、standardTimeOffset()、daylightTimeOffset() 和abbreviation()。
int QTimeZone::offsetFromUtc(const QDateTime &atDateTime) const
返回给定atDateTime 处的总有效偏移量,即从UTC时间中加上的秒数以获得当地时间。这包括任何可能生效的夏令时偏移量,即对于给定的日期和时间,它是standardTimeOffset()和daylightTimeOffset()的和。
例如,对于时区“Europe/Berlin”,标准时间偏移量为 +3600 秒,夏令时偏移量为 +3600 秒。 在标准时间期间,offsetFromUtc() 将返回 +3600(UTC+01:00),而在夏令时期间,它将返回 +7200(UTC+02:00)。
只有在启用了timezone 功能时,此方法才可用。
另请参阅 standardTimeOffset() 和daylightTimeOffset()。
QTimeZone::OffsetData QTimeZone::previousTransition(const QDateTime &beforeDateTime) const
返回给定beforeDateTime 之前的第一条时区过渡。当您已知某条过渡的时间,并希望查找其前一条过渡时,此功能最为有用。
如果给定的beforeDateTime 之前不存在过渡,则会返回一个无效的OffsetData ,其atUtc 为无效的QDateTime 。
给定的beforeDateTime 不包含该过渡。
仅当启用了timezone 功能时,此方法才可用。
另请参阅 hasTransitions()、nextTransition() 和transitions()。
int QTimeZone::standardTimeOffset(const QDateTime &atDateTime) const
返回给定atDateTime 下的标准时间偏移量,即从 UTC 时间中加上的秒数,以获得当地标准时间。这不包括可能生效的任何夏令时偏移量。
例如,对于时区“Europe/Berlin”,标准时间偏移量为+3600秒。无论是在标准时间还是夏令时期间,offsetFromUtc() 都会返回+3600(UTC+01:00)。
此方法仅在启用timezone 功能时可用。
另请参阅 offsetFromUtc() 和daylightTimeOffset()。
[noexcept] void QTimeZone::swap(QTimeZone &other)
将该时区实例与other 进行交换。此操作速度极快,且绝不会失败。
[static] QTimeZone QTimeZone::systemTimeZone()
返回一个描述本地系统时间的QTimeZone 对象。
仅当启用了timezone 功能时,此方法才可用。返回的实例通常等同于轻量级时间表示形式QTimeZone(QTimeZone::LocalTime) ,尽管它是以时区形式实现的。
返回的对象不会因后续系统时区的变更而改变。它表示调用asBackendZone() 时生效的本地时间。在配置错误的系统上(例如缺少 Qt 编译所依赖的后端时区数据的系统),该对象可能无效。在这种情况下,会输出一个警告。
另请参阅 utc()、Initialization 、asBackendZone() 和systemTimeZoneId()。
[static] QByteArray QTimeZone::systemTimeZoneId()
返回当前系统时区的 IANA 标识符。
等同于调用 `systemTimeZone()` 和 `id()`,但可能会跳过部分计算过程来获取该值。通过返回的字节数组构建 `QTimeZone ` 将产生与 `systemTimeZone()` 相同的结果。
如果后端无法确定正确的系统时区,则结果为空。在这种情况下,systemTimeZone() 和isValid() 返回 false,且若调用systemTimeZone() 中的任一方法,将输出警告。
如果后端能够确定正确的系统区域但无法确定其名称,则返回一个空字节数组。例如,在 Windows 上,系统本机 ID 会被转换为 IANA ID——如果内部转换代码不认识该系统 ID,则结果应为空。 在这种情况下,systemTimeZone() 和isValid() 的返回值应为 true。
此方法仅在启用timezone 功能时可用。
注意:在 Qt 6.7之前, 当无法确定结果时,会返回误导性的结果“UTC”。
另请参阅 systemTimeZone()。
[since 6.2] QLocale::Territory QTimeZone::territory() const
返回该时区的所属地区。
若返回值为AnyTerritory ,则表示该时区无已知的区域关联。 在某些情况下,这可能是因为该时区没有关联的地域——例如 UTC——或者因为该时区在多个地域中使用——例如 CET。在其他情况下,QTimeZone 后端可能无法确定该时区与哪个地域相关联——例如,因为它并非其所在地域的主要时区。
此方法仅在启用timezone 功能时可用。
该功能自 Qt 6.2 起引入。
[constexpr noexcept, since 6.5] Qt::TimeSpec QTimeZone::timeSpec() const
返回一个Qt::TimeSpec ,用于标识时间表示的类型。
如果结果为Qt::TimeZone ,则该时间描述为时区(基于系统提供的或标准数据);否则,它是一种轻量级时间表示形式。如果结果为Qt::LocalTime ,则表示本地时间:详情请参见Qt::TimeSpec 。
该函数于 Qt 6.5 中引入。
另请参阅 fixedSecondsAheadOfUtc() 和asBackendZone()。
CFTimeZoneRef QTimeZone::toCFTimeZone() const
根据QTimeZone 对象创建一个CFTimeZone对象。
调用方拥有该 CFTimeZone 对象,并负责释放它。
另请参阅 fromCFTimeZone()。
NSTimeZone *QTimeZone::toNSTimeZone() const
根据QTimeZone 创建一个NSTimeZone。
该 NSTimeZone 对象将被自动释放。
另请参阅 fromNSTimeZone()。
QTimeZone::OffsetDataList QTimeZone::transitions(const QDateTime &fromDateTime, const QDateTime &toDateTime) const
返回给定日期和时间之间所有时区转换的列表。
给定的fromDateTime 和toDateTime 均包含起始和结束时间。每个条目的atUtc 成员描述了时区转换的时刻,此时其他成员所指定的偏移量和缩写将生效。
仅当启用了timezone 功能时,此方法才可用。
另请参阅 hasTransitions()、nextTransition(),以及previousTransition()。
[static] QTimeZone QTimeZone::utc()
返回一个QTimeZone 对象,该对象将UTC描述为一个时区。
仅当启用了timezone 功能时,此方法才可用。它等同于向QTimeZone(int offsetSeconds) 以及轻量级时间表示法QTimeZone(QTimeZone::UTC) 传递 0,尽管与后者不同,它是以时区形式实现的。
另请参阅 systemTimeZone()、Initialization 以及asBackendZone()。
[static] QByteArray QTimeZone::windowsIdToDefaultIanaId(const QByteArray &windowsId)
返回给定windowsId 的默认IANA ID。
由于一个 Windows ID 可能涵盖多个不同地区的多个 IANA ID,因此该函数会返回使用频率最高的 IANA ID,而不考虑具体地区,故应谨慎使用。通常最好直接查询特定地区的默认值。
此方法仅在启用timezone 功能时可用。
另请参阅 ianaIdToWindowsId() 和windowsIdToIanaIds()。
[static] QByteArray QTimeZone::windowsIdToDefaultIanaId(const QByteArray &windowsId, QLocale::Territory territory)
返回给定windowsId 和territory 的默认IANA ID。
由于一个 Windows 标识符可能涵盖特定区域内的多个 IANA 标识符,因此将返回该区域内使用最频繁的 IANA 标识符。
作为特例,AnyTerritory 会返回那些与特定区域无关的 IANA ID 中的默认值,而World 则会在与给定windowsId 没有特定关联的区域中返回其默认值。
如果返回值为空,则表示对于该windowsId ,不存在与给定territory 对应的特定 IANA ID。在这种情况下,回退到windowsIdToDefaultIanaId(windowsId) 是合理的。
此方法仅在启用timezone 功能时可用。
另请参阅 ianaIdToWindowsId()、windowsIdToIanaIds() 和territory()。
[static] QList<QByteArray> QTimeZone::windowsIdToIanaIds(const QByteArray &windowsId)
返回给定windowsId 的所有IANA标识符。
返回的列表按字母顺序排序。
仅当启用了timezone 功能时,此方法才可用。
另请参阅 ianaIdToWindowsId() 和windowsIdToDefaultIanaId()。
[static] QList<QByteArray> QTimeZone::windowsIdToIanaIds(const QByteArray &windowsId, QLocale::Territory territory)
返回给定windowsId 和territory 的所有 IANA 标识符。
作为特例,AnyTerritory 会选择那些与特定领土无关联的 IANA 标识符,而World 则会在与给定windowsId 无特定关联的领土中,选择该 的默认值。
返回的列表按使用频率排序,即同一区域内面积较大的区域排在前面。
只有在启用timezone 功能时,此方法才可用。
另请参阅 ianaIdToWindowsId()、windowsIdToDefaultIanaId() 和territory()。
[noexcept] QTimeZone &QTimeZone::operator=(QTimeZone &&other)
将other 以“移动赋值”的方式赋值给此QTimeZone 实例,将其数据的所有权转移至该实例。
QTimeZone &QTimeZone::operator=(const QTimeZone &other)
赋值运算符,将other 赋值给this。
成员变量文档
const int QTimeZone::MaxUtcOffsetSecs
预计相对于协调世界时(UTC)的时区偏移量不会超过此值。
21世纪初各时区中,与UTC的偏移量最大值为+14小时(圣诞岛,基里巴斯,基里蒂马蒂),即比格林尼治时间东偏14小时。
历史上,在1867年俄罗斯将阿拉斯加出售给美国之前,阿拉斯加采用与俄罗斯相同的日期,因此其时区偏移量曾超过格林尼治以东15小时。由于阿拉斯加当时使用当地太阳平均时,其时区偏移量虽有变化,但均未超过格林尼治以东16小时。
另请参阅 MinUtcOffsetSecs 。
const int QTimeZone::MinUtcOffsetSecs
预计相对于UTC的时区偏移量不应低于此值。
21世纪初所有时区中,UTC偏移量最小的为-12小时(美国贝克岛),即比格林尼治标准时间西偏12小时。
历史上,直到1844年,菲律宾(当时由西班牙控制)一直采用与西班牙美洲殖民地相同的日期,因此其时区偏移量接近格林尼治以西16小时。 由于菲律宾当时使用当地平均太阳时,其部分偏远地区可能曾采用比格林尼治标准时间西偏 16 小时以上的时区,但 21 世纪初的任何时区都无法追溯到如此极端的时区设置。
另见 MaxUtcOffsetSecs 。
相关非会员
[noexcept] bool operator!=(const QTimeZone &lhs, const QTimeZone &rhs)
如果lhs 时区与rhs 时区不一致,则返回true 。
如果两种表示在内部描述上存在差异,即使它们对所有时间点的表示完全一致,也应视为不同。特别是,一种轻量级时间表示可能与某个时区一致,但二者并不相等。
[noexcept] bool operator==(const QTimeZone &lhs, const QTimeZone &rhs)
如果lhs 时区与rhs 时区相等,则返回true 。
如果两种表示法的内部描述不同,即使它们对所有时间点的表示完全一致,这两者也被视为不同。特别是,一种轻量级时间表示可能与某个时区重合,但二者并不相等。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.