cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(pipes): updated pipe documentation

Browse Source
This commit is contained in:
Misko Hevery
2016-09-08 21:41:09 -07:00
committed by Igor Minar
parent caa1cd2470
commit 2c42a50fc3
20 changed files with 321 additions and 292 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
modules/@angular/common/src/pipes/date_pipe.ts
View File

@ -15,23 +15,25 @@ import {InvalidPipeArgumentError} from './invalid_pipe_argument_error';
/**
* Formats a date value to a string based on the requested format.
* @ngModule CommonModule
* @whatItDoes Formats a date according to locale rules.
* @howToUse `date_expression | date[:format]`
* @description
*
* WARNINGS:
* - this pipe is marked as pure hence it will not be re-evaluated when the input is mutated.
* Instead users should treat the date as an immutable object and change the reference when the
* pipe needs to re-run (this is to avoid reformatting the date on every change detection run
* which would be an expensive operation).
* - this pipe uses the Internationalization API. Therefore it is only reliable in Chrome and Opera
* browsers.
* Where:
* - `expression` is a date object or a number (milliseconds since UTC epoch) or an ISO string
* (https://www.w3.org/TR/NOTE-datetime).
* - `format` indicates which date/time components to include. The format can be predifined as
* shown below or custom as shown in the table.
* - `'medium'`: equivalent to `'yMMMdjms'` (e.g. `Sep 3, 2010, 12:05:08 PM` for `en-US`)
* - `'short'`: equivalent to `'yMdjm'` (e.g. `9/3/2010, 12:05 PM` for `en-US`)
* - `'fullDate'`: equivalent to `'yMMMMEEEEd'` (e.g. `Friday, September 3, 2010` for `en-US`)
* - `'longDate'`: equivalent to `'yMMMMd'` (e.g. `September 3, 2010` for `en-US`)
* - `'mediumDate'`: equivalent to `'yMMMd'` (e.g. `Sep 3, 2010` for `en-US`)
* - `'shortDate'`: equivalent to `'yMd'` (e.g. `9/3/2010` for `en-US`)
* - `'mediumTime'`: equivalent to `'jms'` (e.g. `12:05:08 PM` for `en-US`)
* - `'shortTime'`: equivalent to `'jm'` (e.g. `12:05 PM` for `en-US`)
*
* ## Usage
*
* expression | date[:format]
*
* where `expression` is a date object or a number (milliseconds since UTC epoch) or an ISO string
* (https://www.w3.org/TR/NOTE-datetime) and `format` indicates which date/time components to
* include:
*
* | Component | Symbol | Short Form | Long Form | Numeric | 2-digit |
* |-----------|:------:|--------------|-------------------|-----------|-----------|
@ -52,19 +54,16 @@ import {InvalidPipeArgumentError} from './invalid_pipe_argument_error';
* In javascript, only the components specified will be respected (not the ordering,
* punctuations, ...) and details of the formatting will be dependent on the locale.
*
* `format` can also be one of the following predefined formats:
*
* - `'medium'`: equivalent to `'yMMMdjms'` (e.g. Sep 3, 2010, 12:05:08 PM for en-US)
* - `'short'`: equivalent to `'yMdjm'` (e.g. 9/3/2010, 12:05 PM for en-US)
* - `'fullDate'`: equivalent to `'yMMMMEEEEd'` (e.g. Friday, September 3, 2010 for en-US)
* - `'longDate'`: equivalent to `'yMMMMd'` (e.g. September 3, 2010 for en-US)
* - `'mediumDate'`: equivalent to `'yMMMd'` (e.g. Sep 3, 2010 for en-US)
* - `'shortDate'`: equivalent to `'yMd'` (e.g. 9/3/2010 for en-US)
* - `'mediumTime'`: equivalent to `'jms'` (e.g. 12:05:08 PM for en-US)
* - `'shortTime'`: equivalent to `'jm'` (e.g. 12:05 PM for en-US)
*
* Timezone of the formatted text will be the local system timezone of the end-user's machine.
*
* WARNINGS:
* - this pipe is marked as pure hence it will not be re-evaluated when the input is mutated.
* Instead users should treat the date as an immutable object and change the reference when the
* pipe needs to re-run (this is to avoid reformatting the date on every change detection run
* which would be an expensive operation).
* - this pipe uses the Internationalization API. Therefore it is only reliable in Chrome and Opera
* browsers.
*
* ### Examples
*
* Assuming `dateObj` is (year: 2015, month: 6, day: 15, hour: 21, minute: 43, second: 11)
@ -77,7 +76,7 @@ import {InvalidPipeArgumentError} from './invalid_pipe_argument_error';
* {{ dateObj | date:'mmss' }} // output is '43:11'
* ```
*
* {@example core/pipes/ts/date_pipe/date_pipe_example.ts region='DatePipe'}
* {@example common/pipes/ts/date_pipe.ts region='DatePipe'}
*
* @stable
*/