JavaTM 2 Platform
Standard Ed. 5.0

java.util
类 TimeZone

java.lang.Object
  继承者 java.util.TimeZone
所有已实现的接口:
Serializable, Cloneable
直接已知子类:
SimpleTimeZone

public abstract class TimeZone
extends Object
implements Serializable, Cloneable

TimeZone 表示时区偏移量,也可以计算夏令时。

通常,使用 getDefault 获得 TimeZonegetDefault 基于程序运行所在的时区创建 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
         GMT Sign Hours Minutes
         GMT Sign Hours
Sign: 下面之一
         + -
 Hours:
         Digit
         Digit Digit
 Minutes:
         Digit Digit
 Digit: 下面之一
         0 1 2 3 4 5 6 7 8 9
 
Hours 必须在 0 至 23 之间,Minutes 必须在 00 至 59 之间。例如,"GMT+10" 和 "GMT+0010" 分别意味着比 GMT 提前 10 小时和 10 分钟。

格式是与区域无关的,并且数字必须取自 Unicode 标准的 Basic Latin 块。没有夏令时转换安排可以用自定义时区 ID 指定。如果指定的字符串与语法不匹配,就使用 "GMT"

当创建一个 TimeZone 时,指定的自定义时区 ID 采用下面的语法进行标准化:

 NormalizedCustomID:
         GMT Sign TwoDigitHours : Minutes
Sign: 下面之一
         + -
 TwoDigitHours:
         Digit Digit
 Minutes:
         Digit Digit
 Digit: 下面之一
         0 1 2 3 4 5 6 7 8 9
 
例如,TimeZone.getTimeZone("GMT-8").getID() 返回 "GMT-08:00"。

三字母时区 ID

为了与 JDK 1.1.x 兼容,一些三字母时区 ID(比如 "PST"、"CTT"、"AST")也受支持。但是,它们的使用被废弃,这是因为相同的缩写经常用于多个时区(例如,"CST" 可以是美国的 "Central Standard Time" 和 "China Standard Time"),但是 Java 平台只可以识别其中一种。

从以下版本开始:
JDK1.1
另请参见:
Calendar, GregorianCalendar, SimpleTimeZone, 序列化表格

字段摘要
static int LONG
          指出长名称的 getDisplayName() 的风格说明符。
static int SHORT
          指出短名称(比如 "PST")的 getDisplayName() 的风格说明符。
 
构造方法摘要
TimeZone()
          单独的构造方法。
 
方法摘要
 Object clone()
          创建此 TimeZone 的一个副本。
static String[] getAvailableIDs()
          获取受支持的所有可用 ID。
static String[] getAvailableIDs(int rawOffset)
          根据给定的时区偏移量获取可用的 ID。
static TimeZone getDefault()
          获取此主机的默认 TimeZone
 String getDisplayName()
          返回适合于展示给默认区域的用户的时区名称。
 String getDisplayName(boolean daylight, int style)
          返回适合于展示给默认区域的用户的时区名称。
 String getDisplayName(boolean daylight, int style, Locale locale)
          返回适合于展示给指定区域的用户的时区名称。
 String getDisplayName(Locale locale)
          返回适合于展示给指定区域的用户的时区名称。
 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
 boolean hasSameRules(TimeZone other)
          如果此区域和另一个区域具有相同的规则和偏移量,也就是说,如果此区域只可能在 ID 上与另一个区域不同,则返回 true。
abstract  boolean inDaylightTime(Date date)
          查询给定的日期是否在此时区的夏令时中。
static void setDefault(TimeZone zone)
          设置由 getDefault 方法返回的 TimeZone
 void setID(String ID)
          设置时区 ID。
abstract  void setRawOffset(int offsetMillis)
          把基准时区偏移量设置到 GMT。
abstract  boolean useDaylightTime()
          查询此时区是否使用夏令时。
 
从类 java.lang.Object 继承的方法
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

字段详细信息

SHORT

public static final int SHORT
指出短名称(比如 "PST")的 getDisplayName() 的风格说明符。

从以下版本开始:
1.2
另请参见:
LONG, 常量字段值

LONG

public static final int LONG
指出长名称的 getDisplayName() 的风格说明符。

从以下版本开始:
1.2
另请参见:
SHORT, 常量字段值
构造方法详细信息

TimeZone

public TimeZone()
单独的构造方法。(由子类构造方法调用,通常是隐式的。)

方法详细信息

getOffset

public abstract int getOffset(int era,
                              int year,
                              int month,
                              int day,
                              int dayOfWeek,
                              int milliseconds)
获取当前日期的时区偏移量(在夏令时情况下进行修改)。这是添加到 UTC 获取本地时间的偏移量。

如果基础 TimeZone 实现子类支持历史夏令时安排和 GMT 偏移量改变,那么此方法就返回历史上正确的偏移量。

参数:
era - 给定日期的年代。
year - 给定日期的年份。
month - 给定日期的月份。月份是以零为基础的,比如 0 代表一月。
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 以获取本地时间的时间量(以毫秒为单位)。
从以下版本开始:
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 - 新的时区 ID。

getDisplayName

public final String getDisplayName()
返回适合于展示给默认区域的用户的时区名称。此方法返回长名称,不包括夏令时。如果显示名称对于区域不可用,那么此方法以标准化自定义 ID 格式返回一个字符串。

返回:
默认区域中时区的可读名称。
从以下版本开始:
1.2

getDisplayName

public final String getDisplayName(Locale locale)
返回适合于展示给指定区域的用户的时区名称。此方法返回长名称,不包括夏令时。如果显示名称对于区域不可用,那么此方法以标准化自定义 ID 格式返回一个字符串。

参数:
locale - 要提供显示名称的区域。
返回:
给定区域中时区的可读名称,如果给定区域不可识别,则返回默认区域中时区的可读名称。
从以下版本开始:
1.2

getDisplayName

public final String getDisplayName(boolean daylight,
                                   int style)
返回适合于展示给默认区域的用户的时区名称。如果显示名称对于区域不可用,那么此方法以标准化自定义 ID 格式返回一个字符串。

参数:
daylight - 如果为 true,则返回夏令时名称。
style - LONGSHORT
返回:
默认区域中时区的可读名称。
从以下版本开始:
1.2

getDisplayName

public String getDisplayName(boolean daylight,
                             int style,
                             Locale locale)
返回适合于展示给指定区域的用户的时区名称。如果显示名称对于区域不可用,那么此方法以标准化自定义 ID 格式返回一个字符串。

参数:
daylight - 如果为 true,返回夏令时名称。
style - LONGSHORT
locale - 要提供显示名称的区域。
返回:
给定区域中时区的可读名称,如果给定的区域不可识别,则返回默认区域中时区的可读名称。
抛出:
IllegalArgumentException - 风格是无效的。
从以下版本开始:
1.2

getDSTSavings

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

如果此时区遵守夏令时规则,则默认的实现始终返回 3600000 毫秒(即 1 小时)。否则,返回 0(零)。

如果基础 TimeZone 实现子类支持历史夏令时变化,则此方法返回已知的最新夏令时值。

返回:
节约的时间量(以毫秒为单位)
从以下版本开始:
1.4

useDaylightTime

public abstract boolean useDaylightTime()
查询此时区是否使用夏令时。

如果基础 TimeZone 实现子类支持历史夏令时安排变化,那么方法引用最新的夏令时安排信息。

返回:
如果此时区使用夏令时,则返回 true,否则返回 false。

inDaylightTime

public abstract boolean inDaylightTime(Date date)
查询给定的日期是否在此时区的夏令时中。

参数:
date - 给定的日期。
返回:
如果给定的日期在夏令时中,则返回 true,否则返回 false。

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 区域。

getAvailableIDs

public static String[] getAvailableIDs(int rawOffset)
根据给定的时区偏移量获取可用的 ID。

参数:
rawOffset - 给定的时区 GMT 偏移量。
返回:
一组 ID,其中该 ID 时区具有指定的 GMT 偏移量。例如,"America/Phoenix" 和 "America/Denver" 都有 GMT-07:00,但其夏令时行为是不同的。

getAvailableIDs

public static String[] getAvailableIDs()
获取受支持的所有可用 ID。

返回:
一组 ID。

getDefault

public static TimeZone getDefault()
获取此主机的默认 TimeZone。默认 TimeZone 的来源可能随实现的变化而变化。

返回:
默认的 TimeZone
另请参见:
setDefault(java.util.TimeZone)

setDefault

public static void setDefault(TimeZone zone)
设置由 getDefault 方法返回的 TimeZone。如果 zone 为 null,把默认值重设为第一次启动虚拟机时的最初值。

参数:
zone - 新的默认时区
另请参见:
getDefault()

hasSameRules

public boolean hasSameRules(TimeZone other)
如果此区域和另一个区域具有相同的规则和偏移量,也就是说,如果此区域只可能在 ID 上与另一个区域不同,则返回 true。如果其他区域为 null,则返回 false。

参数:
other - 要进行比较的 TimeZone 对象
返回:
如果其他区域不为 null,并且与此区域不同(可能只有 ID 不同),则返回 true
从以下版本开始:
1.2

clone

public Object clone()
创建此 TimeZone 的一个副本。

覆盖:
Object 中的 clone
返回:
TimeZone 的一个副本
另请参见:
Cloneable

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策