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: 如果格式器的 Calendar 是格里高里歷，則應用以下規則。
  
  • 對於格式化來說，如果網要字母的數量為 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 日。
  否則，則應用日曆系統特定的形式。對於格式化和解析，如果網要字母的數量為 4 或大於 4，則使用日曆特定的 long form。否則，則使用日曆特定的 short or abbreviated form。
• 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