honeymoose/angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: test api doc for pipes (#24141)

Browse Source 
PR Close #24141
This commit is contained in:
Judy Bogart 2018-05-25 14:44:33 -07:00 committed by Jason Aden
parent 941d2cdaaf
commit d244523ae6
4 changed files with 201 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
packages/common/src/pipes/case_conversion_pipes.ts
View File

File diff suppressed because one or more lines are too long

123
packages/common/src/pipes/date_pipe.ts
View File

@ -15,11 +15,48 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
* @ngModule CommonModule * @ngModule CommonModule
* @description * @description
* *
* Uses the function {@link formatDate} to format a date according to locale rules. * Formats a date value according to locale rules.
* *
* The following tabled describes the formatting options. * 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.
* *
* | Field Type | Format | Description | Example Value | * @see `formatDate()`
*
*
* @usageNotes
*
* 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.
*
* - `'short'`: equivalent to `'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`).
* - `'long'`: equivalent to `'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
* 9:03:01 AM GMT+01:00`).
* - `'shortDate'`: equivalent to `'M/d/yy'` (`6/15/15`).
* - `'mediumDate'`: equivalent to `'MMM d, y'` (`Jun 15, 2015`).
* - `'longDate'`: equivalent to `'MMMM d, y'` (`June 15, 2015`).
* - `'fullDate'`: equivalent to `'EEEE, MMMM d, y'` (`Monday, June 15, 2015`).
* - `'shortTime'`: equivalent to `'h:mm a'` (`9:03 AM`).
* - `'mediumTime'`: equivalent to `'h:mm:ss a'` (`9:03:01 AM`).
* - `'longTime'`: equivalent to `'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`).
*
* ### 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 & GGG | Abbreviated | AD | * | Era | G, GG & GGG | Abbreviated | AD |
* | | GGGG | Wide | Anno Domini | * | | GGGG | Wide | Anno Domini |
@ -75,30 +112,40 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
* | | O, OO & OOO | Short localized GMT format | GMT-8 | * | | O, OO & OOO | Short localized GMT format | GMT-8 |
* | | OOOO | Long localized GMT format | GMT-08:00 | * | | OOOO | Long localized GMT format | GMT-08:00 |
* *
* Note that timezone correction is not applied to an ISO string that has no time component, such as "2016-09-19"
* *
* When the expression is a ISO string without time (e.g. 2016-09-19) the time zone offset is not * ### Format examples
* applied and the formatted text will have the same day, month and year of the expression.
* *
* WARNINGS: * These examples transform a date into various formats,
* - this pipe has only access to en-US locale data by default. If you want to localize the dates * assuming that `dateObj` is a JavaScript `Date` object for
* in another language, you will have to import data for other locales. * year: 2015, month: 6, day: 15, hour: 21, minute: 43, second: 11,
* See the ["I18n guide"](guide/i18n#i18n-pipes) to know how to import additional locale * given in the local time for the `en-US` locale.
* data.
* - Fields suffixed with * are only available in the extra dataset.
* See the ["I18n guide"](guide/i18n#i18n-pipes) to know how to import extra locale
* data.
* - 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).
* *
* ### Examples * ```
* {{ 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'
* ```
* *
* Assuming `dateObj` is (year: 2015, month: 6, day: 15, hour: 21, minute: 43, second: 11) * ### Usage example
* in the _local_ time and locale is 'en-US':
* *
* {@example common/pipes/ts/date_pipe.ts region='DatePipe'} * 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();
* }
* ```
* *
*/ */
// clang-format on // clang-format on
@ -107,29 +154,17 @@ export class DatePipe implements PipeTransform {
constructor(@Inject(LOCALE_ID) private locale: string) {} constructor(@Inject(LOCALE_ID) private locale: string) {}
/** /**
* @param value a date object or a number (milliseconds since UTC epoch) or an ISO string * @param value The date expression: a `Date` object, a number
* (https://www.w3.org/TR/NOTE-datetime). * (milliseconds since UTC epoch), or an ISO string (https://www.w3.org/TR/NOTE-datetime).
* @param format indicates which date/time components to include. The format can be predefined as * @param format The date/time components to include, using predefined options or a
* shown below (all examples are given for `en-US`) or custom as shown in the table. * custom format string.
* - `'short'`: equivalent to `'M/d/yy, h:mm a'` (e.g. `6/15/15, 9:03 AM`). * @param timezone A timezone offset (such as `'+0430'`), or a standard
* - `'medium'`: equivalent to `'MMM d, y, h:mm:ss a'` (e.g. `Jun 15, 2015, 9:03:01 AM`). * UTC/GMT or continental US timezone abbreviation. Default is
* - `'long'`: equivalent to `'MMMM d, y, h:mm:ss a z'` (e.g. `June 15, 2015 at 9:03:01 AM * the local system timezone of the end-user's machine.
* GMT+1`). * @param locale A locale code for the locale format rules to use.
* - `'full'`: equivalent to `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (e.g. `Monday, June 15, 2015 at * When not supplied, uses the value of `LOCALE_ID`, which is `en-US` by default.
* 9:03:01 AM GMT+01:00`). * See [Setting your app locale](guide/i18n#setting-up-the-locale-of-your-app).
* - `'shortDate'`: equivalent to `'M/d/yy'` (e.g. `6/15/15`). * @returns A date string in the desired format.
* - `'mediumDate'`: equivalent to `'MMM d, y'` (e.g. `Jun 15, 2015`).
* - `'longDate'`: equivalent to `'MMMM d, y'` (e.g. `June 15, 2015`).
* - `'fullDate'`: equivalent to `'EEEE, MMMM d, y'` (e.g. `Monday, June 15, 2015`).
* - `'shortTime'`: equivalent to `'h:mm a'` (e.g. `9:03 AM`).
* - `'mediumTime'`: equivalent to `'h:mm:ss a'` (e.g. `9:03:01 AM`).
* - `'longTime'`: equivalent to `'h:mm:ss a z'` (e.g. `9:03:01 AM GMT+1`).
* - `'fullTime'`: equivalent to `'h:mm:ss a zzzz'` (e.g. `9:03:01 AM GMT+01:00`).
* @param timezone to be used for formatting the time. It understands UTC/GMT and the continental
* US time zone
* abbreviations, but for general use, use a time zone offset (e.g. `'+0430'`).
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default).
*/ */
transform(value: any, format = 'mediumDate', timezone?: string, locale?: string): string|null { transform(value: any, format = 'mediumDate', timezone?: string, locale?: string): string|null {
if (value == null || value === '' || value !== value) return null; if (value == null || value === '' || value !== value) return null;

11
packages/common/src/pipes/json_pipe.ts
View File

@ -12,14 +12,21 @@ import {Pipe, PipeTransform} from '@angular/core';
* @ngModule CommonModule * @ngModule CommonModule
* @description * @description
* *
* Converts value into string using `JSON.stringify`. Useful for debugging. * Converts a value into its JSON-format representation. Useful for debugging.
* *
* ### Example * @usageNotes
*
* The following component uses a JSON pipe to convert an object
* to JSON format, and displays the string in both formats for comparison.
* {@example common/pipes/ts/json_pipe.ts region='JsonPipe'} * {@example common/pipes/ts/json_pipe.ts region='JsonPipe'}
* *
* *
*/ */
@Pipe({name: 'json', pure: false}) @Pipe({name: 'json', pure: false})
export class JsonPipe implements PipeTransform { export class JsonPipe implements PipeTransform {
/**
* @param value A value of any type to convert into a JSON-format string.
*/
transform(value: any): string { return JSON.stringify(value, null, 2); } transform(value: any): string { return JSON.stringify(value, null, 2); }
} }

122
packages/common/src/pipes/number_pipe.ts
View File

@ -15,14 +15,19 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
* @ngModule CommonModule * @ngModule CommonModule
* @description * @description
* *
* Uses the function {@link formatNumber} to format a number according to locale rules. * Transforms a number into a string,
* formatted according to locale rules that determine group sizing and
* separator, decimal-point character, and other locale-specific
* configurations.
* *
* Formats a number as text. Group sizing and separator and other locale-specific * @see `formatNumber()`
* configurations are based on the locale.
* *
* ### Example * @usageNotes
* The following code shows how the pipe transforms numbers
* into text strings, according to various format specifications,
* where the caller's default locale is `en-US`.
* *
* {@example common/pipes/ts/number_pipe.ts region='NumberPipe'} * <code-example path="common/pipes/ts/number_pipe.ts" region='NumberPipe'></code-example>
* *
* *
*/ */
@ -31,16 +36,19 @@ export class DecimalPipe implements PipeTransform {
constructor(@Inject(LOCALE_ID) private _locale: string) {} constructor(@Inject(LOCALE_ID) private _locale: string) {}
/** /**
* @param value a number to be formatted. * @param value The number to be formatted.
* @param digitsInfo a `string` which has a following format: <br> * @param digitsInfo Decimal representation options, specified by a string
* in the following format:<br>
* <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>. * <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>.
* - `minIntegerDigits` is the minimum number of integer digits to use. Defaults to `1`. * - `minIntegerDigits`: The minimum number of integer digits before the decimal point.
* - `minFractionDigits` is the minimum number of digits after the decimal point. Defaults to * Default is `1`.
* `0`. * - `minFractionDigits`: The minimum number of digits after the decimal point.
* - `maxFractionDigits` is the maximum number of digits after the decimal point. Defaults to * Default is `0`.
* `3`. * - `maxFractionDigits`: The maximum number of digits after the decimal point.
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by * Default is `3`.
* default). * @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).
*/ */
transform(value: any, digitsInfo?: string, locale?: string): string|null { transform(value: any, digitsInfo?: string, locale?: string): string|null {
if (isEmpty(value)) return null; if (isEmpty(value)) return null;
@ -60,12 +68,19 @@ export class DecimalPipe implements PipeTransform {
* @ngModule CommonModule * @ngModule CommonModule
* @description * @description
* *
* Uses the function {@link formatPercent} to format a number as a percentage according * Transforms a number to a percentage
* to locale rules. * string, formatted according to locale rules that determine group sizing and
* separator, decimal-point character, and other locale-specific
* configurations.
* *
* ### Example * @see `formatPercent()`
* *
* {@example common/pipes/ts/percent_pipe.ts region='PercentPipe'} * @usageNotes
* The following code shows how the pipe transforms numbers
* into text strings, according to various format specifications,
* where the caller's default locale is `en-US`.
*
* <code-example path="common/pipes/ts/percent_pipe.ts" region='PercentPipe'></code-example>
* *
* *
*/ */
@ -75,10 +90,19 @@ export class PercentPipe implements PipeTransform {
/** /**
* *
* @param value a number to be formatted as a percentage. * @param value The number to be formatted as a percentage.
* @param digitsInfo see {@link DecimalPipe} for more details. * @param digitsInfo Decimal representation options, specified by a string
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by * in the following format:<br>
* default). * <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>.
* - `minIntegerDigits`: The minimum number of integer digits before the decimal point.
* Default is `1`.
* - `minFractionDigits`: The minimum number of digits after the decimal point.
* Default is `0`.
* - `maxFractionDigits`: The maximum number of digits after the decimal point.
* Default is `3`.
* @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).
*/ */
transform(value: any, digitsInfo?: string, locale?: string): string|null { transform(value: any, digitsInfo?: string, locale?: string): string|null {
if (isEmpty(value)) return null; if (isEmpty(value)) return null;
@ -98,12 +122,19 @@ export class PercentPipe implements PipeTransform {
* @ngModule CommonModule * @ngModule CommonModule
* @description * @description
* *
* Uses the functions {@link getCurrencySymbol} and {@link formatCurrency} to format a * Transforms a number to a currency string, formatted according to locale rules
* number as currency using locale rules. * that determine group sizing and separator, decimal-point character,
* and other locale-specific configurations.
* *
* ### Example * @see `getCurrencySymbol()`
* @see `formatCurrency()`
* *
* {@example common/pipes/ts/currency_pipe.ts region='CurrencyPipe'} * @usageNotes
* The following code shows how the pipe transforms numbers
* into text strings, according to various format specifications,
* where the caller's default locale is `en-US`.
*
* <code-example path="common/pipes/ts/currency_pipe.ts" region='CurrencyPipe'></code-example>
* *
* *
*/ */
@ -113,20 +144,31 @@ export class CurrencyPipe implements PipeTransform {
/** /**
* *
* @param value a number to be formatted as currency. * @param value The number to be formatted as currency.
* @param currencyCodeis the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, * @param currencyCode The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code,
* such as `USD` for the US dollar and `EUR` for the euro. * such as `USD` for the US dollar and `EUR` for the euro.
* @param display indicates whether to show the currency symbol, the code or a custom value: * @param display The format for the currency indicator. One of the following:
* - `code`: use code (e.g. `USD`). * - `code`: Show the code (such as `USD`).
* - `symbol`(default): use symbol (e.g. `$`). * - `symbol`(default): Show the symbol (such as `$`).
* - `symbol-narrow`: some countries have two symbols for their currency, one regular and one * - `symbol-narrow`: Use the narrow symbol for locales that have two symbols for their
* narrow (e.g. the canadian dollar CAD has the symbol `CA$` and the symbol-narrow `$`). * currency.
* - `string`: use this value instead of a code or a symbol. * For example, the Canadian dollar CAD has the symbol `CA$` and the symbol-narrow `$`. If the
* - boolean (deprecated from v5): `true` for symbol and false for `code`. * locale has no narrow symbol, uses the standard symbol for the locale.
* If there is no narrow symbol for the chosen currency, the regular symbol will be used. * - String: Use the given string value instead of a code or a symbol.
* @param digitsInfo see {@link DecimalPipe} for more details. * - Boolean (marked deprecated in v5): `true` for symbol and false for `code`.
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by *
* default). * @param digitsInfo Decimal representation options, specified by a string
* in the following format:<br>
* <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>.
* - `minIntegerDigits`: The minimum number of integer digits before the decimal point.
* Default is `1`.
* - `minFractionDigits`: The minimum number of digits after the decimal point.
* Default is `0`.
* - `maxFractionDigits`: The maximum number of digits after the decimal point.
* Default is `3`.
* @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).
*/ */
transform( transform(
value: any, currencyCode?: string, value: any, currencyCode?: string,
@ -167,7 +209,7 @@ function isEmpty(value: any): boolean {
} }
/** /**
* Transforms a string into a number (if needed) * Transforms a string into a number (if needed).
*/ */
function strToNumber(value: number | string): number { function strToNumber(value: number | string): number {
// Convert strings to numbers // Convert strings to numbers