QTimeZone Class

成员函数文档

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

offset 与世界协调时的距离必须在 -16 小时至 +16 小时之间，否则将返回无效时区。返回的QTimeZone 是轻量级时间表示，而不是时区（由系统提供或标准数据支持）。

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

此函数在 Qt 6.5 中引入。

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

[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-with-offset（UTC-with-offset）ID 如果实际上不是 IANA ID，则生成实例的id() 可能与传给构造函数的 ID 不同。

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

另请参阅 availableTimeZoneIds() 和id()。

[explicit] QTimeZone::QTimeZone(int offsetSeconds)

创建一个时区实例，其与 UTC 的偏移量（offsetSeconds ）为给定值。

offsetSeconds 与 UTC 的偏移必须在 -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 中，以帮助用户选择时区。

offsetSeconds 与世界协调时的时差范围必须在 -16 小时至 +16 小时之间。zoneId 必须不是 isTimeZoneIdAvailable() 为真的 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 移动 this 的构造函数。

[noexcept] QTimeZone::~QTimeZone()

破坏时区。

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

返回给定atDateTime 的时区缩写。

缩写可能会根据夏令时甚至历史事件发生变化。

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

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

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

另请参阅 isTimeZoneIdAvailable()。

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

返回所有可用的 IANA 时区 ID（标准时间偏移量为offsetSeconds ）列表。

在支持给定偏移量的情况下，即使QTimeZone(offsetSeconds).id() 不是 IANA ID，也会包含在列表中。只有在没有具有给定偏移量的 IANA UTC-offset ID 时，才会出现这种情况。

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

另请参阅 isTimeZoneIdAvailable() 和QTimeZone(int)。

QString QTimeZone::comment() const

返回时区的任何注释。

主机平台可能会提供注释，以帮助用户选择正确的时区。根据平台的不同，注释可能不会本地化。

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

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

返回给定atDateTime 的夏令时偏移量，即在标准时间偏移量上加上多少秒才能得到当地夏令时。

例如，"欧洲/柏林 "时区的夏令时偏移为 +3600 秒。在标准时间内，didayTimeOffset() 将返回 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 指示。显示名称可能会根据 DST 或历史事件发生变化。如果没有给定类型的合适本地化名称，可使用其他名称类型，或返回空字符串。

如果未提供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 ，其中包含 CFTimeZonetimeZone 的副本。

另请参阅 toCFTimeZone() 。

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

构造一个新的QTimeZone ，其中包含 NSTimeZonetimeZone 的副本。

另请参阅 toNSTimeZone() 。

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

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

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

此函数在 Qt 6.4 中引入。

[since 6.8] bool QTimeZone::hasAlternativeName(QByteArrayView alias) const

如果alias 是该时区的替代名称，则返回true 。

IANA（前身为奥尔森）数据库在其历史上对一些时区进行了重命名。还有一些时区在 1970 年之前只有差异，但现在被视为同义时区。在后一种情况下，一些后端可能拥有 1970 年之前的数据，并生成不同的区。其他后端则可能产生除id() 以外无法区分的区。此方法可确定 ID 是否（至少自 1970 年以来）与此时区对象所描述的时区相同。

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

此函数在 Qt 6.8 中引入。

bool QTimeZone::hasDaylightTime() const

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

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

另请参阅 isDaylightTime() 和daylightTimeOffset()。

bool QTimeZone::hasTransitions() const

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

转换是时区的变化：当 DST 启用或关闭时，以及当局改变时区偏移量时，都会发生转换。

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

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

[static] 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 的构造函数也会接受一些实际上不是 IANA ID 的UTC-偏移 ID：它对这些 ID 的处理等同于传递以秒为单位的相应偏移量，这与第一个例外情况相同。

在这两种例外情况下，如果存在具有指定偏移量的 IANA UTC 偏移区，所构建的实例就会使用该 IANA 区的 ID，尽管它可能与传递给构造函数的（非 IANA）UTC 偏移 ID 不同。否则，实例将使用根据偏移量合成的 ID，形式为 UTC±hh:mm:ss，省略任何表示零秒或零分的尾部 :00。同样，该 ID 可能与传递给构造函数的 UTC 偏移 ID 不同。

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

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

如果在给定的atDateTime 时实行夏令时，则返回true 。

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

另请参阅 hasDaylightTime() 和daylightTimeOffset()。

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

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

这可能包括availableTimeZoneIds() 中未列出的一些非国际原子能机构 ID，特别是 UTC 偏移 ID。

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

另请参阅 availableTimeZoneIds()。

[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 之后没有过渡时间，那么将返回一个无效的OffsetData ，并以一个无效的QDateTime 作为其atUtc 。

给定的afterDateTime 是排他性的。

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

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

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

返回给定forDateTime 的有效偏移细节。

这等同于单独调用abbreviation() 和所有三个偏移函数，但可能更有效，并可能获得不同的缩写本地化。如果在给定的日期时间内没有这些数据，则将返回一个无效的OffsetData ，并以一个无效的QDateTime 作为其atUtc 。

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

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

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

返回给定atDateTime 时的总有效偏移量，即在 UTC 基础上增加多少秒才能得到当地时间。这包括任何可能生效的 DST 偏移，即给定日期时间的standardTimeOffset() 和daylightTimeOffset() 之和。

例如，对于 "欧洲/柏林 "时区，标准时间偏移为 +3600 秒，DST 偏移为 +3600 秒。在标准时间期间，offsetFromUtc() 将返回 +3600 (UTC+01:00)，而在 DST 期间，它将返回 +7200 (UTC+02:00)。

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

另请参阅 standardTimeOffset() 和daylightTimeOffset()。

QTimeZone::OffsetData QTimeZone::previousTransition(const QDateTime &beforeDateTime) const

返回给定beforeDateTime 之前的第一个时区转换时间。当您有一个过渡时间，并希望找到它之前的过渡时间时，这将非常有用。

如果在给定的beforeDateTime 之前没有过渡时间，那么将返回一个无效的OffsetData ，并以一个无效的QDateTime 作为其atUtc 。

给定的beforeDateTime 是排他性的。

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

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

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

返回给定atDateTime 的标准时间偏移量，即在 UTC 基础上增加多少秒才能得到当地标准时间。这不包括任何可能生效的 DST 偏移。

例如，"欧洲/柏林 "时区的标准时间偏移为 +3600 秒。在标准时间和 DST 期间，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() 为假，如果调用systemTimeZone() 或该方法，都会输出警告。

如果后端能确定正确的系统区，但不能确定其名称，则返回空字节数组。例如，在 Windows 系统中，系统本机 ID 会转换为 IANA ID，如果内部翻译代码不知道系统 ID，结果将为空。在这种情况下，systemTimeZone().isValid() 将为真。

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

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

给定的fromDateTime 和toDateTime 包括在内。每个条目的atUtc 成员描述了转换的时刻，其他成员给出的偏移和缩写在该时刻生效。

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

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

[static] QTimeZone QTimeZone::utc()

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

该方法仅在启用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 ID 可能涵盖给定区域内的多个 IANA ID，因此将返回该区域内最常用的 IANA ID。

作为特例，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 ID。

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

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

另请参阅 ianaIdToWindowsId() 和windowsIdToDefaultIanaId()。

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

返回给定windowsId 和territory 的所有 IANA ID。

作为特例，AnyTerritory 选择那些与领土无关的 IANA ID，而World 则选择与给定windowsId 无关的领土的默认 IANA ID。

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

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

另请参阅 ianaIdToWindowsId()、windowsIdToDefaultIanaId() 和territory()。

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

Move-assignsother 至QTimeZone 实例，将其数据所有权转移至该实例。

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

赋值操作符，将other 赋值给此变量。