DateTimeFormatter 類別

參考

定義

命名空間:: Windows.Globalization.DateTimeFormatting

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

編輯

格式化日期和時間。

public ref class DateTimeFormatter sealed

/// [Windows.Foundation.Metadata.Activatable(Windows.Globalization.DateTimeFormatting.IDateTimeFormatterFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class DateTimeFormatter final

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(Windows.Globalization.DateTimeFormatting.IDateTimeFormatterFactory, 65536, "Windows.Foundation.UniversalApiContract")]
class DateTimeFormatter final

[Windows.Foundation.Metadata.Activatable(typeof(Windows.Globalization.DateTimeFormatting.IDateTimeFormatterFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class DateTimeFormatter

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Globalization.DateTimeFormatting.IDateTimeFormatterFactory), 65536, "Windows.Foundation.UniversalApiContract")]
public sealed class DateTimeFormatter

function DateTimeFormatter(yearFormat, monthFormat, dayFormat, dayOfWeekFormat, hourFormat, minuteFormat, secondFormat, languages, geographicRegion, calendar, clock)

Public NotInheritable Class DateTimeFormatter

繼承: Object Platform::Object IInspectable DateTimeFormatter

屬性: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows 需求

裝置系列	Windows 10 (已於 10.0.10240.0 引進)
API contract	Windows.Foundation.UniversalApiContract (已於 v1.0 引進)

範例

使用 DateTimeFormatter 類別來格式化日期。

// Format a date via a string template. Note that the order specifed in the string pattern does
// not determine the order of the parts of the formatted string. The user's language and region
// preferences will determine the pattern of the date returned based on the specified parts.

var formatter = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("month day dayofweek year");
DateTime dateToFormat = DateTime.Now;
var mydate = formatter.Format(dateToFormat);

模式文法下列文法會定義模式可接受的專案：

<pattern> ::= [<literal-text>] <datetime-pattern> [<literal-text>] |
              [<literal-text>] <datetime-pattern> <pattern>

<literal-text> ::= <literal-character>+

<literal-character> ::= [^{}] | "{openbrace}" | "{closebrace}"

<datetime-pattern> ::= <date-pattern> | <time-pattern>

<date-pattern> ::= <era> | <year> | <month> | <day> | <dayofweek>

<time-pattern> ::= <period> | <hour> | <minute> | <second> | <timezone>

<era> ::= "{era.abbreviated" [<ideal-length>] "}"

<year> ::= "{year.full" [<ideal-length>] "}" |
           "{year.abbreviated" [<ideal-length>] "}"

<month> ::= "{month.full}" |
            "{month.solo.full}" |
            "{month.abbreviated" [<ideal-length>] "}"
            "{month.solo.abbreviated" [<ideal-length>] "}"
            "{month.integer" [<ideal-length>] "}"

<dayofweek> ::= "{dayofweek.full}" |
                "{dayofweek.solo.full}" |
                "{dayofweek.abbreviated" [<ideal-length>] "}"
                "{dayofweek.solo.abbreviated" [<ideal-length>] "}"

<day> ::= "{day.integer" [<ideal-length>] "}"

<period> ::= "{period.abbreviated" [<ideal-length>] "}"

<hour> ::= "{hour.integer" [<ideal-length>] "}"

<minute> ::= "{minute.integer" [<ideal-length>] "}"

<second> ::= "{second.integer" [<ideal-length>] "}"

<timezone> ::= "{timezone.full}" |
                "{timezone.abbreviated" [<ideal-length>] "}"

<ideal-length> ::= "(" <non-zero-digit> ")"

<non-zero-digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

範本文法下列文法會定義範本接受的內容：

<template> ::= <opt-whitespace> <date> <opt-whitespace> |
               <opt-whitespace> <time> <opt-whitespace> |
               <opt-whitespace> <specific-date> <whitespace> <time> <opt-whitespace> |
               <opt-whitespace> <time> <whitespace> <specific-date> <opt-whitespace> |
               <opt-whitespace> <relative-date> <whitespace> <time> <opt-whitespace> |
               <opt-whitespace> <time> <whitespace> <relative-date> <opt-whitespace>

<opt-whitespace> ::= [<whitespace>] 

<whitespace> ::= " "+ 

<date> ::= <year> | <month> | <day> | <month-year> | <relative-date> | <specific-date>

<relativedate> ::= <dayofweek> | <month-day> | <relative-longdate>

<specificdate> ::= <shortdate> | <longdate>

<month-day> ::= <month> <whitespace> <day> |
                <day> <whitespace> <month>

<relative-longdate> ::= <month> <whitespace> <day> <whitespace> <dayofweek> |
                        <month> <whitespace> <dayofweek> <whitespace> <day> |
                        <day> <whitespace> <month> <whitespace> <dayofweek> |
                        <day> <whitespace> <dayofweek> <whitespace> <month> |
                        <dayofweek> <whitespace> <day> <whitespace> <month> |
                        <dayofweek> <whitespace> <month> <whitespace> <day>

<month-year> ::= <month> <whitespace> <year> |
                 <year> <whitespace> <month>


<shortdate> ::= "shortdate" |
                <month> <whitespace> <day> <whitespace> <year> |
                <month> <whitespace> <year> <whitespace> <day> |
                <day> <whitespace> <month> <whitespace> <year> |
                <day> <whitespace> <year> <whitespace> <month> |
                <year> <whitespace> <day> <whitespace> <month> |
                <year> <whitespace> <month> <whitespace> <day>


<longdate> ::= "longdate" |
               <year> <whitespace> <month> <whitespace> <day> <whitespace> <dayofweek> |
               <year> <whitespace> <month> <whitespace> <dayofweek> <whitespace> <day> |
               <year> <whitespace> <day> <whitespace> <month> <whitespace> <dayofweek> |
               <year> <whitespace> <day> <whitespace> <dayofweek> <whitespace> <month> |
               <year> <whitespace> <dayofweek> <whitespace> <day> <whitespace> <month> |
               <year> <whitespace> <dayofweek> <whitespace> <month> <whitespace> <day> |
               <month> <whitespace> <year> <whitespace> <day> <whitespace> <dayofweek> |
               <month> <whitespace> <year> <whitespace> <dayofweek> <whitespace> <day> |
               <day> <whitespace> <year> <whitespace> <month> <whitespace> <dayofweek> |
               <day> <whitespace> <year> <whitespace> <dayofweek> <whitespace> <month> |
               <dayofweek> <whitespace> <year> <whitespace> <day> <whitespace> <month> |
               <dayofweek> <whitespace> <year> <whitespace> <month> <whitespace> <day> |
               <month> <whitespace> <day> <whitespace> <year> <whitespace> <dayofweek> |
               <month> <whitespace> <dayofweek> <whitespace> <year> <whitespace> <day> |
               <day> <whitespace> <month> <whitespace> <year> <whitespace> <dayofweek> |
               <day> <whitespace> <dayofweek> <whitespace> <year> <whitespace> <month> |
               <dayofweek> <whitespace> <day> <whitespace> <year> <whitespace> <month> |
               <dayofweek> <whitespace> <month> <whitespace> <year> <whitespace> <day> |
               <month> <whitespace> <day> <whitespace> <dayofweek> <whitespace> <year> |
               <month> <whitespace> <dayofweek> <whitespace> <day> <whitespace> <year> |
               <day> <whitespace> <month> <whitespace> <dayofweek> <whitespace> <year> |
               <day> <whitespace> <dayofweek> <whitespace> <month> <whitespace> <year> |
               <dayofweek> <whitespace> <day> <whitespace> <month> <whitespace> <year> |
               <dayofweek> <whitespace> <month> <whitespace> <day> <whitespace> <year>

<time> ::= <hour> | 
           <hour> <whitespace> <timezone> |
           <timezone> <whitespace> <hour> |
           <shorttime> |
           <longtime>

<shorttime> ::= "shorttime" |
                <hour> <whitespace> <minute> |
                <minute> <whitespace> <hour> |
                <timezone> <whitespace> <hour> <whitespace> <minute> |
                <timezone> <whitespace> <minute> <whitespace> <hour> |
                <hour> <whitespace> <timezone> <whitespace> <minute> |
                <minute> <whitespace> <timezone> <whitespace> <hour> |
                <hour> <whitespace> <minute> <whitespace> <timezone> |
                <minute> <whitespace> <hour> <whitespace> <timezone>

<longtime> ::= "longtime" |
               <hour> <whitespace> <minute> <whitespace> <second> |
               <hour> <whitespace> <second> <whitespace> <minute> |
               <minute> <whitespace> <hour> <whitespace> <second> |
               <minute> <whitespace> <second> <whitespace> <hour> |
               <second> <whitespace> <minute> <whitespace> <hour> |
               <second> <whitespace> <hour> <whitespace> <minute> |
               <timezone> <whitespace> <hour> <whitespace> <minute> <whitespace> <second> |
               <timezone> <whitespace> <hour> <whitespace> <second> <whitespace> <minute> |
               <timezone> <whitespace> <minute> <whitespace> <hour> <whitespace> <second> |
               <timezone> <whitespace> <minute> <whitespace> <second> <whitespace> <hour> |
               <timezone> <whitespace> <second> <whitespace> <minute> <whitespace> <hour> |
               <timezone> <whitespace> <second> <whitespace> <hour> <whitespace> <minute> |
               <hour> <whitespace> <timezone> <whitespace> <minute> <whitespace> <second> |
               <hour> <whitespace> <timezone> <whitespace> <second> <whitespace> <minute> |
               <minute> <whitespace> <timezone> <whitespace> <hour> <whitespace> <second> |
               <minute> <whitespace> <timezone> <whitespace> <second> <whitespace> <hour> |
               <second> <whitespace> <timezone> <whitespace> <minute> <whitespace> <hour> |
               <second> <whitespace> <timezone> <whitespace> <hour> <whitespace> <minute> |
               <hour> <whitespace> <minute> <whitespace> <timezone> <whitespace> <second> |
               <hour> <whitespace> <second> <whitespace> <timezone> <whitespace> <minute> |
               <minute> <whitespace> <hour> <whitespace> <timezone> <whitespace> <second> |
               <minute> <whitespace> <second> <whitespace> <timezone> <whitespace> <hour> |
               <second> <whitespace> <minute> <whitespace> <timezone> <whitespace> <hour> |
               <second> <whitespace> <hour> <whitespace> <timezone> <whitespace> <minute> |
               <hour> <whitespace> <minute> <whitespace> <second> <whitespace> <timezone> |
               <hour> <whitespace> <second> <whitespace> <minute> <whitespace> <timezone> |
               <minute> <whitespace> <hour> <whitespace> <second> <whitespace> <timezone> |
               <minute> <whitespace> <second> <whitespace> <hour> <whitespace> <timezone> |
               <second> <whitespace> <minute> <whitespace> <hour> <whitespace> <timezone> |
               <second> <whitespace> <hour> <whitespace> <minute> <whitespace> <timezone>

<year> ::= "year" | "year.full" | "year.abbreviated"

<month> ::= "month" | "month.full" | "month.abbreviated" | "month.numeric"

<day> ::= "day"

<dayofweek> ::= "dayofweek" | "dayofweek.full" | "dayofweek.abbreviated"

<hour> ::= "hour"

<minute> ::= "minute"

<second> ::= "second"

<timezone> ::= "timezone" | "timezone.full" | "timezone.abbreviated"

備註

注意

此 API 即將更新，以支援 2019 年 5 月日紀元變更。如果您的應用程式支援日曆，您應該驗證它是否能夠正確處理新紀元。如需詳細資訊，請參閱準備您的應用程式以進行日文紀元變更。

注意

如果您的 app 會將此類別中使用的語言標籤傳遞給任何國家語言支援函式，則必須先呼叫 ResolveLocaleName來轉換標籤。

DateTimeFormatter 的一些建構函式會採用 formatTemplate 字串參數，指定要格式化的要求元件。此參數可以是 格式範本 或 格式模式。格式範本方便使用，並提供您指定語言、時鐘和行事曆的一般格式設定。格式模式提供比格式範本更大的輸出控制。如果您需要非標準格式設定，請使用格式模式，而不是範本。

在格式範本中，您可以指定要包含在格式化輸出中的元件 (時間、日期、星期幾等 ) 。格式器會針對指定的語言、時鐘和行事曆，將元件格式化。範本中的元件順序並不重要;格式器會根據下列格式範本語言中顯示的順序來排序元件。

下表列出一些常用的範本。在具有多個元件的範本中，元件可以是任何支援的元件變化，而且元件可能依任何順序排列。例如，支援「dayofweek.full year.numeric day」。 (請參閱下列範例之後，以取得定義有效 templates 的文法。)

重要

您無法任意合併元件，而且一定取得有效的範本。唯一有效的範本是由提供的文法所定義。

[範本]
longdate
shortdate
長期
shorttime
dayofweek
dayofweek.full
dayofweek.abbreviated
day
月
month.full
month.abbreviated
month.numeric
year
year.full
year.abbreviated
dayofweek day month year
dayofweek day month
日月年
日月
月、年
hour
minute
second
小時分鐘秒
小時分鐘
timezone
timezone.full
timezone.abbreviated
年月日小時

下表顯示使用範本、語言和時鐘各種值所建立之格式子的範例輸出。「對等模式」資料行提供產生與範本相同輸出的模式。

範本	Language	時鐘	輸出	對等模式
longdate	zh-TW	<未指定>	星期一，2013 年 9 月 2 日	{dayofweek.full}、{month.full} {day.integer}、{year.full}
longdate	fr-FR	<未指定>	lundi 29embre 2013	{dayofweek.full} {day.integer} {month.full} {year.full}
shortdate	zh-TW	<未指定>	9‎/‎2‎/‎2013	{month.integer}/{day.integer}/{year.full}
shortdate	fr-FR	<未指定>	02‎/‎09‎/‎2013	{day.integer (2) }/{month.integer (2) }/{year.full}
dayofweek month day	zh-TW	<未指定>	星期一，9 月 2 日	{dayofweek.full}、 {month.full} {day.integer}
month dayofweek	zh-TW	<未指定>	星期一，9 月 2 日	{dayofweek.full}、 {month.full} {day.integer}
長期	zh-TW	<未指定>	上午 6：01：24	{hour.integer}：{minute.integer (2) }：{second.integer (2) } {period.abbreviated}
長期	zh-TW	24HourClock	‎17‎:‎32‎:‎45	{hour.integer}：{minute.integer (2) }：{second.integer (2) }
長期	fr-FR	<未指定>	17‎:‎32‎:‎45	{hour.integer (2) }：{minute.integer (2) }：{second.integer (2) }
shorttime	zh-TW	<未指定>	上午 6：01	{hour.integer}：{minute.integer (2) } {period.abbreviated}
shorttime	zh-TW	24HourClock	17‎:‎32	{hour.integer}：{minute.integer (2) }
shorttime	fr-FR	<未指定>	17‎:‎32	{hour.integer (2) }：{minute.integer (2) }

格式模式 是由以大括弧分隔的欄位所組成的常值字串，例如「{day.numeric}/{month.numeric}/{year.full}」。下表列出一些常用的欄位。 (請參閱下列範例之後的文法，以定義有效的 patterns.)

重要

您無法任意合併欄位，而且必須取得有效的模式。唯一有效的模式是由提供的文法所定義。

格式模式欄位
{openbrace}
{closebrace}
{dayofweek.solo. <type > } ，其中 < type > 為 full / abbreviated / abbreviated (n)
{dayofweek. <type > } ，其中 < type > 為 full / abbreviated / abbreviated (n)
{day。 <type > } ，其中 < type > 是 integer / integer (n)
{month. <type > } ，其中 < type > 為 full / abbreviated / abbreviated (n) / integer / integer (n)
{month.solo. <type > } ，其中 < type > 為 full / abbreviated / abbreviated (n)
{year. <type > } ，其中 < type > 為 full / abbreviated / abbreviated (n)
{era. <type > } ，其中 < type > 為 full / abbreviated / abbreviated (n)
{hour. <type > } ，其中 < type > 是 integer / integer (n)
{period。 <type > } ，其中 < type > 為 full / abbreviated / abbreviated (n)
{minute. <type > } ，其中 < type > 是 integer / integer (n)
{second. <type > } ，其中 < type > 是 integer / integer (n)
{時區。 <type > } ，其中 < type > 為 full / abbreviated / abbreviated (n)

注意

使用 {openbrace} 或 {closebrace} 來指定「{」或「}」顯示為常值字串的一部分。

solo 會指定獨立表單。對於具有 Genitive 大小寫區分的語言，Genitive 案例是未標示的案例。若要取得提名案例，請使用 solo。
整數 (2) (，例如) 為「05」，而 整數 (1) 會產生「5」。 integer 會針對指定的語言/行事曆組合產生最佳 n 。
多年來， full 會產生 (「2013」) 的所有數位。縮寫與 縮寫 (2) 同義，這是西曆 (「13」) 的 2 位數年份。 (其他行事曆最終可能會使用其他專案作為預設值;我們已保留縮寫，讓指定語言/行事曆組合的最佳語意。) 縮寫 (n ) 截斷為最小有效 n 位數 (例如，2013 且 n =1 為「3」) 。

下表顯示使用各種模式、語言和時鐘值所建立之格式子的範例輸出。

模式	語言	時鐘	輸出
{dayofweek.full}、{month.full} {day.integer}、{year.full}	zh-TW	<未指定>	星期一，2013 年 9 月 2 日
{dayofweek.full}， {day.integer (2) } {month.full}， {year.full}	fr-FR	<未指定>	lundi， 02sepembre， 2013
{month.integer}/{day.integer}/{year.full}	zh-TW	<未指定>	9/‎2/2013
{month.integer}/{day.integer}/{year.abbreviated}	zh-TW	<未指定>	9/‎2/13
{month.integer (2) }/{day.integer (2) }/{year.abbreviated}	zh-TW	<未指定>	09/‎02/13
{hour.integer}：{minute.integer (2) }：{second.integer (2) } {period.abbreviated}	zh-TW	<未指定>	上午 6：01：24
{hour.integer}：{minute.integer (2) }：{second.integer (2) } {period.abbreviated}	zh-TW	24HourClock	17:32:45

建構函式

DateTimeFormatter(HourFormat, MinuteFormat, SecondFormat)	建立以小時、分鐘和秒格式初始化的 DateTimeFormatter 物件。
DateTimeFormatter(String)	建立由格式範本字串初始化的 DateTimeFormatter 物件。
DateTimeFormatter(String, IIterable<String>)	建立由格式範本字串和語言清單初始化的 DateTimeFormatter 物件。
DateTimeFormatter(String, IIterable<String>, String, String, String)	建立由格式範本字串、語言清單、地理區域、行事曆和時鐘初始化的 DateTimeFormatter 物件。
DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat)	建立以年、月、日和周格式初始化的 DateTimeFormatter 物件。
DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>)	建立 DateTimeFormatter 物件，此物件是以年、月、日、周的日、小時、分鐘和秒格式初始化，以及語言清單。
DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>, String, String, String)	建立指定所有格式和識別碼的 DateTimeFormatter 物件。

屬性

Calendar	取得格式化日期時使用的行事曆。
Clock	取得格式化時間時所使用的時鐘。
GeographicRegion	取得或設定格式化日期和時間時所使用的區域。
IncludeDay	取得範本中的 DayFormat 。
IncludeDayOfWeek	取得範本中的 DayOfWeekFormat 。
IncludeHour	取得範本中的 HourFormat 。
IncludeMinute	取得範本中的 MinuteFormat 。
IncludeMonth	取得範本中的 MonthFormat 。
IncludeSecond	取得範本中的 SecondFormat 。
IncludeYear	取得範本中的 YearFormat 。
Languages	取得格式化日期和時間時所使用的語言識別項優先順序清單。
LongDate	取得 DateTimeFormatter 物件，該物件會根據使用者選擇的長日期模式來格式化日期。
LongTime	取得 DateTimeFormatter 物件，這個物件會根據使用者選擇長時間模式來格式化時間。
NumeralSystem	取得或設定用來格式化日期和時間的編號系統。
Patterns	取得對應至這個範本的模式，這些模式會在格式化日期和時間時使用。
ResolvedGeographicRegion	取得最近用來格式化日期和時間的地理區域。
ResolvedLanguage	取得最近用來格式化日期和時間的語言。
ShortDate	取得 DateTimeFormatter 物件，該物件會根據使用者選擇的簡短日期模式來格式化日期。
ShortTime	取得 DateTimeFormatter 物件，這個物件會根據使用者選擇的簡短時間模式來格式化時間。
Template	取得這個格式範本的字串表示。

方法

Format(DateTime)	傳回所提供日期和時間的字串表示。
Format(DateTime, String)	傳回字串，表示指定時區中的指定日期和時間，符合格式器目前使用的範本。

適用於

DateTimeFormatter 類別

定義

Windows 需求

範例

備註

建構函式

屬性

方法

適用於

另請參閱

意見反應

意見反應

其他資源