From 2e0dea6710d8029d7153ee3ddbb0e30a0afaefca Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 5 Feb 2021 13:03:12 +0700 Subject: [PATCH] docs: improve description, examples of DecimalPipe's digitsInfo parameter (#40714) Fixes #40671 PR Close #40714 --- packages/common/src/pipes/number_pipe.ts | 92 +++++++++++-------- .../common/pipes/ts/e2e_test/pipe_spec.ts | 12 +-- .../examples/common/pipes/ts/number_pipe.ts | 41 ++++----- 3 files changed, 78 insertions(+), 67 deletions(-) diff --git a/packages/common/src/pipes/number_pipe.ts b/packages/common/src/pipes/number_pipe.ts index 4c1c54ff55f..7cb4873aa27 100644 --- a/packages/common/src/pipes/number_pipe.ts +++ b/packages/common/src/pipes/number_pipe.ts @@ -17,33 +17,61 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * @ngModule CommonModule * @description * - * 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. - * - * If no parameters are specified, the function rounds off to the nearest value using this - * [rounding method](https://en.wikibooks.org/wiki/Arithmetic/Rounding). - * The behavior differs from that of the JavaScript ```Math.round()``` function. - * In the following case for example, the pipe rounds down where - * ```Math.round()``` rounds up: - * - * ```html - * -2.5 | number:'1.0-0' - * > -3 - * Math.round(-2.5) - * > -2 - * ``` + * Formats a value according to digit options and locale rules. + * Locale determines group sizing and separator, + * decimal point character, and other locale-specific configurations. * * @see `formatNumber()` * * @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`. + * + * ### digitsInfo + * + * The value's decimal representation is specified by the `digitsInfo` + * parameter, written in the following format:
+ * + * ``` + * {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits} + * ``` + * + * - `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. + * + * If the formatted value is truncated it will be rounded using the "to-nearest" method: + * + * ``` + * {{3.6 | number: '1.0-0'}} + * + * + * {{-3.6 | number:'1.0-0'}} + * + * ``` + * + * ### locale + * + * `locale` will format a value according to locale rules. + * Locale determines group sizing and separator, + * decimal point character, and other locale-specific configurations. + * + * 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). * * ### Example * + * The following code shows how the pipe transforms values + * according to various format specifications, + * where the caller's default locale is `en-US`. + * * * * @publicApi @@ -51,25 +79,17 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; @Pipe({name: 'number'}) export class DecimalPipe implements PipeTransform { constructor(@Inject(LOCALE_ID) private _locale: string) {} - - /** - * @param value The number to be formatted. - * @param digitsInfo Decimal representation options, specified by a string - * in the following format:
- * {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}. - * - `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: number|string, digitsInfo?: string, locale?: string): string|null; transform(value: null|undefined, digitsInfo?: string, locale?: string): null; transform(value: number|string|null|undefined, digitsInfo?: string, locale?: string): string|null; + + /** + * @param value The value to be formatted. + * @param digitsInfo Sets digit and decimal representation. + * [See more](#digitsinfo). + * @param locale Specifies what locale format rules to use. + * [See more](#locale). + */ transform(value: number|string|null|undefined, digitsInfo?: string, locale?: string): string |null { if (!isValue(value)) return null; diff --git a/packages/examples/common/pipes/ts/e2e_test/pipe_spec.ts b/packages/examples/common/pipes/ts/e2e_test/pipe_spec.ts index be8b80965d0..c7532f2cb69 100644 --- a/packages/examples/common/pipes/ts/e2e_test/pipe_spec.ts +++ b/packages/examples/common/pipes/ts/e2e_test/pipe_spec.ts @@ -75,14 +75,10 @@ describe('pipe', () => { browser.get(URL); waitForElement('number-pipe'); const examples = element.all(by.css('number-pipe p')); - expect(examples.get(0).getText()).toEqual('e (no formatting): 2.718'); - expect(examples.get(1).getText()).toEqual('e (3.1-5): 002.71828'); - expect(examples.get(2).getText()).toEqual('e (4.5-5): 0,002.71828'); - expect(examples.get(3).getText()).toEqual('e (french): 0\u202f002,71828'); - expect(examples.get(4).getText()).toEqual('pi (no formatting): 3.14'); - expect(examples.get(5).getText()).toEqual('pi (3.1-5): 003.14'); - expect(examples.get(6).getText()).toEqual('pi (3.5-5): 003.14000'); - expect(examples.get(7).getText()).toEqual('-2.5 (1.0-0): -3'); + expect(examples.get(0).getText()).toEqual('No specified formatting: 3.142'); + expect(examples.get(1).getText()).toEqual('With digitsInfo parameter specified: 0,003.14159'); + expect(examples.get(2).getText()) + .toEqual('With digitsInfo and locale parameters specified: 0\u202f003,14159'); }); }); diff --git a/packages/examples/common/pipes/ts/number_pipe.ts b/packages/examples/common/pipes/ts/number_pipe.ts index f0178ea9ff9..0a2af30c813 100644 --- a/packages/examples/common/pipes/ts/number_pipe.ts +++ b/packages/examples/common/pipes/ts/number_pipe.ts @@ -11,40 +11,35 @@ import {Component} from '@angular/core'; // we need to import data for the french locale import localeFr from './locale-fr'; -// registering french data -registerLocaleData(localeFr); +registerLocaleData(localeFr, 'fr'); // #docregion NumberPipe @Component({ selector: 'number-pipe', template: `
- -

e (no formatting): {{e | number}}

- -

e (3.1-5): {{e | number:'3.1-5'}}

+

+ No specified formatting: + {{pi | number}} + +

- -

e (4.5-5): {{e | number:'4.5-5'}}

+

+ With digitsInfo parameter specified: + {{pi | number:'4.1-5'}} + +

- -

e (french): {{e | number:'4.5-5':'fr'}}

+

+ With digitsInfo and + locale parameters specified: + {{pi | number:'4.1-5':'fr'}} + +

- -

pi (no formatting): {{pi | number}}

- - -

pi (3.1-5): {{pi | number:'3.1-5'}}

- - -

pi (3.5-5): {{pi | number:'3.5-5'}}

- - -

-2.5 (1.0-0): {{-2.5 | number:'1.0-0'}}

` }) export class NumberPipeComponent { - pi: number = 3.14; - e: number = 2.718281828459045; + pi: number = 3.14159265359; } // #enddocregion