DateTimeFormatter 類別

定義

[Android.Runtime.Register("java/time/format/DateTimeFormatter", ApiSince=26, DoNotGenerateAcw=true)]
public sealed class DateTimeFormatter : Java.Lang.Object

[<Android.Runtime.Register("java/time/format/DateTimeFormatter", ApiSince=26, DoNotGenerateAcw=true)>]
type DateTimeFormatter = class
    inherit Object

繼承

Object

Object

DateTimeFormatter

屬性

RegisterAttribute

備註

列印和剖析日期時間物件的格式器。

這個類別提供列印和剖析的主要應用程式進入點，並提供常見的實DateTimeFormatter作：<ul<>li>使用預先定義的常數，<#ISO_LOCAL_DATE例如 /li li 使用模式字母<uuuu-MMM-dd，例如 /li<>>li>使用本地化樣式，例如 long 或<medium /li><></ul>

更複雜的格式器是由 DateTimeFormatterBuilder DateTimeFormatterBuilder提供。

主要日期時間類別提供兩種方法-一個用於格式化，format(DateTimeFormatter formatter)另一個用於剖析。 parse(CharSequence text, DateTimeFormatter formatter)

例如： <blockquote>

LocalDate date = LocalDate.now();
             String text = date.format(formatter);
             LocalDate parsedDate = LocalDate.parse(text, formatter);

</blockquote>

除了格式之外，還可以使用所需的Locale、Chronology、ZoneId和 DecimalStyle 來建立格式器。

方法 #withLocale withLocale 會傳回覆寫地區設定的新格式器。 地區設定會影響格式化和剖析的某些層面。 例如， #ofLocalizedDate ofLocalizedDate 提供使用地區設定特定日期格式的格式器。

方法會 #withChronology withChronology 傳回覆寫時序表的新格式器。 如果覆寫，日期時間值會在格式化之前轉換成時序。 在剖析日期時間值時，會在傳回日期時間值之前，轉換為時序。

方法會 #withZone withZone 傳回覆寫區域的新格式器。 如果覆寫，日期時間值會在格式化之前，使用要求的 ZoneId 轉換為 ZonedDateTime。 在剖析期間，會在傳回值之前套用 ZoneId。

方法會 #withDecimalStyle withDecimalStyle 傳回覆 寫 DecimalStyle的新格式器。 DecimalStyle 符號用於格式化和剖析。

某些應用程式可能需要使用較舊的 Format java.text.Format 類別進行格式設定。 方法 #toFormat() 會傳回的實作 java.text.Format。

<h2 id=“predefined”>Predefined Formatters/h2><table class=“striped” style=“text-align：left”><caption>Predefined Formatters<</caption><thead><tr><th scope=“col”>Formatter</<>th scope=“col”>Description</th th scope=“col”>Example</<>th<>/tr<>/thead<>tbody<>tr><th scope=“row”>#ofLocalizedDate ofLocalizedDate(dateStyle)</thtd> Formatter with date style from the locale /td td>>< '2011-12-03'</td></tr><><th scope=“row”/th td Formatter with time style from the locale </td>>< td td> '10：15：30'</td<>/tr<>><tr th scope=“row”><#ofLocalizedTime ofLocalizedTime(timeStyle)><#ofLocalizedDateTime ofLocalizedDateTime(dateTimeStyle)/th<>><td> Formatter with a style for the locale<</td td td>><><'3 Jun 2008 11：05：30'</td></tr<>><th scope=“row”><#ofLocalizedDateTime ofLocalizedDateTime(dateStyle,timeStyle)/th<>td> Formatter with datee </td td td>>< '3 Jun 2008 11：05'</td<>/tr<><>th scope=“row”><#BASIC_ISO_DATE/th><td>Basic ISO date </td td'20111203<>>'</td<>/tr tr><><th scope=“row”>#ISO_LOCAL_DATE</th><td> ISO Local Date </td'2011-12-03<>>'</td></tr tr<<>>th scope=“row”/th td> ISO Date with offset /td td td'2011-12-03<>>+01：00'</td></tr tr<>><th scope=“row”#ISO_OFFSET_DATE#ISO_DATE><<>/th<<>>td> ISO Date with or without offset <</td td><td '>2011-12-03+01:00';'2011-12-03'</td<>/tr th><><scope=“row”><#ISO_LOCAL_TIME/th<>td> Time without offset </td td'10<>>：15：30'</td<>/tr th>><<scope=“row”><#ISO_OFFSET_TIME/th<>td> Time with offset </td td'10><>：15：30+01：00'</td<>/tr tr<>><th scope=“row”>/th><td> 時間，不含位移 </td td'10><>：15：30+01：00';#ISO_TIME<'10：15：30'</td<>/tr><th><scope=“row”>#ISO_LOCAL_DATE_TIME</th><td> ISO 本地日期和時間 </td td'2011-12-03T10><>：15：30'</td></tr<><>th scope=“row”#ISO_OFFSET_DATE_TIME<>/th><td> Date Time with Offset </td td'2011-12-03T10><>：15：30+01：00'</td></tr tr th><><scope=“row”><#ISO_ZONED_DATE_TIME/th<>td> Zoned Date Time </td<>td'2011-12-03T10>：15：30+01：00[Europe/Paris]'/<td></tr tr><><th scope=“row”>#ISO_DATE_TIME</th><td> 具有 ZoneId </td td'2011-12-03T10>><：15：30+01：00[Europe/Paris]'</td></tr tr><th><scope=“row”/>#ISO_ORDINAL_DATE<th><td> Year and day of year </td td'2012-337<>>'</td<>/tr tr><th><scope=“row”<#ISO_WEEK_DATE>/th><td> Year and Week </td td'2012-W48-6><>'</td></tr><<>th scope=“row”#ISO_INSTANT<>/th><td> Instant </td td'2011-12-03T10><>：15：30Z'</td></tr tr><<>th scope=“row”>#RFC_1123_DATE_TIME</th><td> RFC 1123 / RFC 822 </td td'Tue>><， 3 Jun 2008 11：05：30 GMT'</td<>/tr<>/tbody></table>

<h2 id=“patterns”>Patterns for Formatting and Parsing</h2> Patterns is based a simple sequence of letters and symbols. 模式是用來使用 #ofPattern(String) 和 #ofPattern(String, Locale) 方法來建立 Formatter。 例如， "d MMM uuuu" 會將 2011-12-03 格式設定為 '3 Dec 2011'. 從模式建立的格式器可以視需要使用多次，它是固定的，而且是安全線程的。

例如： <blockquote>

LocalDate date = LocalDate.now();
             DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
             String text = date.format(formatter);
             LocalDate parsedDate = LocalDate.parse(text, formatter);

</blockquote>

所有字母 'A' 到 'Z' 和 'a' 到 'z' 都會保留為模式字母。 已定義下列模式字母：<table class=“striped”><caption>Pattern Letters and Symbols</caption><thead<>tr><th scope=“col>”Symbol<></th scope=“col”Meaning</th scope=“col”>>Presentation</th scope=>“col”Examples</><><th></thead><tbody><tr><th scope=“row”>G</th><td era</td>><td>text</td td>><AD;西元;A</td><tr><th scope=“row”>u</th><td>year<<><>/td><>2004; 04/<>td tr th scope=“row”>y</th><td>year-of-era</><><td year/>><td td 2004; 04<</td<>><tr><th scope=“row”>D</th><td>day-of-year</td td number</td><>><td>189</td><tr><th scope=“row”>M/L</th<>td>month-of-year</td td>><number/text</td td><td>7; 07;七月;七月;J</td><tr><th scope=“row”>d</th><td>day-of-month</td td><>number</<>>td td 10</td<>tr><th scope=“row”>g</th<>>td modified-julian-day</td<><> td number/td<>>td 2451334</td>

<tr><th scope=“row”>Q/q</th><td>quarter-of-year</td td>><number/text</td td>><3; 03;Q3;3rd quarter</td><tr><th scope=“row”>Y</th<>td>week-based-year</td>>><<>< 1996; 96</td<>tr><th scope=“row”>w</><th td>week-of-week-of-year</>><td number</><>td td 27</td<>tr><th scope=“row”>W</th><td>week-of-month</td><td>number</td><td>4</td><tr><th scope=“row”>E</th><td>day-of-week</td td<>>text</td td td><>Tue;星期二;T</td><tr><th scope=“row”>e/c</th><td>localized day-of-week</td td>><number/text</td td>><2; 02;星期二;星期二;T</td><tr><th scope=“row”>F</th><td>day-of-week-in-month</td td><>number</td td>><3</td>

<tr><th scope=“row”>a</th><td>am-pm-of-day</td><>td text</td><<><> tr><th scope=“row”>h</th><td>clock-hour-of-am-pm （1-1-1 12）</td<>td>number</td><td>12</td><tr><th scope=“row”>K</th><td>hour-of-am-pm （0-11）</td><>td number</td td><>0</td><tr><th scope=“row”>k/th><td>clock-hour-of-day< （1-24）</td td>><number</td td>24</td><>

<tr><th scope=“row”>H</th><td>hour-of-day （0-23）</td>><td number</<>>td td 0</<>td tr><th scope=“row”m</>><th td minute-of-hour</>><><<>td 30</<><>td tr th scope=“row”>>s</th><>td second-of minute</td>>><<>< 55</td><tr><th scope=“row”>S</th><td>fraction-of-second<<>></td><>978</><td tr th scope=“row”>A</th><>td milli-of-day<><>/td number</><>td td 1234</td><tr><><th scope=“row”>n</th<>td>nano-of-second</td td number</td><>><td>987654321</td<>tr><th scope=“row”>N</th><td>nano-of-day</td td>><number</td td<>>1234000000</td>

<tr><th scope=“row”>V</th><td>time-zone ID</td><>td zone-id</td td>><America/Los_Angeles;Z;-08：30</td<>tr><th scope=“row”>v</th><td>generic time-zone name/td><>td zone-name<</td td><>pacific Time;PT</td><tr><th scope=“row”>z</th><td>time-zone name/td><>td zone-name<</td td>><Pacific Standard Time;PST</td><tr><th scope=“row”>O</th><td>localized zone-offset/td><>td offset-O<</td td>><gmt+8;GMT+08：00;UTC-08：00</td<>tr><th scope=“row”>X</th<>td>zone-offset<<> 'Z' for zero</td td><>>Z; -08; -0830; -08：30; -083015; -08：30：15</td><tr><th scope=“row”>x</th><td>zone-offset/td<>>offset-x<</td<>td td>+0000; -0830; -08：30; -083015; -08：30：15</td><tr><th scope=“row“>Z</th><td>zone-offset/td td>><offset-Z<</td td td><>+0000;-0800;-08：00</td>

<tr><th scope=“row”>p</th><td>pad next</td>><td pad modifier</td td><1</td>>

<tr><th scope=“row”>'</th><>td escape for text/td td><<><><<>>></td tr th scope=“row”>''</th<>>td single quote</>><td literal<</<<>>td td td'/><td tr><th scope=“row”>[</th<>>td optional section start</td<>>< td/td<>td tr><><><th scope=“row”>]</th td選擇性區段 end</td<>td/td td><><>><</td tr><th scope=“row”>#</th>><td 保留供未來使用</<><>><><><td td/td td/td tr><th scope=“row”>{</<>>th td 保留供未來使用</td<<>>>< td/td td></td tr><th scope=“row”>}</th<>td<>td<>>>保留供日後使用</td><td></td<>td></td<>/tbody></table>

模式字母計數會決定格式。

<b>文字</b>：文字樣式是根據所使用的模式字母數目來決定。 小於 4 個模式字母會使用 TextStyle#SHORT short form。 只有 4 個模式字母會使用 TextStyle#FULL full form。 只有 5 個模式字母會使用 TextStyle#NARROW narrow form。 圖樣字母 'L'、'c' 和 'q' 會指定文字樣式的獨立形式。

<b>Number</b>：如果字母計數為 1，則值會使用最少數位數輸出，而不需填補。 否則，數位計數會作為輸出字段的寬度，並視需要以零填補值。 下列模式字母具有字母計數的條件約束。 只能指定一個字母 『c』 和 『F』。 最多可以指定 'd'、'H'、'h'、'K'、'k'、'm' 和 's' 的兩個字母。 最多可以指定三個 『D』 字母。

<b>Number/Text</b>：如果模式字母的計數為 3 或更大，請使用上述的 Text 規則。 否則，請使用上述數字規則。

<b>Fraction</b>：將 nano-of-second 字段輸出為小數秒。 nano-of-second 值有九位數，因此模式字母的計數是從 1 到 9。 如果小於 9，則會截斷 nano-of-second 值，而輸出的最大有效位數。

<b>年</b>：字母計數會決定使用填補的最小字段寬度。 如果字母計數為 2，則會 DateTimeFormatterBuilder#appendValueReduced reduced 使用兩位數表單。 若要列印，這會輸出最右邊的兩位數。 為了剖析，這會使用 2000 的基底值進行剖析，導致包含 2000 到 2099 範圍內的一年。 如果字母計數小於四個（但不是兩個），則符號只會根據 來 SignStyle#NORMAL輸出負年。 否則，如果超過板寬度，則會根據 輸出 SignStyle#EXCEEDS_PAD符號。

<b>ZoneId</b>：這會輸出時區標識符，例如 'Europe/Paris'。 如果字母計數是兩個，則會輸出時區標識符。 任何其他字母計數都會 IllegalArgumentException擲回 。

<b>區域名稱</b>：這會輸出時區標識符的顯示名稱。 如果模式字母是 『z』，則輸出是日光節約感知區域名稱。 如果沒有足夠的資訊來判斷 DST 是否適用，則會使用忽略日光節約時間的名稱。 如果字母計數為一、二或三個，則簡短名稱會輸出。 如果字母計數為四，則完整名稱會輸出。 五個以上的字母會 IllegalArgumentException擲回 。

如果模式字母是 'v'，則輸出會提供忽略日光節約時間的區域名稱。 如果字母計數為一，則簡短名稱會輸出。 如果字母計數為四，則完整名稱會輸出。 兩個、三個和五個以上的字母會擲回 IllegalArgumentException。

<b>Offset X 和 x</b>：這會根據圖樣字母數目來格式化位移。 一個字母只會輸出小時，例如 『+01』，除非分鐘不是零，在此情況下，分鐘也是輸出，例如 『+0130』。 兩個字母會輸出小時和分鐘，沒有冒號，例如 『+0130』。 三個字母會輸出小時和分鐘，冒號，例如 『+01：30』。 四個字母會輸出小時和分鐘和選擇性秒，沒有冒號，例如 『+013015』。 五個字母會輸出小時和分鐘和選擇性秒，冒號，例如 『+01：30：15』。 六個以上的字母會 IllegalArgumentException擲回 。 圖樣字母 'X' （大寫） 會在輸出位移為零時輸出 'Z'，而模式字母 'x' （小寫） 則會輸出 '+00'、'+0000'或 '+00：00'。

<b>位移 O</b>：使用非零位移，這會根據模式字母數目來格式化本地化位移。 一個字母會輸出本地化位移的 TextStyle#SHORT 簡短形式，也就是當地語系化位移文字，例如 'GMT'，如果非零，則為選擇性的 2 位數分鐘和秒，例如 'GMT+8'。 四個字母會輸出 TextStyle#FULL 完整表單，其當地語系化位移文字，例如 'GMT，具有 2 位數的小時和分鐘字段、非零的選擇性第二個字段，以及冒號，例如 'GMT+08：00'。 如果位移為零，則只會輸出本地化的文字。 任何其他字母計數都會 IllegalArgumentException擲回 。

<b>位移 Z</b>：這會根據圖樣字母數目來格式化位移。 一、二或三個字母會輸出小時和分鐘，沒有冒號，例如 『+0130』。 當位移為零時，輸出會是 『+0000』。 四個字母會輸出 TextStyle#FULL 完整格式的當地語系化位移，相當於 Offset-O 的四個字母。 如果位移為零，輸出將會是對應的當地語系化位移文字。 五個字母會輸出小時、分鐘，如果非零則為選擇性秒，則為冒號。 如果位移為零，則會輸出 'Z'。 六個以上的字母會 IllegalArgumentException擲回 。

<b>選擇性區段</b>：選擇性區段標記的運作方式與呼叫 DateTimeFormatterBuilder#optionalStart() 和 DateTimeFormatterBuilder#optionalEnd()完全相同。

<b>Pad 修飾詞</b>：修改緊接在後面以空格填補的模式。 面板寬度取決於圖樣字母的數目。 這與呼叫 DateTimeFormatterBuilder#padNext(int)相同。

例如，『ppH』 會將空白填補在左邊的小時輸出為 2。

任何無法辨識的信件都是錯誤。 '['、']'、'{'、'}'、'#' 以外的任何非字母字元，都會直接輸出單引號。 儘管如此，建議您在所有您想要直接輸出的字元周圍使用單引號，以確保未來的變更不會中斷您的應用程式。

<h2 id=“resolving”>Resolving/h2> Parsing< 會實作為兩階段作業。 首先，文字會使用格式器所定義的版面配置來剖析，產生 Map 域對值、 ZoneId 和 Chronology。 其次，剖析的數據是 <em>resolved</em>，藉由驗證、結合和簡化各種欄位，變成更有用的欄位。

這個類別會提供五個剖析方法。 其中四個會同時執行剖析和解析階段。 第五個方法 #parseUnresolved(CharSequence, ParsePosition)只會執行第一個階段，讓結果無法解決。 因此，它基本上是低階作業。

解析階段是由這個類別上設定的兩個參數所控制。

ResolverStyle是一個列舉，提供三種不同的方法，嚴格，智慧和寬大。 智慧選項是預設值。 您可以使用 來設定 #withResolverStyle(ResolverStyle)它。

參數 #withResolverFields(TemporalField...) 允許解析開始之前解析的欄位集進行篩選。 例如，如果格式器已剖析一年、月、月、月和年，則有兩種方法可以解析日期：（年 + 月 + 月+ 日）和（年 + 年 + 日）。 解析程式欄位允許選取這兩種方法之一。 如果未設定解析程式欄位，則這兩種方法都必須產生相同的日期。

解決個別欄位以形成完整的日期和時間，是一個複雜的程式，其行為分散在數個類別中。 它遵循下列步驟： <ol><li>確定時程表。 結果的時序表是剖析的時序表，或者如果沒有剖析時序，則為這個類別上設定的時序，如果為 null，則為 IsoChronology。 <li>已 ChronoField 解析日期欄位。 這是使用 Chronology#resolveDate(Map, ResolverStyle)來達成。 欄位解析的相關文件位於的實作 Chronology中。 <li>已 ChronoField 解析時間欄位。 這會記錄在 上 ChronoField ，而且所有時序都相同。 <li>任何未 ChronoField 處理的欄位。 這是使用 TemporalField#resolve(Map, TemporalAccessor, ResolverStyle)來達成。 欄位解析的相關文件位於的實作 TemporalField中。 <li>重新 ChronoField 解析日期和時間欄位。 這可讓步驟 4 中的欄位產生 ChronoField 值，並將其處理成日期和時間。 <如果至少有一小時可用，則 li>A LocalTime 會形成。 這牽涉到提供分鐘、秒和小數秒的預設值。 <li>任何剩餘未解析的欄位會針對任何已解決的日期和時間進行交叉檢查。 因此，較早階段會將 （year + month + day-of-month） 解析為日期，而這個階段會檢查該日期的星期幾是否有效。 <li>如果剖析 #parsedExcessDays（） 超過天數，則會在日期可用時新增至日期。 <li> 如果存在第二個基底的欄位，但 LocalTime 未剖析，則解析程式可確保可符合的合約 ChronoField。。 如果遺漏，這些會設定為零。 <li>如果剖析日期和時間，而且有位移或區域存在，則會建立字段 ChronoField#INSTANT_SECONDS 。 如果剖析位移，則位移會與 LocalDateTime 結合以形成立即，並忽略任何區域。 ZoneId如果 剖析時沒有位移，則區域會與 LocalDateTime 結合，以使用 的規則ChronoLocalDateTime#atZone(ZoneId)來形成立即。 </老>

已在1.8中新增。

的 java.time.format.DateTimeFormatterJava 檔。

此頁面的部分是根據 Android 開放原始碼專案所建立和共用的工作進行修改，並根據 Creative Commons 2.5 屬性授權中所述的詞彙使用。

屬性

方法

明確介面實作

擴充方法

適用於