DateTimeFormatter 类

  • 参考

定义

命名空间:
Windows.Globalization.DateTimeFormatting
编辑

设置日期和时间格式。

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 月日本纪元更改。 如果应用程序支持日语日历，则应验证它是否正确处理了新纪元。 有关详细信息 ，请参阅为日本纪元更改准备应用程序 。

注意

如果你的应用将此类中使用的语言标记传递给任何 国家/地区语言支持 函数，则它必须首先通过调用 ResolveLocaleName 来转换标记。

DateTimeFormatter 的某些构造函数采用 formatTemplate 字符串参数，用于指定要设置格式的请求组件。 此参数可以是 格式模板 或 格式模式。 格式模板使用十分方便，并提供你指定的语言、时钟和日历的典型格式设置。 与格式模板相比，格式模式可以更好地控制输出。 如果需要非标准格式，请使用格式模式而不是模板。

在格式模板中，指定要包含在格式化输出中的组件 (时间、日期、星期几等 ) 。 格式化程序根据指定的语言、时钟和日历设置相应的组件格式。 模板中组件的顺序无关紧要;格式化程序根据以下格式模板语言中显示的顺序对组件进行排序。

下表列出了一些常用的模板。 在具有多个组件的模板中，组件可以是任何受支持的组件变体，并且这些组件可以按任意顺序排列。 例如，支持“dayofweek.full year month.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
第 2 个
hour minute second
小时分钟
timezone
timezone.full
timezone.abbreviated
年月日小时

下表显示了使用各种模板、语言和时钟值创建的格式化程序的示例输出。 “等效模式”列提供与模板相同的输出的模式。

模板Language时钟输出等效模式
longdatezh-CN<未指定>2013 年 9 月 2 日，星期一{dayofweek.full}、{month.full} {day.integer}、{year.full}
longdatefr-FR<未指定>lundi 2 2013 年 9 月 2 日{dayofweek.full} {day.integer} {month.full} {year.full}
shortdatezh-CN<未指定>9‎/‎2‎/‎2013{month.integer}/{day.integer}/{year.full}
shortdatefr-FR<未指定>02‎/‎09‎/‎2013{day.integer (2) }/{month.integer (2) }/{year.full}
dayofweek month dayzh-CN<未指定>9 月 2 日星期一{dayofweek.full}，{month.full} {day.integer}
month day dayofweekzh-CN<未指定>9 月 2 日星期一{dayofweek.full}，{month.full} {day.integer}
长期zh-CN<未指定>上午 6：01：24{hour.integer}：{minute.integer (2) }：{second.integer (2) } {period.abbreviated}
长期zh-CN24HourClock‎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) }
shorttimezh-CN<未指定>上午 6：01{hour.integer}：{minute.integer (2) } {period.abbreviated}
shorttimezh-CN24HourClock17‎:‎32{hour.integer}：{minute.integer (2) }
shorttimefr-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)
{timezone.<type>} ，其中 <type> 为 full/ abbreviated / abbreviated (n)

注意

  • 使用 {openbrace} 或 {closebrace} 指定“{”或“}”显示为文本字符串的一部分。
  • solo 指定独立窗体。 对于具有常规大小写区分的语言，一元大小写为未标记大小写。 若要获取提名案例，请使用 solo。
  • 整数 (2) (例如，) 为“05”，而 整数 (1) 生成“5”。 integer 为给定语言/日历组合生成最佳 n 。
  • 多年来， full 生成 (“2013”) 的所有数字。 abbreviated 与 缩写 (2) 同义，这是公历 (“13”) 的 2 位数年份。 (其他日历最终可能会使用其他内容作为默认值;我们一直保持 缩写 ，使给定语言/日历组合的语义最佳。) 缩写 (n) 被截断为最小有效 n 位 (例如， n =1 的 2013 为“3”) 。

下表显示了使用各种模式、语言和时钟值创建的格式化程序的示例输出。

模式语言时钟输出
{dayofweek.full}、{month.full} {day.integer}、{year.full}zh-CN<未指定>2013 年 9 月 2 日，星期一
{dayofweek.full}， {day.integer (2) } {month.full}， {year.full}fr-FR<未指定>lundi， 2013 年 9 月 2 日
{month.integer}/{day.integer}/{year.full}zh-CN<未指定>9/‎2/2013
{month.integer}/{day.integer}/{year.abbreviated}zh-CN<未指定>9/‎2/13
{month.integer (2) }/{day.integer (2) }/{year.abbreviated}zh-CN<未指定>09/‎02/13
{hour.integer}：{minute.integer (2) }：{second.integer (2) } {period.abbreviated}zh-CN<未指定>上午 6：01：24
{hour.integer}：{minute.integer (2) }：{second.integer (2) } {period.abbreviated}zh-CN24HourClock17: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)

返回一个字符串，该字符串表示给定时区中的给定日期和时间，符合格式化程序当前使用的模板。

适用于

另请参阅