diff --git a/zh-cn/application-dev/internationalization/i18n-guidelines.md b/zh-cn/application-dev/internationalization/i18n-guidelines.md index a8acb6712629a290279d144e68297ae0668bb2c9..52412dc5966912a2b0d04485cbe0404e9c49abc4 100644 --- a/zh-cn/application-dev/internationalization/i18n-guidelines.md +++ b/zh-cn/application-dev/internationalization/i18n-guidelines.md @@ -1,13 +1,13 @@ # I18n开发指导 -I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使用方法。 +本模块提供系统相关的或者增强的国际化能力，包括区域管理、电话号码处理、日历等，相关接口为ECMA 402标准中未定义的补充接口。更多接口和使用方式请见[I18N](../reference/apis/js-apis-i18n.md)。 +[Intl](intl-guidelines.md)模块提供了ECMA 402标准定义的基础国际化接口，与本模块共同使用可提供完整地国际化支持能力。 ## 获取系统语言区域信息 调用系统提供的接口访问系统的语言区域信息。 - ### 接口说明 | 模块 | 接口名称 | 描述 | @@ -20,15 +20,13 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 | ohos.i18n | getDisplayLanguage(language:string,locale:string,sentenceCase?:boolean):string | 获取语言的本地化表示。 | | ohos.i18n | getDisplayCountry(country:string,locale:string,sentenceCase?:boolean):string | 获取国家的本地化表示。 | - ### 开发步骤 1. 获取系统语言。 调用getSystemLanguage方法获取当前系统设置的语言（i18n为导入的模块）。 - - ``` + ```js var language = i18n.getSystemLanguage(); ``` @@ -36,7 +34,7 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用getSystemRegion方法获取当前系统设置的区域 - ``` + ```js var region = i18n.getSystemRegion(); ``` @@ -44,7 +42,7 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用getSystemLocale方法获取当前系统设置的Locale - ``` + ```js var locale = i18n.getSystemLocale(); ``` @@ -52,8 +50,7 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用isRTL方法获取Locale的语言是否为从右到左语言。 - - ``` + ```js var rtl = i18n.isRTL("zh-CN"); ``` @@ -61,7 +58,7 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用is24HourClock方法来判断当前系统的时间是否采用24小时制。 - ``` + ```js var hourClock = i18n.is24HourClock(); ``` @@ -69,7 +66,7 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用getDisplayLanguage方法获取某一语言的本地化表示。其中，language表示待本地化显示的语言，locale表示本地化的Locale，sentenceCase结果是否需要首字母大写。 - ``` + ```js var language = "en"; var locale = "zh-CN"; var sentenceCase = false; @@ -80,18 +77,16 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用getDisplayCountry方法获取某一国家的本地化表示。其中，country表示待本地化显示的国家，locale表示本地化的Locale，sentenceCase结果是否需要首字母大写。 - ``` + ```js var country = "US"; var locale = "zh-CN"; var sentenceCase = false; var localizedCountry = i18n.getDisplayCountry(country, locale, sentenceCase); ``` - ## 获取日历信息 -调用日历[Calendar](../reference/apis/js-apis-intl.md)相关接口来获取日历的相关信息，例如获取日历的本地化显示、一周起始日、一年中第一周的最小天数等。 - +调用日历[Calendar](../reference/apis/js-apis-i18n.md#calendar8)相关接口来获取日历的相关信息，例如获取日历的本地化显示、一周起始日、一年中第一周的最小天数等。 ### 接口说明 @@ -110,23 +105,21 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 | ohos.i18n | getDisplayName(locale:string):string8+ | 获取日历对象的本地化表示。 | | ohos.i18n | isWeekend(date?:Date):boolean8+ | 判断给定的日期是否在日历中是周末。 | - ### 开发步骤 1. 实例化日历对象。 调用getCalendar方法获取指定locale和type的时区对象（i18n为导入的模块）。其中，type表示合法的日历类型，目前合法的日历类型包括："buddhist", "chinese", "coptic", "ethiopic", "hebrew", "gregory", "indian", "islamic_civil", "islamic_tbla", "islamic_umalqura", "japanese", "persian"。当type没有给出时，采用区域默认的日历类型。 - - ``` - var calendar = i18n.getCalendar("zh-CN", "gregory); + ```js + var calendar = i18n.getCalendar("zh-CN", "gregory"); ``` 2. 设置日历对象的时间。 调用setTime方法设置日历对象的时间。setTime方法接收两种类型的参数。一种是传入一个Date对象，另一种是传入一个数值表示从1970.1.1 00:00:00 GMT逝去的毫秒数。 - ``` + ```js var date1 = new Date(); calendar.setTime(date1); var date2 = 1000; @@ -137,16 +130,15 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用set方法设置日历对象的年、月、日、时、分、秒。 - ``` + ```js calendar.set(2021, 12, 21, 6, 0, 0) ``` 4. 设置、获取日历对象的时区。 调用setTimeZone方法和getTimeZone方法来设置、获取日历对象的时区。其中，setTimeZone方法需要传入一个字符串表示需要设置的时区。 - - ``` + ```js calendar.setTimeZone("Asia/Shanghai"); var timezone = calendar.getTimeZone(); ``` @@ -155,8 +147,7 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用setFirstDayOfWeek方法和getFirstDayOfWeek方法设置、获取日历对象的一周起始日。其中，setFirstDayOfWeek需要传入一个数值表示一周的起始日，1代表周日，7代表周六。 - - ``` + ```js calendar.setFirstDayOfWeek(1); var firstDayOfWeek = calendar.getFirstDayOfWeek(); ``` @@ -164,34 +155,30 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 6. 设置、获取日历对象第一周的最小天数 调用setMinimalDaysInFirstWeek方法和getMinimalDaysInFirstWeek方法来设置、获取日历对象第一周的最小天数。 - ``` + ```js calendar.setMinimalDaysInFirstWeek(3); var minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek(); ``` 7. 获取日历对象的本地化显示 调用getDisplayName来获取日历对象的本地化显示。 - - ``` + ```js var localizedName = calendar.getDisplayName("zh-CN"); ``` 8. 判断某一个日期是否为周末。 调用isWeekend方法来判断输入的Date是否为周末。 - - ``` + ```js var date = new Date(); var weekend = calendar.isWeekend(date); ``` - ## 电话号码格式化 -调用电话号码格式化[PhoneNumberFormat](../reference/apis/js-apis-intl.md)的接口，实现对针对不同国家电话号码的格式化以及判断电话号码格式是否正确的功能。 - +调用电话号码格式化[PhoneNumberFormat](../reference/apis/js-apis-i18n.md#phonenumberformat8)的接口，实现对针对不同国家电话号码的格式化以及判断电话号码格式是否正确的功能。 ### 接口说明 @@ -201,23 +188,21 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 | ohos.i18n | isValidNumber(number:string):boolean8+ | 判断number是否是一个格式正确的电话号码。 | | ohos.i18n | format(number:string):string8+ | 对number按照指定国家及风格进行格式化。 | - ### 开发步骤 1. 实例化电话号码格式化对象。 调用PhoneNumberFormat的构造函数来实例化电话号码格式化对象，需要传入电话号码的国家代码及格式化选项。其中，格式化选项是可选的，包括style选项，该选项的取值包括："E164", "INTERNATIONAL", "NATIONAL", "RFC3966"。 - - ``` - var phoneNumberFormat = new i18n.PhoneNubmerFormat("CN", {type: "E164"}); + ```js + var phoneNumberFormat = new i18n.PhoneNumberFormat("CN", {type: "E164"}); ``` 2. 判断电话号码格式是否正确。 调用isValidNumber方法来判断输入的电话号码的格式是否正确。 - ``` + ```js var validNumber = phoneNumberFormat.isValidNumber("15812341234"); ``` @@ -225,31 +210,27 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用电话号码格式化对象的format方法来对输入的电话号码进行格式化。 - ``` + ```js var formattedNumber = phoneNumberFormat.format("15812341234"); ``` - ## 度量衡转换 度量衡转换接口可以实现度量衡转换的相关功能。 - ### 接口说明 | 模块 | 接口名称 | 描述 | | -------- | -------- | -------- | | ohos.i18n | unitConvert(fromUnit:UnitInfo,toUnit:UnitInfo,value:number,locale:string,style?:string):string8+ | 将fromUnit的单位转换为toUnit的单位，并根据区域与风格进行格式化。 | - ### 开发步骤 1. 度量衡单位转换。 - 调用[unitConvert](../reference/apis/js-apis-intl.md)方法实现度量衡单位转换，并进行格式化显示的功能。 + 调用[unitConvert](../reference/apis/js-apis-i18n.md#unitconvert8)方法实现度量衡单位转换，并进行格式化显示的功能。 - - ``` + ```js var fromUnit = {unit: "cup", measureSystem: "US"}; var toUnit = {unit: "liter", measureSystem: "SI"}; var number = 1000; @@ -258,11 +239,9 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 i18n.Util.unitConvert(fromUtil, toUtil, number, locale, style); ``` - ## 字母表索引 -调用字母表索引[IndexUtil](../reference/apis/js-apis-intl.md)的接口可以获取不同Locale的字母表索引，以及实现计算字符串所属索引的功能。 - +调用字母表索引[IndexUtil](../reference/apis/js-apis-i18n.md#indexutil8)的接口可以获取不同Locale的字母表索引，以及实现计算字符串所属索引的功能。 ### 接口说明 @@ -273,7 +252,6 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 | ohos.i18n | addLocale(locale:string): void8+ | 将新的Locale对应的索引加入当前索引列表。 | | ohos.i18n | getIndex(text:string):string8+ | 获取text对应的索引。 | - ### 开发步骤 1. 实例化字母表索引对象。 @@ -281,15 +259,15 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用getInstance方法来实例化特定locale对应的字母表索引对象。当locale参数为空时，实例化系统默认Locale的字母表索引对象。 - ``` - var indexUtil = getInstance("zh-CN"); + ```js + var indexUtil = i18n.getInstance("zh-CN"); ``` 2. 获取索引列表。 调用getIndexList方法来获取当前Locale对应的字母表索引列表。 - ``` + ```js var indexList = indexUtil.getIndexList(); ``` @@ -297,7 +275,7 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用addLocale方法，将新的Locale对应的字母表索引添加到当前字母表索引列表中。 - ``` + ```js indexUtil.addLocale("ar") ``` @@ -305,16 +283,14 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用getIndex方法来获取某一字符串对应的字母表索引。 - ``` + ```js var text = "access index"; indexUtil.getIndex(text); ``` - ## 获取文本断点位置 -当文本比较长无法在一行进行显示时，调用文本断点[BreakIterator8](../reference/apis/js-apis-intl.md)的接口，来获取文本可以断行的位置。 - +当文本比较长无法在一行进行显示时，调用文本断点[BreakIterator8](../reference/apis/js-apis-i18n.md#breakiterator8)的接口，来获取文本可以断行的位置。 ### 接口说明 @@ -331,15 +307,13 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 | ohos.i18n | following(offset:number):number8+ | 将断行对象移动到offset指定位置的后面一个分割点的位置。 | | ohos.i18n | isBoundary(offset:number):boolean8+ | 判断某个位置是否是分割点。 | - ### 开发步骤 1. 实例化断行对象。 调用getLineInstance方法来实例化断行对象。 - - ``` + ```js var locale = "en-US" var breakIterator = i18n.getLineInstance(locale); ``` @@ -348,8 +322,7 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 调用setLineBreakText方法和getLineBreakText方法来设置、访问要断行处理的文本。 - - ``` + ```js var text = "Apple is my favorite fruit"; breakIterator.setLineBreakText(text); var breakText = breakIterator.getLineBreakText(); @@ -358,9 +331,8 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 3. 获取断行对象当前的位置。 调用current方法来获取断行对象在当前处理文本中的位置。 - - ``` + ```js var pos = breakIterator.current(); ``` @@ -368,8 +340,7 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 系统提供了很多接口可以用于调整断行对象在处理文本中的位置，包括first, last, next, previous, following。 - - ``` + ```js var firstPos = breakIterator.first(); // 将断行对象设置到第一个分割点的位置，即文本的起始位置； var lastPos = breakIterator.last(); // 将断行对象设置到最后一个分割点的位置，即文本末尾的下一个位置； // 将断行对象向前或向后移动一定数量的分割点。 @@ -384,8 +355,7 @@ I18n开发指导提供了未在ECMA 402中定义的国际化能力接口的使 5. 判断某个位置是否为分割点。 调用isBoundary方法来判断一个方法是否为分割点；如果该位置是分割点，则返回true，并且将断行对象移动到该位置；如果该位置不是分割点，则返回false，并且将断行对象移动到该位置后的一个分割点。 - - ``` + ```js var isboundary = breakIterator.isBoundary(5); - ``` + ``` \ No newline at end of file diff --git a/zh-cn/application-dev/internationalization/intl-guidelines.md b/zh-cn/application-dev/internationalization/intl-guidelines.md index 46da7279de53cc77d45db1dfca156d2c467f699f..f4e6705ec756d2a03027450909dafe47e7d6780c 100644 --- a/zh-cn/application-dev/internationalization/intl-guidelines.md +++ b/zh-cn/application-dev/internationalization/intl-guidelines.md @@ -1,11 +1,12 @@ # Intl开发指导 -Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方法。 +本模块提供提供基础的应用国际化能力，包括时间日期格式化、数字格式化、排序等，相关接口在ECMA 402标准中定义。更多接口和使用方式请见[Intl](../reference/apis/js-apis-intl.md)。 -## 设置区域信息 +[I18N](i18n-guidelines.md)模块提供其他非ECMA 402定义的国际化接口，与本模块共同使用可提供完整地国际化支持能力。 -调用[Locale](../reference/apis/js-apis-intl.md)的相关接口实现最大化区域信息或最小化区域信息。 +## 设置区域信息 +调用[Locale](../reference/apis/js-apis-intl.md#locale)的相关接口实现最大化区域信息或最小化区域信息。 ### 接口说明 @@ -17,17 +18,30 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 | ohos.intl | maximize():Locale | 最大化区域信息。 | | ohos.intl | minimize():Locale | 最小化区域信息。 | - ### 开发步骤 1. 实例化Locale对象。 - 使用Locale的构造函数创建Locale对象，该方法接收一个表示Locale的字符串及可选的[属性](../reference/apis/js-apis-intl.md)列表（intl为导入的模块名）。 + 使用Locale的构造函数创建Locale对象，该方法接收一个表示Locale的字符串及可选的[属性](../reference/apis/js-apis-intl.md#localeoptions)列表（intl为导入的模块名）。 + + 表示Locale的字符串参数可以分为以下四部分：语言、脚本、地区、扩展参数。各个部分按照顺序使用中划线“-”进行连接。 + - 语言：必选，使用2个或3个小写英文字母表示（可参考ISO-639标准），例如英文使用“en”表示，中文使用“zh”表示。 + - 脚本：可选，使用4个英文字母表示，其中首字母需要大写，后面3个使用小写字母（可参考ISO-15924）。例如，中文繁体使用脚本“Hant”表示，中文简体使用脚本“Hans”表示。 + - 国家或地区：可选，使用两个大写字母表示（可参考ISO-3166），例如中国使用“CN”表示，美国使用“US”表示； + - 扩展参数：可选，由key和value两部分组成，目前支持以下扩展参数（可参考BCP 47扩展）。各个扩展参数之间没有严格的顺序，使用“-key-value”的格式书写。扩展参数整体使用“-u”连接到语言、脚本、地区后面。例如“zh-u-nu-latn-ca-chinese”表示使用“latn”数字系统，“chinese”日历系统。扩展参数也可以通过第二个参数传入。 + | 扩展参数ID | 扩展参数说明 | + | -------- | -------- | + | ca | 表示日历系统 | + | co | 表示排序规则 | + | hc | 表示守时惯例 | + | nu | 表示数字系统 | + | kn | 表示字符串排序、比较时是否考虑数字的实际值 | + | kf | 表示字符串排序、比较时是否考虑大小写 | - ``` + ```js var locale = "zh-CN"; - var options = {caseFirst: false, calendar: "chinese", collation: pinyin}; + var options = {caseFirst: false, calendar: "chinese", collation: "pinyin"}; var localeObj = new intl.Locale(locale, options); ``` @@ -35,7 +49,7 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 调用toString方法来获取Locale对象的字符串表示，其中包括了语言、区域及其他选项信息。 - ``` + ```js var localeStr = localeObj.toString(); ``` @@ -43,7 +57,7 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 调用maximize方法来最大化区域信息，即当缺少脚本与地区信息时，对其进行补全。 - ``` + ```js var maximizedLocale = localeObj.maximize(); ``` @@ -51,15 +65,13 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 调用minimize方法来最小化区域信息，即当存在脚本与地区信息时，对其进行删除。 - ``` + ```js var minimizedLocale = localeObj.minimize(); ``` - ## 格式化日期时间 -调用日期时间格式化[DateTimeFormat](../reference/apis/js-apis-intl.md)的接口，实现针对特定Locale的日期格式化以及时间段格式化功能。 - +调用日期时间格式化[DateTimeFormat](../reference/apis/js-apis-intl.md#datetimeformat)的接口，实现针对特定Locale的日期格式化以及时间段格式化功能。 ### 接口说明 @@ -71,21 +83,19 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 | ohos.intl | formatRange(startDate:Date,endDate:Date):string | 依据DateTimeFormat对象的Locale及其他格式化属性，计算时间段的格式化表示。 | | ohos.intl | resolvedOptions():DateTimeOptions | 获取DateTimeFormat对象的相关属性。 | - ### 开发步骤 1. 实例化日期时间格式化对象。 一种方法是使用DateTimeFormat提供的默认构造函数，通过访问系统语言和地区设置，获取系统默认Locale，并将其作为DateTimeFormat对象内部的Locale（intl为导入的模块名）。 - - ``` + ```js var dateTimeFormat = new intl.DateTimeFormat(); ``` - 另一种方法是使用开发者提供的Locale和格式化参数来创建日期时间格式化对象。其中，格式化参数是可选的，完整的格式化参数列表见[DateTimeOptions](../reference/apis/js-apis-intl.md)。 + 另一种方法是使用开发者提供的Locale和格式化参数来创建日期时间格式化对象。其中，格式化参数是可选的，完整的格式化参数列表见[DateTimeOptions](../reference/apis/js-apis-intl.md#datetimeoptions)。 - ``` + ```js var options = {dateStyle: "full", timeStyle: "full"}; var dateTimeFormat = new intl.DateTimeFormat("zh-CN", options); ``` @@ -94,34 +104,33 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 使用DateTimeFormat的format方法对一个Date对象进行格式化，该方法会返回一个字符串作为格式化的结果。 - ``` - Date date = new Date(); + ```js + var date = new Date(); var formatResult = dateTimeFormat.format(date); ``` 3. 格式化时间段。 - 使用DateTimeFormat的formatRange方法对一个时间段进行格式化。该方法需要传入两个Date对象，分别表示时间段的起止时间，返回一个字符串作为格式化的结果。 + 使用DateTimeFormat的formatRange方法对一个时间段进行格式化。该方法需要传入两个Date对象，分别表示时间段的起止日期，返回一个字符串作为格式化的结果。当传入的两个Date对象表示同一天时，返回对象为该日期的表示；当传入的两个Date对象不是同一天时，返回结果为这两个日期的区间表示。 - ``` - Date startDate = new Date(); - Date endDate = new Date(); - var formatResult = dateTimeFormat.formatRange(startDate, endDate); + ```js + var startDate = new Date(2021, 11, 17, 3, 24, 0); + var endDate = new Date(2021, 11, 18, 3, 24, 0); + var datefmt = new Intl.DateTimeFormat("en-GB"); + datefmt.formatRange(startDate, endDate); ``` 4. 访问日期时间格式化对象的相关属性。 DateTimeFormat的resolvedOptions方法会返回一个对象，该对象包含了DateTimeFormat对象的所有相关属性及其值。 - ``` + ```js var options = dateTimeFormat.resolvedOptions(); ``` - ## 数字格式化 -调用数字格式化[NumberFormat](../reference/apis/js-apis-intl.md)的接口，实现针对特定Locale的数字格式化功能。 - +调用数字格式化[NumberFormat](../reference/apis/js-apis-intl.md#numberformat)的接口，实现针对特定Locale的数字格式化功能。 ### 接口说明 @@ -132,21 +141,19 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 | ohos.intl | format(number:number):string | 依据NumberFormat对象的Locale及其他格式化属性，计算数字的格式化表示。 | | ohos.intl | resolvedOptions():NumberOptions | 获取NumberFormat对象的相关属性。 | - ### 开发步骤 1. 实例化数字格式化对象。 一种方法是使用NumberFormat提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 - - ``` + ```js var numberFormat = new intl.NumberFormat(); ``` - 另一种方法是使用开发者提供的Locale和格式化参数来创建数字格式化对象。其中，格式化参数是可选的，完整的格式化参数列表参见[NumberOptions](../reference/apis/js-apis-intl.md)。 + 另一种方法是使用开发者提供的Locale和格式化参数来创建数字格式化对象。其中，格式化参数是可选的，完整的格式化参数列表参见[NumberOptions](../reference/apis/js-apis-intl.md#numberoptions)。 - ``` + ```js var options = {compactDisplay: "short", notation: "compact"}; var numberFormat = new intl.NumberFormat("zh-CN", options); ``` @@ -155,7 +162,7 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 使用NumberFormat的format方法对传入的数字进行格式化。该方法返回一个字符串作为格式化的结果。 - ``` + ```js var number = 1234.5678 var formatResult = numberFormat.format(number); ``` @@ -164,15 +171,13 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 NumberFormat的resolvedOptions方法会返回一个对象，该对象包含了NumberFormat对象的所有相关属性及其值。 - ``` + ```js var options = numberFormat.resolvedOptions(); ``` - ## 字符串排序 -不同区域的用户对于字符串排序具有不同的需求。调用字符串排序[Collator](../reference/apis/js-apis-intl.md)的接口，实现针对特定Locale的字符串排序功能。 - +不同区域的用户对于字符串排序具有不同的需求。调用字符串排序[Collator](../reference/apis/js-apis-intl.md#collator8)的接口，实现针对特定Locale的字符串排序功能。 ### 接口说明 @@ -183,29 +188,27 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 | ohos.intl | compare(first:string,second:string):number8+ | 依据排序对象的Locale及其属性，计算两个字符串的比较结果。 | | ohos.intl | resolvedOptions():CollatorOptions8+ | 获取排序对象的相关属性。 | - ### 开发步骤 1. 实例化排序对象。 一种方法是使用Collator提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 - - ``` + ```js var collator = new intl.Collator(); ``` - 另一种方法是使用开发者提供的Locale和其他相关参数来创建Collator对象，完整的参数列表参见[CollatorOptions](../reference/apis/js-apis-intl.md)。 + 另一种方法是使用开发者提供的Locale和其他相关参数来创建Collator对象，完整的参数列表参见[CollatorOptions](../reference/apis/js-apis-intl.md#collatoroptions8)。 - ``` - var collator= new intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort"}; + ```js + var collator= new intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort"}); ``` 2. 比较字符串。 - 使用Collator的compare方法对传入的两个字符串进行比较。该方法返回一个数值作为比较的结果，返回-1表示第一个字符串小于第二个字符串，返回1表示第一个字符大于第二个字符串，返回0表示两个字符串相同。 + 使用Collator的compare方法对传入的两个字符串进行比较。该方法返回一个数值作为比较的结果，返回-1表示第一个字符串小于第二个字符串，返回1表示第一个字符大于第二个字符串，返回0表示两个字符串相同。基于两个字符串的比较结果，开发者可以字符串集合进行排序。 - ``` + ```js var str1 = "first string"; var str2 = "second string"; var compareResult = collator.compare(str1, str2); @@ -215,15 +218,13 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 Collator的resolvedOptions方法会返回一个对象，该对象包含了Collator对象的所有相关属性及其值。 - ``` + ```js var options = collator.resolvedOptions(); ``` - ## 判定单复数类别 -在一些语言的语法中，当数字后面存在名词时，名词需要根据数字的值采用不同的形式。调用单复数[PluralRules](../reference/apis/js-apis-intl.md)的接口，可以实现针对特定Locale计算数字单复数类别的功能，从而选择合适的名词单复数表示。 - +在一些语言的语法中，当数字后面存在名词时，名词需要根据数字的值采用不同的形式。调用单复数[PluralRules](../reference/apis/js-apis-intl.md#pluralrules8)的接口，可以实现针对特定Locale计算数字单复数类别的功能，从而选择合适的名词单复数表示。 ### 接口说明 @@ -240,31 +241,28 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 一种方法是使用PluralRules提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 - - ``` + ```js var pluralRules = new intl.PluralRules(); ``` - 另一种方法是使用开发者提供的Locale和其他相关参数来创建单复数对象。完整的参数列表参见[PluralRulesOptions](../reference/apis/js-apis-intl.md)。 + 另一种方法是使用开发者提供的Locale和其他相关参数来创建单复数对象。完整的参数列表参见[PluralRulesOptions](../reference/apis/js-apis-intl.md#pluralrulesoptions8)。 - ``` - var plurals = new intl.PluralRules("zh-CN", {localeMatcher: "best fit", type: "cardinal"}; + ```js + var pluralRules = new intl.PluralRules("zh-CN", {localeMatcher: "best fit", type: "cardinal"}); ``` 2. 计算数字单复数类别。 使用PluralRules的select方法计算传入数字的单复数类别。该方法返回一个字符串作为传入数字的类别，包括："zero", "one", "two", "few", "many", "other"六个类别。 - ``` + ```js var number = 1234.5678 var categoryResult = plurals.select(number); ``` - ## 相对时间格式化 -调用相对时间格式化[RelativeTimeFormat](../reference/apis/js-apis-intl.md)的接口，实现针对特定Locale的相对时间格式化功能。 - +调用相对时间格式化[RelativeTimeFormat](../reference/apis/js-apis-intl.md#relativetimeformat8)的接口，实现针对特定Locale的相对时间格式化功能。 ### 接口说明 @@ -276,29 +274,27 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 | ohos.intl | formatToParts(value:number,unit:string):Array<object>8+ | 依据相对时间格式化对象的Locale及其他格式化属性，返回相对时间格式化表示的各个部分。 | | ohos.intl | resolvedOptions():RelativeTimeFormatResolvedOptions8+ | 获取相对时间格式化对象的相关属性。 | - ### 开发步骤 1. 实例化相对时间格式化对象。 一种方法是使用RelativeTimeFormat提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 - - ``` + ```js var relativeTimeFormat = new intl.RelativeTimeFormat(); ``` - 另一种方法是使用开发者提供的Locale和格式化参数来创建相对时间格式化对象。其中，格式化参数是可选的，完整的参数列表参见[ RelativeTimeFormatInputOptions](../reference/apis/js-apis-intl.md)。 + 另一种方法是使用开发者提供的Locale和格式化参数来创建相对时间格式化对象。其中，格式化参数是可选的，完整的参数列表参见[ RelativeTimeFormatInputOptions](../reference/apis/js-apis-intl.md#relativetimeformatinputoptions8)。 ``` - var relativeTimeFormat = new intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"}; + var relativeTimeFormat = new intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"}); ``` 2. 相对时间格式化。 使用RelativeTimeFormat的format方法对相对时间进行格式化。方法接收一个表示相对时间长度的数值和表示单位的字符串，其中单位包括："year", "quarter", "month", "week", "day", "hour", "minute", "second"。方法返回一个字符串作为格式化的结果。 - ``` + ```js var number = 2; var unit = "year" var formatResult = relativeTimeFormat.format(number, unit); @@ -308,7 +304,7 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 获取相对时间格式化结果的各个部分，从而自定义格式化结果。 - ``` + ```js var number = 2; var unit = "year" var formatResult = relativeTimeFormat.formatToParts(number, unit); @@ -316,9 +312,9 @@ Intl开发指导提供了ECMA 402中定义的国际化能力接口的使用方 4. 访问相对时间格式化对象的相关属性。 - RelativeTimeFormat的resolvedOptions方法会返回一个对象，该对象包含了RelativeTimeFormat对象的所有相关属性及其值，完整的属性列表参见[ RelativeTimeFormatResolvedOptions](../reference/apis/js-apis-intl.md)。 + RelativeTimeFormat的resolvedOptions方法会返回一个对象，该对象包含了RelativeTimeFormat对象的所有相关属性及其值，完整的属性列表参见[ RelativeTimeFormatResolvedOptions](../reference/apis/js-apis-intl.md#relativetimeformatresolvedoptions8)。 - ``` + ```js var options = numberFormat.resolvedOptions(); ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-i18n.md b/zh-cn/application-dev/reference/apis/js-apis-i18n.md index fff45c8b7c38b1c905f413003f1b550bca8b3dcd..d84e7183ac86ed17606acf85933dc3b444a93e10 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-i18n.md +++ b/zh-cn/application-dev/reference/apis/js-apis-i18n.md @@ -1,14 +1,17 @@ # 国际化-I18n -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + 本模块提供系统相关的或者增强的国际化能力，包括区域管理、电话号码处理、日历等，相关接口为ECMA 402标准中未定义的补充接口。 +[Intl模块](js-apis-intl.md)提供了ECMA 402标准定义的基础国际化接口，与本模块共同使用可提供完整地国际化支持能力。 + +> **说明：** +> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > -> - I18N模块包含国际化能力增强接口（未在ECMA 402中定义）。 +> - I18N模块包含国际化能力增强接口（未在ECMA 402中定义），包括区域管理、电话号码处理、日历等，国际化基础能力请参考[Intl模块](js-apis-intl.md)。 ## 导入模块 -``` +```js import i18n from '@ohos.i18n'; ``` @@ -34,7 +37,7 @@ getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): st | string | 指定语言的本地化显示文本。 | **示例：** - ``` + ```js i18n.getDisplayLanguage("zh", "en-GB", true); i18n.getDisplayLanguage("zh", "en-GB"); ``` @@ -61,7 +64,7 @@ getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): stri | string | 指定国家的本地化显示文本。 | **示例：** - ``` + ```js i18n.getDisplayCountry("zh-CN", "en-GB", true); i18n.getDisplayCountry("zh-CN", "en-GB"); ``` @@ -86,7 +89,7 @@ isRTL(locale: string): boolean | boolean | true表示该locale从右至左显示语言；false表示该locale从左至右显示语言。 | **示例：** - ``` + ```js i18n.isRTL("zh-CN");// 中文不是RTL语言，返回false i18n.isRTL("ar-EG");// 阿语是RTL语言，返回true ``` @@ -106,7 +109,7 @@ getSystemLanguage(): string | string | 系统语言ID。 | **示例：** - ``` + ```js i18n.getSystemLanguage(); ``` @@ -115,14 +118,14 @@ getSystemLanguage(): string setSystemLanguage(language: string): boolean -设置系统语言。 +设置系统语言。当前调用该接口不支持系统界面语言的实时刷新。 + +此接口为系统接口。 **需要权限**：ohos.permission.UPDATE_CONFIGURATION **系统能力**：SystemCapability.Global.I18n -**系统API**: 该接口为系统接口，三方应用不支持调用。 - **参数：** | 参数名 | 类型 | 说明 | | -------- | ------ | ----- | @@ -134,7 +137,7 @@ setSystemLanguage(language: string): boolean | boolean | 返回true，表示系统语言设置成功；返回false，表示系统语言设置失败。 | **示例：** - ``` + ```js i18n.setSystemLanguage('zh'); ``` @@ -145,9 +148,9 @@ getSystemLanguages(): Array<string> 获取系统支持的语言列表。 -**系统能力**：SystemCapability.Global.I18n +此接口为系统接口。 -**系统API**: 该接口为系统接口，三方应用不支持调用。 +**系统能力**：SystemCapability.Global.I18n **返回值：** | 类型 | 说明 | @@ -155,7 +158,7 @@ getSystemLanguages(): Array<string> | Array<string> | 系统支持的语言ID列表。 | **示例：** - ``` + ```js i18n.getSystemLanguages(); ``` @@ -166,9 +169,9 @@ getSystemCountries(language: string): Array<string> 获取针对输入语言系统支持的区域列表。 -**系统能力**：SystemCapability.Global.I18n +此接口为系统接口。 -**系统API**: 该接口为系统接口，三方应用不支持调用。 +**系统能力**：SystemCapability.Global.I18n **参数：** | 参数名 | 类型 | 说明 | @@ -181,7 +184,7 @@ getSystemCountries(language: string): Array<string> | Array<string> | 系统支持的区域ID列表。 | **示例：** - ``` + ```js i18n.getSystemCountries('zh'); ``` @@ -200,7 +203,7 @@ getSystemRegion(): string | string | 系统地区ID。 | **示例：** - ``` + ```js i18n.getSystemRegion(); ``` @@ -211,12 +214,12 @@ setSystemRegion(region: string): boolean 设置系统区域。 +此接口为系统接口。 + **需要权限**：ohos.permission.UPDATE_CONFIGURATION **系统能力**：SystemCapability.Global.I18n -**系统API**: 该接口为系统接口，三方应用不支持调用。 - **参数：** | 参数名 | 类型 | 说明 | | ------ | ------ | ----- | @@ -228,7 +231,7 @@ setSystemRegion(region: string): boolean | boolean | 返回true，表示系统区域设置成功；返回false，表示系统区域设置失败。 | **示例：** - ``` + ```js i18n.setSystemRegion('CN'); ``` @@ -247,7 +250,7 @@ getSystemLocale(): string | string | 系统区域ID。 | **示例：** - ``` + ```js i18n.getSystemLocale(); ``` @@ -258,12 +261,12 @@ setSystemLocale(locale: string): boolean 设置系统Locale。 +此接口为系统接口。 + **需要权限**：ohos.permission.UPDATE_CONFIGURATION **系统能力**：SystemCapability.Global.I18n -**系统API**: 该接口为系统接口，三方应用不支持调用。 - **参数：** | 参数名 | 类型 | 说明 | | ------ | ------ | --------------- | @@ -275,7 +278,7 @@ setSystemLocale(locale: string): boolean | boolean | 返回true，表示系统Locale设置成功；返回false，表示系统Locale设置失败。 | **示例：** - ``` + ```js i18n.setSystemLocale('zh-CN'); ``` @@ -286,9 +289,9 @@ isSuggested(language: string, region?: string): boolean 判断当前语言和区域是否匹配。 -**系统能力**：SystemCapability.Global.I18n +此接口为系统接口。 -**系统API**: 该接口为系统接口，三方应用不支持调用。 +**系统能力**：SystemCapability.Global.I18n **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -302,7 +305,7 @@ isSuggested(language: string, region?: string): boolean | boolean | 返回true，表示当前语言和地区匹配；返回false，表示当前语言和地区不匹配。 | **示例：** - ``` + ```js i18n.isSuggested('zh', 'CN'); ``` @@ -327,7 +330,7 @@ getCalendar(locale: string, type? : string): Calendar | [Calendar](#calendar8) | 日历对象。 | **示例：** - ``` + ```js i18n.getCalendar("zh-Hans", "gregory"); ``` @@ -349,7 +352,7 @@ setTime(date: Date): void | date | Date | 是 | 将要设置的日历对象的内部时间日期。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("en-US", "gregory"); var date = new Date(2021, 10, 7, 8, 0, 0, 0); calendar.setTime(date); @@ -370,7 +373,7 @@ setTime(time: number): void | time | number | 是 | time为从1970.1.1 00:00:00 GMT逝去的毫秒数。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("en-US", "gregory"); calendar.setTime(10540800000); ``` @@ -395,7 +398,7 @@ set(year: number, month: number, date:number, hour?: number, minute?: number, se | second | number | 否 | 设置的秒。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.10.1 08:00:00 ``` @@ -415,7 +418,7 @@ setTimeZone(timezone: string): void | timezone | string | 是 | 设置的时区id，如“Asia/Shanghai”。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.setTimeZone("Asia/Shanghai"); ``` @@ -435,7 +438,7 @@ getTimeZone(): string | string | 日历对象的时区id。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.setTimeZone("Asia/Shanghai"); calendar.getTimeZone(); // Asia/Shanghai" @@ -456,7 +459,7 @@ getFirstDayOfWeek(): number | number | 获取一周的起始日，1代表周日，7代表周六。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("en-US", "gregory"); calendar.getFirstDayOfWeek(); ``` @@ -476,7 +479,7 @@ setFirstDayOfWeek(value: number): void | value | number | 否 | 设置一周的起始日，1代表周日，7代表周六。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.setFirstDayOfWeek(0); ``` @@ -496,7 +499,7 @@ getMinimalDaysInFirstWeek(): number | number | 一年中第一周的最小天数。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.getMinimalDaysInFirstWeek(); ``` @@ -516,7 +519,7 @@ setMinimalDaysInFirstWeek(value: number): void | value | number | 否 | 一年中第一周的最小天数。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.setMinimalDaysInFirstWeek(3); ``` @@ -541,7 +544,7 @@ get(field: string): number | number | 与field相关联的值，如当前Calendar对象的内部日期的年份为1990，get("year")返回1990。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.10.1 08:00:00 calendar.get("hour_of_day"); // 8 @@ -567,7 +570,7 @@ getDisplayName(locale: string): string | string | 日历在locale所指示的区域的名字。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("en-US", "buddhist"); calendar.getDisplayName("zh"); // 佛历 ``` @@ -592,7 +595,7 @@ isWeekend(date?: Date): boolean | boolean | 当所判断的日期为周末时，返回 true，否则返回false。 | **示例：** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.set(2021, 11, 11, 8, 0, 0); // set time to 2021.11.11 08:00:00 calendar.isWeekend(); // false @@ -619,7 +622,7 @@ constructor(country: string, options?: PhoneNumberFormatOptions) | options | [PhoneNumberFormatOptions](#phonenumberformatoptions8) | 否 | 电话号码格式化对象的相关选项。 | **示例：** - ``` + ```js var phoneNumberFormat= new i18n.PhoneNumberFormat("CN", {"type": "E164"}); ``` @@ -643,7 +646,7 @@ isValidNumber(number: string): boolean | boolean | 返回true表示电话号码的格式正确，返回false表示电话号码的格式错误。 | **示例：** - ``` + ```js var phonenumberfmt = new i18n.PhoneNumberFormat("CN"); phonenumberfmt.isValidNumber("15812312312"); ``` @@ -668,17 +671,43 @@ format(number: string): string | string | 格式化后的电话号码。 | **示例：** - ``` + ```js var phonenumberfmt = new i18n.PhoneNumberFormat("CN"); phonenumberfmt.format("15812312312"); ``` +### getLocationName9+ + +getLocationName(number: string, locale: string): string + +获取电话号码归属地。 + +**系统能力**：SystemCapability.Global.I18n + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---- | +| number | string | 是 | 电话号码 | +| locale | string | 是 | 区域ID | + +**返回值：** +| 类型 | 说明 | +| ------ | -------- | +| string | 电话号码归属地。 | + +**示例：** + ```js + var phonenumberfmt = new i18n.PhoneNumberFormat("CN"); + phonenumberfmt.getLocationName("15812312345", "zh-CN"); + ``` + + ## PhoneNumberFormatOptions8+ 表示电话号码格式化对象可设置的属性。 -**系统能力**：以下各项对应的系统能力均为SystemCapability.Global.I18n +**系统能力**：SystemCapability.Global.I18n | 名称 | 参数类型 | 可读 | 可写 | 说明 | | ---- | ------ | ---- | ---- | ---------------------------------------- | @@ -689,7 +718,7 @@ format(number: string): string 度量衡单位信息。 -**系统能力**：以下各项对应的系统能力均为SystemCapability.Global.I18n +**系统能力**：SystemCapability.Global.I18n | 名称 | 参数类型 | 可读 | 可写 | 说明 | | ------------- | ------ | ---- | ---- | ---------------------------------------- | @@ -723,11 +752,35 @@ static unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: | string | 按照toUnit的单位格式化后，得到的字符串。 | **示例：** - ``` + ```js i18n.Util.unitConvert({unit: "cup", measureSystem: "US"}, {unit: "liter", measureSystem: "SI"}, 1000, "en-US", "long"); ``` +### getDateOrder9+ + +static getDateOrder(locale: string): string + +获取某一区域的日期的年、月、日排列顺序。 + +**系统能力**：SystemCapability.Global.I18n + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------- | +| locale | string | 是 | 格式化时使用的区域参数，如：zh-Hans-CN。 | + +**返回值：** +| 类型 | 说明 | +| ------ | ------------------- | +| string | 返回某一区域的日期的年、月、日排列顺序 | + +**示例：** + ```js + i18n.Util.getDateOrder("zh-CN"); + ``` + + ## getInstance8+ getInstance(locale?:string): IndexUtil @@ -747,7 +800,7 @@ getInstance(locale?:string): IndexUtil | [IndexUtil](#indexutil8) | locale对应的IndexUtil对象。 | **示例：** - ``` + ```js var indexUtil= i18n.getInstance("zh-CN"); ``` @@ -769,7 +822,7 @@ getIndexList(): Array<string> | Array<string> | 返回当前locale对应的索引列表。 | **示例：** - ``` + ```js var indexUtil = i18n.getInstance("zh-CN"); var indexList = indexUtil.getIndexList(); ``` @@ -789,7 +842,7 @@ addLocale(locale: string): void | locale | string | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 | **示例：** - ``` + ```js var indexUtil = i18n.getInstance("zh-CN"); indexUtil.addLocale("en-US"); ``` @@ -814,9 +867,9 @@ getIndex(text: string): string | string | 输入文本对应的索引值。 | **示例：** - ``` + ```js var indexUtil= i18n.getInstance("zh-CN"); - indexUtil.getIndex("hi"); // 返回h + indexUtil.getIndex("hi"); // 返回hi ``` @@ -842,7 +895,7 @@ static isDigit(char: string): boolean | boolean | 返回true表示输入的字符是数字，返回false表示输入的字符不是数字。 | **示例：** - ``` + ```js var isdigit = i18n.Character.isDigit("1"); // 返回true ``` @@ -866,7 +919,7 @@ static isSpaceChar(char: string): boolean | boolean | 返回true表示输入的字符是空格符，返回false表示输入的字符不是空格符。 | **示例：** - ``` + ```js var isspacechar = i18n.Character.isSpaceChar("a"); // 返回false ``` @@ -890,7 +943,7 @@ static isWhitespace(char: string): boolean | boolean | 返回true表示输入的字符是空白符，返回false表示输入的字符不是空白符。 | **示例：** - ``` + ```js var iswhitespace = i18n.Character.isWhitespace("a"); // 返回false ``` @@ -914,7 +967,7 @@ static isRTL(char: string): boolean | boolean | 返回true表示输入的字符是从右到左语言的字符，返回false表示输入的字符不是从右到左语言的字符。 | **示例：** - ``` + ```js var isrtl = i18n.Character.isRTL("a"); // 返回false ``` @@ -938,7 +991,7 @@ static isIdeograph(char: string): boolean | boolean | 返回true表示输入的字符是表意文字，返回false表示输入的字符不是表意文字。 | **示例：** - ``` + ```js var isideograph = i18n.Character.isIdeograph("a"); // 返回false ``` @@ -962,7 +1015,7 @@ static isLetter(char: string): boolean | boolean | 返回true表示输入的字符是字母，返回false表示输入的字符不是字母。 | **示例：** - ``` + ```js var isletter = i18n.Character.isLetter("a"); // 返回true ``` @@ -986,7 +1039,7 @@ static isLowerCase(char: string): boolean | boolean | 返回true表示输入的字符是小写字母，返回false表示输入的字符不是小写字母。 | **示例：** - ``` + ```js var islowercase = i18n.Character.isLowerCase("a"); // 返回true ``` @@ -1010,7 +1063,7 @@ static isUpperCase(char: string): boolean | boolean | 返回true表示输入的字符是大写字母，返回false表示输入的字符不是大写字母。 | **示例：** - ``` + ```js var isuppercase = i18n.Character.isUpperCase("a"); // 返回false ``` @@ -1034,7 +1087,7 @@ static getType(char: string): string | string | 输入字符的一般类别值。 | **示例：** - ``` + ```js var type = i18n.Character.getType("a"); ``` @@ -1058,7 +1111,7 @@ getLineInstance(locale: string): BreakIterator | [BreakIterator](#breakiterator8) | 用于进行断句的处理器。 | **示例：** - ``` + ```js var iterator = i18n.getLineInstance("en"); ``` @@ -1080,7 +1133,7 @@ setLineBreakText(text: string): void | text | string | 是 | 指定BreakIterator进行断句的文本。 | **示例：** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); ``` @@ -1100,7 +1153,7 @@ getLineBreakText(): string | string | BreakIterator对象正在处理的文本 | **示例：** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.getLineBreakText(); // Apple is my favorite fruit. @@ -1121,7 +1174,7 @@ current(): number | number | BreakIterator在当前所处理的文本中的位置。 | **示例：** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.current(); // 0 @@ -1142,7 +1195,7 @@ first(): number | number | 被处理文本的第一个分割点的偏移量。 | **示例：** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.first(); // 0 @@ -1163,7 +1216,7 @@ last(): number | number | 被处理的文本的最后一个分割点的偏移量 | **示例：** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.last(); // 27 @@ -1189,7 +1242,7 @@ next(index?: number): number | number | 返回移动了index个分割点后，当前[BreakIterator](#breakiterator8)在文本中的位置。若移动index个分割点后超出了所处理的文本的长度范围，返回-1。 | **示例：** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.first(); // 0 @@ -1212,7 +1265,7 @@ previous(): number | number | 返回移动到前一个分割点后，当前[BreakIterator](#breakiterator8)在文本中的位置。若移动index个分割点后超出了所处理的文本的长度范围，返回-1。 | **示例：** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.first(); // 0 @@ -1240,7 +1293,7 @@ following(offset: number): number | number | 返回[BreakIterator](#breakiterator8)移动后的位置，如果由offset所指定的位置的下一个分割点超出了文本的范围则返回-1。 | **示例：** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.following(0); // 6 @@ -1268,7 +1321,7 @@ isBoundary(offset: number): boolean | boolean | 如果是一个分割点返回true, 否则返回false。 | **示例：** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.isBoundary(0); // true; @@ -1290,7 +1343,7 @@ is24HourClock(): boolean | boolean | 返回true，表示系统24小时开关开启；返回false，表示系统24小时开关关闭。 | **示例：** - ``` + ```js var is24HourClock = i18n.is24HourClock(); ``` @@ -1316,7 +1369,7 @@ set24HourClock(option: boolean): boolean | boolean | 返回true，表示修改成功；返回false，表示修改失败。 | **示例：** - ``` + ```js // 将系统时间设置为24小时制 var success = i18n.set24HourClock(true); ``` @@ -1344,7 +1397,7 @@ addPreferredLanguage(language: string, index?: number): boolean | boolean | 返回true，表示添加成功；返回false，表示添加失败。 | **示例：** - ``` + ```js // 将语言zh-CN添加到系统偏好语言列表中 var language = 'zh-CN'; var index = 0; @@ -1373,7 +1426,7 @@ removePreferredLanguage(index: number): boolean | boolean | 返回true，表示删除成功；返回false，表示删除失败。 | **示例：** - ``` + ```js // 删除系统偏好语言列表中的第一个偏好语言 var index = 0; var success = i18n.removePreferredLanguage(index); @@ -1394,7 +1447,7 @@ getPreferredLanguageList(): Array<string> | Array<string> | 系统偏好语言列表。 | **示例：** - ``` + ```js var preferredLanguageList = i18n.getPreferredLanguageList(); ``` @@ -1413,7 +1466,7 @@ getFirstPreferredLanguage(): string | string | 偏好语言列表中的第一个语言。 | **示例：** - ``` + ```js var firstPreferredLanguage = i18n.getFirstPreferredLanguage(); ``` @@ -1437,15 +1490,15 @@ getTimeZone(zoneID?: string): TimeZone | TimeZone | 时区ID对应的时区对象。 | **示例：** - ``` + ```js var timezone = i18n.getTimeZone(); ``` -## RelativeTimeFormat8+ +## TimeZone -### getID8+ +### getID getID(): string @@ -1459,13 +1512,13 @@ getID(): string | string | 时区对象对应的时区ID。 | **示例：** - ``` + ```js var timezone = i18n.getTimeZone(); timezone.getID(); ``` -### getDisplayName8+ +### getDisplayName getDisplayName(locale?: string, isDST?: boolean): string @@ -1485,13 +1538,13 @@ getDisplayName(locale?: string, isDST?: boolean): string | string | 时区对象在指定区域的表示。 | **示例：** - ``` + ```js var timezone = i18n.getTimeZone(); timezone.getDisplayName("zh-CN", false); ``` -### getRawOffset8+ +### getRawOffset getRawOffset(): number @@ -1505,13 +1558,13 @@ getRawOffset(): number | number | 时区对象表示的时区与UTC时区的偏差。 | **示例：** - ``` + ```js var timezone = i18n.getTimeZone(); timezone.getRawOffset(); ``` -### getOffset8+ +### getOffset getOffset(date?: number): number @@ -1525,7 +1578,212 @@ getOffset(date?: number): number | number | 某一时刻时区对象表示的时区与UTC时区的偏差。 | **示例：** - ``` + ```js var timezone = i18n.getTimeZone(); timezone.getOffset(1234567890); + ``` + + +### getAvailableIDs9+ + +static getAvailableIDs(): Array<string> + +获取系统支持的时区ID。 + +**系统能力**：SystemCapability.Global.I18n + +**返回值：** +| 类型 | 说明 | +| ------------------- | ----------- | +| Array<string> | 系统支持的时区ID列表 | + +**示例：** + ```ts + var ids = i18n.TimeZone.getAvailableIDs(); + ``` + + +### getAvailableZoneCityIDs9+ + +static getAvailableZoneCityIDs(): Array<string> + +获取系统支持的时区城市ID。 + +**系统能力**：SystemCapability.Global.I18n + +**返回值：** +| 类型 | 说明 | +| ------------------- | ------------- | +| Array<string> | 系统支持的时区城市ID列表 | + +**示例：** + ```ts + var cityIDs = i18n.TimeZone.getAvailableZoneCityIDs(); + ``` + + +### getCityDisplayName9+ + +static getCityDisplayName(cityID: string, locale: string): string + +获取某时区城市在locale下的本地化显示。 + +**系统能力**：SystemCapability.Global.I18n + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------ | +| cityID | string | 是 | 时区城市ID | +| locale | string | 是 | 区域ID | + +**返回值：** +| 类型 | 说明 | +| ------ | ------------------ | +| string | 时区城市在locale下的本地化显示 | + +**示例：** + ```ts + var displayName = i18n.TimeZone.getCityDisplayName("Shanghai", "zh-CN"); + ``` + + +### getTimezoneFromCity9+ + +static getTimezoneFromCity(cityID: string): TimeZone + +创建某时区城市对应的时区对象。 + +**系统能力**：SystemCapability.Global.I18n + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------ | +| cityID | string | 是 | 时区城市ID | + +**返回值：** +| 类型 | 说明 | +| -------- | ----------- | +| TimeZone | 时区城市对应的时区对象 | + +**示例：** + ```ts + var timezone = i18n.TimeZone.getTimezoneFromCity("Shanghai"); + ``` + + +## i18n.setUsingLocalDigit9+ + +setUsingLocalDigit(flag: boolean): boolean + +设置是否打开本地数字开关。 + +此接口为系统接口。 + +**需要权限**：ohos.permission.UPDATE_CONFIGURATION + +**系统能力**：SystemCapability.Global.I18n + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +| ---- | ------- | ---- | ------------------------------- | +| flag | boolean | 是 | true表示打开本地数字开关，false表示关闭本地数字开关。 | + +**返回值：** +| 类型 | 说明 | +| ------- | ----------------------------------- | +| boolean | true表示本地数字开关设置成功，false表示本地数字开关设置失败。 | + +**示例：** + ```ts + var status = i18n.setUsingLocalDigit(true); + ``` + + +## i18n.getUsingLocalDigit9+ + +getUsingLocalDigit(): boolean + +获取系统当前是否打开本地数字开关。 + +**系统能力**：SystemCapability.Global.I18n + +**返回值：** +| 类型 | 说明 | +| ------- | ---------------------------------------- | +| boolean | true表示系统当前已打开本地数字开关，false表示系统当前未打开本地数字开关。 | + +**示例：** + ```ts + var status = i18n.getUsingLocalDigit(); + ``` + + +## Transliterator9+ + + +### getAvailableIDs9+ + +static getAvailableIDs(): string[] + +获取音译支持的ID列表。 + +**系统能力**：SystemCapability.Global.I18n + +**返回值：** +| 类型 | 说明 | +| -------- | ---------- | +| string[] | 音译支持的ID列表。 | + +**示例：** + ```ts + i18n.Transliterator.getAvailableIDs(); + ``` + + +### getInstance9+ + +static getInstance(id: string): Transliterator + +创建音译对象。 + +**系统能力**：SystemCapability.Global.I18n + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | -------- | +| id | string | 是 | 音译支持的ID。 | + +**返回值：** +| 类型 | 说明 | +| ---------------------------------- | ----- | +| [Transliterator](#transliterator9) | 音译对象。 | + +**示例：** + ```ts + var transliterator = i18n.Transliterator.getInstance("Any-Latn"); + ``` + + +### transform9+ + +transform(text: string): string + +将输入字符串从源格式转换为目标格式。 + +**系统能力**：SystemCapability.Global.I18n + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | ------ | +| text | string | 是 | 输入字符串。 | + +**返回值：** +| 类型 | 说明 | +| ------ | -------- | +| string | 转换后的字符串。 | + +**示例：** + ```ts + var transliterator = i18n.Transliterator.getInstance("Any-Latn"); + transliterator.transform("中国"); ``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-intl.md b/zh-cn/application-dev/reference/apis/js-apis-intl.md index 194a9ae443c99078fca73b70f746b13912663771..9157c68e4501463b98633d1c86451b6e455c0f44 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-intl.md +++ b/zh-cn/application-dev/reference/apis/js-apis-intl.md @@ -1,14 +1,17 @@ # 国际化-Intl -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** + 本模块提供提供基础的应用国际化能力，包括时间日期格式化、数字格式化、排序等，相关接口在ECMA 402标准中定义。 +[I18N模块](js-apis-i18n.md)提供其他非ECMA 402定义的国际化接口，与本模块共同使用可提供完整地国际化支持能力。 + +> **说明：** > - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > -> - Intl模块包含国际化能力基础接口（在ECMA 402中定义）。 +> - Intl模块包含国际化能力基础接口（在ECMA 402中定义），包括时间日期格式化、数字格式化、排序等，国际化增强能力请参考[I18N模块](js-apis-i18n.md)。 ## 导入模块 -``` +```js import Intl from '@ohos.intl'; ``` @@ -43,7 +46,7 @@ constructor() **系统能力**：SystemCapability.Global.I18n **示例：** - ``` + ```js var locale = new Intl.Locale(); ``` @@ -63,7 +66,7 @@ constructor(locale: string, options?: LocaleOptions) | options | LocaleOptions | 否 | 用于创建区域对象的选项。 | **示例：** - ``` + ```js var locale = new Intl.Locale("zh-CN"); ``` @@ -82,7 +85,7 @@ toString(): string | string | 字符串形式的区域信息。 | **示例：** - ``` + ```js var locale = new Intl.Locale("zh-CN"); locale.toString(); ``` @@ -102,7 +105,7 @@ maximize(): Locale | [Locale](#locale) | 最大化后的区域对象。 | **示例：** - ``` + ```js var locale = new Intl.Locale("zh-CN"); locale.maximize(); ``` @@ -122,7 +125,7 @@ minimize(): Locale | [Locale](#locale) | 最小化后的区域对象。 | **示例：** - ``` + ```js var locale = new Intl.Locale("zh-CN"); locale.minimize(); ``` @@ -132,7 +135,7 @@ minimize(): Locale 表示区域初始化选项。 -**系统能力**：以下各项对应的系统能力均为SystemCapability.Global.I18n +**系统能力**：SystemCapability.Global.I18n | 名称 | 参数类型 | 可读 | 可写 | 说明 | | --------------- | ------- | ---- | ---- | ---------------------------------------- | @@ -156,7 +159,7 @@ constructor() **系统能力**：SystemCapability.Global.I18n **示例：** - ``` + ```js var datefmt= new Intl.DateTimeFormat(); ``` @@ -176,13 +179,13 @@ constructor(locale: string | Array<string>, options?: DateTimeOptions) | options | [DateTimeOptions](#datetimeoptions) | 否 | 用于创建时间日期格式化的选项。 | **示例：** - ``` + ```js var datefmt= new Intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' }); ``` **示例：** - ``` + ```js var datefmt= new Intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' }); ``` @@ -206,7 +209,7 @@ format(date: Date): string | string | 格式化后的时间日期字符串 | **示例：** - ``` + ```js var date = new Date(2021, 11, 17, 3, 24, 0); var datefmt = new Intl.DateTimeFormat("en-GB"); datefmt.format(date); @@ -233,7 +236,7 @@ formatRange(startDate: Date, endDate: Date): string | string | 格式化后的时间日期段字符串。 | **示例：** - ``` + ```js var startDate = new Date(2021, 11, 17, 3, 24, 0); var endDate = new Date(2021, 11, 18, 3, 24, 0); var datefmt = new Intl.DateTimeFormat("en-GB"); @@ -255,7 +258,7 @@ resolvedOptions(): DateTimeOptions | [DateTimeOptions](#datetimeoptions) | DateTimeFormat 对象的格式化选项。 | **示例：** - ``` + ```js var datefmt = new Intl.DateTimeFormat("en-GB"); datefmt.resolvedOptions(); ``` @@ -265,7 +268,7 @@ resolvedOptions(): DateTimeOptions 表示时间日期格式化选项。 -**系统能力**：以下各项对应的系统能力均为SystemCapability.Global.I18n +**系统能力**：SystemCapability.Global.I18n | 名称 | 参数类型 | 可读 | 可写 | 说明 | | --------------- | ------- | ---- | ---- | ---------------------------------------- | @@ -302,7 +305,7 @@ constructor() **系统能力**：SystemCapability.Global.I18n **示例：** - ``` + ```js var numfmt = new Intl.NumberFormat(); ``` @@ -322,7 +325,7 @@ constructor(locale: string | Array<string>, options?: NumberOptions) | options | [NumberOptions](#numberoptions) | 否 | 用于创建数字格式化的选项。 | **示例：** - ``` + ```js var numfmt = new Intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"}); ``` @@ -347,7 +350,7 @@ format(number: number): string; **示例：** - ``` + ```js var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"}); numfmt.format(1223); ``` @@ -368,7 +371,7 @@ resolvedOptions(): NumberOptions **示例：** - ``` + ```js var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"}); numfmt.resolvedOptions(); ``` @@ -388,7 +391,7 @@ resolvedOptions(): NumberOptions | currencyDisplay | string | 是 | 是 | 货币的显示方式，取值包括："symbol", "narrowSymbol", "code", "name"。 | | unit | string | 是 | 是 | 单位名称，如："meter"，"inch"，“hectare”等。 | | unitDisplay | string | 是 | 是 | 单位的显示格式，取值包括："long", "short", "narrow"。 | -| unitUsage8+ | string | 是 | 是 | 单位的使用场景，取值包括："default", "area-land-agricult", "area-land-commercl", "area-land-residntl", "length-person", "length-person-small", "length-rainfall", "length-road", "length-road-small", "length-snowfall", "length-vehicle", "length-visiblty", "length-visiblty-small", "length-person-informal", "length-person-small-informal", "length-road-informal", "speed-road-travel", "speed-wind", "temperature-person", "temperature-weather", "volume-vehicle-fuel"。 | +| unitUsage8+ | string | 是 | 是 | 单位的使用场景，取值包括："default", "area-land-agricult", "area-land-commercl", "area-land-residntl", "length-person", "length-person-small", "length-rainfall", "length-road", "length-road-small", "length-snowfall", "length-vehicle", "length-visiblty", "length-visiblty-small", "length-person-informal", "length-person-small-informal", "length-road-informal", "speed-road-travel", "speed-wind", "temperature-person", "temperature-weather", "volume-vehicle-fuel"。 | | signDisplay | string | 是 | 是 | 数字符号的显示格式，取值包括："auto", "never", "always", "expectZero"。 | | compactDisplay | string | 是 | 是 | 紧凑型的显示格式，取值包括："long", "short"。 | | notation | string | 是 | 是 | 数字的格式化规格，取值包括："standard", "scientific", "engineering", "compact"。 | @@ -415,7 +418,7 @@ constructor() **系统能力**：SystemCapability.Global.I18n **示例：** - ``` + ```js var collator = new Intl.Collator(); ``` @@ -436,7 +439,7 @@ constructor(locale: string | Array<string>, options?: CollatorOptions) | options | [CollatorOptions](#collatoroptions) | 否 | 用于创建排序对象的选项。 | **示例：** - ``` + ```js var collator = new Intl.Collator("zh-CN", {localeMatcher: "lookup", usage: "sort"}); ``` @@ -461,7 +464,7 @@ compare(first: string, second: string): number | number | 比较结果。当number为负数，表示first排序在second之前；当number为0，表示first与second排序相同；当number为正数，表示first排序在second之后。 | **示例：** - ``` + ```js var collator = new Intl.Collator("zh-Hans"); collator.compare("first", "second"); ``` @@ -481,17 +484,17 @@ resolvedOptions(): CollatorOptions | [CollatorOptions](#collatoroptions) | 返回的Collator对象的属性。 | **示例：** - ``` + ```js var collator = new Intl.Collator("zh-Hans"); var options = collator.resolvedOptions(); ``` -## CollatorOptions8+ +## CollatorOptions8+ 表示Collator可设置的属性。 -**系统能力**：以下各项对应的系统能力均为SystemCapability.Global.I18n +**系统能力**：SystemCapability.Global.I18n | 名称 | 参数类型 | 可读 | 可写 | 说明 | | ----------------- | ------- | ---- | ---- | ---------------------------------------- | @@ -516,7 +519,7 @@ constructor() **系统能力**：SystemCapability.Global.I18n **示例：** - ``` + ```js var pluralRules = new Intl.PluralRules(); ``` @@ -536,8 +539,8 @@ constructor(locale: string | Array<string>, options?: PluralRulesOptions) | options | [PluralRulesOptions](#pluralrulesoptions) | 否 | 用于创建单复数对象的选项。 | **示例：** - ``` - var pluralRules= new Intl.PluraRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"}); + ```js + var pluralRules= new Intl.PluralRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"}); ``` @@ -560,17 +563,17 @@ select(n: number): string | string | 单复数类别，取值包括："zero"，"one"，"two", "few", "many", "others"。 | **示例：** - ``` + ```js var pluralRules = new Intl.PluralRules("zh-Hans"); pluralRules.select(1); ``` -## PluralRulesOptions8+ +## PluralRulesOptions8+ 表示PluralRules对象可设置的属性。 -**系统能力**：以下各项对应的系统能力均为SystemCapability.Global.I18n +**系统能力**：SystemCapability.Global.I18n | 名称 | 参数类型 | 可读 | 可写 | 说明 | | ------------------------ | ------ | ---- | ---- | ---------------------------------------- | @@ -595,7 +598,7 @@ constructor() **系统能力**：SystemCapability.Global.I18n **示例：** - ``` + ```js var relativetimefmt = new Intl.RelativeTimeFormat(); ``` @@ -615,7 +618,7 @@ constructor(locale: string | Array<string>, options?: RelativeTimeFormatIn | options | [RelativeTimeFormatInputOptions](#relativetimeformatinputoptions) | 否 | 用于创建相对时间格式化对象的选项。 | **示例：** - ``` + ```js var relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"}); ``` @@ -640,7 +643,7 @@ format(value: number, unit: string): string | string | 格式化后的相对时间。 | **示例：** - ``` + ```js var relativetimefmt = new Intl.RelativeTimeFormat("zh-CN"); relativetimefmt.format(3, "quarter") ``` @@ -666,7 +669,7 @@ formatToParts(value: number, unit: string): Array<object> | Array<object> | 返回可用于自定义区域设置格式的相对时间格式的对象数组。 | **示例：** - ``` + ```js var relativetimefmt = new Intl.RelativeTimeFormat("en", {"numeric": "auto"}); var parts = relativetimefmt.format(10, "seconds"); ``` @@ -686,17 +689,17 @@ resolvedOptions(): RelativeTimeFormatResolvedOptions | [RelativeTimeFormatResolvedOptions](#relativetimeformatresolvedoptions) | RelativeTimeFormat 对象的格式化选项。 | **示例：** - ``` + ```js var relativetimefmt= new Intl.RelativeTimeFormat("en-GB"); relativetimefmt.resolvedOptions(); ``` -## RelativeTimeFormatInputOptions8+ +## RelativeTimeFormatInputOptions8+ 表示RelativeTimeFormat对象可设置的属性。 -**系统能力**：以下各项对应的系统能力均为SystemCapability.Global.I18n +**系统能力**：SystemCapability.Global.I18n | 名称 | 参数类型 | 可读 | 可写 | 说明 | | ------------- | ------ | ---- | ---- | ---------------------------------------- | @@ -705,11 +708,11 @@ resolvedOptions(): RelativeTimeFormatResolvedOptions | style | string | 是 | 是 | 国际化消息的长度，取值包括："long", "short", "narrow"。 | -## RelativeTimeFormatResolvedOptions8+ +## RelativeTimeFormatResolvedOptions8+ 表示RelativeTimeFormat对象可设置的属性。 -**系统能力**：以下各项对应的系统能力均为SystemCapability.Global.I18n +**系统能力**：SystemCapability.Global.I18n | 名称 | 参数类型 | 可读 | 可写 | 说明 | | --------------- | ------ | ---- | ---- | ---------------------------------------- |