JavaTM 2 Platform
Standard Ed. 5.0

java.text
类 DateFormat

java.lang.Object
  继承者 java.text.Format
      继承者 java.text.DateFormat
所有已实现的接口:
Serializable, Cloneable
直接已知子类:
SimpleDateFormat

public abstract class DateFormat
extends Format

DateFormat 是日期/时间格式化子类的抽象类,它以与语言无关的方式格式化并分析日期或时间。日期/时间格式化子类(如 SimpleDateFormat)允许进行格式化(也就是日期 -> 文本)、分析(文本-> 日期)和标准化。将日期表示为 Date 对象,或者表示为从 GMT(格林尼治标准时间)1970 年,1 月 1 日 00:00:00 这一刻开始的毫秒数。

DateFormat 提供了很多类方法,以获得基于默认或给定语言环境和多种格式化风格的默认日期/时间 Formatter。格式化风格包括 FULL、LONG、MEDIUM 和 SHORT。方法描述中提供了使用这些风格的更多细节和示例。

DateFormat 可帮助进行格式化并分析任何语言环境的日期。对于月、星期,甚至日历格式(阴历和阳历),其代码可完全与语言环境的约定无关。

要格式化一个当前语言环境下的日期,可使用某个静态工厂方法:

  myString = DateFormat.getDateInstance().format(myDate);
 

如果格式化多个日期,那么获得该格式并多次使用它是更为高效的做法,这样系统就不必多次获取有关环境语言和国家/地区约定的信息了。

  DateFormat df = DateFormat.getDateInstance();
  for (int i = 0; i < myDate.length; ++i) {
    output.println(df.format(myDate[i]) + "; ");
  }
 

要格式化不同语言环境的日期,可在 getDateInstance() 的调用中指定它。

  DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE);
 

还可使用 DateFormat 进行分析。

  myDate = df.parse(myString);
 

使用 getDateInstance 来获得该国家/地区的标准日期格式。另外还提供了一些其他静态工厂方法。使用 getTimeInstance 可获得该国家/地区的时间格式。使用 getDateTimeInstance 可获得日期和时间格式。可以将不同选项传入这些工厂方法,以控制结果的长度(从 SHORT 到 MEDIUM 到 LONG 再到 FULL)。确切的结果取决于语言环境,但是通常:

如果愿意,还可以在格式上设置时区。如果想对格式化或分析施加更多的控制(或者给予用户更多的控制),可以尝试将从工厂方法所获得的 DateFormat 强制转换为 SimpleDateFormat。这适用于大多数国家/地区;只是要记住将其放入一个 try 代码块中,以防遇到特殊的格式。

还可以使用借助 ParsePosition 和 FieldPosition 的分析和格式化方法形式来

同步

DateFormat 不是同步的。建议为每个线程创建独立的格式实例。如果多个线程同时访问一个格式,则它必须保持外部同步。

另请参见:
Format, NumberFormat, SimpleDateFormat, Calendar, GregorianCalendar, TimeZone, 序列化表格

嵌套类摘要
static class DateFormat.Field
          定义了各种常量,这些常量用作 DateFormat.formatToCharacterIterator 所返回的 AttributedCharacterIterator 中的属性键和 FieldPosition 中的字段标识符。
 
字段摘要
static int AM_PM_FIELD
          用于对齐 AM_PM 字段的有用常量。
protected  Calendar calendar
          DateFormat 使用 calendar 来生成实现日期和时间格式化所需的时间字段值。
static int DATE_FIELD
          用于对齐 DATE 字段的有用常量。
static int DAY_OF_WEEK_FIELD
          用于对齐 DAY_OF_WEEK 字段的有用常量。
static int DAY_OF_WEEK_IN_MONTH_FIELD
          用于对齐 DAY_OF_WEEK_IN_MONTH 字段的有用常量。
static int DAY_OF_YEAR_FIELD
          用于对齐 DAY_OF_YEAR 字段的有用常量。
static int DEFAULT
          用于默认模式的常量。
static int ERA_FIELD
          用于对齐 ERA 字段的有用常量。
static int FULL
          用于 FULL 模式的常量。
static int HOUR_OF_DAY0_FIELD
          用于对齐从 0 开始的 HOUR_OF_DAY 字段的有用常量。
static int HOUR_OF_DAY1_FIELD
          用于对齐从 1 开始的 HOUR_OF_DAY 字段的有用常量。
static int HOUR0_FIELD
          用于对齐从 0 开始的 HOUR 字段的有用常量。
static int HOUR1_FIELD
          用于对齐从 1 开始的 HOUR 字段的有用常量。
static int LONG
          用于 LONG 模式的常量。
static int MEDIUM
          用于 MEDIUM 模式的常量。
static int MILLISECOND_FIELD
          用于对齐 MILLISECOND 字段的有用常量。
static int MINUTE_FIELD
          用于对齐 MINUTE 字段的有用常量。
static int MONTH_FIELD
          用于对齐 MONTH 字段的有用常量。
protected  NumberFormat numberFormat
          数字 formatter,DateFormat 用其来格式化日期和时间中的数字。
static int SECOND_FIELD
          用于对齐 SECOND 字段的有用常量。
static int SHORT
          用于 SHORT 模式的常量。
static int TIMEZONE_FIELD
          用于对齐 TIMEZONE 字段的有用常量。
static int WEEK_OF_MONTH_FIELD
          用于对齐 WEEK_OF_MONTH 字段的有用常量。
static int WEEK_OF_YEAR_FIELD
          用于对齐 WEEK_OF_YEAR 字段的有用常量。
static int YEAR_FIELD
          用于对齐 YEAR 字段的有用常量。
 
构造方法摘要
protected DateFormat()
          创建一个新的 DateFormat。
 
方法摘要
 Object clone()
          重写 Cloneable
 boolean equals(Object obj)
          重写 equals
 String format(Date date)
          将一个 Date 格式化为日期/时间字符串。
abstract  StringBuffer format(Date date, StringBuffer toAppendTo, FieldPosition fieldPosition)
          将一个 Date 格式化为日期/时间字符串。
 StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition fieldPosition)
          重写 Format。
static Locale[] getAvailableLocales()
          返回所有语言环境的数组,此类的 get*Instance 方法可以为其返回已本地化的实例。
 Calendar getCalendar()
          获得与此日期/时间 formatter 关联的日历。
static DateFormat getDateInstance()
          获得日期 formatter,该 formatter 具有默认语言环境的默认格式化风格。
static DateFormat getDateInstance(int style)
          获得日期 formatter,该 formatter 具有默认语言环境的给定格式化风格。
static DateFormat getDateInstance(int style, Locale aLocale)
          获得日期 formatter,该 formatter 具有给定语言环境的给定格式化风格。
static DateFormat getDateTimeInstance()
          获得日期/时间 formatter,该 formatter 具有默认语言环境的默认格式化风格。
static DateFormat getDateTimeInstance(int dateStyle, int timeStyle)
          获得日期/时间 formatter,该 formatter 具有默认语言环境的给定日期和时间格式化风格。
static DateFormat getDateTimeInstance(int dateStyle, int timeStyle, Locale aLocale)
          获得日期/时间 formatter,该 formatter 具有给定语言环境的给定格式化风格。
static DateFormat getInstance()
          获得为日期和时间使用 SHORT 风格的默认日期/时间 formatter。
 NumberFormat getNumberFormat()
          获得此日期/时间 formatter 用于格式化和分析时间的数字 formatter。
static DateFormat getTimeInstance()
          获得时间 formatter,该 formatter 具有默认语言环境的默认格式化风格。
static DateFormat getTimeInstance(int style)
          获得时间 formatter,该 formatter 具有默认语言环境的给定格式化风格。
static DateFormat getTimeInstance(int style, Locale aLocale)
          获得时间 formatter,该 formatter 具有给定语言环境的给定格式化风格。
 TimeZone getTimeZone()
          获得时区。
 int hashCode()
          重写 hashCode
 boolean isLenient()
          告知日期/时间分析是否为不严格的。
 Date parse(String source)
          从给定字符串的开始分析文本,以生成一个日期。
abstract  Date parse(String source, ParsePosition pos)
          根据给定的分析位置开始分析日期/时间字符串。
 Object parseObject(String source, ParsePosition pos)
          分析字符串中的文本,以生成一个 Date
 void setCalendar(Calendar newCalendar)
          设置此日期格式所使用的日历。
 void setLenient(boolean lenient)
          指定日期/时间分析是否不严格。
 void setNumberFormat(NumberFormat newNumberFormat)
          允许用户设置数字 formatter。
 void setTimeZone(TimeZone zone)
          为此 DateFormat 对象的日历设置时区。
 
从类 java.text.Format 继承的方法
format, formatToCharacterIterator, parseObject
 
从类 java.lang.Object 继承的方法
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

字段详细信息

calendar

protected Calendar calendar
DateFormat 使用 calendar 来生成实现日期和时间格式化所需的时间字段值。子类应将此 calendar 初始化为适合于与此 DateFormat 关联的语言环境的日历。


numberFormat

protected NumberFormat numberFormat
数字 formatter,DateFormat 用其来格式化日期和时间中的数字。子类应将此 numberFormat 初始化为适合于与此 DateFormat 关联的语言环境的数字格式。


ERA_FIELD

public static final int ERA_FIELD
用于对齐 ERA 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

YEAR_FIELD

public static final int YEAR_FIELD
用于对齐 YEAR 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

MONTH_FIELD

public static final int MONTH_FIELD
用于对齐 MONTH 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

DATE_FIELD

public static final int DATE_FIELD
用于对齐 DATE 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

HOUR_OF_DAY1_FIELD

public static final int HOUR_OF_DAY1_FIELD
用于对齐从 1 开始的 HOUR_OF_DAY 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。HOUR_OF_DAY1_FIELD 用于从 1 开始的 24 小时时钟。例如,23:59 + 01:00 的结果是 24:59。

另请参见:
常量字段值

HOUR_OF_DAY0_FIELD

public static final int HOUR_OF_DAY0_FIELD
用于对齐从 0 开始的 HOUR_OF_DAY 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。HOUR_OF_DAY0_FIELD 用于从 0 开始的 24 小时时钟。例如,23:59 + 01:00 的结果是 00:59。

另请参见:
常量字段值

MINUTE_FIELD

public static final int MINUTE_FIELD
用于对齐 MINUTE 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

SECOND_FIELD

public static final int SECOND_FIELD
用于对齐 SECOND 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

MILLISECOND_FIELD

public static final int MILLISECOND_FIELD
用于对齐 MILLISECOND 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

DAY_OF_WEEK_FIELD

public static final int DAY_OF_WEEK_FIELD
用于对齐 DAY_OF_WEEK 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

DAY_OF_YEAR_FIELD

public static final int DAY_OF_YEAR_FIELD
用于对齐 DAY_OF_YEAR 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

DAY_OF_WEEK_IN_MONTH_FIELD

public static final int DAY_OF_WEEK_IN_MONTH_FIELD
用于对齐 DAY_OF_WEEK_IN_MONTH 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

WEEK_OF_YEAR_FIELD

public static final int WEEK_OF_YEAR_FIELD
用于对齐 WEEK_OF_YEAR 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

WEEK_OF_MONTH_FIELD

public static final int WEEK_OF_MONTH_FIELD
用于对齐 WEEK_OF_MONTH 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

AM_PM_FIELD

public static final int AM_PM_FIELD
用于对齐 AM_PM 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

HOUR1_FIELD

public static final int HOUR1_FIELD
用于对齐从 1 开始的 HOUR 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。HOUR1_FIELD 用于从 1 开始的 12 小时时钟。例如,11:30 PM + 1 小时的结果是 12:30 AM。

另请参见:
常量字段值

HOUR0_FIELD

public static final int HOUR0_FIELD
用于对齐从 0 开始的 HOUR 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。HOUR0_FIELD 用于从 0 开始的 12 小时时钟。例如,11:30 PM + 1 小时的结果是 00:30 AM。

另请参见:
常量字段值

TIMEZONE_FIELD

public static final int TIMEZONE_FIELD
用于对齐 TIMEZONE 字段的有用常量。用于日期/时间格式化的 FieldPosition 中。

另请参见:
常量字段值

FULL

public static final int FULL
用于 FULL 模式的常量。

另请参见:
常量字段值

LONG

public static final int LONG
用于 LONG 模式的常量。

另请参见:
常量字段值

MEDIUM

public static final int MEDIUM
用于 MEDIUM 模式的常量。

另请参见:
常量字段值

SHORT

public static final int SHORT
用于 SHORT 模式的常量。

另请参见:
常量字段值

DEFAULT

public static final int DEFAULT
用于默认模式的常量。其值为 MEDIUM。

另请参见:
常量字段值
构造方法详细信息

DateFormat

protected DateFormat()
创建一个新的 DateFormat。

方法详细信息

format

public final StringBuffer format(Object obj,
                                 StringBuffer toAppendTo,
                                 FieldPosition fieldPosition)
重写 Format。将时间对象格式化为时间字符串。时间对象的示例有以毫秒表示的时间值和 Date 对象。

指定者:
Format 中的 format
参数:
obj - 必须为 Number 或 Date。
toAppendTo - 用于返回的时间字符串的字符串缓冲区。
fieldPosition - 跟踪返回字符串中字段的位置。输入时:如果需要,是一个对齐字段。输出时:对齐字段的偏移量。例如,在给定时间文本 "1996.07.10 AD at 15:08:56 PDT" 的情况下,如果给定的 fieldPosition 是 DateFormat.YEAR_FIELD,则将 fieldPosition 的开始索引和结束索引分别设置为 0 和 4。注意,如果在一个模式中多次出现同一时间字段,则为第一次出现的该时间字段设置 fieldPosition。例如,使用模式 "h a z (zzzz)" 和对齐字段 DateFormat.TIMEZONE_FIELD 将某个 Date 格式化为时间字符串 "1 PM PDT (Pacific Daylight Time)" 时,针对时区模式字符 'z' 的首个匹配项,将 fieldPosition 的开始索引和结束索引分别设置为 5 和 8。
返回:
已格式化的时间字符串。
另请参见:
Format

format

public abstract StringBuffer format(Date date,
                                    StringBuffer toAppendTo,
                                    FieldPosition fieldPosition)
将一个 Date 格式化为日期/时间字符串。

参数:
date - 要格式化为日期/时间字符串的 Date。
toAppendTo - 用于返回的日期/时间字符串的字符串缓冲区。
fieldPosition - 跟踪返回字符串中字段的位置。输入时:如果需要,是一个对齐字段。输出时:对齐字段的偏移量。例如,在给定时间文本 "1996.07.10 AD at 15:08:56 PDT" 的情况下,如果给定的 fieldPosition 是 DateFormat.YEAR_FIELD,则将 fieldPosition 的开始索引和结束索引分别设置为 0 和 4。注意,如果在一个模式中多次出现同一时间字段,则为该时间字段的首个匹配项设置 fieldPosition。例如,使用模式 "h a z (zzzz)" 和对齐字段 DateFormat.TIMEZONE_FIELD 将某个 Date 格式化为时间字符串 "1 PM PDT (Pacific Daylight Time)" 时,针对时区模式字符 'z' 的首个匹配项,将 fieldPosition 的开始索引和结束索引分别设置为 5 和 8。
返回:
已格式化的日期/时间字符串。

format

public final String format(Date date)
将一个 Date 格式化为日期/时间字符串。

参数:
date - 要格式化为时间字符串的时间值。
返回:
已格式化的时间字符串。

parse

public Date parse(String source)
           throws ParseException
从给定字符串的开始分析文本,以生成一个日期。该方法不使用给定字符串的整个文本。

有关日期分析的更多信息,请参阅 parse(String, ParsePosition) 方法。

参数:
source - 一个 String,应从其开始处进行分析。
返回:
分析字符串得到的 Date
抛出:
ParseException - 如果无法分析指定字符串的开始处。

parse

public abstract Date parse(String source,
                           ParsePosition pos)
根据给定的分析位置开始分析日期/时间字符串。例如,时间文本 "07/10/96 4:5 PM, PDT" 会分析成等同于 Date(837039928046) 的 Date。

在默认情况下,进行的分析是不严格的:如果输入的形式不是此对象的格式化方法使用的形式,但仍可作为日期进行分析,则分析将获得成功。客户机可能通过调用 setLenient(false) 来强调严格遵守该格式。

参数:
source - 要分析的日期/时间字符串
pos - 输入时,是开始进行分析的位置;输出时,是分析终止的位置,如果分析失败,则为开始位置。
返回:
一个 Date,如果无法分析输入,则为 null
另请参见:
setLenient(boolean)

parseObject

public Object parseObject(String source,
                          ParsePosition pos)
分析字符串中的文本,以生成一个 Date

该方法试图从 pos 所给定的索引处开始分析文本。如果分析成功,则将 pos 的索引更新为所用最后一个字符后面的索引(分析过程不一定使用到字符串末尾为止的所有字符),并返回分析得到的日期。可以使用更新后的 pos 指示下一次调用此方法的开始点。如果发生错误,则不更改 pos 的索引,并将 pos 的错误索引设置为发生错误处的字符索引,并且返回 null。

有关日期分析的更多信息,请参阅 parse(String, ParsePosition) 方法。

指定者:
Format 中的 parseObject
参数:
source - 一个 String,应分析其中的部分内容。
pos - 具有索引和上述错误索引信息的 ParsePosition 对象。
返回:
分析字符串得到的 Date。在出现错误的情况下返回 null。
抛出:
NullPointerException - 如果 pos 为 null。

getTimeInstance

public static final DateFormat getTimeInstance()
获得时间 formatter,该 formatter 具有默认语言环境的默认格式化风格。

返回:
时间 formatter。

getTimeInstance

public static final DateFormat getTimeInstance(int style)
获得时间 formatter,该 formatter 具有默认语言环境的给定格式化风格。

参数:
style - 给定的格式化风格例如,SHORT 用于 US 语言环境中的 "h:mm a"。
返回:
时间 formatter。

getTimeInstance

public static final DateFormat getTimeInstance(int style,
                                               Locale aLocale)
获得时间 formatter,该 formatter 具有给定语言环境的给定格式化风格。

参数:
style - 给定的格式化风格例如,SHORT 用于 US 语言环境中的 "h:mm a"。
aLocale - 给定的语言环境。
返回:
时间 formatter。

getDateInstance

public static final DateFormat getDateInstance()
获得日期 formatter,该 formatter 具有默认语言环境的默认格式化风格。

返回:
日期 formatter。

getDateInstance

public static final DateFormat getDateInstance(int style)
获得日期 formatter,该 formatter 具有默认语言环境的给定格式化风格。

参数:
style - 给定的格式化风格例如,SHORT 用于 US 语言环境中的 "M/d/yy"。
返回:
日期 formatter。

getDateInstance

public static final DateFormat getDateInstance(int style,
                                               Locale aLocale)
获得日期 formatter,该 formatter 具有给定语言环境的给定格式化风格。

参数:
style - 给定的格式化风格例如,SHORT 用于 US 语言环境中的 "M/d/yy"。
aLocale - 给定的语言环境。
返回:
日期 formatter。

getDateTimeInstance

public static final DateFormat getDateTimeInstance()
获得日期/时间 formatter,该 formatter 具有默认语言环境的默认格式化风格。

返回:
日期/时间 formatter。

getDateTimeInstance

public static final DateFormat getDateTimeInstance(int dateStyle,
                                                   int timeStyle)
获得日期/时间 formatter,该 formatter 具有默认语言环境的给定日期和时间格式化风格。

参数:
dateStyle - 给定的日期格式化风格。例如,SHORT 用于 US 语言环境中的 "M/d/yy"。
timeStyle - 给定的时间格式化风格。例如,SHORT 用于 US 语言环境中的 "h:mm a"。
返回:
日期/时间 formatter。

getDateTimeInstance

public static final DateFormat getDateTimeInstance(int dateStyle,
                                                   int timeStyle,
                                                   Locale aLocale)
获得日期/时间 formatter,该 formatter 具有给定语言环境的给定格式化风格。

参数:
dateStyle - 给定的日期格式化风格。
timeStyle - 给定的时间格式化风格。
aLocale - 给定的语言环境。
返回:
日期/时间 formatter。

getInstance

public static final DateFormat getInstance()
获得为日期和时间使用 SHORT 风格的默认日期/时间 formatter。


getAvailableLocales

public static Locale[] getAvailableLocales()
返回所有语言环境的数组,此类的 get*Instance 方法可以为其返回已本地化的实例。返回的数组至少必须包含一个等于 Locale.USLocale 实例。

返回:
一个语言环境数组,为这些语言环境提供了已本地化的 DateFormat 实例。

setCalendar

public void setCalendar(Calendar newCalendar)
设置此日期格式所使用的日历。最初为指定或默认的语言环境使用默认的日历。

参数:
newCalendar - 该日期格式所使用的新 Calendar

getCalendar

public Calendar getCalendar()
获得与此日期/时间 formatter 关联的日历。

返回:
与此日期/时间 formatter 关联的日历。

setNumberFormat

public void setNumberFormat(NumberFormat newNumberFormat)
允许用户设置数字 formatter。

参数:
newNumberFormat - 给定的新 NumberFormat。

getNumberFormat

public NumberFormat getNumberFormat()
获得此日期/时间 formatter 用于格式化和分析时间的数字 formatter。

返回:
此日期/时间 formatter 使用的数字 formatter。

setTimeZone

public void setTimeZone(TimeZone zone)
为此 DateFormat 对象的日历设置时区。

参数:
zone - 给定的新时区。

getTimeZone

public TimeZone getTimeZone()
获得时区。

返回:
与此 DateFormat 的日历相关联的时区。

setLenient

public void setLenient(boolean lenient)
指定日期/时间分析是否不严格。进行不严格分析时,分析程序可能使用启发式的方法来解释与此对象的格式不精确匹配的输入。进行严格分析时,输入必须匹配此对象的格式。

参数:
lenient - 为 true 时,分析过程是不严格的
另请参见:
Calendar.setLenient(boolean)

isLenient

public boolean isLenient()
告知日期/时间分析是否为不严格的。


hashCode

public int hashCode()
重写 hashCode

覆盖:
Object 中的 hashCode
返回:
此对象的一个哈希码值。
另请参见:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)
重写 equals

覆盖:
Object 中的 equals
参数:
obj - 要与之比较的引用对象。
返回:
如果此对象与 obj 参数相同,则返回 true;否则返回 false
另请参见:
Object.hashCode(), Hashtable

clone

public Object clone()
重写 Cloneable

覆盖:
Format 中的 clone
返回:
此实例的一个克隆。
另请参见:
Cloneable

JavaTM 2 Platform
Standard Ed. 5.0

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

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