java.text
类 SimpleDateFormat

java.lang.Object
  java.text.Format
      java.text.DateFormat
          java.text.SimpleDateFormat

所有已实现的接口：

Serializable, Cloneable

public class SimpleDateFormat
extends DateFormat

SimpleDateFormat 是一个以与语言环境相关的方式来格式化和分析日期的具体类。它允许进行格式化（日期 -> 文本）、分析（文本 -> 日期）和规范化。

SimpleDateFormat 使得可以选择任何用户定义的日期-时间格式的模式。但是，仍然建议通过 DateFormat 中的 getTimeInstance、getDateInstance 或 getDateTimeInstance 来新的创建日期-时间格式化程序。每一个这样的类方法都能够返回一个以默认格式模式初始化的日期/时间格式化程序。可以根据需要使用 applyPattern 方法来修改格式模式。有关使用这些方法的更多信息，请参阅 DateFormat。

日期和时间模式

日期和时间格式由日期和时间模式 字符串指定。在日期和时间模式字符串中，未加引号的字母 'A' 到 'Z' 和 'a' 到 'z' 被解释为模式字母，用来表示日期或时间字符串元素。文本可以使用单引号 (') 引起来，以免进行解释。"''" 表示单引号。所有其他字符均不解释；只是在格式化时将它们简单复制到输出字符串，或者在分析时与输入字符串进行匹配。

定义了以下模式字母（所有其他字符 'A' 到 'Z' 和 'a' 到 'z' 都被保留）：

字母	日期或时间元素	表示	示例
G	Era 标志符	Text	AD
y	年	Year	1996; 96
M	年中的月份	Month	July; Jul; 07
w	年中的周数	Number	27
W	月份中的周数	Number	2
D	年中的天数	Number	189
d	月份中的天数	Number	10
F	月份中的星期	Number	2
E	星期中的天数	Text	Tuesday; Tue
a	Am/pm 标记	Text	PM
H	一天中的小时数（0-23）	Number	0
k	一天中的小时数（1-24）	Number	24
K	am/pm 中的小时数（0-11）	Number	0
h	am/pm 中的小时数（1-12）	Number	12
m	小时中的分钟数	Number	30
s	分钟中的秒数	Number	55
S	毫秒数	Number	978
z	时区	General time zone	Pacific Standard Time; PST; GMT-08:00
Z	时区	RFC 822 time zone	-0800

模式字母通常是重复的，其数量确定其精确表示：

• Text: 对于格式化来说，如果模式字母的数量大于或等于 4，则使用完全形式；否则，在可用的情况下使用短形式或缩写形式。对于分析来说，两种形式都是可接受的，与模式字母的数量无关。
• Number: 对于格式化来说，模式字母的数量是最小的数位，如果数位不够，则用 0 填充以达到此数量。对于分析来说，模式字母的数量被忽略，除非必须分开两个相邻字段。
• Year: 对于格式化来说，如果模式字母的数量为 2，则年份截取为 2 位数,否则将年份解释为 number。

  对于分析来说，如果模式字母的数量大于 2，则年份照字面意义进行解释，而不管数位是多少。因此使用模式 "MM/dd/yyyy"，将 "01/11/12" 分析为公元 12 年 1 月 11 日。

  在分析缩写年份模式（"y" 或 "yy"）时，SimpleDateFormat 必须相对于某个世纪来解释缩写的年份。这通过将日期调整为 SimpleDateFormat 实例创建之前的 80 年和之后 20 年范围内来完成。例如，在 "MM/dd/yy" 模式下，如果 SimpleDateFormat 实例是在 1997 年 1 月 1 日创建的，则字符串 "01/11/12" 将被解释为 2012 年 1 月 11 日，而字符串 "05/04/64" 将被解释为 1964 年 5 月 4 日。在分析时，只有恰好由两位数字组成的字符串（如 Character.isDigit(char) 所定义的）被分析为默认的世纪。其他任何数字字符串将照字面意义进行解释，例如单数字字符串，3 个或更多数字组成的字符串，或者不都是数字的两位数字字符串（例如"-1"）。因此，在相同的模式下， "01/02/3" 或 "01/02/003" 解释为公元 3 年 1 月 2 日。同样，"01/02/-3" 分析为公元前 4 年 1 月 2 日。

• Month: 如果模式字母的数量为 3 或大于 3，则将月份解释为 text；否则解释为 number。
• General time zone: 如果时区有名称，则将它们解释为 text。对于表示 GMT 偏移值的时区，使用以下语法：

       GMTOffsetTimeZone:
               GMT Sign Hours : Minutes
       Sign: one of
               + -
       Hours:
               Digit
               Digit Digit
       Minutes:
               Digit Digit
       Digit: one of
               0 1 2 3 4 5 6 7 8 9

  Hours 必须在 0 到 23 之间，Minutes 必须在 00 到 59 之间。格式是与语言环境无关的，并且数字必须取自 Unicode 标准的 Basic Latin 块。

  对于分析来说，RFC 822 time zones 也是可接受的。

• RFC 822 time zone: 对于格式化来说，使用 RFC 822 4-digit 时区格式：

       RFC822TimeZone:
               Sign TwoDigitHours Minutes
       TwoDigitHours:
               Digit Digit

  TwoDigitHours 必须在 00 和 23 之间。其他定义请参阅 general time zones。

  对于分析来说，general time zones 也是可接受的。

SimpleDateFormat 还支持本地化日期和时间模式 字符串。在这些字符串中，以上所述的模式字母可以用其他与语言环境有关的模式字母来替换。SimpleDateFormat 不处理除模式字母之外的文本本地化；而由类的客户端来处理。

示例

以下示例显示了如何在美国语言环境中解释日期和时间模式。给定的日期和时间为美国太平洋时区的本地时间 2001-07-04 12:08:56。

日期和时间模式	结果
"yyyy.MM.dd G 'at' HH:mm:ss z"	2001.07.04 AD at 12:08:56 PDT
"EEE, MMM d, ''yy"	Wed, Jul 4, '01
"h:mm a"	12:08 PM
"hh 'o''clock' a, zzzz"	12 o'clock PM, Pacific Daylight Time
"K:mm a, z"	0:08 PM, PDT
"yyyyy.MMMMM.dd GGG hh:mm aaa"	02001.July.04 AD 12:08 PM
"EEE, d MMM yyyy HH:mm:ss Z"	Wed, 4 Jul 2001 12:08:56 -0700
"yyMMddHHmmssZ"	010704120856-0700
"yyyy-MM-dd'T'HH:mm:ss.SSSZ"	2001-07-04T12:08:56.235-0700

同步

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

另请参见：

Java Tutorial, Calendar, TimeZone, DateFormat, DateFormatSymbols, 序列化表格

嵌套类摘要

从类 java.text.DateFormat 继承的嵌套类/接口

DateFormat.Field

字段摘要

从类 java.text.DateFormat 继承的字段

AM_PM_FIELD, calendar, DATE_FIELD, DAY_OF_WEEK_FIELD, DAY_OF_WEEK_IN_MONTH_FIELD, DAY_OF_YEAR_FIELD, DEFAULT, ERA_FIELD, FULL, HOUR_OF_DAY0_FIELD, HOUR_OF_DAY1_FIELD, HOUR0_FIELD, HOUR1_FIELD, LONG, MEDIUM, MILLISECOND_FIELD, MINUTE_FIELD, MONTH_FIELD, numberFormat, SECOND_FIELD, SHORT, TIMEZONE_FIELD, WEEK_OF_MONTH_FIELD, WEEK_OF_YEAR_FIELD, YEAR_FIELD

构造方法摘要

SimpleDateFormat()
用默认的模式和默认语言环境的日期格式符号构造 SimpleDateFormat。

SimpleDateFormat(String pattern)
用给定的模式和默认语言环境的日期格式符号构造 SimpleDateFormat。

SimpleDateFormat(String pattern, DateFormatSymbols formatSymbols)
用给定的模式和日期符号构造 SimpleDateFormat。

SimpleDateFormat(String pattern, Locale locale)
用给定的模式和给定语言环境的默认日期格式符号构造 SimpleDateFormat。

方法摘要

void	applyLocalizedPattern(String pattern) 将给定的本地化模式字符串应用于此日期格式。
void	applyPattern(String pattern) 将给定模式字符串应用于此日期格式。
Object	clone() 创建此 SimpleDateFormat 的一个副本。
boolean	equals(Object obj) 比较给定对象与此 SimpleDateFormat 的相等性。
StringBuffer	format(Date date, StringBuffer toAppendTo, FieldPosition pos) 将给定的 Date 格式化为日期/时间字符串，并将结果追加到给定的 StringBuffer。
AttributedCharacterIterator	formatToCharacterIterator(Object obj) 格式化生成 AttributedCharacterIterator 的对象。
Date	get2DigitYearStart() 返回在 100 年周期内被解释的两位数字年份的开始日期。
DateFormatSymbols	getDateFormatSymbols() 获取此日期格式的日期和时间格式符号的一个副本。
int	hashCode() 返回此 SimpleDateFormat 对象的哈希码值。
Date	parse(String text, ParsePosition pos) 分析字符串的文本，生成 Date。
void	set2DigitYearStart(Date startDate) 设置 100 年周期的两位数年份，该年份将被解释为从用户指定的日期开始。
void	setDateFormatSymbols(DateFormatSymbols newFormatSymbols) 设置此日期格式的日期和时间格式符号。
String	toLocalizedPattern() 返回描述此日期格式的本地化模式字符串。
String	toPattern() 返回描述此日期格式的模式字符串。

从类 java.text.DateFormat 继承的方法

format, format, getAvailableLocales, getCalendar, getDateInstance, getDateInstance, getDateInstance, getDateTimeInstance, getDateTimeInstance, getDateTimeInstance, getInstance, getNumberFormat, getTimeInstance, getTimeInstance, getTimeInstance, getTimeZone, isLenient, parse, parseObject, setCalendar, setLenient, setNumberFormat, setTimeZone

从类 java.text.Format 继承的方法

format, parseObject

从类 java.lang.Object 继承的方法

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

SimpleDateFormat

public SimpleDateFormat()

用默认的模式和默认语言环境的日期格式符号构造 SimpleDateFormat。注：此构造方法可能不支持所有语言环境。要覆盖所有地区，请使用 DateFormat 类中的工厂方法。

SimpleDateFormat

public SimpleDateFormat(String pattern)

用给定的模式和默认语言环境的日期格式符号构造 SimpleDateFormat。注：此构造方法可能不支持所有语言环境。要覆盖所有语言环境，请使用 DateFormat 类中的工厂方法。

参数：

pattern - 描述日期和时间格式的模式

抛出：

NullPointerException - 如果给定的模式为 null

IllegalArgumentException - 如果给定的模式无效

SimpleDateFormat

public SimpleDateFormat(String pattern,
                        Locale locale)

用给定的模式和给定语言环境的默认日期格式符号构造 SimpleDateFormat。注：此构造方法可能不支持所有语言环境。要覆盖所有语言环境，请使用 DateFormat 类中的工厂方法。

参数：

pattern - 描述日期和时间格式的模式

locale - 其日期格式符号要被使用的语言环境

抛出：

NullPointerException - 如果给定的模式为 null

IllegalArgumentException - 如果给定的模式无效

SimpleDateFormat

public SimpleDateFormat(String pattern,
                        DateFormatSymbols formatSymbols)

用给定的模式和日期符号构造 SimpleDateFormat。

参数：

pattern - 描述日期和时间格式的模式

formatSymbols - 要用来格式化的日期格式符号

抛出：

NullPointerException - 如果给定的模式或 formatSymbols 为 null

IllegalArgumentException - 如果给定的模式无效

方法详细信息

set2DigitYearStart

public void set2DigitYearStart(Date startDate)

设置 100 年周期的两位数年份，该年份将被解释为从用户指定的日期开始。

参数：

startDate - 在分析时，两位数年份将被置于 startDate 和 startDate + 100 years 之间的范围内。

从以下版本开始：

1.2

另请参见：

get2DigitYearStart()

get2DigitYearStart

public Date get2DigitYearStart()

返回在 100 年周期内被解释的两位数字年份的开始日期。

返回：

在 100 年周期内被分析的两位数字年份的开始日期

从以下版本开始：

1.2

另请参见：

set2DigitYearStart(java.util.Date)

format

public StringBuffer format(Date date,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

将给定的 Date 格式化为日期/时间字符串，并将结果追加到给定的 StringBuffer。

指定者：

类 DateFormat 中的 format

参数：

date - 要被格式化为日期-时间字符串的日期-时间值。

toAppendTo - 新的日期-时间文本被追加的位置。

pos - 格式化的位置。输入时：如果需要，是一个对齐字段。输出时：为对齐字段的偏移量。

返回：

格式化的日期-时间字符串。

抛出：

NullPointerException - 如果给定的日期为 null

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)

格式化生成 AttributedCharacterIterator 的对象。可以使用返回的 AttributedCharacterIterator 来生成所得的字符串，以及确定关于所得字符串的信息。

AttributedCharacterIterator 的每个属性键都是 DateFormat.Field 类型的，对应的属性值与属性键相同。

覆盖：

类 Format 中的 formatToCharacterIterator

参数：

obj - 要格式化的对象

返回：

描述格式化的值的 AttributedCharacterIterator。

抛出：

NullPointerException - 如果 obj 为 null。

IllegalArgumentException - 如果 Format 不能格式化给定的对象，或者 Format 的模式字符串无效。

从以下版本开始：

1.4

parse

public Date parse(String text,
                  ParsePosition pos)

分析字符串的文本，生成 Date。

此方法试图分析从 pos 给定的索引处开始的文本。如果分析成功，则将 pos 的索引更新为所用最后一个字符后面的索引（不必对直到字符串结尾的所有字符进行分析），并返回分析得到的日期。更新后的 pos 可以用来指示下次调用此方法的起始点。如果发生错误，则不更改 pos 的索引，并将 pos 的错误索引设置为发生错误处的字符索引，并且返回 null。

指定者：

类 DateFormat 中的 parse

参数：

text - 应该分析其中一部分的 String。

pos - 具有以上所述的索引和错误索引信息的 ParsePosition 对象。

返回：

从字符串进行分析的 Date。如果发生错误，则返回 null。

抛出：

NullPointerException - 如果 text 或 pos 为 null。

另请参见：

DateFormat.setLenient(boolean)

toPattern

public String toPattern()

返回描述此日期格式的模式字符串。

返回：

描述此日期格式的模式字符串。

toLocalizedPattern

public String toLocalizedPattern()

返回描述此日期格式的本地化模式字符串。

返回：

描述此日期格式的本地化模式字符串。

applyPattern

public void applyPattern(String pattern)

将给定模式字符串应用于此日期格式。

参数：

pattern - 此日期格式的新的日期和时间模式

抛出：

NullPointerException - 如果给定的模式为 null

IllegalArgumentException - 如果给定的模式无效

applyLocalizedPattern

public void applyLocalizedPattern(String pattern)

将给定的本地化模式字符串应用于此日期格式。

参数：

pattern - 要被映射到此格式的新的日期和时间格式模式的字符串

抛出：

NullPointerException - 如果给定的模式为 null

IllegalArgumentException - 如果给定的模式无效

getDateFormatSymbols

public DateFormatSymbols getDateFormatSymbols()

获取此日期格式的日期和时间格式符号的一个副本。

返回：

此日期格式的日期和时间格式符号

另请参见：

setDateFormatSymbols(java.text.DateFormatSymbols)

setDateFormatSymbols

public void setDateFormatSymbols(DateFormatSymbols newFormatSymbols)

设置此日期格式的日期和时间格式符号。

参数：

newFormatSymbols - 新的日期和时间格式符号

抛出：

NullPointerException - 如果给定的 newFormatSymbols 为 null

另请参见：

getDateFormatSymbols()

clone

public Object clone()

创建此 SimpleDateFormat 的一个副本。此复制也将克隆格式的日期格式符号。

覆盖：

类 DateFormat 中的 clone

返回：

此 SimpleDateFormat 的一个克隆

另请参见：

Cloneable

hashCode

public int hashCode()

返回此 SimpleDateFormat 对象的哈希码值。

覆盖：

类 DateFormat 中的 hashCode

返回：

此 SimpleDateFormat 对象的哈希码值。

另请参见：

Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)

比较给定对象与此 SimpleDateFormat 的相等性。

覆盖：

类 DateFormat 中的 equals

参数：

obj - 要与之比较的引用对象。

返回：

true 如果给定对象与此 SimpleDateFormat 相等

另请参见：

Object.hashCode(), Hashtable