!12945 更新国际化开发指南及api文档

Merge pull request !12945 from sunyaozu/master

zh-cn/application-dev/reference/apis/js-apis-intl.md

@@ -14,7 +14,7 @@
 ```js
 import Intl from '@ohos.intl';
 ```
-
+未正确导入包可能产生不明确的接口行为。
 
 ## Locale
 
@@ -47,7 +47,10 @@ constructor()
 
 **示例：** 
   ```js
-  var locale = new Intl.Locale();
+  // 默认构造函数使用系统当前locale创建Locale对象
+  var locale = new Intl.Locale()
+  // 返回系统当前localel
+  var localeID = locale.toString()
   ```
 
 
@@ -63,12 +66,14 @@ constructor(locale: string, options?: LocaleOptions)
 
 | 参数名                  | 类型                               | 必填   | 说明                           |
 | -------------------- | -------------------------------- | ---- | ---------------------------- |
-| locale               | string                           | 是    | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 |
+| locale               | string                           | 是    | 包含区域信息的字符串，包括语言以、脚本、国家或地区。语言、脚本、国家或地区的国际标准及组合方式请见[Intl开发指导](../../internationalization/intl-guidelines.md#设置区域信息) |
 | options<sup>9+</sup> | [LocaleOptions](#localeoptions9) | 否    | 用于创建区域对象的选项。                 |
 
 **示例：** 
   ```js
-  var locale = new Intl.Locale("zh-CN");
+  // 创建 "zh-CN" Locale对象
+  var locale = new Intl.Locale("zh-CN")
+  var localeID = locale.toString() // localeID = "zh-CN"
   ```
 
 
@@ -76,7 +81,7 @@ constructor(locale: string, options?: LocaleOptions)
 
 toString(): string
 
-将区域信息转换为字符串
+获取区域对象的字符串表示
 
 **系统能力**：SystemCapability.Global.I18n
 
@@ -84,12 +89,13 @@ toString(): string
 
 | 类型     | 说明          |
 | ------ | ----------- |
-| string | 字符串形式的区域信息。 |
+| string | 区域对象的字符串表示。 |
 
 **示例：** 
   ```js
-  var locale = new Intl.Locale("zh-CN");
-  locale.toString();
+  // 创建 "en-GB" Locale对象
+  var locale = new Intl.Locale("en-GB");
+  var localeID = locale.toString(); // localeID = "en-GB"
   ```
 
 
@@ -109,8 +115,17 @@ maximize(): Locale
 
 **示例：** 
   ```js
-  var locale = new Intl.Locale("zh-CN");
+  // 创建 "zh" Locale对象
+  var locale = new Intl.Locale("zh");
+  // 补齐Locale对象的脚本和地区
+  locale.maximize();
+  var localeID = locale.toString(); // localeID = "zh-Hans-CN"
+
+  // 创建 "en-US" Locale对象
+  locale = new Intl.Locale("en-US");
+  // 补齐Locale对象的脚本
   locale.maximize();
+  localeID = locale.toString(); // localeID = "en-Latn-US"
   ```
 
 
@@ -130,8 +145,17 @@ minimize(): Locale
 
 **示例：** 
   ```js
-  var locale = new Intl.Locale("zh-CN");
+  // 创建 "zh-Hans-CN" Locale对象
+  var locale = new Intl.Locale("zh-Hans-CN");
+  // 去除Locale对象的脚本和地区
   locale.minimize();
+  var localeID = locale.toString(); // localeID = "zh"
+
+  // 创建 "en-US" Locale对象
+  locale = new Intl.Locale("en-US");
+  // 去除Locale对象的地区
+  locale.minimize();
+  localeID = locale.toString(); // localeID = "en"
   ```
 
 
@@ -164,6 +188,7 @@ constructor()
 
 **示例：** 
   ```js
+  // 使用系统当前locale创建DateTimeFormat对象
   var datefmt= new Intl.DateTimeFormat();
   ```
 
@@ -185,12 +210,14 @@ constructor(locale: string | Array&lt;string&gt;, options?: DateTimeOptions)
 
 **示例：** 
   ```js
+  // 使用 "zh-CN" locale创建DateTimeFormat对象，日期风格为full，时间风格为medium
   var datefmt= new Intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' });
   ```
 
 
 **示例：** 
   ```js
+  // 使用 ["ban", "zh"] locale列表创建DateTimeFormat对象，因为ban为非法LocaleID，因此使用zh Locale创建DateTimeFormat对象
   var datefmt= new Intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' });
   ```
 
@@ -218,8 +245,13 @@ format(date: Date): string
 **示例：** 
   ```js
   var date = new Date(2021, 11, 17, 3, 24, 0);
+  // 使用 en-GB locale创建DateTimeFormat对象
   var datefmt = new Intl.DateTimeFormat("en-GB");
-  datefmt.format(date);
+  var formattedDate = datefmt.format(date); // formattedDate "17/12/2021"
+
+  // 使用 en-GB locale创建DateTimeFormat对象，dateStyle设置为full，timeStyle设置为medium
+  datefmt = new Intl.DateTimeFormat("en-GB", { dateStyle: 'full', timeStyle: 'medium' });
+  formattedDate = datefmt.format(date); // formattedDate "Friday, 17 December 2021 at 03:24:00"
   ```
 
 
@@ -248,8 +280,9 @@ formatRange(startDate: Date, endDate: Date): string
   ```js
   var startDate = new Date(2021, 11, 17, 3, 24, 0);
   var endDate = new Date(2021, 11, 18, 3, 24, 0);
+  // 使用 en-GB locale创建DateTimeFormat对象
   var datefmt = new Intl.DateTimeFormat("en-GB");
-  datefmt.formatRange(startDate, endDate);
+  var formattedDateRange = datefmt.formatRange(startDate, endDate); // formattedDateRange = "17/12/2021-18/12/2021"
   ```
 
 
@@ -269,8 +302,11 @@ resolvedOptions(): DateTimeOptions
 
 **示例：** 
   ```js
-  var datefmt = new Intl.DateTimeFormat("en-GB");
-  datefmt.resolvedOptions();
+  var datefmt = new Intl.DateTimeFormat("en-GB", { dateStyle: 'full', timeStyle: 'medium' });
+  // 返回DateTimeFormat对象的配置项
+  var options = datefmt.resolvedOptions();
+  var dateStyle = options.dateStyle; // dateStyle = "full"
+  var timeStyle = options.timeStyle; // timeStyle = "medium"
   ```
 
 
@@ -316,6 +352,7 @@ constructor()
 
 **示例：** 
   ```js
+  // 使用系统当前locale创建NumberFormat对象
   var numfmt = new Intl.NumberFormat();
   ```
 
@@ -337,6 +374,7 @@ constructor(locale: string | Array&lt;string&gt;, options?: NumberOptions)
 
 **示例：** 
   ```js
+  // 使用 en-GB locale创建NumberFormat对象，style设置为decimal，notation设置为scientific
   var numfmt = new Intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"});
   ```
 
@@ -364,8 +402,9 @@ format(number: number): string;
 
 **示例：** 
   ```js
+  // 使用 ["en-GB", "zh"] locale列表创建NumberFormat对象，因为en-GB为合法LocaleID，因此使用en-GB创建NumberFormat对象
   var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
-  numfmt.format(1223);
+  var formattedNumber = numfmt.format(1223); // formattedNumber = 1.223E3
   ```
 
 
@@ -387,7 +426,10 @@ resolvedOptions(): NumberOptions
 **示例：** 
   ```js
   var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
-  numfmt.resolvedOptions();
+  // 获取NumberFormat对象配置项
+  var options = numfmt.resolvedOptions();
+  var style = options.style; // style = decimal
+  var notation = options.notation // notation = scientific
   ```
 
 
@@ -433,6 +475,7 @@ constructor()
 
 **示例：** 
   ```js
+  // 使用系统locale创建Collator对象
   var collator = new Intl.Collator();
   ```
 
@@ -454,6 +497,7 @@ constructor(locale: string | Array&lt;string&gt;, options?: CollatorOptions)
 
 **示例：** 
   ```js
+  // 使用 zh-CN locale创建Collator对象，localeMatcher设置为lookup，usage设置为sort
   var collator = new Intl.Collator("zh-CN", {localeMatcher: "lookup", usage: "sort"});
   ```
 
@@ -481,8 +525,10 @@ compare(first: string, second: string): number
 
 **示例：** 
   ```js
-  var collator = new Intl.Collator("zh-Hans");
-  collator.compare("first", "second");
+  // 使用en-GB locale创建Collator对象
+  var collator = new Intl.Collator("en-GB");
+  // 比较 "first" 和 "second" 的先后顺序
+  var compareResult = collator.compare("first", "second"); // compareResult = -1
   ```
 
 
@@ -502,8 +548,11 @@ resolvedOptions(): CollatorOptions
 
 **示例：** 
   ```js
-  var collator = new Intl.Collator("zh-Hans");
+  var collator = new Intl.Collator("zh-Hans", { usage: 'sort', ignorePunctuation: 'true' });
+  // 获取Collator对象的配置项
   var options = collator.resolvedOptions();
+  var usage = options.usage; // usage = "sort"
+  var ignorePunctuation = options.ignorePunctuation // ignorePunctuation = true
   ```
 
 
@@ -537,6 +586,7 @@ constructor()
 
 **示例：** 
   ```js
+  // 使用系统locale创建PluralRules对象
   var pluralRules = new Intl.PluralRules();
   ```
 
@@ -558,6 +608,7 @@ constructor(locale: string | Array&lt;string&gt;, options?: PluralRulesOptions)
 
 **示例：** 
   ```js
+  // 使用 zh-CN locale创建PluralRules对象，localeMatcher设置为lookup，type设置为cardinal
   var pluralRules= new Intl.PluralRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"});
   ```
 
@@ -584,8 +635,10 @@ select(n: number): string
 
 **示例：** 
   ```js
+  // 使用 zh-Hans locale创建PluralRules对象
   var pluralRules = new Intl.PluralRules("zh-Hans");
-  pluralRules.select(1);
+  // 计算 zh-Hans locale中数字1对应的单复数类别
+  var plural = pluralRules.select(1); // plural = other
   ```
 
 
@@ -619,6 +672,7 @@ constructor()
 
 **示例：** 
   ```js
+  // 使用系统locale创建RelativeTimeFormat对象
   var relativetimefmt = new Intl.RelativeTimeFormat();
   ```
 
@@ -640,6 +694,7 @@ constructor(locale: string | Array&lt;string&gt;, options?: RelativeTimeFormatIn
 
 **示例：** 
   ```js
+  // 使用 zh-CN locale创建RelativeTimeFormat对象，localeMatcher设置为lookup，numeric设置为always，style设置为long
   var relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"});
   ```
 
@@ -667,8 +722,10 @@ format(value: number, unit: string): string
 
 **示例：** 
   ```js
+  // 使用 zh-CN locale创建RelativeTimeFormat对象
   var relativetimefmt = new Intl.RelativeTimeFormat("zh-CN");
-  relativetimefmt.format(3, "quarter")
+  // 计算 zh-CN locale中数字3，单位quarter的本地化表示
+  var formatResult = relativetimefmt.format(3, "quarter")； // formatResult = "3个季度后"
   ```
 
 
@@ -695,8 +752,9 @@ formatToParts(value: number, unit: string): Array&lt;object&gt;
 
 **示例：** 
   ```js
+  // 使用 en locale创建RelativeTimeFormat对象，numeric设置为auto
   var relativetimefmt = new Intl.RelativeTimeFormat("en", {"numeric": "auto"});
-  var parts = relativetimefmt.format(10, "seconds");
+  var parts = relativetimefmt.formatToParts(10, "seconds"); // parts = [ {type: "literal", value: "in"}, {type: "integer", value: 10, unit: "second"}, {type: "literal", value: "seconds"} ]
   ```
 
 
@@ -716,8 +774,11 @@ resolvedOptions(): RelativeTimeFormatResolvedOptions
 
 **示例：** 
   ```js
-  var relativetimefmt= new Intl.RelativeTimeFormat("en-GB");
-  relativetimefmt.resolvedOptions();
+  // 使用 en-GB locale创建RelativeTimeFormat对象
+  var relativetimefmt= new Intl.RelativeTimeFormat("en-GB", { style: "short" });
+  // 获取RelativeTimeFormat对象配置项
+  var options = relativetimefmt.resolvedOptions();
+  var style = options.style; // style = "short"
   ```