模块 java.base

包 java.time

类 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/格林威治的偏移量的区域

大多数固定偏移量由 ZoneOffset 表示。在任何 ZoneId 上调用 normalized() 将确保固定偏移 ID 将表示为 ZoneOffset。

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

这种区别还有其他影响。序列化 ZoneId 只会发送 ID，而序列化规则会发送整个数据集。同样，两个 ID 的比较只检查 ID，而两个规则的比较检查整个数据集。

时区 ID

ID 在系统内是唯一的。 ID 分为三种类型。

最简单的 ID 类型是来自 ZoneOffset 的 ID。这由“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/格林威治的偏移量。

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

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

实现要求：

这个抽象密封类允许两种实现，它们都是不可变的和线程安全的。一种实现对基于区域的 ID 进行建模，另一种是ZoneOffset 对基于偏移量的 ID 进行建模。这种差异在序列化中是可见的。

密封类层次结构图：

自从：

1.8

参见：

• Serialized Form

字段摘要

字段

修饰符和类型	Field	描述
static final Map<String,String>	SHORT_IDS	区域映射重写以启用要使用的短时区名称。

方法总结

修饰符和类型	方法	描述
boolean	equals(Object obj)	检查此时区 ID 是否等于另一个时区 ID。
static ZoneId	from(TemporalAccessor temporal)	从时间对象中获取 ZoneId 的实例。
static Set<String>	getAvailableZoneIds()	获取可用区域 ID 的集合。
String	getDisplayName(TextStyle style, Locale locale)	获取区域的文本表示形式，例如“英国时间”或“+02:00”。
abstract String	getId()	获取唯一的时区 ID。
abstract ZoneRules	getRules()	获取允许执行计算的此 ID 的时区规则。
int	hashCode()	此时区 ID 的哈希码。
ZoneId	normalized()	规范化时区 ID，尽可能返回 ZoneOffset。
static ZoneId	of(String zoneId)	从 ID 中获取 ZoneId 的实例，确保该 ID 有效且可供使用。
static ZoneId	of(String zoneId, Map<String,String> aliasMap)	使用别名映射来补充标准区域 ID，使用其 ID 获取 ZoneId 的实例。
static ZoneId	ofOffset(String prefix, ZoneOffset offset)	获得 ZoneId 包装偏移量的实例。
static ZoneId	systemDefault()	获取系统默认时区。
String	toString()	使用 ID 将此区域输出为 String 。

在类 java.lang.Object 中声明的方法

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

字段详细信息

SHORT_IDS

public static final Map <String ,String > SHORT_IDS
            

区域映射重写以启用要使用的短时区名称。

java.util.TimeZone 中已弃用短区域 ID。此map允许通过 of(String, Map) 工厂方法继续使用 ID。

此map包含符合 TZDB 2005r 及更高版本的 ID 映射，其中“EST”、“MST”和“HST”映射到不包括夏令时的 ID。

这映射如下：

• EST - -05:00
• HST - -10:00
• MST - -07:00
• ACT - 澳大利亚/达尔文
• AET - 澳大利亚/悉尼
• AGT - 美国/阿根廷/布宜诺斯艾利斯
• 艺术 - 非洲/开罗
• AST - 美国/安克雷奇
• BET - 美国/圣保罗
• BST - 亚洲/达卡
• CAT - 非洲/哈拉雷
• CNT - 美国/St_Johns
• CST——美国/芝加哥
• CTT - 亚洲/上海
• EAT - 非洲/亚的斯亚贝巴
• ECT - 欧洲/巴黎
• IET - 美国/印第安纳州/印第安纳波利斯
• IST - 亚洲/加尔各答
• JST - 亚洲/东京
• 麻省理工学院 - 太平洋/阿皮亚
• NET - 亚洲/埃里温
• NST - 太平洋/奥克兰
• PLT - 亚洲/卡拉奇
• PNT - 美洲/凤凰城
• PRT - 美洲/波多黎各
• PST - 美国/洛杉矶
• SST - 太平洋/瓜达尔卡纳尔
• VST - 亚洲/胡志明市

map是不可修改的。

方法详情

systemDefault

public static ZoneId  systemDefault()
            

获取系统默认时区。

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

返回：

区域 ID，不为空

抛出：

DateTimeException - 如果转换后的区域 ID 格式无效

ZoneRulesException - 如果找不到转换后的区域 ID

getAvailableZoneIds

public static Set <String > getAvailableZoneIds()
            

获取可用区域 ID 的集合。

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

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

返回：

一组区域 ID 的可修改副本，不为空

of

public static ZoneId  of(String  zoneId, Map <String ,String > aliasMap)
            

使用别名映射来补充标准区域 ID，使用其 ID 获取 ZoneId 的实例。

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

参数：

zoneId - 时区 ID，不为空

aliasMap - 别名区域 ID（通常是缩写）到真实区域 ID 的映射，不为空

返回：

区域 ID，不为空

抛出：

DateTimeException - 如果区域 ID 的格式无效

ZoneRulesException - 如果区域 ID 是无法找到的区域 ID

of

public static ZoneId  of(String  zoneId)
            

从 ID 中获取 ZoneId 的实例，确保该 ID 有效且可供使用。

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

解析匹配zone ID的步骤如下。

• 如果区域 ID 等于“Z”，则结果为 ZoneOffset.UTC 。
• 如果区域 ID 由单个字母组成，则区域 ID 无效并抛出 DateTimeException。
• 如果区域 ID 以“+”或“-”开头，则使用 ZoneOffset.of(String) 将 ID 解析为 ZoneOffset。
• 如果区域 ID 等于“GMT”、“UTC”或“UT”，则结果是具有相同 ID 和规则的 ZoneId 等同于 ZoneOffset.UTC。
• 如果区域 ID 以“UTC+”、“UTC-”、“GMT+”、“GMT-”、“UT+”或“UT-”开头，则该 ID 是一个基于偏移量的前缀 ID。 ID 分为两部分，有两个或三个字母的前缀和一个以符号开头的后缀。后缀被解析为 ZoneOffset 。结果将是一个 ZoneId，带有指定的 UTC/GMT/UT 前缀和按照 ZoneOffset.getId() 的规范化偏移 ID。返回的规则 ZoneId 将等同于解析的 ZoneOffset 。
• 所有其他 ID 都被解析为基于区域的区域 ID。区域 ID 必须与正则表达式 [A-Za-z][A-Za-z0-9~/._+-]+ 匹配，否则将抛出 DateTimeException。如果区域 ID 不在配置的 ID 集中，则抛出 ZoneRulesException。区域 ID 的详细格式取决于提供数据的组。默认数据集由 IANA 时区数据库 (TZDB) 提供。这具有“{area}/{city}”形式的区域 ID，例如“欧洲/巴黎”或“美国/纽约”。这与 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)
            

获取区域的文本表示形式，例如“英国时间”或“+02:00”。

这将返回用于标识时区 ID 的文本名称，适合呈现给用户。参数控制返回文本的样式和locale。

如果未找到文本映射，则返回 full ID 。

参数：

style - 所需文本的长度，不为空

locale - 要使用的locale，不为空

返回：

区域的文本值，不为空

getRules

public abstract ZoneRules  getRules()
            

获取允许执行计算的此 ID 的时区规则。

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

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

规则由 ZoneRulesProvider 提供。高级提供者可以支持在不重新启动 Java 运行时的情况下对规则进行动态更新。如果是这样，那么这个方法的结果可能会随着时间的推移而改变。每个单独的调用仍将保持线程安全。

ZoneOffset 将始终返回一组偏移量永远不会改变的规则。

返回：

规则，不为空

抛出：

ZoneRulesException - 如果此 ID 没有可用的规则

normalized

public ZoneId  normalized()
            

规范化时区 ID，尽可能返回 ZoneOffset。

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

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

返回：

时区唯一 ID，不为空

equals

public boolean equals(Object  obj)
            

检查此时区 ID 是否等于另一个时区 ID。

比较基于ID。

重写：

equals 在类 Object 中

参数：

obj - 要检查的对象，null 返回 false

返回：

如果这等于另一个时区 ID，则为真

参见：

• Object.hashCode()
• HashMap

hashCode

public int hashCode()
            

此时区 ID 的哈希码。

重写：

hashCode 在类 Object 中

返回：

合适的哈希码

参见：

• Object.equals(java.lang.Object)
• System.identityHashCode(java.lang.Object)

toString

public String  toString()
            

使用 ID 将此区域输出为 String 。

重写：

toString 在类 Object 中

返回：

此时区 ID 的字符串表示形式，不为空