QTimeZone 类

成员函数文档

返回一个在 UTC 之前固定 offset（以秒为单位）的时间表示。

offset 从 UTC 的范围必须是 -16 小时到 +16 小时，否则将返回一个无效的时间区域。返回的 QTimeZone 是一个轻量级的时间表示，不是一个时区（由系统提供的标准数据支持）。

如果偏移量为 0，则返回实例的 timeSpec() 将是 Qt::UTC。否则，如果 offset 无效，timeSpec() 将是 Qt::OffsetFromUTC。当返回一个无效的时间区域时，其 timeSpec() 将为 Qt::TimeZone。

此功能是在 Qt 6.5 中引入的。

另请参阅QTimeZone(int)，asBackendZone()，fixedSecondsAheadOfUtc()，MinUtcOffsetSecs 和 MaxUtcOffsetSecs。

[noexcept] QTimeZone::QTimeZone()

创建一个空/无效的时间区域实例。

[noexcept，自 6.5 版起] QTimeZone::QTimeZone(QTimeZone::Initialization spec)

创建一个描述 UTC 或本地时间的轻量级实例。

此功能是在 Qt 6.5 中引入的。

另请参阅fromSecondsAheadOfUtc()，asBackendZone()，utc() 和 systemTimeZone。

[explicit] QTimeZone::QTimeZone(int offsetSeconds)

创建一个给定 UTC 偏移量 offsetSeconds 的时间区域实例。

offsetSeconds 从 UTC 的范围必须是 -16 小时到 +16 小时，否则将返回一个无效的时间区域。

此构造函数仅在启用功能 timezone 时可用。返回的实例相当于轻量级时间表示 QTimeZone::fromSecondsAfterUtc(offsetSeconds)，尽管它作为时区实现。

另请参阅MinUtcOffsetSecs，MaxUtcOffsetSecs 和 id。

[explicit] QTimeZone::QTimeZone(const QByteArray &ianaId)

创建一个具有请求的 IANA ID ianaId 的时间区域实例。

ID 必须是可用的系统 ID 之一或有效的 UTC-with-offset ID，否则将返回一个无效的时间区域。对于 UTC-with-offset ID，如果它们实际上不是 IANA ID，那么生成的实例的 id() 可能与构造函数中传递的 ID 不同。

此构造函数仅在启用功能 timezone 时可用。

另请参阅 availableTimeZoneIds() 和 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中以帮助用户选择时区。

时区ID zoneId 不能是 availableTimeZoneIds() 返回的可用的系统ID之一。《i translate="no">offsetSeconds 从UTC的偏移量必须在 -16 小时到 +16 小时之间。

如果自定义时区没有特定的地区，则将其设置为 QLocale::AnyTerritory 的默认值。

此构造函数仅在启用功能 timezone 时可用。

另请参阅 id()，offsetFromUtc()，displayName()，abbreviation()，territory()，comment()，MinUtcOffsetSecs 和 MaxUtcOffsetSecs。

[noexcept] QTimeZone::QTimeZone(const QTimeZone &other)

复制构造函数：从 other 复制到当前对象。

[noexcept] QTimeZone::QTimeZone(QTimeZone &&other)

将此对象的构造函数从 other 迁移。

[noexcept] QTimeZone::~QTimeZone()

销毁时区。

QString QTimeZone::abbreviation(const QDateTime &atDateTime) const

返回给定 atDateTime 的时区缩写。缩写可能会因夏令时或历史事件而变化。

请注意，缩写不一定唯一标识时区，不应该用它来代替ID或显示名称。

此方法仅在启用 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。

[静态] QList<QByteArray> QTimeZone::availableTimeZoneIds()

返回此系统上所有可用的 IANA 时区 ID 的列表。

此方法仅在启用 timezone 功能时可用。

另请参阅 isTimeZoneIdAvailable。

[静态] QList<QByteArray> QTimeZone::availableTimeZoneIds(QLocale::Territory territory)

返回给定 territory 上所有可用的 IANA 时区 ID 的列表。

作为一个特例，若 territory 为 AnyTerritory，将选择那些没有已知地理关联的时区，例如 UTC。如果您需要所有领土的所有时区 ID 列表，请使用标准的 availableTimeZoneIds() 方法。

此方法仅在启用 timezone 功能时可用。

另请参阅 isTimeZoneIdAvailable() 和 territory。

[静态] QList<QByteArray> QTimeZone::availableTimeZoneIds(int offsetSeconds)

返回具有给定标准时间偏移量 offsetSeconds 的所有可用的 IANA 时区 ID 的列表。

如果支持给定的偏移量，则即使在它不是一个 IANA ID，也会将 QTimeZone(offsetSeconds).id() 包含在列表中。这仅在没有任何具有给定偏移量的 IANA UTC-offset 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(const QDateTime &atDateTime, QTimeZone::NameType nameType = QTimeZone::DefaultName, const QLocale &locale = QLocale()) const

返回给定atDateTime在给定nameType和locale中的本地时区显示名称。请求的nameType和locale可能不支持所有平台，在这种情况下将返回最佳可用的选项。

如果未提供locale，则使用应用程序默认的区域设置。

显示名称可能会因日光节约时间或历史事件而更改。

此方法仅在启用 timezone 功能时可用。

另请参阅abbreviation。

QString QTimeZone::displayName(QTimeZone::TimeType timeType, QTimeZone::NameType nameType = QTimeZone::DefaultName, const QLocale &locale = QLocale()) const

返回给定timeType和nameType在给定locale中的本地时区显示名称。请求的nameType和locale可能不支持所有平台，在这种情况下将返回最佳可用的选项。

如果未提供locale，则使用应用程序默认的区域设置。

如果时区显示名称随着时间的推移而更改，则将使用最新的名称。

此方法仅在启用 timezone 功能时可用。

另请参阅abbreviation。

[constexpr noexcept, since 6.5] int QTimeZone::fixedSecondsAheadOfUtc() const

对于轻量级时间表示，其timeSpec()是Qt::OffsetFromUTC，则此函数返回所描述的UTC固定偏移量。对于任何其他时间表示，即使该时间表示具有从UTC的恒定偏移量，也将返回0。

此功能是在 Qt 6.5 中引入的。

[static] QTimeZone QTimeZone::fromCFTimeZone(CFTimeZoneRef timeZone)

构建一个新的QTimeZone，其中包含CFTimeZone timeZone的副本。

另请参阅toCFTimeZone。

[static] QTimeZone QTimeZone::fromNSTimeZone(const NSTimeZone *timeZone)

构建一个新的QTimeZone，其中包含NSTimeZone timeZone的副本。

另请参阅toNSTimeZone。

[static, since 6.4] QTimeZone QTimeZone::fromStdTimeZonePtr(const int *timeZone)

返回一个表示与timeZone相同时区的QTimeZone对象。参数timeZone的IANA ID必须是有效的系统ID之一，否则将返回无效时区。

此方法仅在启用 timezone 功能时可用。

此函数自Qt 6.4版开始引入。

bool QTimeZone:: hasDaylightTime() const

如果时区曾在任何时候实行夏令时，则返回true。

此方法仅在启用 timezone 功能时可用。

另请参阅isDaylightTime() 和 daylightTimeOffset。

bool QTimeZone:: hasTransitions() const

如果系统后端支持获取时区转换，则返回true。

时区转换是指时区中的时间变化：这些情况发生在DST开启或关闭以及当局更改时区偏移时。

此方法仅在启用 timezone 功能时可用。

另请参阅nextTransition、previousTransition 和 transitions。

[静态] QByteArray QTimeZone:: ianaIdToWindowsId(const QByteArray &ianaId)

返回给定ianaId的Windows ID等效。

此方法仅在启用 timezone 功能时可用。

另请参阅windowsIdToDefaultIanaId 和 windowsIdToIanaIds。

QByteArray QTimeZone:: id() const

返回该时区的IANA ID。

在所有平台上都使用IANA ID。在Windows上，这些ID由Windows ID转换为时区和领土的最佳匹配IANA ID。

如果此时区实例不是由IANA ID构建的，则其ID根据其构造方式确定。在大多数情况下，用于构建实例的ID被使用。(自定义时区的构造函数使用其传递的ID，该ID不得是IANA ID。)这里有两个例外。

• 仅通过传递秒数作为UTC偏移构建的实例在构建时未传递任何ID。
• 仅接受IANA ID的构造函数也会接受一些实际上是UTC-offset ID的UTC-offset ID：其对这些的处理与对第一个例外的对应偏移相同。

在两种例外情况下，如果存在具有指定偏移的IANA UTC-offset区域，构造的实例将使用该IANA区域的ID，即使这可能与其传递给构造函数的(非IANA) UTC-offset ID不同。否则，实例使用从其偏移合成的ID，形式为UTC±hh:mm:ss，省略任何结尾为:00的零秒或分钟。同样，这可能与传递给构造函数的UTC-offset ID不同。

此方法仅在启用 timezone 功能时可用。

bool QTimeZone:: isDaylightTime(const QDateTime &atDateTime) const

如果给定atDateTime当时施用了夏令时，则返回true。

此方法仅在启用 timezone 功能时可用。

另请参阅hasDaylightTime 和 daylightTimeOffset。

[静态] bool QTimeZone:: isTimeZoneIdAvailable(const QByteArray &ianaId)

如果系统上可用给定的时区ianaId，则返回true。

这可能包括一些非IANA ID，特别是UTC偏移量ID，这些ID未在availableTimeZoneIds()中列出。

此方法仅在启用 timezone 功能时可用。

另请参阅availableTimeZoneIds()。

[静态constexpr noexcept，自6.5版本起] bool QTimeZone::isUtcOrFixedOffset(Qt::TimeSpec spec)

如果spec是Qt::UTC或Qt::OffsetFromUTC，则返回true。

此功能是在 Qt 6.5 中引入的。

[constexpr noexcept，自6.5版本起] bool QTimeZone::isUtcOrFixedOffset() const

如果timeSpec()是Qt::UTC或Qt::OffsetFromUTC，则返回true。

当为真时，时间描述不会随时间变化，例如不进行时区夏令时变更，例如本地时间或时 zone 时间。了解这一点可能会有助于调用代码减少其他检查的需要。

此功能是在 Qt 6.5 中引入的。

bool QTimeZone::isValid() const

如果此时区有效，则返回true。

QTimeZone::OffsetData QTimeZone::nextTransition(const QDateTime &afterDateTime) const

返回给定afterDateTime之后的第一个时区转换。当你有一个转换时间并希望找到之后的转换时，这最有用。

如果给定的afterDateTime之后没有转换，将返回一个无效的OffsetData，其atUtc包含一个无效的QDateTime。

给定的afterDateTime是排他的。

此方法仅在启用 timezone 功能时可用。

另请参阅hasTransitions()、previousTransition()和transitions()。

QTimeZone::OffsetData QTimeZone::offsetData(const QDateTime &forDateTime) const

返回给定forDateTime处的实际偏移量详细信息。

这等价于调用abbreviation()和三个偏移量函数，但更有效。如果给定datetime没有这些数据，则将返回一个无效的OffsetData，其atUtc包含一个无效的QDateTime。

此方法仅在启用 timezone 功能时可用。

另请参阅offsetFromUtc()、standardTimeOffset()、daylightTimeOffset()和abbreviation()。

int QTimeZone::offsetFromUtc(const QDateTime &atDateTime) const

返回给定atDateTime处的总有效偏移量，即添加到UTC以获得本地时间的秒数。这包括可能生效的任何DST偏移量，即给定时对的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 ID。

等同于调用systemTimeZone().id()，但可能绕过一些计算来获取它。从返回的字节序列构建QTimeZone将产生与systemTimeZone相同的结果。

如果后端无法确定正确的系统时区，结果将为空。在这种情况下，systemTimeZone() 和 isValid()将是false，并且在调用systemTimeZone() 方法时将输出警告。

如果后端能够确定正确的系统时区但无法确定其名称，将返回一个空字节数组。例如，在Windows中，系统本地ID被转换为IANA ID - 如果系统ID在内部翻译代码中未知，则结果应为空。在这种情况下，systemTimeZone() 和 isValid() 应为true。

此方法仅在启用 timezone 功能时可用。

另请参阅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

返回给定datetimes之间的所有时区转换列表。

给定的从datetime和toDateTime是包含的。《每个条目的atUtc成员描述转换的时刻，此时其他成员给出的偏移量和缩写开始生效。

此方法仅在启用 timezone 功能时可用。

另请参阅 hasTransitions()，nextTransition()，以及previousTransition。

[静态] QTimeZone QTimeZone::utc()

返回一个描述UTC时区的QTimeZone对象。

此方法仅在启用特征timezone时可用。它与将0传递给QTimeZone(int offsetSeconds)以及轻量级时间表示QTimeZone(QTimeZone::UTC)等效，尽管后者作为时区实现，而前者不是。

另请参阅 systemTimeZone()，Initialization，以及asBackendZone。

[静态] QByteArray QTimeZone::windowsIdToDefaultIanaId(const QByteArray &windowsId)

返回给定的默认IANA ID。

由于Windows ID可以涵盖不同领土中的多个IANA ID，此函数返回频率最高的IANA ID，不考虑领土，因此应谨慎使用。通常最好请求特定领土的默认值。

此方法仅在启用 timezone 功能时可用。

另请参阅 ianaIdToWindowsId() 和windowsIdToIanaIds。

[静态] QByteArray QTimeZone::windowsIdToDefaultIanaId(const QByteArray &windowsId, QLocale::Territory territory)

返回给定和领土的默认IANA ID。

由于Windows ID可以涵盖给定领土中的多个IANA ID，因此返回该领土中频率最高的IANA ID。

作为一个特殊情况，AnyTerritory返回与IANA ID没有已知领土关联的默认值。

此方法仅在启用 timezone 功能时可用。

另请参阅 ianaIdToWindowsId，windowsIdToIanaIds，以及territory。

[静态] QList<QByteArray> QTimeZone::windowsIdToIanaIds(const QByteArray &windowsId)

返回给定的所有IANA ID。

返回的列表按字母顺序排序。

此方法仅在启用 timezone 功能时可用。

另请参阅 ianaIdToWindowsId 和windowsIdToDefaultIanaId。

[静态] QList<QByteArray> QTimeZone::windowsIdToIanaIds(const QByteArray &windowsId, QLocale::Territory territory)

返回给定和领土的所有IANA ID。

作为特殊情况，AnyTerritory选择与IANA ID没有已知领土关联的那些。

返回的列表按使用频率排序，即领土内较大的时区先列出。

此方法仅在启用 timezone 功能时可用。

另请参阅 ianaIdToWindowsId，windowsIdToDefaultIanaId，以及territory。

QTimeZone &QTimeZone::operator=(const QTimeZone &other)

赋值运算符，将other赋值给当前对象。

[noexcept] QTimeZone &QTimeZone::operator=(QTimeZone &&other)

移动赋值操作，将other的所有权转移到当前QTimeZone实例。