Module java.base
Package java.time

Class ZoneId

java.lang.Object
java.time.ZoneId
所有已实现的接口:
Serializable
直接已知的子类:
ZoneOffset
public abstract sealed class ZoneId extends Object implements Serializable permits ZoneOffset (not exhaustive)
一个时区ID，例如Europe/Paris。

ZoneId用于标识用于在Instant和LocalDateTime之间进行转换的规则。有两种不同类型的ID：

  • 固定偏移 - 从UTC/Greenwich完全解析的偏移，对所有本地日期时间使用相同的偏移
  • 地理区域 - 一个区域，应用于从UTC/Greenwich找到偏移的特定规则
大多数固定偏移由ZoneOffset表示。在任何ZoneId上调用normalized()将确保固定偏移ID将被表示为ZoneOffset。

实际规则，描述偏移何时以及如何更改，由ZoneRules定义。这个类只是一个用于获取基础规则的ID。采取这种方法是因为规则由政府定义并经常更改，而ID是稳定的。

区别还有其他影响。序列化ZoneId将仅发送ID，而序列化规则将发送整个数据集。类似地，两个ID的比较仅检查ID，而两个规则的比较检查整个数据集。

时区ID

该ID在系统内是唯一的。有三种ID类型。

ID的最简单类型来自ZoneOffset。这包括'Z'和以'+'或'-'开头的ID。

下一种ID类型是带有某种前缀的偏移样式ID，例如'GMT+2'或'UTC+01:00'。被识别的前缀是'UTC'，'GMT'和'UT'。偏移量是后缀，并将在创建期间被标准化。这些ID可以使用normalized()标准化为ZoneOffset。

第三种ID类型是基于区域的ID。基于区域的ID必须是两个或更多字符，并且不能以'UTC'，'GMT'，'UT'，'+'或'-'开头。基于区域的ID由配置定义，请参见ZoneRulesProvider。配置侧重于提供从ID到基础ZoneRules的查找。

时区规则由政府定义并经常更改。有许多组织，这里称为组，监视时区更改并整理它们。默认组是IANA时区数据库（TZDB）。其他组织包括IATA（航空业机构）和Microsoft。

每个组都定义其提供的区域ID的格式。TZDB组定义诸如'Europe/London'或'America/New_York'之类的ID。TZDB ID优先于其他组。

强烈建议在除TZDB之外的组提供的所有ID中包含组名，以避免冲突。例如，IATA航空公司时区区域ID通常与三字母机场代码相同。但是，乌得勒支的机场代码是'UTC'，这显然是一个冲突。除TZDB之外的组提供的区域ID的推荐格式是'group~region'。因此，如果定义了IATA数据，乌得勒支机场将是'IATA~UTC'。

序列化

该类可以序列化，并以外部形式存储字符串时区ID。 ZoneOffset子类使用专用格式，仅存储与UTC/Greenwich的偏移量。

ZoneId可以在Java Runtime中反序列化，其中ID是未知的。例如，如果服务器端Java Runtime已更新为新的区域ID，但客户端Java Runtime尚未更新。在这种情况下，ZoneId对象将存在，并且可以使用getId，equals，hashCode，toString，getDisplayName和normalized进行查询。但是，任何对getRules的调用将失败，并显示ZoneRulesException。这种方法旨在允许在具有不完整时区信息的Java Runtime上加载和查询ZonedDateTime，但不允许修改。

这是一个基于值的类；程序员应将相等的实例视为可互换，并且不应将实例用于同步，否则可能会发生不可预测的行为。例如，在将来的版本中，同步可能会失败。应该使用equals方法进行比较。

实现要求:
这个抽象密封类允许两种实现，两者都是不可变且线程安全的。一种实现模拟基于区域的ID，另一种是模拟基于偏移的ID的ZoneOffset。这种差异在序列化中可见。
密封类层次结构图:
ZoneId的密封类层次结构图ZoneId的密封类层次结构图
自从:
1.8
参见:

  • Field Details

    • SHORT_IDS

      public static final Map<String,String> SHORT_IDS
      一个区域覆盖的映射，以便使用短时区名称。

      在java.util.TimeZone中已弃用短时区ID。此映射允许通过of(String, Map)工厂方法继续使用这些ID。

      此映射包含与TZDB 2005r及更高版本一致的ID映射，其中'EST'，'MST'和'HST'映射到不包括夏令时的ID。

      映射如下：

      • EST - -05:00
      • HST - -10:00
      • MST - -07:00
      • ACT - Australia/Darwin
      • AET - Australia/Sydney
      • AGT - America/Argentina/Buenos_Aires
      • ART - Africa/Cairo
      • AST - America/Anchorage
      • BET - America/Sao_Paulo
      • BST - Asia/Dhaka
      • CAT - Africa/Harare
      • CNT - America/St_Johns
      • CST - America/Chicago
      • CTT - Asia/Shanghai
      • EAT - Africa/Addis_Ababa
      • ECT - Europe/Paris
      • IET - America/Indiana/Indianapolis
      • IST - Asia/Kolkata
      • JST - Asia/Tokyo
      • MIT - Pacific/Apia
      • NET - Asia/Yerevan
      • NST - Pacific/Auckland
      • PLT - Asia/Karachi
      • PNT - America/Phoenix
      • PRT - America/Puerto_Rico
      • PST - America/Los_Angeles
      • SST - Pacific/Guadalcanal
      • VST - Asia/Ho_Chi_Minh
      该映射是不可修改的。

  • Method Details

    • systemDefault

      public static ZoneId systemDefault()
      获取系统默认时区。

      这将查询TimeZone.getDefault()以查找默认时区并将其转换为ZoneId。如果系统默认时区更改，则此方法的结果也将更改。

      返回:
      时区ID，不为null
      抛出:
      DateTimeException - 如果转换后的时区ID格式无效
      ZoneRulesException - 如果找不到转换后的时区区域ID

    • getAvailableZoneIds

      public static Set<String> getAvailableZoneIds()
      获取可用的时区ID集。

      此集合包括所有可用基于区域的ID的字符串形式。偏移式时区ID不包括在返回的集合中。ID可以传递给of(String)以创建ZoneId。

      时区ID的集合可以随时间增加，尽管在典型应用程序中，ID集合是固定的。每次调用此方法都是线程安全的。

      返回:
      时区ID集的可修改副本，不为null

    • of

      public static ZoneId of(String zoneId, Map<String,String> aliasMap)
      使用其ID和别名映射获取ZoneId的实例。

      许多时区用户使用简短缩写，例如PST表示'太平洋标准时间'，PDT表示'太平洋夏令时间'。这些缩写不是唯一的，因此不能用作ID。此方法允许设置并在应用程序中重复使用字符串到时区的映射。

      参数:
      zoneId - 时区ID，不为null
      aliasMap - 别名时区ID的映射（通常是缩写）到真实时区ID，不为null
      返回:
      时区ID，不为null
      抛出:
      DateTimeException - 如果时区ID格式无效
      ZoneRulesException - 如果时区ID是无法找到的区域ID

    • of

      public static ZoneId of(String zoneId)
      从ID获取ZoneId的实例，确保ID有效且可用于使用。

      此方法解析ID生成ZoneId或ZoneOffset。如果ID为'Z'，或以'+'或'-'开头，则返回ZoneOffset。结果将始终是一个有效的ID，可以从中获取ZoneRules。

      解析按以下步骤逐步匹配时区ID。

      • 如果时区ID等于'Z'，结果为ZoneOffset.UTC。
      • 如果时区ID由单个字母组成，则时区ID无效，将抛出DateTimeException。
      • 如果时区ID以'+'或'-'开头，则使用ZoneOffset.of(String)将ID解析为ZoneOffset。
      • 如果时区ID等于'GMT'、'UTC'或'UT'，则结果是具有相同ID和规则等效于ZoneOffset.UTC的ZoneId。
      • 如果时区ID以'UTC+'、'UTC-'、'GMT+'、'GMT-'、'UT+'或'UT-'开头，则ID是带有前缀偏移的ID。ID分为两部分，一个是两个或三个字母的前缀，另一个是以符号开头的后缀。后缀将被解析为ZoneOffset。结果将是具有指定的UTC/GMT/UT前缀和根据ZoneOffset.getId()规范化的偏移ID的ZoneId。返回的ZoneId的规则将等效于解析的ZoneOffset。
      • 所有其他ID都将被解析为基于区域的时区ID。区域ID必须与正则表达式[A-Za-z][A-Za-z0-9~/._+-]+匹配，否则将抛出DateTimeException。如果时区ID不在配置的ID集合中，则将抛出ZoneRulesException。区域ID的详细格式取决于提供数据的组。默认数据集由IANA时区数据库（TZDB）提供。这些区域ID的形式为'{area}/{city}'，例如'Europe/Paris'或'America/New_York'。这与大多数TimeZone的ID兼容。
      参数：
      zoneId - 时区ID，非空
      返回：
      时区ID，非空
      抛出：
      DateTimeException - 如果时区ID格式无效
      ZoneRulesException - 如果时区ID是找不到的区域ID

    • ofOffset

      public static ZoneId ofOffset(String prefix, ZoneOffset offset)
      从偏移获取ZoneId的实例。

      如果前缀为"GMT"、"UTC"或"UT"，则返回带有前缀和非零偏移的ZoneId。如果前缀为空""，则返回ZoneOffset。

      参数：
      prefix - 时区ID，非空
      offset - 偏移，非空
      返回：
      时区ID，非空
      抛出：
      IllegalArgumentException - 如果前缀不是"GMT"、"UTC"或"UT"，或""

    • from

      public static ZoneId from(TemporalAccessor temporal)
      从时间对象获取ZoneId的实例。

      根据指定的时间获取时区。 TemporalAccessor表示一组任意的日期和时间信息，此工厂将其转换为ZoneId的实例。

      TemporalAccessor表示某种形式的日期和时间信息。此工厂将任意时间对象转换为ZoneId的实例。

      转换将尝试以有利于基于区域的时区而不是基于偏移的时区的方式获取时区，使用TemporalQueries.zone()。

      此方法与函数接口TemporalQuery的签名匹配，允许通过方法引用ZoneId::from来使用作为查询。

      参数：
      temporal - 要转换的时间对象，非空
      返回：
      时区ID，非空
      抛出：
      DateTimeException - 如果无法转换为ZoneId

    • getId

      public abstract String getId()
      获取唯一的时区ID。

      此ID唯一定义此对象。基于偏移的ID的格式由ZoneOffset.getId()定义。

      返回：
      时区唯一ID，非空

    • getDisplayName

      public String getDisplayName(TextStyle style, Locale locale)
      获取时区的文本表示，例如'British Time'或'+02:00'。

      返回用于标识时区ID的文本名称，适合向用户展示。参数控制返回文本的样式和区域设置。

      如果找不到文本映射，则返回完整ID。

      参数：
      style - 所需文本的长度，非空
      locale - 要使用的区域设置，非空
      返回：
      时区的文本值，非空

    • getRules

      public abstract ZoneRules getRules()
      获取此ID的时区规则，允许执行计算。

      规则提供与时区相关的功能，例如查找给定时刻或本地日期时间的偏移量。

      如果在Java Runtime中反序列化时区时，该时区可能无效，因为加载规则的Java Runtime与存储它的Java Runtime不同。在这种情况下，调用此方法将抛出ZoneRulesException。

      规则由ZoneRulesProvider提供。高级提供程序可能支持动态更新规则而无需重新启动Java Runtime。如果是这样，那么此方法的结果可能随时间而变化。每个单独的调用仍将保持线程安全。

      ZoneOffset将始终返回一组规则，其中偏移量永远不会更改。

      返回：
      规则，非空
      抛出：
      ZoneRulesException - 如果此ID没有可用的规则

    • normalized

      public ZoneId normalized()
      规范化时区ID，返回ZoneOffset（如果可能）。

      返回一个规范化的ZoneId，可以代替此ID使用。结果将具有与此对象返回的ZoneRules等效的ZoneId，但是getId()返回的ID可能不同。

      规范化检查此ZoneId的规则是否具有固定偏移量。如果是，则返回等于该偏移量的ZoneOffset。否则返回this。

      返回：
      时区唯一ID，非空

    • equals

      public boolean equals(Object obj)
      检查此时区ID是否等于另一个时区ID。

      比较基于ID。

      覆盖：
      equals 在类 Object中
      参数：
      obj - 要检查的对象，null返回false
      返回：
      如果这个等于另一个时区ID，则为true
      参见：

    • hashCode

      public int hashCode()
      此时区ID的哈希码。
      覆盖：
      hashCode 在类 Object
      返回：
      适当的哈希码
      参见：

    • toString

      public String toString()
      使用ID将此时区输出为String。
      覆盖：
      toString 在类 Object
      返回：
      此时区ID的字符串表示，非空