模板语法
服务端渲染
API / @angular/common

DatePipe

Formats a date value according to locale rules.

根据区域设置规则格式化日期值。

{{ value_expression | date [ : format [ : timezone [ : locale ] ] ] }}

输入值

valueany

The date expression: a Date object, a number (milliseconds since UTC epoch), or an ISO string (https://www.w3.org/TR/NOTE-datetime).

日期表达式：Date 对象、数字（从 UTC 时代以来的毫秒数）或一个 ISO 字符串 (https://www.w3.org/TR/NOTE-datetime)。

参数

format'mediumDate'

The date/time components to include, using predefined options or a custom format string.

要包含的日期、时间部分的格式，使用预定义选项或自定义格式字符串。

可选. 默认值是 'mediumDate'.

timezonestring

A timezone offset (such as '+0430'), or a standard UTC/GMT or continental US timezone abbreviation. Default is the local system timezone of the end-user's machine.

一个时区偏移（比如'+0430'）或标准的 UTC/GMT 或美国大陆时区的缩写。默认为最终用户机器上的本地系统时区。

可选. 默认值是 undefined.

localestring

A locale code for the locale format rules to use. When not supplied, uses the value of LOCALE_ID, which is en-US by default. See Setting your app locale.

要使用的区域格式规则的区域代码。 如果不提供，就使用 LOCALE_ID 的值，默认为 en-US。 参见设置应用的区域。

可选. 默认值是 undefined.

参见

说明

Only the en-US locale data comes with Angular. To localize dates in another language, you must import the corresponding locale data. See the I18n guide for more information.

Angular 只自带了 en-US 区域的数据。要想在其它语言中对日期进行本地化，你必须导入相应的区域数据。 欲知详情，参见 I18n guide。

使用说明

The result of this pipe is not reevaluated when the input is mutated. To avoid the need to reformat the date on every change-detection cycle, treat the date as an immutable object and change the reference when the pipe needs to run again.

当输入值发生变化时，该管道的结果并不会改变。如果不想在每个变更检测周期中都强制重新格式化该日期，请把日期看做一个不可变对象， 当需要让该管道重新运行时，请赋给它一个新的对象，以更改它的引用。

Pre-defined format options

预定义的格式选项

Examples are given in en-US locale.

下面是 en-US 区域的例子。

  • 'short': equivalent to 'M/d/yy, h:mm a' (6/15/15, 9:03 AM).

    'short': 等价于 'M/d/yy, h:mm a' (6/15/15, 9:03 AM).

  • 'medium': equivalent to 'MMM d, y, h:mm:ss a' (Jun 15, 2015, 9:03:01 AM).

    'medium': 等价于 'MMM d, y, h:mm:ss a' (Jun 15, 2015, 9:03:01 AM).

  • 'long': equivalent to 'MMMM d, y, h:mm:ss a z' (`June 15, 2015 at 9:03:01 AM

    'long': 等价于 'MMMM d, y, h:mm:ss a z' (`June 15, 2015 at 9:03:01 AM

GMT+1`).

  • 'full': equivalent to 'EEEE, MMMM d, y, h:mm:ss a zzzz' (`Monday, June 15, 2015 at

    'full': 等价于 'EEEE, MMMM d, y, h:mm:ss a zzzz' (`Monday, June 15, 2015 at

9:03:01 AM GMT+01:00`).

  • 'shortDate': equivalent to 'M/d/yy' (6/15/15).

    'shortDate': 等价于 'M/d/yy' (6/15/15).

  • 'mediumDate': equivalent to 'MMM d, y' (Jun 15, 2015).

    'mediumDate': 等价于 'MMM d, y' (Jun 15, 2015).

  • 'longDate': equivalent to 'MMMM d, y' (June 15, 2015).

    'longDate': 等价于 'MMMM d, y' (June 15, 2015).

  • 'fullDate': equivalent to 'EEEE, MMMM d, y' (Monday, June 15, 2015).

    'fullDate': 等价于 'EEEE, MMMM d, y' (Monday, June 15, 2015).

  • 'shortTime': equivalent to 'h:mm a' (9:03 AM).

    'shortTime': 等价于 'h:mm a' (9:03 AM).

  • 'mediumTime': equivalent to 'h:mm:ss a' (9:03:01 AM).

    'mediumTime': 等价于 'h:mm:ss a' (9:03:01 AM).

  • 'longTime': equivalent to 'h:mm:ss a z' (9:03:01 AM GMT+1).

    'longTime': 等价于 'h:mm:ss a z' (9:03:01 AM GMT+1).

  • 'fullTime': equivalent to 'h:mm:ss a zzzz' (9:03:01 AM GMT+01:00).

    'fullTime': 等价于 'h:mm:ss a zzzz' (9:03:01 AM GMT+01:00).

Custom format options

自定义格式选项

You can construct a format string using symbols to specify the components of a date-time value, as described in the following table. Format details depend on the locale. Fields marked with (*) are only available in the extra data set for the given locale.

你可以使用符号来构造出格式字符串，以指定日期-时间值的各个部分，如下表所示。 具体格式取决于区域设置。 标 * 的字段表示仅在特定区域的数据中才有效。

Field type字段类型Format格式Description说明Example Value范例值
Era纪元G, GG & GGGAbbreviated缩略AD
GGGGWide全称Anno Domini
GGGGGNarrow最简A
Year年yNumeric数字:minimum digits最小位数2, 20, 201, 2017, 20173
yyNumeric数字: 2digits + zero padded数字 + 0 补位02, 20, 01, 17, 73
yyyNumeric数字: 3digits + zero padded数字 + 0 补位002, 020, 201, 2017, 20173
yyyyNumeric数字: 4digits or more + zero padded或更多数字 + 0 补位0002, 0020, 0201, 2017, 20173
Month月MNumeric数字:1 digit1 数字9, 12
MMNumeric数字: 2digits + zero padded数字 + 0 补位09, 12
MMMAbbreviated缩略Sep
MMMMWide全称September
MMMMMNarrow最简S
Month standalone独立月份LNumeric数字:1 digit1 数字9, 12
LLNumeric数字: 2digits + zero padded数字 + 0 补位09, 12
LLLAbbreviated缩略Sep
LLLLWide全称September
LLLLLNarrow最简S
Week of year年内周次wNumeric数字:minimum digits最小位数1... 53
wwNumeric数字: 2digits + zero padded数字 + 0 补位01... 53
Week of month月内周次WNumeric数字:1 digit1 数字1... 5
Day of month月内日dNumeric数字:minimum digits最小位数1
ddNumeric数字: 2digits + zero padded数字 + 0 补位01
Week day周内日E, EE & EEEAbbreviated缩略Tue
EEEEWide全称Tuesday
EEEEENarrow最简T
EEEEEEShort短Tu
Period日内时段a, aa & aaaAbbreviated缩略am/pm or AM/PM
aaaaWide全称(fallback to a when missing)(缺少时等同于 a )ante meridiem/post meridiem
aaaaaNarrow最简a/p
Period*日内时段B, BB & BBBAbbreviated缩略mid.
BBBBWide全称am, pm, midnight, noon, morning, afternoon, evening, night
BBBBBNarrow最简md
Period standalone*独立时段b, bb & bbbAbbreviated缩略mid.
bbbbWide全称am, pm, midnight, noon, morning, afternoon, evening, night
bbbbbNarrow最简md
Hour 1-12小时(1-12)hNumeric数字:minimum digits最小位数1, 12
hhNumeric数字: 2digits + zero padded数字 + 0 补位01, 12
Hour 0-23小时(0-23)HNumeric数字:minimum digits最小位数0, 23
HHNumeric数字: 2digits + zero padded数字 + 0 补位00, 23
Minute分mNumeric数字:minimum digits最小位数8, 59
mmNumeric数字: 2digits + zero padded数字 + 0 补位08, 59
Second秒sNumeric数字:minimum digits最小位数0... 59
ssNumeric数字: 2digits + zero padded数字 + 0 补位00... 59
Fractional seconds分数秒SNumeric数字:1 digit1 数字0... 9
SSNumeric数字: 2digits + zero padded数字 + 0 补位00... 99
SSSNumeric数字: 3digits + zero padded数字 + 0 补位(=milliseconds毫秒)000... 999
Zone时区z, zz & zzzShort specific non location format (fallback to O)位置无关短格式（默认为0）GMT-8
zzzzLong specific non location format (fallback to OOOO)位置无关长格式（默认为0000）GMT-08:00
Z, ZZ & ZZZISO8601basic format基本格式-0800
ZZZZLong localized GMT format本地化 GMT 长格式GMT-8:00
ZZZZZISO8601extended format + Z indicator for offset 0扩展格式 + 偏移为 0 时用 Z 表示(= XXXXX)-08:00
O, OO & OOOShort localized GMT format本地化 GMT 短格式GMT-8
OOOOLong localized GMT format本地化 GMT 长格式GMT-08:00

Note that timezone correction is not applied to an ISO string that has no time component, such as "2016-09-19"

请注意，时区校正不适用于没有时间部分的ISO字符串，例如“2016-09-19”

Format examples

格式范例

These examples transform a date into various formats, assuming that dateObj is a JavaScript Date object for year: 2015, month: 6, day: 15, hour: 21, minute: 43, second: 11, given in the local time for the en-US locale.

下面这些例子会把日期转换成多种格式。 这里假设 dateObj 是个 JavaScript 的 Date 对象： 2015 年 6 月 15 日 21 时 43 分 11 秒， 使用的是 en-US 区域的当地时间。

{{ dateObj | date }} // output is 'Jun 15, 2015' {{ dateObj | date:'medium' }} // output is 'Jun 15, 2015, 9:43:11 PM' {{ dateObj | date:'shortTime' }} // output is '9:43 PM' {{ dateObj | date:'mmss' }} // output is '43:11'

Usage example

使用范例

The following component uses a date pipe to display the current date in different formats.

下列组件借助一个日期管道来以不同的格式显示当前日期。

@Component({ selector: 'date-pipe', template: `<div> <p>Today is {{today | date}}</p> <p>Or if you prefer, {{today | date:'fullDate'}}</p> <p>The time is {{today | date:'h:mm a z'}}</p> </div>` }) // Get the current date and time as a date-time value. export class DatePipeComponent { today: number = Date.now(); }