docs(common): move Pipe param docs to `transform` function (#23062)
PR Close #23062
This commit is contained in:
parent
079d8e57d5
commit
cdd05bd2ca
|
@ -17,30 +17,7 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
|
|||
*
|
||||
* Uses the function {@link formatDate} to format a date according to locale rules.
|
||||
*
|
||||
* Where:
|
||||
* - `value` 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 predefined as
|
||||
* shown below (all examples are given for `en-US`) or custom as shown in the table.
|
||||
* - `'short'`: equivalent to `'M/d/yy, h:mm a'` (e.g. `6/15/15, 9:03 AM`).
|
||||
* - `'medium'`: equivalent to `'MMM d, y, h:mm:ss a'` (e.g. `Jun 15, 2015, 9:03:01 AM`).
|
||||
* - `'long'`: equivalent to `'MMMM d, y, h:mm:ss a z'` (e.g. `June 15, 2015 at 9:03:01 AM GMT+1`).
|
||||
* - `'full'`: equivalent to `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (e.g. `Monday, June 15, 2015 at
|
||||
* 9:03:01 AM GMT+01:00`).
|
||||
* - `'shortDate'`: equivalent to `'M/d/yy'` (e.g. `6/15/15`).
|
||||
* - `'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`).
|
||||
* - `timezone` to be used for formatting. It understands UTC/GMT and the continental US time zone
|
||||
* abbreviations, but for general use, use a time zone offset (e.g. `'+0430'`).
|
||||
* If not specified, the local system timezone of the end-user's browser will be used.
|
||||
* - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
|
||||
* default).
|
||||
*
|
||||
* The following tabled describes the formatting options.
|
||||
*
|
||||
* | Field Type | Format | Description | Example Value |
|
||||
* |--------------------|-------------|---------------------------------------------------------------|------------------------------------------------------------|
|
||||
|
@ -129,6 +106,29 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
|
|||
export class DatePipe implements PipeTransform {
|
||||
constructor(@Inject(LOCALE_ID) private locale: string) {}
|
||||
|
||||
/**
|
||||
* @param value a date object or a number (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
|
||||
* shown below (all examples are given for `en-US`) or custom as shown in the table.
|
||||
* - `'short'`: equivalent to `'M/d/yy, h:mm a'` (e.g. `6/15/15, 9:03 AM`).
|
||||
* - `'medium'`: equivalent to `'MMM d, y, h:mm:ss a'` (e.g. `Jun 15, 2015, 9:03:01 AM`).
|
||||
* - `'long'`: equivalent to `'MMMM d, y, h:mm:ss a z'` (e.g. `June 15, 2015 at 9:03:01 AM GMT+1`).
|
||||
* - `'full'`: equivalent to `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (e.g. `Monday, June 15, 2015 at
|
||||
* 9:03:01 AM GMT+01:00`).
|
||||
* - `'shortDate'`: equivalent to `'M/d/yy'` (e.g. `6/15/15`).
|
||||
* - `'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 {
|
||||
if (value == null || value === '' || value !== value) return null;
|
||||
|
||||
|
|
|
@ -18,13 +18,6 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g;
|
|||
*
|
||||
* Maps a value to a string that pluralizes the value according to locale rules.
|
||||
*
|
||||
* Where:
|
||||
* - `expression` is a number.
|
||||
* - `mapping` is an object that mimics the ICU format, see
|
||||
* http://userguide.icu-project.org/formatparse/messages
|
||||
* - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
|
||||
* default)
|
||||
*
|
||||
* ## Example
|
||||
*
|
||||
* {@example common/pipes/ts/i18n_pipe.ts region='I18nPluralPipeComponent'}
|
||||
|
@ -35,6 +28,13 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g;
|
|||
export class I18nPluralPipe implements PipeTransform {
|
||||
constructor(private _localization: NgLocalization) {}
|
||||
|
||||
/**
|
||||
* @param value the number to be formatted
|
||||
* @param pluralMap an object that mimics the ICU format, see
|
||||
* http://userguide.icu-project.org/formatparse/messages.
|
||||
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
|
||||
* default).
|
||||
*/
|
||||
transform(value: number, pluralMap: {[count: string]: string}, locale?: string): string {
|
||||
if (value == null) return '';
|
||||
|
||||
|
|
|
@ -15,19 +15,22 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
|
|||
*
|
||||
* Generic selector that displays the string that matches the current value.
|
||||
*
|
||||
* Where `mapping` is an object that indicates the text that should be displayed
|
||||
* for different values of the provided `expression`.
|
||||
* If none of the keys of the mapping match the value of the `expression`, then the content
|
||||
* of the `other` key is returned when present, otherwise an empty string is returned.
|
||||
* If none of the keys of the `mapping` match the `value`, then the content
|
||||
* of the `other` key is returned when present, otherwise an empty string is returned.
|
||||
*
|
||||
* ## Example
|
||||
* ## Example
|
||||
*
|
||||
* {@example common/pipes/ts/i18n_pipe.ts region='I18nSelectPipeComponent'}
|
||||
*
|
||||
* @experimental
|
||||
* @experimental
|
||||
*/
|
||||
@Pipe({name: 'i18nSelect', pure: true})
|
||||
export class I18nSelectPipe implements PipeTransform {
|
||||
/**
|
||||
* @param value a string to be internationalized.
|
||||
* @param mapping an object that indicates the text that should be displayed
|
||||
* for different values of the provided `value`.
|
||||
*/
|
||||
transform(value: string|null|undefined, mapping: {[key: string]: string}): string {
|
||||
if (value == null) return '';
|
||||
|
||||
|
|
|
@ -20,16 +20,6 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
|
|||
* Formats a number as text. Group sizing and separator and other locale-specific
|
||||
* configurations are based on the locale.
|
||||
*
|
||||
* Where:
|
||||
* - `value` is a number
|
||||
* - `digitInfo` is a `string` which has a following format: <br>
|
||||
* <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>.
|
||||
* - `minIntegerDigits` is the minimum number of integer digits to use. Defaults to `1`.
|
||||
* - `minFractionDigits` is the minimum number of digits after the decimal point. Defaults to `0`.
|
||||
* - `maxFractionDigits` is the maximum number of digits after the decimal point. Defaults to `3`.
|
||||
* - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
|
||||
* default).
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* {@example common/pipes/ts/number_pipe.ts region='NumberPipe'}
|
||||
|
@ -40,6 +30,16 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
|
|||
export class DecimalPipe implements PipeTransform {
|
||||
constructor(@Inject(LOCALE_ID) private _locale: string) {}
|
||||
|
||||
/**
|
||||
* @param value a number to be formatted.
|
||||
* @param digitsInfo a `string` which has a following format: <br>
|
||||
* <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>.
|
||||
* - `minIntegerDigits` is the minimum number of integer digits to use. Defaults to `1`.
|
||||
* - `minFractionDigits` is the minimum number of digits after the decimal point. Defaults to `0`.
|
||||
* - `maxFractionDigits` is the maximum number of digits after the decimal point. Defaults to `3`.
|
||||
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
|
||||
* default).
|
||||
*/
|
||||
transform(value: any, digitsInfo?: string, locale?: string): string|null {
|
||||
if (isEmpty(value)) return null;
|
||||
|
||||
|
@ -61,12 +61,6 @@ export class DecimalPipe implements PipeTransform {
|
|||
* Uses the function {@link formatPercent} to format a number as a percentage according
|
||||
* to locale rules.
|
||||
*
|
||||
* Where:
|
||||
* - `value` is a number.
|
||||
* - `digitInfo` See {@link DecimalPipe} for more details.
|
||||
* - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
|
||||
* default).
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* {@example common/pipes/ts/percent_pipe.ts region='PercentPipe'}
|
||||
|
@ -77,6 +71,13 @@ export class DecimalPipe implements PipeTransform {
|
|||
export class PercentPipe implements PipeTransform {
|
||||
constructor(@Inject(LOCALE_ID) private _locale: string) {}
|
||||
|
||||
/**
|
||||
*
|
||||
* @param value a number to be formatted as a percentage.
|
||||
* @param digitsInfo see {@link DecimalPipe} for more details.
|
||||
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
|
||||
* default).
|
||||
*/
|
||||
transform(value: any, digitsInfo?: string, locale?: string): string|null {
|
||||
if (isEmpty(value)) return null;
|
||||
|
||||
|
@ -98,22 +99,6 @@ export class PercentPipe implements PipeTransform {
|
|||
* Uses the functions {@link getCurrencySymbol} and {@link formatCurrency} to format a
|
||||
* number as currency using locale rules.
|
||||
*
|
||||
* Where:
|
||||
* - `value` is a number.
|
||||
* - `currencyCode` is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such
|
||||
* as `USD` for the US dollar and `EUR` for the euro.
|
||||
* - `display` indicates whether to show the currency symbol, the code or a custom value:
|
||||
* - `code`: use code (e.g. `USD`).
|
||||
* - `symbol`(default): use symbol (e.g. `$`).
|
||||
* - `symbol-narrow`: some countries have two symbols for their currency, one regular and one
|
||||
* narrow (e.g. the canadian dollar CAD has the symbol `CA$` and the symbol-narrow `$`).
|
||||
* - `string`: use this value instead of a code or a symbol.
|
||||
* - boolean (deprecated from v5): `true` for symbol and false for `code`.
|
||||
* If there is no narrow symbol for the chosen currency, the regular symbol will be used.
|
||||
* - `digitInfo` See {@link DecimalPipe} for more details.
|
||||
* - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
|
||||
* default).
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* {@example common/pipes/ts/currency_pipe.ts region='CurrencyPipe'}
|
||||
|
@ -124,6 +109,23 @@ export class PercentPipe implements PipeTransform {
|
|||
export class CurrencyPipe implements PipeTransform {
|
||||
constructor(@Inject(LOCALE_ID) private _locale: string) {}
|
||||
|
||||
/**
|
||||
*
|
||||
* @param value a number to be formatted as currency.
|
||||
* @param currencyCodeis the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, 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:
|
||||
* - `code`: use code (e.g. `USD`).
|
||||
* - `symbol`(default): use symbol (e.g. `$`).
|
||||
* - `symbol-narrow`: some countries have two symbols for their currency, one regular and one
|
||||
* narrow (e.g. the canadian dollar CAD has the symbol `CA$` and the symbol-narrow `$`).
|
||||
* - `string`: use this value instead of a code or a symbol.
|
||||
* - boolean (deprecated from v5): `true` for symbol and false for `code`.
|
||||
* If there is no narrow symbol for the chosen currency, the regular symbol will be used.
|
||||
* @param digitsInfo see {@link DecimalPipe} for more details.
|
||||
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
|
||||
* default).
|
||||
*/
|
||||
transform(
|
||||
value: any, currencyCode?: string,
|
||||
display: 'code'|'symbol'|'symbol-narrow'|string|boolean = 'symbol', digitsInfo?: string,
|
||||
|
|
|
@ -13,30 +13,17 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
|
|||
* @ngModule CommonModule
|
||||
* @description
|
||||
*
|
||||
* Creates a new List or String containing a subset (slice) of the elements.
|
||||
*
|
||||
* Where the input expression is a `List` or `String`, and:
|
||||
* - `start`: The starting index of the subset to return.
|
||||
* - **a positive integer**: return the item at `start` index and all items after
|
||||
* in the list or string expression.
|
||||
* - **a negative integer**: return the item at `start` index from the end and all items after
|
||||
* in the list or string expression.
|
||||
* - **if positive and greater than the size of the expression**: return an empty list or string.
|
||||
* - **if negative and greater than the size of the expression**: return entire list or string.
|
||||
* - `end`: The ending index of the subset to return.
|
||||
* - **omitted**: return all items until the end.
|
||||
* - **if positive**: return all items before `end` index of the list or string.
|
||||
* - **if negative**: return all items before `end` index from the end of the list or string.
|
||||
* Creates a new `Array` or `String` containing a subset (slice) of the elements.
|
||||
*
|
||||
* All behavior is based on the expected behavior of the JavaScript API `Array.prototype.slice()`
|
||||
* and `String.prototype.slice()`.
|
||||
*
|
||||
* When operating on a [List], the returned list is always a copy even when all
|
||||
* When operating on an `Array`, the returned `Array` is always a copy even when all
|
||||
* the elements are being returned.
|
||||
*
|
||||
* When operating on a blank value, the pipe returns the blank value.
|
||||
*
|
||||
* ## List Example
|
||||
* ### List Example
|
||||
*
|
||||
* This `ngFor` example:
|
||||
*
|
||||
|
@ -56,6 +43,20 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
|
|||
|
||||
@Pipe({name: 'slice', pure: false})
|
||||
export class SlicePipe implements PipeTransform {
|
||||
/**
|
||||
* @param value a list or a string to be sliced.
|
||||
* @param start the starting index of the subset to return:
|
||||
* - **a positive integer**: return the item at `start` index and all items after
|
||||
* in the list or string expression.
|
||||
* - **a negative integer**: return the item at `start` index from the end and all items after
|
||||
* in the list or string expression.
|
||||
* - **if positive and greater than the size of the expression**: return an empty list or string.
|
||||
* - **if negative and greater than the size of the expression**: return entire list or string.
|
||||
* @param end the ending index of the subset to return:
|
||||
* - **omitted**: return all items until the end.
|
||||
* - **if positive**: return all items before `end` index of the list or string.
|
||||
* - **if negative**: return all items before `end` index from the end of the list or string.
|
||||
*/
|
||||
transform(value: any, start: number, end?: number): any {
|
||||
if (value == null) return value;
|
||||
|
||||
|
|
Loading…
Reference in New Issue