Module java.base

Package java.util

Class TimeZone

java.lang.Object

java.util.TimeZone

所有已实现的接口:

Serializable, Cloneable

直接已知的子类:

SimpleTimeZone

       public abstract class TimeZone extends Object implements Serializable, Cloneable
      

TimeZone 表示一个时区偏移，并且可以计算夏令时。

通常，您可以使用 getDefault 来获取一个 TimeZone，它会基于程序运行的时区创建一个 TimeZone。例如，在日本运行的程序中，getDefault 会创建一个基于日本标准时间的 TimeZone 对象。

您也可以使用 getTimeZone 以及一个时区ID来获取一个 TimeZone。例如，美国太平洋时区的时区ID是 "America/Los_Angeles"。因此，您可以通过以下方式获取一个美国太平洋时区的 TimeZone 对象：

TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles");

您可以使用 getAvailableIDs 方法遍历所有支持的时区ID。然后，您可以选择一个支持的ID来获取一个 TimeZone。如果您想要的时区没有被支持的ID表示，那么可以指定一个自定义的时区ID 来生成一个 TimeZone。自定义时区ID 的语法是：

 CustomID:
         GMT Sign Hours : Minutes : Seconds
         GMT Sign Hours : Minutes
         GMT Sign Hours Minutes
         GMT Sign Hours
 Sign: 其中之一
         + -
 Hours:
         Digit
         Digit Digit
 Minutes:
         Digit Digit
 Seconds:
         Digit Digit
 Digit: 其中之一
         0 1 2 3 4 5 6 7 8 9
 

Hours 必须在 0 到 23 之间，Minutes/Seconds 必须在 00 到 59 之间。例如，"GMT+10" 和 "GMT+0010" 分别表示比 GMT 提前十小时和十分钟。

该格式与语言环境无关，数字必须取自 Unicode 标准的基本拉丁区块。自定义时区ID 不能指定夏令时转换计划。如果指定的字符串不符合语法，将使用 "GMT"。

在创建 TimeZone 时，指定的自定义时区ID 会被规范化为以下语法：

 NormalizedCustomID:
         GMT Sign TwoDigitHours : Minutes [ColonSeconds]
 Sign: 其中之一
         + -
 TwoDigitHours:
         Digit Digit
 Minutes:
         Digit Digit
 ColonSeconds:
         : Digit Digit
 Digit: 其中之一
         0 1 2 3 4 5 6 7 8 9
 

例如，TimeZone.getTimeZone("GMT-8").getID() 返回 "GMT-08:00"。只有在秒值非零时，ColonSeconds 部分才会出现。

三字母时区ID

为了与 JDK 1.1.x 兼容，还支持一些其他三字母时区ID（例如 "PST"、"CTT"、"AST"）。然而，它们的使用已被弃用，因为同一缩写通常用于多个时区（例如，"CST" 可能是美国的 "中部标准时间" 和中国的 "中国标准时间"），此时 Java 平台只能识别其中一个。

自 JDK 版本:

1.1

参见:

• Calendar
• GregorianCalendar
• SimpleTimeZone
• 序列化形式

Field Summary

Fields

Modifier and Type	Field	Description
static final int	LONG	用于 getDisplayName() 的样式说明符，表示长名称，例如 "太平洋标准时间"。
static final int	SHORT	用于 getDisplayName() 的样式说明符，表示短名称，例如 "PST"。

Constructor Summary

Constructors

Constructor	Description
TimeZone()	唯一构造函数。

Method Summary

Modifier and Type	Method	Description
Object	clone()	创建此 TimeZone 的副本。
static String[]	getAvailableIDs()	获取所有支持的可用ID。
static String[]	getAvailableIDs(int rawOffset)	根据给定的毫秒级时区偏移获取可用的ID。
static TimeZone	getDefault()	获取 Java 虚拟机的默认 TimeZone。
final String	getDisplayName()	返回适合在默认语言环境中向用户展示的此 TimeZone 的长标准时间名称。
final String	getDisplayName(boolean daylight, int style)	返回适合在默认语言环境中向用户展示的此 TimeZone 的指定样式的名称。
String	getDisplayName(boolean daylight, int style, Locale locale)	返回适合在指定语言环境中向用户展示的此 TimeZone 的指定样式的名称。
final String	getDisplayName(Locale locale)	返回适合在指定语言环境中向用户展示的此 TimeZone 的长标准时间名称。
int	getDSTSavings()	返回要添加到本地标准时间以获取本地壁钟时间的时间量。
String	getID()	获取此时区的ID。
abstract int	getOffset(int era, int year, int month, int day, int dayOfWeek, int milliseconds)	获取当前日期的时区偏移，如果存在夏令时，则进行修改。
int	getOffset(long date)	返回指定日期时此时区与 UTC 的偏移。
abstract int	getRawOffset()	返回以毫秒为单位的时间量，以将 UTC 添加到此时区的标准时间。
static TimeZone	getTimeZone(String ID)	获取给定ID的 TimeZone。
static TimeZone	getTimeZone(ZoneId zoneId)	获取给定 zoneId 的 TimeZone。
boolean	hasSameRules(TimeZone other)	如果此时区具有与另一个时区相同的规则和偏移，则返回 true。
abstract boolean	inDaylightTime(Date date)	查询给定的 date 是否处于此时区的夏令时。
boolean	observesDaylightTime()	如果此 TimeZone 当前处于夏令时，或者将来任何时间从标准时间转换为夏令时，则返回 true。
static void	setDefault(TimeZone zone)	设置由 getDefault 方法返回的 TimeZone。
void	setID(String ID)	设置时区ID。
abstract void	setRawOffset(int offsetMillis)	将此 TimeZone 对象转换为 ZoneId。
ZoneId	toZoneId()	查询此 TimeZone 是否使用夏令时。
abstract boolean	useDaylightTime()	用于 getDisplayName() 的样式说明符，表示短名称，例如 "PST"。

Methods declared in class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

SHORT

             public static final int SHORT
            

A style specifier for getDisplayName() indicating a short name, such as "PST."

自 JDK 版本:

1.2

参见:

• LONG
• 常量字段值

LONG

             public static final int LONG
            

用于 getDisplayName() 的样式说明符，表示长名称，例如 "太平洋标准时间"。

自 JDK 版本:

1.2

参见:

• SHORT
• 常量字段值

Constructor Details

TimeZone

             public TimeZone()
            

唯一构造函数。（通常由子类构造函数隐式调用。）

Method Details

getOffset

             public abstract int getOffset(int era, int year, int month, int day, int dayOfWeek, int milliseconds)
            

获取当前日期的时区偏移，如果存在夏令时，则进行修改。这是要添加到 UTC 以获取本地时间的偏移量。

如果底层的 TimeZone 实现子类支持历史夏令时计划和 GMT 偏移更改，则此方法返回历史上正确的偏移。

参数:

era - 给定日期的纪元。

year - 给定日期的年份。

month - 给定日期的月份。月份从 0 开始计数。例如，1 代表一月。

day - 给定日期的当月日期。

dayOfWeek - 给定日期的星期几。

milliseconds - 标准本地时间中的一天中的毫秒数。

返回:

要添加到 GMT 以获取本地时间的毫秒数偏移量。

参见:

• Calendar.ZONE_OFFSET
• Calendar.DST_OFFSET

getOffset

             public int getOffset(long date)
            

返回指定日期时此时区与 UTC 的偏移。如果指定日期时夏令时生效，则偏移值会根据夏令时的时间调整。

如果底层的 TimeZone 实现子类支持历史夏令时计划和 GMT 偏移更改，则此方法返回历史上正确的偏移值。

参数:

date - 自 1970 年 1 月 1 日 00:00:00 GMT 以来表示的日期的毫秒数

返回:

要添加到 UTC 以获取本地时间的毫秒数时间量。

自 JDK 版本:

1.4

参见:

• Calendar.ZONE_OFFSET
• Calendar.DST_OFFSET

setRawOffset

             public abstract void setRawOffset(int offsetMillis)
            

将基本时区偏移设置为 GMT。这是要添加到 UTC 以获取本地时间的偏移量。

如果底层的 TimeZone 实现子类支持历史 GMT 偏移更改，则指定的 GMT 偏移将设置为最新的 GMT 偏移，并且将使用已知最新 GMT 偏移值与所有历史 GMT 偏移值的差异来调整。

参数:

offsetMillis - 要添加到 GMT 以获取本地时间的基本时区偏移。

getRawOffset

             public abstract int getRawOffset()
            

返回以毫秒为单位的时间量，以将 UTC 添加到此时区的标准时间。因为此值不受夏令时的影响，所以称为 原始偏移。

如果底层的 TimeZone 实现子类支持历史 GMT 偏移更改，则该方法返回当前日期的原始偏移值。例如，在檀香山，其原始偏移在 1947 年从 GMT-10:30 更改为 GMT-10:00，此方法始终返回 -36000000 毫秒（即 -10 小时）。

返回值:

要添加到UTC的原始偏移时间量（以毫秒为单位）。

参见:

• Calendar.ZONE_OFFSET

getID

             public String getID()
            

获取此时区的ID。

返回值:

此时区的ID。

setID

             public void setID(String ID)
            

设置时区ID。这不会更改时区对象中的任何其他数据。

实现要求:

如果ID为null，默认实现会抛出NullPointerException。

参数:

ID - 新的时区ID。

抛出:

NullPointerException - 如果ID为null，此方法可能会抛出NullPointerException。

getDisplayName

             public final String getDisplayName()
            

返回此TimeZone的长标准时间名称，适合在默认区域设置中向用户展示。

此方法等效于：

getDisplayName(false, LONG,
               Locale.getDefault(Locale.Category.DISPLAY));

返回值:

此时区在默认区域设置中的可读名称。

自 JDK 版本:

1.2

参见:

• getDisplayName(boolean, int, Locale)
• Locale.getDefault(Locale.Category)
• Locale.Category

getDisplayName

             public final String getDisplayName(Locale locale)
            

返回此TimeZone的长标准时间名称，适合在指定的locale中向用户展示。

此方法等效于：

getDisplayName(false, LONG, locale);

参数:

locale - 提供显示名称的区域设置。

返回值:

此时区在给定区域设置中的可读名称。

抛出:

NullPointerException - 如果locale为null。

自 JDK 版本:

1.2

参见:

• getDisplayName(boolean, int, Locale)

getDisplayName

             public final String getDisplayName(boolean daylight, int style)
            

返回此TimeZone的指定style的名称，适合在默认区域设置中向用户展示。如果指定的daylight为true，则返回夏令时名称（即使此TimeZone不遵守夏令时）。否则，返回标准时间名称。

此方法等效于：

getDisplayName(daylight, style,
               Locale.getDefault(Locale.Category.DISPLAY));

参数:

daylight - 指定夏令时名称为true，或指定标准时间名称为false

style - LONG或SHORT

返回值:

此时区在默认区域设置中的可读名称。

抛出:

IllegalArgumentException - 如果style无效。

自 JDK 版本:

1.2

参见:

• getDisplayName(boolean, int, Locale)
• Locale.getDefault(Locale.Category)
• Locale.Category
• DateFormatSymbols.getZoneStrings()

getDisplayName

             public String getDisplayName(boolean daylight, int style, Locale locale)
            

返回此TimeZone的指定style的名称，适合在指定的locale中向用户展示。如果指定的daylight为true，则返回夏令时名称（即使此TimeZone不遵守夏令时）。否则，返回标准时间名称。

在查找时区名称时，使用从指定locale派生的默认Locale搜索路径。（不执行回退Locale搜索。）如果在搜索路径的任何Locale中（包括Locale.ROOT）找到时区名称，则返回该名称。否则，返回规范化的自定义ID格式的字符串。

实现要求:

如果style无效，或者ID为null，默认实现会抛出IllegalArgumentException。

参数:

daylight - 指定夏令时名称为true，或指定标准时间名称为false

style - LONG或SHORT

locale - 提供显示名称的区域设置。

返回值:

此时区在给定区域设置中的可读名称。

抛出:

IllegalArgumentException - 如果style无效，此方法可能会抛出IllegalArgumentException。

NullPointerException - 如果ID为null，此方法可能会抛出NullPointerException。

自 JDK 版本:

1.2

参见:

• DateFormatSymbols.getZoneStrings()

getDSTSavings

             public int getDSTSavings()
            

返回要添加到本地标准时间以获取本地挂钟时间的时间量。

如果调用useDaylightTime()返回true，默认实现将返回3600000毫秒（即一小时）。否则，返回0（零）。

如果底层TimeZone实现子类支持历史和未来的夏令时时间表更改，此方法将返回最后已知的夏令时规则的节约时间，可能是未来的预测。

如果需要在任何给定时间戳的节约时间量，请使用带有此TimeZone和时间戳的Calendar构造，并调用Calendar.get(Calendar.DST_OFFSET)。

返回值:

节约时间的毫秒数

自 JDK 版本:

1.4

参见:

• inDaylightTime(Date)
• getOffset(long)
• getOffset(int,int,int,int,int,int)
• Calendar.ZONE_OFFSET

useDaylightTime

             public abstract boolean useDaylightTime()
            

查询此TimeZone是否使用夏令时。

如果底层TimeZone实现子类支持历史和未来的夏令时时间表更改，此方法指的是最后已知的夏令时规则，可能是未来的预测，可能与当前规则不同。如果应考虑当前规则，考虑调用observesDaylightTime()。

返回值:

如果此TimeZone使用夏令时，则为true，否则为false。

参见:

• inDaylightTime(Date)
• Calendar.DST_OFFSET

observesDaylightTime

             public boolean observesDaylightTime()
            

如果此TimeZone当前处于夏令时，或者将来的任何时间从标准时间转换为夏令时，则返回true。

默认实现如果useDaylightTime()或inDaylightTime(new Date())返回true，则返回true。

返回值:

如果此TimeZone当前处于夏令时，或者将来的任何时间从标准时间转换为夏令时，则返回true；否则返回false。

自 JDK 版本:

1.7

参见:

• useDaylightTime()
• inDaylightTime(Date)
• Calendar.DST_OFFSET

inDaylightTime

             public abstract boolean inDaylightTime(Date date)
            

查询给定的date是否在该时区的夏令时中。

参数:

date - 给定的日期。

返回:

如果给定的日期在夏令时中，则返回true，否则返回false。

抛出:

NullPointerException - 如果date为null，则此方法可能会抛出NullPointerException。

getTimeZone

             public static TimeZone getTimeZone(String ID)
            

获取给定ID的TimeZone。

参数:

ID - 一个TimeZone的ID，可以是缩写，如"PST"，全名，如"America/Los_Angeles"，或自定义ID，如"GMT-8:00"。请注意，对缩写的支持仅用于与JDK 1.1.x的兼容性，应使用全名。

返回:

指定的TimeZone，如果给定的ID无法理解，则返回GMT时区。

抛出:

NullPointerException - 如果ID为null。

getTimeZone

             public static TimeZone getTimeZone(ZoneId zoneId)
            

获取给定zoneId的TimeZone。

参数:

zoneId - 从中获取时区ID的ZoneId

返回:

指定的TimeZone，如果给定的ID无法理解，则返回GMT时区。

抛出:

NullPointerException - 如果zoneId为null。

自Java版本:

1.8

toZoneId

             public ZoneId toZoneId()
            

将此TimeZone对象转换为ZoneId。

返回:

表示与此TimeZone相同时区的ZoneId。

自Java版本:

1.8

getAvailableIDs

             public static String[] getAvailableIDs(int rawOffset)
            

根据给定的毫秒级时区偏移量获取可用的ID。

参数:

rawOffset - 给定的时区GMT偏移量（以毫秒为单位）。

返回:

一个ID数组，其中该ID的时区具有指定的GMT偏移量。例如，"America/Phoenix"和"America/Denver"都具有GMT-07:00，但在夏令时行为上有所不同。

参见:

• getRawOffset()

getAvailableIDs

             public static String[] getAvailableIDs()
            

获取所有支持的可用ID。

返回:

一个ID数组。

getDefault

             public static TimeZone getDefault()
            

获取Java虚拟机的默认TimeZone。如果缓存的默认TimeZone可用，则返回其克隆。否则，该方法将采取以下步骤来确定默认时区。

• 如果可用，使用user.timezone属性值作为默认时区ID。
• 检测平台时区ID。平台时区和ID映射的来源可能因实现而异。
• 如果给定或检测到的时区ID未知，则使用GMT作为最后手段。

从ID创建的默认TimeZone被缓存，并返回其克隆。返回时，user.timezone属性值设置为该ID。

返回:

默认TimeZone。

参见:

• setDefault(TimeZone)

setDefault

             public static void setDefault(TimeZone zone)
            

设置由getDefault方法返回的TimeZone。zone被缓存。如果zone为null，则清除缓存的默认TimeZone。此方法不会更改user.timezone属性的值。

参数:

zone - 新的默认TimeZone，或null

抛出:

SecurityException - 如果安全管理器的checkPermission拒绝PropertyPermission("user.timezone", "write")

参见:

• getDefault()
• PropertyPermission

hasSameRules

             public boolean hasSameRules(TimeZone other)
            

如果此时区具有与另一个时区相同的规则和偏移量，则返回true。也就是说，如果此时区仅在ID上有所不同，则返回false。如果另一个时区为null，则返回false。

参数:

other - 要与之比较的TimeZone对象

返回:

如果另一个时区不为null且与此时区相同（可能除了ID外），则返回true

自Java版本:

1.2

clone

             public Object clone()
            

创建此TimeZone的副本。

覆盖:

clone 在类 Object

返回:

此TimeZone的克隆

参见:

• Cloneable