diff --git a/aio/content/translations/cn/api-plan.md b/aio/content/translations/cn/api-plan.md index 5c0e9f6ebe..5f79a2432e 100644 --- a/aio/content/translations/cn/api-plan.md +++ b/aio/content/translations/cn/api-plan.md @@ -13,7 +13,7 @@ [x] |router/Router | 4,049 | 1.26 [ ] |animations/animate | 3,817 | 1.19 [x] |common/NgClass | 3,715 | 1.15 -[ ] |common/DatePipe | 3,576 | 1.11 +[x] |common/DatePipe | 3,576 | 1.11 [ ] |forms/FormsModule | 3,381 | 1.05 [x] |core/Input | 3,354 | 1.04 [x] |core/EventEmitter | 3,202 | 0.99 diff --git a/packages/common/src/pipes/date_pipe.ts b/packages/common/src/pipes/date_pipe.ts index c0365c42b5..ede7d40ebe 100644 --- a/packages/common/src/pipes/date_pipe.ts +++ b/packages/common/src/pipes/date_pipe.ts @@ -17,10 +17,15 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * * Formats a date value according to locale rules. * + * 根据区域设置规则格式化日期值。 + * * 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](guide/i18n#i18n-pipes) for more information. * + * Angular 只自带了 `en-US` 区域的数据。要想在其它语言中对日期进行本地化,你必须导入相应的区域数据。 + * 欲知详情,参见 [I18n guide](guide/i18n#i18n-pipes)。 + * * @see `formatDate()` * * @@ -30,97 +35,154 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * 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 | + * 你可以使用符号来构造出格式字符串,以指定日期-时间值的各个部分,如下表所示。 + * 具体格式取决于区域设置。 + * 标 `*` 的字段表示仅在特定区域的数据中才有效。 + * + * | Field type字段类型 | Format格式 | Description说明 | Example Value范例值 | * |--------------------|-------------|---------------------------------------------------------------|------------------------------------------------------------| - * | Era | G, GG & GGG | Abbreviated | AD | - * | | GGGG | Wide | Anno Domini | - * | | GGGGG | Narrow | A | - * | Year | y | Numeric: minimum digits | 2, 20, 201, 2017, 20173 | - * | | yy | Numeric: 2 digits + zero padded | 02, 20, 01, 17, 73 | - * | | yyy | Numeric: 3 digits + zero padded | 002, 020, 201, 2017, 20173 | - * | | yyyy | Numeric: 4 digits or more + zero padded | 0002, 0020, 0201, 2017, 20173 | - * | Month | M | Numeric: 1 digit | 9, 12 | - * | | MM | Numeric: 2 digits + zero padded | 09, 12 | - * | | MMM | Abbreviated | Sep | - * | | MMMM | Wide | September | - * | | MMMMM | Narrow | S | - * | Month standalone | L | Numeric: 1 digit | 9, 12 | - * | | LL | Numeric: 2 digits + zero padded | 09, 12 | - * | | LLL | Abbreviated | Sep | - * | | LLLL | Wide | September | - * | | LLLLL | Narrow | S | - * | Week of year | w | Numeric: minimum digits | 1... 53 | - * | | ww | Numeric: 2 digits + zero padded | 01... 53 | - * | Week of month | W | Numeric: 1 digit | 1... 5 | - * | Day of month | d | Numeric: minimum digits | 1 | - * | | dd | Numeric: 2 digits + zero padded | 01 | - * | Week day | E, EE & EEE | Abbreviated | Tue | - * | | EEEE | Wide | Tuesday | - * | | EEEEE | Narrow | T | - * | | EEEEEE | Short | Tu | - * | Period | a, aa & aaa | Abbreviated | am/pm or AM/PM | - * | | aaaa | Wide (fallback to `a` when missing) | ante meridiem/post meridiem | - * | | aaaaa | Narrow | a/p | - * | Period* | B, BB & BBB | Abbreviated | mid. | - * | | BBBB | Wide | am, pm, midnight, noon, morning, afternoon, evening, night | - * | | BBBBB | Narrow | md | - * | Period standalone* | b, bb & bbb | Abbreviated | mid. | - * | | bbbb | Wide | am, pm, midnight, noon, morning, afternoon, evening, night | - * | | bbbbb | Narrow | md | - * | Hour 1-12 | h | Numeric: minimum digits | 1, 12 | - * | | hh | Numeric: 2 digits + zero padded | 01, 12 | - * | Hour 0-23 | H | Numeric: minimum digits | 0, 23 | - * | | HH | Numeric: 2 digits + zero padded | 00, 23 | - * | Minute | m | Numeric: minimum digits | 8, 59 | - * | | mm | Numeric: 2 digits + zero padded | 08, 59 | - * | Second | s | Numeric: minimum digits | 0... 59 | - * | | ss | Numeric: 2 digits + zero padded | 00... 59 | - * | Fractional seconds | S | Numeric: 1 digit | 0... 9 | - * | | SS | Numeric: 2 digits + zero padded | 00... 99 | - * | | SSS | Numeric: 3 digits + zero padded (= milliseconds) | 000... 999 | - * | Zone | z, zz & zzz | Short specific non location format (fallback to O) | GMT-8 | - * | | zzzz | Long specific non location format (fallback to OOOO) | GMT-08:00 | - * | | Z, ZZ & ZZZ | ISO8601 basic format | -0800 | - * | | ZZZZ | Long localized GMT format | GMT-8:00 | - * | | ZZZZZ | ISO8601 extended format + Z indicator for offset 0 (= XXXXX) | -08:00 | - * | | O, OO & OOO | Short localized GMT format | GMT-8 | - * | | OOOO | Long localized GMT format | GMT-08:00 | + * | Era纪元 | G, GG & GGG | Abbreviated缩略| AD | + * | | GGGG | Wide全称| Anno Domini | + * | | GGGGG | Narrow最简| A | + * | Year | y | Numeric数字: minimum digits最小位数 | 2, 20, 201, 2017, 20173 | + * | | yy | Numeric数字: 2 digits + zero padded数字 + 0 补位 | 02, 20, 01, 17, 73 | + * | | yyy | Numeric数字: 3 digits + zero padded数字 + 0 补位 | 002, 020, 201, 2017, 20173 | + * | | yyyy | Numeric数字: 4 digits or more + zero padded或更多数字 + 0 补位 | 0002, 0020, 0201, 2017, 20173 | + * | Month | M | Numeric数字: 1 digit1 数字 | 9, 12 | + * | | MM | Numeric数字: 2 digits + zero padded数字 + 0 补位 | 09, 12 | + * | | MMM | Abbreviated缩略| Sep | + * | | MMMM | Wide全称| September | + * | | MMMMM | Narrow最简| S | + * | Month standalone独立月份 | L | Numeric数字: 1 digit1 数字 | 9, 12 | + * | | LL | Numeric数字: 2 digits + zero padded数字 + 0 补位 | 09, 12 | + * | | LLL | Abbreviated缩略| Sep | + * | | LLLL | Wide全称| September | + * | | LLLLL | Narrow最简| S | + * | Week of year年内周次 | w | Numeric数字: minimum digits最小位数 | 1... 53 | + * | | ww | Numeric数字: 2 digits + zero padded数字 + 0 补位 | 01... 53 | + * | Week of month月内周次 | W | Numeric数字: 1 digit1 数字 | 1... 5 | + * | Day of month月内日 | d | Numeric数字: minimum digits最小位数 | 1 | + * | | dd | Numeric数字: 2 digits + zero padded数字 + 0 补位 | 01 | + * | Week day周内日 | E, EE & EEE | Abbreviated缩略| Tue | + * | | EEEE | Wide全称| Tuesday | + * | | EEEEE | Narrow最简| T | + * | | EEEEEE | Short | Tu | + * | Period日内时段 | a, aa & aaa | Abbreviated缩略| am/pm or AM/PM | + * | | aaaa | Wide全称(fallback to `a` when missing)(缺少时等同于 `a`)| ante meridiem/post meridiem | + * | | aaaaa | Narrow最简| a/p | + * | Period*日内时段 | B, BB & BBB | Abbreviated缩略| mid. | + * | | BBBB | Wide全称| am, pm, midnight, noon, morning, afternoon, evening, night | + * | | BBBBB | Narrow最简| md | + * | Period standalone*独立时段 | b, bb & bbb | Abbreviated缩略| mid. | + * | | bbbb | Wide全称| am, pm, midnight, noon, morning, afternoon, evening, night | + * | | bbbbb | Narrow最简| md | + * | Hour 1-12小时(1-12) | h | Numeric数字: minimum digits最小位数 | 1, 12 | + * | | hh | Numeric数字: 2 digits + zero padded数字 + 0 补位 | 01, 12 | + * | Hour 0-23小时(0-23) | H | Numeric数字: minimum digits最小位数 | 0, 23 | + * | | HH | Numeric数字: 2 digits + zero padded数字 + 0 补位 | 00, 23 | + * | Minute | m | Numeric数字: minimum digits最小位数 | 8, 59 | + * | | mm | Numeric数字: 2 digits + zero padded数字 + 0 补位 | 08, 59 | + * | Second | s | Numeric数字: minimum digits最小位数 | 0... 59 | + * | | ss | Numeric数字: 2 digits + zero padded数字 + 0 补位 | 00... 59 | + * | Fractional seconds分数秒 | S | Numeric数字: 1 digit1 数字 | 0... 9 | + * | | SS | Numeric数字: 2 digits + zero padded数字 + 0 补位 | 00... 99 | + * | | SSS | Numeric数字: 3 digits + zero padded数字 + 0 补位 (= milliseconds毫秒) | 000... 999 | + * | Zone时区 | z, zz & zzz | Short specific non location format (fallback to O)位置无关短格式(默认为0) | GMT-8 | + * | | zzzz | Long specific non location format (fallback to OOOO)位置无关长格式(默认为0000) | GMT-08:00 | + * | | Z, ZZ & ZZZ | ISO8601 basic format基本格式 | -0800 | + * | | ZZZZ | Long localized GMT format本地化 GMT 长格式 | GMT-8:00 | + * | | ZZZZZ | ISO8601 extended format + Z indicator for offset 0扩展格式 + 偏移为 0 时用 Z 表示 (= XXXXX) | -08:00 | + * | | O, OO & OOO | Short localized GMT format本地化 GMT 短格式 | GMT-8 | + * | | OOOO | Long 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' @@ -130,8 +192,12 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * * ### Usage example * + * ### 使用范例 + * * The following component uses a date pipe to display the current date in different formats. * + * 下列组件借助一个日期管道来以不同的格式显示当前日期。 + * * ``` * @Component({ * selector: 'date-pipe', @@ -156,15 +222,31 @@ export class DatePipe implements PipeTransform { /** * @param value 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)。 + * * @param format The date/time components to include, using predefined options or a * custom format string. + * + * 要包含的日期、时间部分的格式,使用预定义选项或自定义格式字符串。 + * * @param timezone 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 或美国大陆时区的缩写。默认为最终用户机器上的本地系统时区。 + * * @param locale 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](guide/i18n#setting-up-the-locale-of-your-app). + * + * 要使用的区域格式规则的区域代码。 + * 如果不提供,就使用 `LOCALE_ID` 的值,默认为 `en-US`。 + * 参见[设置应用的区域](guide/i18n#setting-up-the-locale-of-your-app)。 + * * @returns A date string in the desired format. + * + * 指定格式的日期字符串。 */ transform(value: any, format = 'mediumDate', timezone?: string, locale?: string): string|null { if (value == null || value === '' || value !== value) return null;