From e8d4f266441ac37e3fcef5a2ec7d571ed381c51b Mon Sep 17 00:00:00 2001 From: Zhicheng Wang Date: Tue, 4 Sep 2018 10:12:28 +0800 Subject: [PATCH] =?UTF-8?q?docs(API):=20=E7=BF=BB=E8=AF=91=E5=AE=8C?= =?UTF-8?q?=E4=BA=86=20DecimalPipe=20=E5=92=8C=20CurrencyPipe?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- aio/content/translations/cn/api-plan.md | 4 +- packages/common/src/pipes/number_pipe.ts | 114 ++++++++++++++++++++++- 2 files changed, 113 insertions(+), 5 deletions(-) diff --git a/aio/content/translations/cn/api-plan.md b/aio/content/translations/cn/api-plan.md index 115226a57b..eb42001a7a 100644 --- a/aio/content/translations/cn/api-plan.md +++ b/aio/content/translations/cn/api-plan.md @@ -46,8 +46,8 @@ [x] | common/NgTemplateOutlet | 0.42 [x] | common/Location | 0.41 [x] | platform-browser/BrowserModule | 0.40 -[ ] | common/DecimalPipe | 0.40 -[ ] | common/CurrencyPipe | 0.39 +[x] | common/DecimalPipe | 0.40 +[x] | common/CurrencyPipe | 0.39 [ ] | router/RouterLinkActive | 0.38 [ ] | core/TemplateRef | 0.38 [ ] | forms/FormBuilder | 0.37 diff --git a/packages/common/src/pipes/number_pipe.ts b/packages/common/src/pipes/number_pipe.ts index 26a9cec33c..4a6768d816 100644 --- a/packages/common/src/pipes/number_pipe.ts +++ b/packages/common/src/pipes/number_pipe.ts @@ -19,13 +19,20 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * 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 + * In the following case for example, the pipe rounds down where * ```Math.round()``` rounds up: - * + * + * 如果没有指定参数，则该函数会使用这个[舍入方法](https://en.wikibooks.org/wiki/Arithmetic/Rounding)。 + * 但其行为与 JavaScript 的 ```Math.round()``` 函数不同。 + * 下面的例子展示了管道与 ```Math.round()``` 的对比： + * * ```html * -2.5 | number:'1.0-0' * > -3 @@ -40,8 +47,12 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * into text strings, according to various format specifications, * where the caller's default locale is `en-US`. * + * 下列代码展示了该管道如何根据多种格式规范来把数字转换成字符串，这里使用的默认语言环境是 `en-US`。 + * * ### Example * + * ### 例子 + * * * * @@ -52,18 +63,38 @@ export class DecimalPipe implements PipeTransform { /** * @param value The number to be formatted. + * + * 要格式化的数字。 + * * @param digitsInfo Decimal representation options, specified by a string * in the following format:
* {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}. + * + * 数字展现的选项，通过如下格式的字符串指定：
+ * {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}。 + * * - `minIntegerDigits`: The minimum number of integer digits before the decimal point. * Default is `1`. + * + * `minIntegerDigits`：在小数点前的最小位数。默认为 `1`。 + * * - `minFractionDigits`: The minimum number of digits after the decimal point. * Default is `0`. + * + * `minFractionDigits`：小数点后的最小位数。默认为 `0`。 + * * - `maxFractionDigits`: The maximum number of digits after the decimal point. * Default is `3`. + * + * `maxFractionDigits`：小数点后的最大为数，默认为 `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). + * + * 要使用的本地化格式代码。 + * 如果未提供，则使用 `LOCALE_ID` 的值，默认为 `en-US`。 + * 参见[为你的应用设置地区（locale）](guide/i18n#setting-up-the-locale-of-your-app)。 */ transform(value: any, digitsInfo?: string, locale?: string): string|null { if (isEmpty(value)) return null; @@ -88,6 +119,9 @@ export class DecimalPipe implements PipeTransform { * separator, decimal-point character, and other locale-specific * configurations. * + * 把数字转换成百分比字符串， + * 根据本地化规则进行格式化，这些规则会决定分组大小和分组分隔符、小数点字符以及其它与本地化环境有关的配置项。 + * * @see `formatPercent()` * * @usageNotes @@ -95,6 +129,9 @@ export class DecimalPipe implements PipeTransform { * into text strings, according to various format specifications, * where the caller's default locale is `en-US`. * + * 下列代码展示了该管道如何根据多种格式规范把数字转换成文本字符串， + * 这里使用的默认语言环境是 `en-US`。 + * * * * @@ -106,18 +143,39 @@ export class PercentPipe implements PipeTransform { /** * * @param value The number to be formatted as a percentage. + * + * 要格式化为百分比的数字。 + * * @param digitsInfo Decimal representation options, specified by a string * in the following format:
* {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}. + * + * 数字展现的选项，通过如下格式的字符串指定：
+ * {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}。 + * + * * - `minIntegerDigits`: The minimum number of integer digits before the decimal point. * Default is `1`. + * + * `minIntegerDigits`：在小数点前的最小位数。默认为 `1`。 + * * - `minFractionDigits`: The minimum number of digits after the decimal point. * Default is `0`. + * + * `minFractionDigits`：小数点后的最小位数。默认为 `0`。 + * * - `maxFractionDigits`: The maximum number of digits after the decimal point. * Default is `3`. + * + * `maxFractionDigits`：小数点后的最大为数，默认为 `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). + * + * 要使用的本地化格式代码。 + * 如果未提供，则使用 `LOCALE_ID` 的值，默认为 `en-US`。 + * 参见[为你的应用设置地区（locale）](guide/i18n#setting-up-the-locale-of-your-app)。 */ transform(value: any, digitsInfo?: string, locale?: string): string|null { if (isEmpty(value)) return null; @@ -141,6 +199,9 @@ export class PercentPipe implements PipeTransform { * that determine group sizing and separator, decimal-point character, * and other locale-specific configurations. * + * 把数字转换成金额字符串， + * 根据本地化规则进行格式化，这些规则会决定分组大小和分组分隔符、小数点字符以及其它与本地化环境有关的配置项。 + * * @see `getCurrencySymbol()` * @see `formatCurrency()` * @@ -149,6 +210,9 @@ export class PercentPipe implements PipeTransform { * into text strings, according to various format specifications, * where the caller's default locale is `en-US`. * + * 下列代码展示了该管道如何根据多种格式规范把数字转换成文本字符串， + * 这里使用的默认语言环境是 `en-US`。 + * * * * @@ -160,33 +224,75 @@ export class CurrencyPipe implements PipeTransform { /** * * @param value The number to be formatted as currency. + * + * 要格式化为货币的数字。 + * * @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. + * + * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 中的货币代码，比如 `USD` 表示美元，`EUR` 表示欧元。 + * * @param display The format for the currency indicator. One of the following: + * + * 货币指示器的格式，有效值包括： + * * - `code`: Show the code (such as `USD`). + * + * `code`: 展示货币代码（如 `USD`）。 + * * - `symbol`(default): Show the symbol (such as `$`). + * + * `symbol`(default): 展示货币符号（如 `$`） + * * - `symbol-narrow`: Use the narrow symbol for locales that have two symbols for their * currency. * For example, the Canadian dollar CAD has the symbol `CA$` and the symbol-narrow `$`. If the * locale has no narrow symbol, uses the standard symbol for the locale. + * + * `symbol-narrow`: 使用区域的窄化符号，它包括两个符号。 + * 比如，加拿大元的符号是 `CA$`，而其窄化符号是 `$`。如果该区域没有窄化符号，则使用它的标准符号。 + * * - String: Use the given string value instead of a code or a symbol. + * + * String: 使用指定的字符串值代替货币代码或符号。 + * * - Boolean (marked deprecated in v5): `true` for symbol and false for `code`. * + * Boolean（从 v5 开始已弃用）：`true` 表示货币符号，`false` 表示货币代码。 + * * @param digitsInfo Decimal representation options, specified by a string * in the following format:
* {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}. + * + * 数字展现的选项，通过如下格式的字符串指定：
+ * {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}。 + * + * * - `minIntegerDigits`: The minimum number of integer digits before the decimal point. * Default is `1`. + * + * `minIntegerDigits`：在小数点前的最小位数。默认为 `1`。 + * * - `minFractionDigits`: The minimum number of digits after the decimal point. * Default is `0`. + * + * `minFractionDigits`：小数点后的最小位数。默认为 `0`。 + * * - `maxFractionDigits`: The maximum number of digits after the decimal point. * Default is `3`. * If not provided, the number will be formatted with the proper amount of digits, * depending on what the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) specifies. * For example, the Canadian dollar has 2 digits, whereas the Chilean peso has none. + * + * `maxFractionDigits`：小数点后的最大为数，默认为 `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). + * + * 要使用的本地化格式代码。 + * 如果未提供，则使用 `LOCALE_ID` 的值，默认为 `en-US`。 + * 参见[为你的应用设置地区（locale）](guide/i18n#setting-up-the-locale-of-your-app)。 */ transform( value: any, currencyCode?: string, @@ -228,6 +334,8 @@ function isEmpty(value: any): boolean { /** * Transforms a string into a number (if needed). + * + * 把字符串转换成数字（如果需要）。 */ function strToNumber(value: number | string): number { // Convert strings to numbers