Skip to content

D
Docs

OpenHarmony / Docs
大约 1 年 前同步成功

通知 159
Star 292
Fork 28
D
Docs

体验新版 GitCode，发现更多精彩内容 >>

未验证 提交 31f7aa0b 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!14474 更新国际化开发指南 

Merge pull request !14474 from sunyaozu/OpenHarmony-3.2-Beta5
上级 0a92ae55 cd1c7dda
隐藏空白更改
内联 并排
Showing with 972 addition and 459 deletion
zh-cn/application-dev/internationalization/i18n-guidelines.md
浏览文件 @ 31f7aa0b
......@@ -4,176 +4,299 @@
[Intl](intl-guidelines.md)模块提供了ECMA 402标准定义的基础国际化接口，与本模块共同使用可提供完整地国际化支持能力。
## 获取系统语言区域信息
## 获取和设置系统国际化相关信息
调用系统提供的接口访问系统的语言区域信息。
调用接口访问和设置系统语言、偏好语言、地区、24小时制、本地数字开关等国际化信息。
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| --------- | ---------------------------------------- | --------------------- |
| ohos.i18n | getSystemLanguage():string | 获取系统语言。 |
| ohos.i18n | getSystemRegion():string | 获取系统区域。 |
| ohos.i18n | getSystemLocale():string | 获取系统Locale。 |
| ohos.i18n | isRTL(locale:string):boolean<sup>7+</sup> | locale对应的语言是否为从右到左语言。 |
| ohos.i18n | is24HourClock():boolean<sup>7+</sup> | 获取当前系统时间是否采用24小时制。 |
| ohos.i18n | getDisplayLanguage(language:string,locale:string,sentenceCase?:boolean):string | 获取语言的本地化表示。 |
| ohos.i18n | getDisplayCountry(country:string,locale:string,sentenceCase?:boolean):string | 获取国家的本地化表示。 |
| System | getDisplayCountry(country:string,locale:string,sentenceCase?:boolean):string<sup>9+</sup> | 获取国家的本地化表示。 |
| System | getDisplayLanguage(language:string,locale:string,sentenceCase?:boolean):string<sup>9+</sup> | 获取语言的本地化表示。 |
| System | getSystemLanguages():Array<string><sup>9+</sup> | 获取系统语言列表。 |
| System | getSystemCountries(language: string):Array<string><sup>9+</sup> | 获取针对输入语言系统支持的国家或地区列表。 |
| System | isSuggested(language: string, region?: string): boolean<sup>9+</sup> | 判断当前语言和地区是否匹配 |
| System | getSystemLanguage():string<sup>9+</sup> | 获取系统语言。 |
| System | setSystemLanguage(language: string)<sup>9+</sup> | 设置系统语言。 |
| System | getSystemRegion():string<sup>9+</sup> | 获取系统地区。 |
| System | setSystemRegion(region: string)<sup>9+</sup> | 设置系统地区。 |
| System | getSystemLocale():string<sup>9+</sup> | 获取系统Locale。 |
| System | setSystemLocale(locale: string)<sup>9+</sup> | 设置系统Locale。 |
| System | is24HourClock():boolean<sup>9+</sup> | 判断系统时间是否为24小时制。 |
| System | set24HourClock():boolean<sup>9+</sup> | 修改系统时间的24小时制设置。 |
| System | addPreferredLanguage(language: string, index?: number)<sup>9+</sup> | 在系统偏好语言列表的指定位置添加偏好语言。 |
| System | removePreferredLanguage(index: number)<sup>9+</sup> | 删除系统偏好语言列表中指定位置的偏好语言。 |
| System | getPreferredLanguageList()<sup>9+</sup> | 获取系统偏好语言列表。 |
| System | getFirstPreferredLanguage()<sup>9+</sup> | 获取系统偏好语言列表中的第一个偏好语言。 |
| System | getAppPreferredLanguage()<sup>9+</sup> | 获取应用偏好语言。 |
| System | setUsingLocalDigit(flag: boolean)<sup>9+</sup> | 设置是否打开本地数字开关。 |
| System | getUsingLocalDigit()<sup>9+</sup> | 获取系统当前是否打开本地数字开关。 |
| | isRTL(locale:string):boolean<sup>9+</sup> | locale对应的语言是否为从右到左语言。 |
### 开发步骤
1. 导入I18n模块。
1. 获取系统语言。
```js
import I18n from '@ohos.i18n'
```
2. 获取和设置系统语言。
调用setSystemLanguage接口设置系统语言（该接口为系统接口，只有具有UPDATE_CONFIGURATION权限的系统应用可以调用）。
调用getSystemLanguage接口获取系统语言。
```js
try {
I18n.System.setSystemLanguage("en"); // 将系统语言设置为 "en"
let language = I18n.System.getSystemLanguage(); // language = "en"
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`)
}
```
调用getSystemLanguage方法获取当前系统设置的语言（i18n为导入的模块）。
3. 获取和设置系统区域。
调用setSystemRegion接口设置系统国家（该接口为系统接口，只有具有UPDATE_CONFIGURATION权限的系统应用可以调用）。
调用getSystemRegion接口获取系统国家。
```js
var language = i18n.getSystemLanguage();
try {
I18n.System.setSystemRegion("CN"); // 将系统国家设置为 "CN"
let region = I18n.System.getSystemRegion(); // region = "CN"
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`)
}
```
2. 获取系统区域。
4. 获取和设置系统Locale。
调用getSystemRegion方法获取当前系统设置的区域
调用setSystemLocale接口设置系统Locale（该接口为系统接口，只有具有UPDATE_CONFIGURATION权限的系统应用可以调用）。Locale的定义请见[Locale](../internationalization/intl-guidelines.md#设置区域信息)
调用getSystemLocale接口获取系统Locale。
```js
var region = i18n.getSystemRegion();
try {
I18n.System.setSystemLocale("zh-Hans-CN"); // 将系统Locale设置为 "zh-Hans-CN"
let locale = I18n.System.getSystemLocale(); // locale = "zh-Hans-CN"
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`)
}
```
3. 获取系统Locale。
5. 判断Locale的语言是否为从右到左语言。
调用getSystemLocale方法获取当前系统设置的Locale
调用isRTL接口获取Locale的语言是否为从右到左语言。
```js
var locale = i18n.getSystemLocale();
try {
let rtl = I18n.isRTL("zh-CN"); // rtl = false
rtl = I18n.isRTL("ar"); // rtl = true
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`)
}
```
4. 判断Locale的语言是否为RTL语言。
6. 获取和设置系统24小时制设置。
调用isRTL方法获取Locale的语言是否为从右到左语言。
调用set24HourClock接口打开系统24小时制设置。
调用is24HourClock接口来判断当前是否打开系统24小时制设置。
```js
var rtl = i18n.isRTL("zh-CN");
try {
I18n.System.set24HourClock(true);
let hourClock = I18n.System.is24HourClock(); // hourClock = true
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`)
}
```
5. 判断当前系统时间是否采用24小时制。
7. 获取语言的本地化表示。
调用is24HourClock方法来判断当前系统的时间是否采用24小时制。
调用getDisplayLanguage接口获取某一语言的本地化表示。其中，language表示待本地化显示的语言，locale表示本地化的Locale，sentenceCase结果是否需要首字母大写。
```js
var hourClock = i18n.is24HourClock();
try {
let language = "en";
let locale = "zh-CN";
let sentenceCase = false;
let localizedLanguage = I18n.System.getDisplayLanguage(language, locale, sentenceCase); // localizedLanguage = "英语"
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`)
}
```
6. 获取语言的本地化表示。
8. 获取国家的本地化表示。
调用getDisplayLanguage方法获取某一语言的本地化表示。其中，language表示待本地化显示的语言，locale表示本地化的Locale，sentenceCase结果是否需要首字母大写。
调用getDisplayCountry接口获取某一国家的本地化表示。其中，country表示待本地化显示的国家，locale表示本地化的Locale，sentenceCase结果是否需要首字母大写。
```js
var language = "en";
var locale = "zh-CN";
var sentenceCase = false;
var localizedLanguage = i18n.getDisplayLanguage(language, locale, sentenceCase);
try {
let country = "US";
let locale = "zh-CN";
let sentenceCase = false;
let localizedCountry = I18n.System.getDisplayCountry(country, locale, sentenceCase); // localizedCountry = "美国"
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`)
}
```
7. 获取国家的本地化表示。
9. 获取系统语言列表和某个语言系统支持的国家列表。
调用getSystemLanguages接口获取系统支持的语言列表。
调用getSystemCountries接口获取某一语言系统支持的地区列表。
```js
try {
let languageList = I18n.System.getSystemLanguages(); // languageList = ["en-Latn-US", "zh-Hans"]
let countryList = I18n.System.getSystemCountries("zh"); // countryList = ["ZW", "YT", ..., "CN", "DE"], 共240个国家和地区
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`)
}
```
10. 判断语言和国家是否匹配。
调用isSuggested接口判断语言和地区是否匹配。
```js
try {
let isSuggest = I18n.System.isSuggested("zh", "CN"); // isSuggest = true
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`)
}
```
调用getDisplayCountry方法获取某一国家的本地化表示。其中，country表示待本地化显示的国家，locale表示本地化的Locale，sentenceCase结果是否需要首字母大写。
11. 获取与设置偏好语言。
调用addPreferredLanguage接口在当前系统偏好语言列表中插入偏好语言。
调用removePreferredLanguage接口移除系统偏好语言列表中的某个语言。（addPreferredLanguage接口和removePreferredLanguage接口为系统接口，只有具有UPDATE_CONFIGURATION权限的系统应用可以调用。）
调用getPreferredLanguageList接口获取系统当前偏好语言列表。
调用getFirstPreferredLanguage接口获取系统偏好语言列表中的第一个偏好语言。
调用getAppPreferredLanguageList接口获取应用偏好语言，应用偏好语言为系统偏好语言列表中第一个与应用的资源匹配的语言。
```js
var country = "US";
var locale = "zh-CN";
var sentenceCase = false;
var localizedCountry = i18n.getDisplayCountry(country, locale, sentenceCase);
try {
I18n.System.addPreferredLanguage("en-GB", 0); // 将"en-GB"设置为系统偏好语言列表的第一个语言
let list = I18n.System.getPreferredLanguageList(); // 获取当前系统偏好语言列表 list = ["en-GB", ...]
I18n.System.removePreferredLanguage(list.length - 1); // 移除当前系统偏好语言列表中的最后一个偏好语言
let firstPreferredLanguage = I18n.System.getFirstPreferredLanguage(); // firstPreferredLanguage = "en-GB"
let appPreferredLanguage = I18n.System.getAppPreferredLanguage(); // 当应用中包含 "en-GB"资源时，应用偏好语言为"en-GB"
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`)
}
```
12. 获取和设置系统本地化数字开关。
调用setUsingLocalDigit接口打开本地化数字开关。（此接口为系统接口，只有具有UPDATE_CONFIGURATION权限的系统应用可以调用。）
调用getUsingLocalDigit接口访问本地化数字开关状态。
当前只有 "ar", "as", "bn", "fa", "mr", "my", "ne", "ur" 8个语言支持打开本地数字开关。
```js
try {
I18n.System.setUsingLocalDigit(true); // 打开本地化数字开关
let status = I18n.System.getUsingLocalDigit(); // status = true
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`)
}
```
## 获取日历信息
调用日历[Calendar](../reference/apis/js-apis-i18n.md#calendar8)相关接口来获取日历的相关信息，例如获取日历的本地化显示、一周起始日、一年中第一周的最小天数等。
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| --------- | ---------------------------------------- | --------------------- |
| ohos.i18n | getCalendar(locale:string,type?:string):Calendar<sup>8+</sup> | 获取指定locale和type的日历对象。 |
| ohos.i18n | setTime(date:Date): void<sup>8+</sup> | 设置日历对象内部的时间日期。 |
| ohos.i18n | setTime(time:number): void<sup>8+</sup> | 设置日历对象内部的时间日期。 |
| ohos.i18n | set(year:number,month:number,date:number,hour?:number,minute?:number,second?:number): void<sup>8+</sup> | 设置日历对象的年、月、日、时、分、秒。 |
| ohos.i18n | setTimeZone(timezone:string): void<sup>8+</sup> | 设置日历对象的时区。 |
| ohos.i18n | getTimeZone():string<sup>8+</sup> | 获取日历对象的时区。 |
| ohos.i18n | getFirstDayOfWeek():number<sup>8+</sup> | 获取日历对象的一周起始日。 |
| ohos.i18n | setFirstDayOfWeek(value:number): void<sup>8+</sup> | 设置日历对象的一周起始日。 |
| ohos.i18n | getMinimalDaysInFirstWeek():number<sup>8+</sup> | 获取一年中第一周的最小天数。 |
| ohos.i18n | setMinimalDaysInFirstWeek(value:number): void<sup>8+</sup> | 设置一年中第一周的最小天数。 |
| ohos.i18n | getDisplayName(locale:string):string<sup>8+</sup> | 获取日历对象的本地化表示。 |
| ohos.i18n | isWeekend(date?:Date):boolean<sup>8+</sup> | 判断给定的日期是否在日历中是周末。 |
| | getCalendar(locale:string,type?:string):Calendar<sup>8+</sup> | 获取指定locale和type的日历对象。 |
| Calendar | setTime(date:Date): void<sup>8+</sup> | 设置日历对象内部的时间日期。 |
| Calendar | setTime(time:number): void<sup>8+</sup> | 设置日历对象内部的时间日期。 |
| Calendar | set(year:number,month:number,date:number,hour?:number,minute?:number,second?:number): void<sup>8+</sup> | 设置日历对象的年、月、日、时、分、秒。 |
| Calendar | setTimeZone(timezone:string): void<sup>8+</sup> | 设置日历对象的时区。 |
| Calendar | getTimeZone():string<sup>8+</sup> | 获取日历对象的时区。 |
| Calendar | getFirstDayOfWeek():number<sup>8+</sup> | 获取日历对象的一周起始日。 |
| Calendar | setFirstDayOfWeek(value:number): void<sup>8+</sup> | 设置日历对象的一周起始日。 |
| Calendar | getMinimalDaysInFirstWeek():number<sup>8+</sup> | 获取一年中第一周的最小天数。 |
| Calendar | setMinimalDaysInFirstWeek(value:number): void<sup>8+</sup> | 设置一年中第一周的最小天数。 |
| Calendar | getDisplayName(locale:string):string<sup>8+</sup> | 获取日历对象的本地化表示。 |
| Calendar | isWeekend(date?:Date):boolean<sup>8+</sup> | 判断给定的日期是否在日历中是周末。 |
### 开发步骤
1. 实例化日历对象。
1. 导入I18n模块。
调用getCalendar方法获取指定locale和type的时区对象（i18n为导入的模块）。其中，type表示合法的日历类型，目前合法的日历类型包括："buddhist", "chinese", "coptic", "ethiopic", "hebrew", "gregory", "indian", "islamic_civil", "islamic_tbla", "islamic_umalqura", "japanese", "persian"。当type没有给出时，采用区域默认的日历类型。
```js
import I18n from '@ohos.i18n'
```
2. 实例化日历对象。
调用getCalendar接口获取指定locale和type的时区对象（i18n为导入的模块）。其中，type表示合法的日历类型，目前合法的日历类型包括："buddhist", "chinese", "coptic", "ethiopic", "hebrew", "gregory", "indian", "islamic_civil", "islamic_tbla", "islamic_umalqura", "japanese", "persian"。当type没有给出时，采用区域默认的日历类型。
```js
var calendar = i18n.getCalendar("zh-CN", "gregory");
let calendar = I18n.getCalendar("zh-CN", "chinese"); // 创建中文农历日历
```
2. 设置日历对象的时间。
3. 设置日历对象的时间。
调用setTime方法设置日历对象的时间。setTime方法接收两种类型的参数。一种是传入一个Date对象，另一种是传入一个数值表示从1970.1.1 00:00:00 GMT逝去的毫秒数。
调用setTime接口设置日历对象的时间。setTime接口接收两种类型的参数。一种是传入一个Date对象，另一种是传入一个数值表示从1970.1.1 00:00:00 GMT逝去的毫秒数。
```js
var date1 = new Date();
let date1 = new Date();
calendar.setTime(date1);
var date2 = 1000;
let date2 = 1000;
calendar.setTime(date2);
```
3. 设置日历对象的年、月、日、时、分、秒。
4. 设置日历对象的年、月、日、时、分、秒。
调用set方法设置日历对象的年、月、日、时、分、秒。
调用set接口设置日历对象的年、月、日、时、分、秒。
```js
calendar.set(2021, 12, 21, 6, 0, 0)
```
4. 设置、获取日历对象的时区。
5. 设置、获取日历对象的时区。
调用setTimeZone方法和getTimeZone方法来设置、获取日历对象的时区。其中，setTimeZone方法需要传入一个字符串表示需要设置的时区。
调用setTimeZone接口和getTimeZone接口来设置、获取日历对象的时区。其中，setTimeZone接口需要传入一个字符串表示需要设置的时区。
```js
calendar.setTimeZone("Asia/Shanghai");
var timezone = calendar.getTimeZone();
let timezone = calendar.getTimeZone(); // timezone = "China Standard Time"
```
5. 设置、获取日历对象的一周起始日。
6. 设置、获取日历对象的一周起始日。
调用setFirstDayOfWeek方法和getFirstDayOfWeek方法设置、获取日历对象的一周起始日。其中，setFirstDayOfWeek需要传入一个数值表示一周的起始日，1代表周日，7代表周六。
调用setFirstDayOfWeek接口和getFirstDayOfWeek接口设置、获取日历对象的一周起始日。其中，setFirstDayOfWeek需要传入一个数值表示一周的起始日，1代表周日，7代表周六。
```js
calendar.setFirstDayOfWeek(1);
var firstDayOfWeek = calendar.getFirstDayOfWeek();
let firstDayOfWeek = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 1
```
6. 设置、获取日历对象第一周的最小天数
调用setMinimalDaysInFirstWeek方法和getMinimalDaysInFirstWeek方法来设置、获取日历对象第一周的最小天数。
7. 设置、获取日历对象第一周的最小天数。
调用setMinimalDaysInFirstWeek接口和getMinimalDaysInFirstWeek接口来设置、获取日历对象第一周的最小天数。
```js
calendar.setMinimalDaysInFirstWeek(3);
var minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek();
let minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 3
```
7. 获取日历对象的本地化显示
8. 获取日历对象的本地化显示。
调用getDisplayName来获取日历对象的本地化显示。
```js
var localizedName = calendar.getDisplayName("zh-CN");
let localizedName = calendar.getDisplayName("zh-CN"); // localizedName = "农历"
```
8. 判断某一个日期是否为周末。
9. 判断某一个日期是否为周末。
调用isWeekend方法来判断输入的Date是否为周末。
调用isWeekend接口来判断输入的Date是否为周末。
```js
var date = new Date();
var weekend = calendar.isWeekend(date);
let date = new Date(2022, 12, 12, 12, 12, 12);
let weekend = calendar.isWeekend(date); // weekend = false
```
## 电话号码格式化
......@@ -182,36 +305,43 @@
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| --------- | ---------------------------------------- | ----------------------- |
| ohos.i18n | constructor(country:string,options?:PhoneNumberFormatOptions)<sup>8+</sup> | 实例化PhoneNumberFormat对象。 |
| ohos.i18n | isValidNumber(number:string):boolean<sup>8+</sup> | 判断number是否是一个格式正确的电话号码。 |
| ohos.i18n | format(number:string):string<sup>8+</sup> | 对number按照指定国家及风格进行格式化。 |
| PhoneNumberFormat | constructor(country:string,options?:PhoneNumberFormatOptions)<sup>8+</sup> | 实例化PhoneNumberFormat对象。 |
| PhoneNumberFormat | isValidNumber(number:string):boolean<sup>8+</sup> | 判断number是否是一个格式正确的电话号码。 |
| PhoneNumberFormat | format(number:string):string<sup>8+</sup> | 对number按照指定国家及风格进行格式化。 |
| PhoneNumberFormat | getLocationName(number: string, locale: string): string<sup>9+</sup> | 获取电话号码归属地。 |
### 开发步骤
1. 实例化电话号码格式化对象。
1. 导入I18n模块。
```js
import I18n from '@ohos.i18n'
```
2. 实例化电话号码格式化对象。
调用PhoneNumberFormat的构造函数来实例化电话号码格式化对象，需要传入电话号码的国家代码及格式化选项。其中，格式化选项是可选的，包括style选项，该选项的取值包括："E164", "INTERNATIONAL", "NATIONAL", "RFC3966"。
```js
var phoneNumberFormat = new i18n.PhoneNumberFormat("CN", {type: "E164"});
let phoneNumberFormat = new I18n.PhoneNumberFormat("CN", {type: "E164"});
```
2. 判断电话号码格式是否正确。
3. 判断电话号码格式是否正确。
调用isValidNumber方法来判断输入的电话号码的格式是否正确。
调用isValidNumber接口来判断输入的电话号码的格式是否正确。
```js
var validNumber = phoneNumberFormat.isValidNumber("15812341234");
let validNumber = phoneNumberFormat.isValidNumber("15812341234"); // validNumber = true
```
3. 电话号码格式化。
4. 电话号码格式化。
调用电话号码格式化对象的format方法来对输入的电话号码进行格式化。
调用电话号码格式化对象的format接口来对输入的电话号码进行格式化。
```js
var formattedNumber = phoneNumberFormat.format("15812341234");
let formattedNumber = phoneNumberFormat.format("15812341234"); // formattedNumber = "+8615812341234"
```
## 度量衡转换
......@@ -220,23 +350,29 @@
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| --------- | ---------------------------------------- | --------------------------------------- |
| ohos.i18n | unitConvert(fromUnit:UnitInfo,toUnit:UnitInfo,value:number,locale:string,style?:string):string<sup>8+</sup> | 将fromUnit的单位转换为toUnit的单位，并根据区域与风格进行格式化。 |
| I18NUtil | unitConvert(fromUnit:UnitInfo,toUnit:UnitInfo,value:number,locale:string,style?:string):string<sup>9+</sup> | 将fromUnit的单位转换为toUnit的单位，并根据区域与风格进行格式化。 |
### 开发步骤
1. 度量衡单位转换。
1. 导入I18n模块。
```js
import I18n from '@ohos.i18n'
```
2. 度量衡单位转换。
调用[unitConvert](../reference/apis/js-apis-i18n.md#unitconvert9)方法实现度量衡单位转换，并进行格式化显示的功能。
调用[unitConvert](../reference/apis/js-apis-i18n.md#unitconvert9)接口实现度量衡单位转换，并进行格式化显示的功能。
```js
var fromUnit = {unit: "cup", measureSystem: "US"};
var toUnit = {unit: "liter", measureSystem: "SI"};
var number = 1000;
var locale = "en-US";
var style = "long";
i18n.Util.unitConvert(fromUtil, toUtil, number, locale, style);
let fromUnit = {unit: "cup", measureSystem: "US"};
let toUnit = {unit: "liter", measureSystem: "SI"};
let number = 1000;
let locale = "en-US";
let style = "long";
let converttedUnit = I18n.I18NUtil.unitConvert(fromUnit, toUnit, number, locale, style); // converttedUnit = "236.588 liters"
```
## 字母表索引
......@@ -245,47 +381,53 @@
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| --------- | ---------------------------------------- | ----------------------- |
| ohos.i18n | getInstance(locale?:string):IndexUtil<sup>8+</sup> | 实例化字母表索引对象。 |
| ohos.i18n | getIndexList():Array&lt;string&gt;<sup>8+</sup> | 获取当前Locale的索引列表。 |
| ohos.i18n | addLocale(locale:string): void<sup>8+</sup> | 将新的Locale对应的索引加入当前索引列表。 |
| ohos.i18n | getIndex(text:string):string<sup>8+</sup> | 获取text对应的索引。 |
| | getInstance(locale?:string):IndexUtil<sup>8+</sup> | 实例化字母表索引对象。 |
| IndexUtil | getIndexList():Array&lt;string&gt;<sup>8+</sup> | 获取当前Locale的索引列表。 |
| IndexUtil | addLocale(locale:string): void<sup>8+</sup> | 将新的Locale对应的索引加入当前索引列表。 |
| IndexUtil | getIndex(text:string):string<sup>8+</sup> | 获取text对应的索引。 |
### 开发步骤
1. 实例化字母表索引对象。
1. 导入I18n模块。
```js
import I18n from '@ohos.i18n'
```
调用getInstance方法来实例化特定locale对应的字母表索引对象。当locale参数为空时，实例化系统默认Locale的字母表索引对象。
2. 实例化字母表索引对象。
调用getInstance接口来实例化特定locale对应的字母表索引对象。当locale参数为空时，实例化系统默认Locale的字母表索引对象。
```js
var indexUtil = i18n.getInstance("zh-CN");
let indexUtil = I18n.getInstance("zh-CN");
```
2. 获取索引列表。
3. 获取索引列表。
调用getIndexList方法来获取当前Locale对应的字母表索引列表。
调用getIndexList接口来获取当前Locale对应的字母表索引列表。
```js
var indexList = indexUtil.getIndexList();
let indexList = indexUtil.getIndexList(); // indexList = ["...", "A", "B", "C", ..., "X", "Y", "Z", "..."]
```
3. 增加新的索引。
4. 增加新的索引。
调用addLocale方法，将新的Locale对应的字母表索引添加到当前字母表索引列表中。
调用addLocale接口，将新的Locale对应的字母表索引添加到当前字母表索引列表中。
```js
indexUtil.addLocale("ar")
```
4. 获取字符串对应的索引。
5. 获取字符串对应的索引。
调用getIndex方法来获取某一字符串对应的字母表索引。
调用getIndex接口来获取某一字符串对应的字母表索引。
```js
var text = "access index";
indexUtil.getIndex(text);
let text = "access index";
let index = indexUtil.getIndex(text); // index = "A"
```
## 获取文本断点位置
......@@ -294,68 +436,297 @@
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| --------- | ---------------------------------------- | ------------------------------ |
| ohos.i18n | getLineInstance(locale:string):BreakIterator<sup>8+</sup> | 实例化断行对象。 |
| ohos.i18n | setLineBreakText(text:string): void<sup>8+</sup> | 设置要处理的文本。 |
| ohos.i18n | getLineBreakText():string<sup>8+</sup> | 获取要处理的文本。 |
| ohos.i18n | current():number<sup>8+</sup> | 获取当前断行对象在处理文本的位置。 |
| ohos.i18n | first():number<sup>8+</sup> | 将断行对象设置到第一个可断句的分割点。 |
| ohos.i18n | last():number<sup>8+</sup> | 将断行对象设置到最后一个可断句的分割点。 |
| ohos.i18n | next(index?:number):number<sup>8+</sup> | 将断行对象移动index个分割点的位置。 |
| ohos.i18n | previous():number<sup>8+</sup> | 将断行对象移动到前一个分割点的位置。 |
| ohos.i18n | following(offset:number):number<sup>8+</sup> | 将断行对象移动到offset指定位置的后面一个分割点的位置。 |
| ohos.i18n | isBoundary(offset:number):boolean<sup>8+</sup> | 判断某个位置是否是分割点。 |
| | getLineInstance(locale:string):BreakIterator<sup>8+</sup> | 实例化断行对象。 |
| BreakIterator | setLineBreakText(text:string): void<sup>8+</sup> | 设置要处理的文本。 |
| BreakIterator | getLineBreakText():string<sup>8+</sup> | 获取要处理的文本。 |
| BreakIterator | current():number<sup>8+</sup> | 获取当前断行对象在处理文本的位置。 |
| BreakIterator | first():number<sup>8+</sup> | 将断行对象设置到第一个可断句的分割点。 |
| BreakIterator | last():number<sup>8+</sup> | 将断行对象设置到最后一个可断句的分割点。 |
| BreakIterator | next(index?:number):number<sup>8+</sup> | 将断行对象移动index个分割点的位置。 |
| BreakIterator | previous():number<sup>8+</sup> | 将断行对象移动到前一个分割点的位置。 |
| BreakIterator | following(offset:number):number<sup>8+</sup> | 将断行对象移动到offset指定位置的后面一个分割点的位置。 |
| BreakIterator | isBoundary(offset:number):boolean<sup>8+</sup> | 判断某个位置是否是分割点。 |
### 开发步骤
1. 实例化断行对象。
1. 导入I18n模块。
```js
import I18n from '@ohos.i18n'
```
2. 实例化断行对象。
调用getLineInstance方法来实例化断行对象。
调用getLineInstance接口来实例化断行对象。
```js
var locale = "en-US"
var breakIterator = i18n.getLineInstance(locale);
let locale = "en-US"
let breakIterator = I18n.getLineInstance(locale);
```
2. 设置、访问要断行处理的文本。
3. 设置、访问要断行处理的文本。
调用setLineBreakText方法和getLineBreakText方法来设置、访问要断行处理的文本。
调用setLineBreakText接口和getLineBreakText接口来设置、访问要断行处理的文本。
```js
var text = "Apple is my favorite fruit";
let text = "Apple is my favorite fruit";
breakIterator.setLineBreakText(text);
var breakText = breakIterator.getLineBreakText();
let breakText = breakIterator.getLineBreakText(); // breakText = "Apple is my favorite fruit"
```
3. 获取断行对象当前的位置。
4. 获取断行对象当前的位置。
调用current方法来获取断行对象在当前处理文本中的位置。
调用current接口来获取断行对象在当前处理文本中的位置。
```js
var pos = breakIterator.current();
let pos = breakIterator.current(); // pos = 0
```
4. 设置断行对象的位置。
5. 设置断行对象的位置。
系统提供了很多接口可以用于调整断行对象在处理文本中的位置，包括first, last, next, previous, following。
```js
var firstPos = breakIterator.first(); // 将断行对象设置到第一个分割点的位置，即文本的起始位置；
var lastPos = breakIterator.last(); // 将断行对象设置到最后一个分割点的位置，即文本末尾的下一个位置；
let firstPos = breakIterator.first(); // 将断行对象设置到第一个分割点的位置，即文本的起始位置；firstPos = 0
let lastPos = breakIterator.last(); // 将断行对象设置到最后一个分割点的位置，即文本末尾的下一个位置；lastPos = 26
// 将断行对象向前或向后移动一定数量的分割点。
// 当传入正数时，向后移动；当传入负数时，向前移动；当未传入数值时，则向后移动一个位置；
// 当移动超出了文本的长度范围，则返回-1；
var nextPos = breakIterator.next(-2);
var previousPos = breakIterator.previous(); // 将断行对象向前移动向前移动一个分割点，当超出文本长度范围时返回-1；
let nextPos = breakIterator.next(-2); // nextPos = 12
let previousPos = breakIterator.previous(); // 将断行对象向前移动向前移动一个分割点，当超出文本长度范围时返回-1； previousPos = 9
// 将断行对象移动到offset指定位置的后面一个分割点。如果offset所指定的位置的下一个分割点超出了文本的长度范围，则返回-1；
var followingPos = breakIterator.following(10);
let followingPos = breakIterator.following(10); // followingPos = 12
```
6. 判断某个位置是否为分割点。
调用isBoundary接口来判断一个接口是否为分割点；如果该位置是分割点，则返回true，并且将断行对象移动到该位置；如果该位置不是分割点，则返回false，并且将断行对象移动到该位置后的一个分割点。
```js
let isboundary = breakIterator.isBoundary(5); // isboundary = false
```
## 获取时区
调用时区[TimeZone](../reference/apis/js-apis-i18n.md#timezone)相关接口来获取时区的相关信息，例如获取时区的ID、本地化显示、时区偏移量等。
### 接口说明
| 类名 | 接口名称 | 描述 |
| --------- | ---------------------------------------- | ------------------------------ |
| | getTimeZone(zoneID?: string): TimeZone<sup>7+</sup> | 获取时区对象。 |
| TimeZone | getID(): string<sup>7+</sup> | 获取时区ID。 |
| TimeZone | getDisplayName(locale?: string, isDST?: boolean): string<sup>7+</sup> | 获取时区的本地化显示。 |
| TimeZone | getRawOffset(): number<sup>7+</sup> | 获取时区对象与UTC时区的偏移量。 |
| TimeZone | getOffset(date?: number): number<sup>7+</sup> | 获取某一时间点时区对象与UTC时区的偏移量。 |
| TimeZone | getAvailableIDs(): Array<string><sup>9+</sup> | 获取系统支持的时区ID列表。 |
| TimeZone | getAvailableZoneCityIDs(): Array<string><sup>9+</sup> | 获取系统支持的时区城市ID列表。 |
| TimeZone | getCityDisplayName(cityID: string, locale: string): string<sup>9+</sup> | 获取时区城市ID的本地化显示。 |
| TimeZone | getTimezoneFromCity(cityID: string): TimeZone<sup>9+</sup> | 获取时区城市ID对应的时区对象。 |
### 开发步骤
1. 导入I18n模块。
```js
import I18n from '@ohos.i18n'
```
2. 实例化时区对象，并获取相关时区信息。
调用getTimeZone接口来获取时区对象。
```js
let timezone = I18n.getTimeZone(); // 使用默认参数可以获取系统时区对象。
```
获取时区ID、本地化显示、时区偏移量、某一时刻的时区偏移量信息。
```js
let timezoneID = timezone.getID(); // timezoneID = "Asia/Shanghai"
let timezoneDisplayName = timezone.getDisplayName(); // timezoneDisplayName = "中国标准时间"
let rawOffset = timezone.getRawOffset(); // rawOffset = 28800000
let offset = timezone.getOffset(new Date().getTime()); // offset = 28800000
```
3. 获取系统支持的时区ID。
调用getAvailableIDs接口获取系统支持的时区ID列表。
时区ID列表中的时区ID可以作为getTimeZone接口的参数，来创建TimeZone对象。
```js
let timezoneIDs = I18n.TimeZone.getAvailableIDs(); // timezoneIDs = ["America/Adak", ...]，共包含24个时区ID
let timezone = I18n.getTimeZone(timezoneIDs[0]);
let timezoneDisplayName = timezone.getDisplayName(); // timezoneDisplayName = "夏威夷-阿留申时间"
```
4. 获取系统支持的时区城市ID。
调用getAvailableZoneCityIDs接口获取系统支持的时区城市ID列表。
调用getCityDisplayName接口获取时区城市ID的本地化显示。
调用getTimezoneFromCity接口基于时区城市ID创建时区对象。
```js
let zoneCityIDs = I18n.TimeZone.getAvailableZoneCityIDs(); // ["Auckland", "Magadan", ...]
let cityDisplayName = I18n.TimeZone.getCityDisplayName(zoneCityIDs[0], "zh-Hans"); // cityDisplayName = "奥克兰(新西兰)"
let timezone = I18n.TimeZone.getTimezoneFromCity(zoneCityIDs[0]);
let timezoneDisplayName = timezone.getDisplayName(); // timezoneDisplayName = "新西兰时间"
```
## 获取音译对象
调用音译[Transliterator](../reference/apis/js-apis-i18n.md#transliterator9)相关接口来创建音译对象，获取音译字符串。
### 接口说明
| 类名 | 接口名称 | 描述 |
| --------- | ---------------------------------------- | ------------------------------ |
| Transliterator | getAvailableIDs():Array<string><sup>9+</sup> | 获取音译支持的ID列表。 |
| Transliterator | getInstance(): Transliterator<sup>9+</sup> | 创建音译对象。 |
| Transliterator | transform(text: string): string<sup>9+</sup> | 获取音译字符串。 |
### 开发步骤
1. 导入I18n模块。
```js
import I18n from '@ohos.i18n'
```
2. 获取支持音译的ID列表。
调用getAvailableIDs接口来获取支持音译的ID列表。
每个ID的格式为 source-destination，例如 ASCII-Latin，表示将ASCII转换为Latin的音译ID。
```js
let ids = I18n.Transliterator.getAvailableIDs(); // ids = ["ASCII-Latin", "Accents-Any", ... ]，共支持671个语言
```
3. 创建音译对象，获取音译字符串。
支持音译的ID列表中的ID可以作为getInstance接口的参数，创建音译对象。
调用transform接口，获取音译字符串。
```js
let transliterator = I18n.Transliterator.getInstance("Any-Latn"); // Any-Latn表示将任意文本转换为Latn文本
let transformText = transliterator.transform("你好"); // transformText = "nǐ hǎo "
```
## 字符类型判断
调用字符[Unicode](../reference/apis/js-apis-i18n.md#unicode9)相关接口来获取字符的相关信息，例如字符是否是数字、字符是否是空格符等。
### 接口说明
| 类名 | 接口名称 | 描述 |
| --------- | ---------------------------------------- | ------------------------------ |
| Unicode | isDigit(char: string): boolean<sup>9+</sup> | 判断字符是否是数字。 |
| Unicode | isSpaceChar(char: string): boolean<sup>9+</sup> | 判断字符是否是空格符。 |
| Unicode | isWhitespace(char: string): boolean<sup>9+</sup> | 判断字符是否是空白符。 |
| Unicode | isRTL(char: string): boolean<sup>9+</sup> | 判断字符是否是从左到右显示的字符。 |
| Unicode | isIdeograph(char: string): boolean<sup>9+</sup> | 判断字符是否是表意文字。 |
| Unicode | isLetter(char: string): boolean<string><sup>9+</sup> | 判断字符是否是字母。 |
| Unicode | isLowerCase(char: string): boolean<string><sup>9+</sup> | 判断字符是否是小写字母。 |
| Unicode | isUpperCase(char: string): boolean<sup>9+</sup> | 判断字符是否是大写字母。 |
| Unicode | getType(char: string): string<sup>9+</sup> | 获取字符的类型。 |
### 开发步骤
1. 导入I18n模块。
```js
import I18n from '@ohos.i18n'
```
2. 判断字符是否具有某种性质。
判断字符是否是数字。
```js
let isDigit = I18n.Unicode.isDigit("1"); // isDigit = true
isDigit = I18n.Unicode.isDigit("a"); // isDigit = false
```
判断字符是否是空格符。
```js
let isSpaceChar = I18n.Unicode.isSpaceChar(" "); // isSpaceChar = true
isSpaceChar = I18n.Unicode.isSpaceChar("\n"); // isSpaceChar = false
```
判断字符是否是空白符。
```js
let isWhitespace = I18n.Unicode.isWhitespace(" "); // isWhitespace = true
isWhitespace = I18n.Unicode.isWhitespace("\n"); // isWhitespace = true
```
判断字符是否是从左到右书写的文字。
```js
let isRTL = I18n.Unicode.isRTL("مرحبًا"); // isRTL = true，阿拉伯语的文字是从左到右书写的文字
isRTL = I18n.Unicode.isRTL("a"); // isRTL = false
```
判断字符是否是表意文字。
```js
let isIdeograph = I18n.Unicode.isIdeograph("你好"); // isIdeograph = true
isIdeograph = I18n.Unicode.isIdeograph("a"); // isIdeograph = false
```
判断字符是否是字母。
```js
let isLetter = I18n.Unicode.isLetter("a"); // isLetter = true
isLetter = I18n.Unicode.isLetter("."); // isLetter = false
```
判断字符是否是小写字母。
```js
let isLowerCase = I18n.Unicode.isLowerCase("a"); // isLetter = true
isLowerCase = I18n.Unicode.isLowerCase("A"); // isLetter = false
```
判断字符是否是大写字母。
```js
let isUpperCase = I18n.Unicode.isUpperCase("a"); // isUpperCase = false
isUpperCase = I18n.Unicode.isUpperCase("A"); // isUpperCase = true
```
3. 获取字符的类型。
调用getType接口获取字符的类型。
```js
let type = I18n.Unicode.getType("a"); // type = U_LOWER_CASE_LETTER
```
## 获取日期中年月日的排列顺序
### 接口说明
| 类名 | 接口名称 | 描述 |
| --------- | ---------------------------------------- | ------------------------------ |
| I18NUtil | getDateOrder(locale: string): string<sup>9+</sup> | 判断日期中年月日的排列顺序。 |
### 开发步骤
1. 导入I18n模块。
```js
import I18n from '@ohos.i18n'
```
5. 判断某个位置是否为分割点。
2. 判断日期的年月日的排序顺序。
调用isBoundary方法来判断一个方法是否为分割点；如果该位置是分割点，则返回true，并且将断行对象移动到该位置；如果该位置不是分割点，则返回false，并且将断行对象移动到该位置后的一个分割点。
调用getDateOrder接口判断某一Locale的日期中，年月日的排列顺序。
接口返回一个字符串，由"y"，"L"，"d"三部分组成，分别表示年、月、日，使用中划线进行拼接。例如，"y-L-d"。
```js
var isboundary = breakIterator.isBoundary(5);
let order = I18n.I18NUtil.getDateOrder("zh-CN"); // order = "y-L-d"，表示中文中年月日的顺序为年-月-日。
```
\ No newline at end of file
zh-cn/application-dev/internationalization/intl-guidelines.md
浏览文件 @ 31f7aa0b
......@@ -10,17 +10,25 @@
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| -------- | -------- | -------- |
| ohos.intl | constructor()<sup>8+</sup> | 实例化Locale对象。 |
| ohos.intl | constructor(locale:string,options?:LocaleOptions) | 基于locale参数及其选项实例化Locale对象。 |
| ohos.intl | toString():string | 将Locale信息转换为字符串。 |
| ohos.intl | maximize():Locale | 最大化区域信息。 |
| ohos.intl | minimize():Locale | 最小化区域信息。 |
| Locale | constructor()<sup>8+</sup> | 实例化Locale对象。 |
| Locale | constructor(locale:string,options?:LocaleOptions) | 基于locale参数及其选项实例化Locale对象。 |
| Locale | toString():string | 将Locale信息转换为字符串。 |
| Locale | maximize():Locale | 最大化区域信息。 |
| Locale | minimize():Locale | 最小化区域信息。 |
### 开发步骤
1. 实例化Locale对象。
1. 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
```js
import Intl from '@ohos.intl'
```
2. 实例化Locale对象。
使用Locale的构造函数创建Locale对象，该方法接收一个表示Locale的字符串及可选的[属性](../reference/apis/js-apis-intl.md#localeoptions)列表（intl为导入的模块名）。
......@@ -40,33 +48,35 @@
```js
var locale = "zh-CN";
var options = {caseFirst: "false", calendar: "chinese", collation: "pinyin"};
var localeObj = new intl.Locale(locale, options);
let locale = "zh-CN";
let options = {caseFirst: "false", calendar: "chinese", collation: "pinyin"};
let localeObj = new Intl.Locale(locale, options);
```
2. 获取Locale的字符串表示。
3. 获取Locale的字符串表示。
调用toString方法来获取Locale对象的字符串表示，其中包括了语言、区域及其他选项信息。
```js
var localeStr = localeObj.toString();
let localeStr = localeObj.toString(); // localeStr = "zh-CN-u-ca-chinese-co-pinyin-kf-false
```
3. 最大化区域信息。
4. 最大化区域信息。
调用maximize方法来最大化区域信息，即当缺少脚本与地区信息时，对其进行补全。
```js
var maximizedLocale = localeObj.maximize();
let maximizedLocale = localeObj.maximize();
let maximizedLocaleStr = maximizedLocale.toString(); // localeStr = "zh-Hans-CN-u-ca-chinese-co-pinyin-kf-false
```
4. 最小化区域信息。
5. 最小化区域信息。
调用minimize方法来最小化区域信息，即当存在脚本与地区信息时，对其进行删除。
```js
var minimizedLocale = localeObj.minimize();
let minimizedLocale = localeObj.minimize();
let minimizedLocaleStr = minimizedLocale.toString(); // zh-u-ca-chinese-co-pinyin-kf-false
```
## 格式化日期时间
......@@ -75,57 +85,69 @@
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| -------- | -------- | -------- |
| ohos.intl | constructor()<sup>8+</sup> | 创建日期时间格式化对象。 |
| ohos.intl | constructor(locale:string\|Array&lt;string&gt;,options?:DateTimeOptions) | 创建日期时间格式化对象，并设置提供的Locale和格式化相关属性。 |
| ohos.intl | format(date:Date):string | 依据DateTimeFormat对象的Locale及其他格式化属性，计算日期时间的格式化表示。 |
| ohos.intl | formatRange(startDate:Date,endDate:Date):string | 依据DateTimeFormat对象的Locale及其他格式化属性，计算时间段的格式化表示。 |
| ohos.intl | resolvedOptions():DateTimeOptions | 获取DateTimeFormat对象的相关属性。 |
| DateTimeFormat | constructor()<sup>8+</sup> | 创建日期时间格式化对象。 |
| DateTimeFormat | constructor(locale:string\|Array&lt;string&gt;,options?:DateTimeOptions) | 创建日期时间格式化对象，并设置提供的Locale和格式化相关属性。 |
| DateTimeFormat | format(date:Date):string | 依据DateTimeFormat对象的Locale及其他格式化属性，计算日期时间的格式化表示。 |
| DateTimeFormat | formatRange(startDate:Date,endDate:Date):string | 依据DateTimeFormat对象的Locale及其他格式化属性，计算时间段的格式化表示。 |
| DateTimeFormat | resolvedOptions():DateTimeOptions | 获取DateTimeFormat对象的相关属性。 |
### 开发步骤
1. 实例化日期时间格式化对象。
1. 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
```js
import Intl from '@ohos.intl'
```
2. 实例化日期时间格式化对象。
一种方法是使用DateTimeFormat提供的默认构造函数，通过访问系统语言和地区设置，获取系统默认Locale，并将其作为DateTimeFormat对象内部的Locale（intl为导入的模块名）。
一种方法是使用DateTimeFormat提供的默认构造函数，通过访问系统语言和地区设置，获取系统默认Locale，并将其作为DateTimeFormat对象内部的Locale。
```js
var dateTimeFormat = new intl.DateTimeFormat();
let dateTimeFormat = new Intl.DateTimeFormat();
```
另一种方法是使用开发者提供的Locale和格式化参数来创建日期时间格式化对象。其中，格式化参数是可选的，完整的格式化参数列表见[DateTimeOptions](../reference/apis/js-apis-intl.md#datetimeoptions)。
```js
var options = {dateStyle: "full", timeStyle: "full"};
var dateTimeFormat = new intl.DateTimeFormat("zh-CN", options);
let options = {dateStyle: "full", timeStyle: "full"};
let dateTimeFormat = new Intl.DateTimeFormat("zh-CN", options);
```
2. 格式化日期时间。
3. 格式化日期时间。
使用DateTimeFormat的format方法对一个Date对象进行格式化，该方法会返回一个字符串作为格式化的结果。
```js
var date = new Date();
var formatResult = dateTimeFormat.format(date);
let options = {dateStyle: "full", timeStyle: "full"};
let dateTimeFormat = new Intl.DateTimeFormat("zh-CN", options);
let date = new Date(2022, 12, 12, 12, 12, 12);
let formatResult = dateTimeFormat.format(date); // formatResult = "2023年1月12日星期四 中国标准时间 下午12:12:12"
```
3. 格式化时间段。
4. 格式化时间段。
使用DateTimeFormat的formatRange方法对一个时间段进行格式化。该方法需要传入两个Date对象，分别表示时间段的起止日期，返回一个字符串作为格式化的结果。
```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);
let startDate = new Date(2021, 11, 17, 3, 24, 0);
let endDate = new Date(2021, 11, 18, 3, 24, 0);
let datefmt = new Intl.DateTimeFormat("en-GB");
let formatRangeResult = datefmt.formatRange(startDate, endDate); // formatRangeResult = "17/12/2021-18/12/2021"
```
4. 访问日期时间格式化对象的相关属性。
5. 访问日期时间格式化对象的相关属性。
DateTimeFormat的resolvedOptions方法会返回一个对象，该对象包含了DateTimeFormat对象的所有相关属性及其值。
```js
var options = dateTimeFormat.resolvedOptions();
let options = {dateStyle: "full", timeStyle: "full"};
let dateTimeFormat = new Intl.DateTimeFormat("zh-CN", options);
let resolvedOptions = dateTimeFormat.resolvedOptions(); // resolvedOptions = {"locale": "zh-CN", "calendar": "gregorian", "dateStyle":"full", "timeStyle":"full", "timeZone": "CST"}
```
## 数字格式化
......@@ -134,45 +156,57 @@
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| -------- | -------- | -------- |
| ohos.intl | constructor()<SUP>8+</SUP> | 创建数字格式化对象。 |
| ohos.intl | constructor(locale:string\|Array&lt;string&gt;,options?:NumberOptions) | 创建数字格式化对象，并设置提供的locale和格式化相关属性。 |
| ohos.intl | format(number:number):string | 依据NumberFormat对象的Locale及其他格式化属性，计算数字的格式化表示。 |
| ohos.intl | resolvedOptions():NumberOptions | 获取NumberFormat对象的相关属性。 |
| NumberFormat | constructor()<SUP>8+</SUP> | 创建数字格式化对象。 |
| NumberFormat | constructor(locale:string\|Array&lt;string&gt;,options?:NumberOptions) | 创建数字格式化对象，并设置提供的locale和格式化相关属性。 |
| NumberFormat | format(number:number):string | 依据NumberFormat对象的Locale及其他格式化属性，计算数字的格式化表示。 |
| NumberFormat | resolvedOptions():NumberOptions | 获取NumberFormat对象的相关属性。 |
### 开发步骤
1. 实例化数字格式化对象。
1. 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
```js
import Intl from '@ohos.intl'
```
2. 实例化数字格式化对象。
一种方法是使用NumberFormat提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。
```js
var numberFormat = new intl.NumberFormat();
let numberFormat = new Intl.NumberFormat();
```
另一种方法是使用开发者提供的Locale和格式化参数来创建数字格式化对象。其中，格式化参数是可选的，完整的格式化参数列表参见[NumberOptions](../reference/apis/js-apis-intl.md#numberoptions)。
```js
var options = {compactDisplay: "short", notation: "compact"};
var numberFormat = new intl.NumberFormat("zh-CN", options);
let options = {compactDisplay: "short", notation: "compact"};
let numberFormat = new Intl.NumberFormat("zh-CN", options);
```
2. 数字格式化。
3. 数字格式化。
使用NumberFormat的format方法对传入的数字进行格式化。该方法返回一个字符串作为格式化的结果。
```js
var number = 1234.5678
var formatResult = numberFormat.format(number);
let options = {compactDisplay: "short", notation: "compact"};
let numberFormat = new Intl.NumberFormat("zh-CN", options);
let number = 1234.5678
let formatResult = numberFormat.format(number); // formatResult = "1235"
```
3. 访问数字格式化对象的相关属性。
4. 访问数字格式化对象的相关属性。
NumberFormat的resolvedOptions方法会返回一个对象，该对象包含了NumberFormat对象的所有相关属性及其值。
```js
var options = numberFormat.resolvedOptions();
let options = {compactDisplay: "short", notation: "compact"};
let numberFormat = new Intl.NumberFormat("zh-CN", options);
let resolvedOptions = numberFormat.resolvedOptions(); // resolvedOptions = {"locale": "zh-CN", "compactDisplay": "short", "notation": "compact", "numberingSystem": "Latn"}
```
## 字符串排序
......@@ -181,45 +215,59 @@
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| -------- | -------- | -------- |
| ohos.intl | constructor()<sup>8+</sup> | 创建排序对象。 |
| ohos.intl | constructor(locale:string\|Array&lt;string&gt;,options?:CollatorOptions)<sup>8+</sup> | 创建排序对象，并设置提供的locale和其他相关属性。 |
| ohos.intl | compare(first:string,second:string):number<sup>8+</sup> | 依据排序对象的Locale及其属性，计算两个字符串的比较结果。 |
| ohos.intl | resolvedOptions():CollatorOptions<sup>8+</sup> | 获取排序对象的相关属性。 |
| Collator | constructor()<sup>8+</sup> | 创建排序对象。 |
| Collator | constructor(locale:string\|Array&lt;string&gt;,options?:CollatorOptions)<sup>8+</sup> | 创建排序对象，并设置提供的locale和其他相关属性。 |
| Collator | compare(first:string,second:string):number<sup>8+</sup> | 依据排序对象的Locale及其属性，计算两个字符串的比较结果。 |
| Collator | resolvedOptions():CollatorOptions<sup>8+</sup> | 获取排序对象的相关属性。 |
### 开发步骤
1. 实例化排序对象。
1. 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
```js
import Intl from '@ohos.intl'
```
2. 实例化排序对象。
一种方法是使用Collator提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。
```js
var collator = new intl.Collator();
let collator = new Intl.Collator();
```
另一种方法是使用开发者提供的Locale和其他相关参数来创建Collator对象，完整的参数列表参见[CollatorOptions](../reference/apis/js-apis-intl.md#collatoroptions9)。
其中，sensitivity参数用于控制哪些级别的差异会被用于比较两个字符串。取值"base"表示，仅比较字符本身，不考虑重音符号、大小写差异。例如，'a' != 'b'，'a' == 'á'，'a' == 'A'。取值"accent"表示考虑重音符号，不考虑大小写的差异。例如，'a' != 'b'，'a' != 'á'，'a' == 'A'。取值"case"表示考虑大小写的差异，不考虑重音符号的差异。例如，'a' != 'b'，'a' == 'á'，'a' != 'A'。取值"variant"表示考虑重音符号、大小写等方面差异。例如'a' != 'b'，'a' != 'á'，'a' != 'A'。
```js
var collator= new intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort"});
let collator= new Intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort", sensitivity: "case"});
```
2. 比较字符串。
3. 比较字符串。
使用Collator的compare方法对传入的两个字符串进行比较。该方法返回一个数值作为比较的结果，返回-1表示第一个字符串小于第二个字符串，返回1表示第一个字符大于第二个字符串，返回0表示两个字符串相同。基于两个字符串的比较结果，开发者可以字符串集合进行排序。
```js
var str1 = "first string";
var str2 = "second string";
var compareResult = collator.compare(str1, str2);
let collator= new Intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort", sensitivity: "case"});
let str1 = "first string";
let str2 = "second string";
let compareResult = collator.compare(str1, str2); // compareResult = -1
str1 = "first";
str2 = "First";
compareResult = collator.compare(str1, str2); // compareResult = -1
```
3. 访问排序对象的相关属性。
4. 访问排序对象的相关属性。
Collator的resolvedOptions方法会返回一个对象，该对象包含了Collator对象的所有相关属性及其值。
```js
var options = collator.resolvedOptions();
let collator= new Intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort"});
let options = collator.resolvedOptions(); // options = {"localeMatcher": "best fit", "locale": "zh-CN", "usage": "sort", "sensitivity": "variant", "ignorePunctuation": "false", "numeric": false, "caseFirst": "false", "collation": "default"}
```
## 判定单复数类别
......@@ -228,36 +276,45 @@
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| -------- | -------- | -------- |
| ohos.intl | constructor()<sup>8+</sup> | 创建单复数对象。 |
| ohos.intl | constructor(locale:string\|Array&lt;string&gt;,options?:PluralRulesOptions)<sup>8+</sup> | 创建单复数对象，并设置提供的locale和其他相关属性。 |
| ohos.intl | select(n:number):string<sup>8+</sup> | 依据单复数对象的Locale及其他格式化属性，计算数字的单复数类别。 |
| PluralRules | constructor()<sup>8+</sup> | 创建单复数对象。 |
| PluralRules | constructor(locale:string\|Array&lt;string&gt;,options?:PluralRulesOptions)<sup>8+</sup> | 创建单复数对象，并设置提供的locale和其他相关属性。 |
| PluralRules | select(n:number):string<sup>8+</sup> | 依据单复数对象的Locale及其他格式化属性，计算数字的单复数类别。 |
### 开发步骤
1. 实例化单复数对象。
1. 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
```js
import Intl from '@ohos.intl'
```
2. 实例化单复数对象。
一种方法是使用PluralRules提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。
```js
var pluralRules = new intl.PluralRules();
let pluralRules = new Intl.PluralRules();
```
另一种方法是使用开发者提供的Locale和其他相关参数来创建单复数对象。完整的参数列表参见[PluralRulesOptions](../reference/apis/js-apis-intl.md#pluralrulesoptions9)。
```js
var pluralRules = new intl.PluralRules("zh-CN", {localeMatcher: "best fit", type: "cardinal"});
let pluralRules = new Intl.PluralRules("zh-CN", {localeMatcher: "best fit", type: "cardinal"});
```
2. 计算数字单复数类别。
3. 计算数字单复数类别。
使用PluralRules的select方法计算传入数字的单复数类别。该方法返回一个字符串作为传入数字的类别，包括："zero", "one", "two", "few", "many", "other"六个类别。
```js
var number = 1234.5678
var categoryResult = plurals.select(number);
let pluralRules = new Intl.PluralRules("zh-CN", {localeMatcher: "best fit", type: "cardinal"});
let number = 1234.5678
let categoryResult = pluralRules.select(number); // categoryResult = "other"
```
## 相对时间格式化
......@@ -266,56 +323,67 @@
### 接口说明
| 模块 | 接口名称 | 描述 |
| 类名 | 接口名称 | 描述 |
| -------- | -------- | -------- |
| ohos.intl | constructor()<sup>8+</sup> | 创建相对时间格式化对象。 |
| ohos.intl | constructor(locale:string\|Array&lt;string&gt;,options?:RelativeTimeFormatInputOptions)<sup>8+</sup> | 创建相对时间格式化对象，并设置提供的locale和格式化相关属性。 |
| ohos.intl | format(value:number,unit:string):string<sup>8+</sup> | 依据相对时间格式化对象的Locale及其他格式化属性，计算相对时间的格式化表示。 |
| ohos.intl | formatToParts(value:number,unit:string):Array&lt;object&gt;<sup>8+</sup> | 依据相对时间格式化对象的Locale及其他格式化属性，返回相对时间格式化表示的各个部分。 |
| ohos.intl | resolvedOptions():RelativeTimeFormatResolvedOptions<sup>8+</sup> | 获取相对时间格式化对象的相关属性。 |
| RelativeTimeFormat | constructor()<sup>8+</sup> | 创建相对时间格式化对象。 |
| RelativeTimeFormat | constructor(locale:string\|Array&lt;string&gt;,options?:RelativeTimeFormatInputOptions)<sup>8+</sup> | 创建相对时间格式化对象，并设置提供的locale和格式化相关属性。 |
| RelativeTimeFormat | format(value:number,unit:string):string<sup>8+</sup> | 依据相对时间格式化对象的Locale及其他格式化属性，计算相对时间的格式化表示。 |
| RelativeTimeFormat | formatToParts(value:number,unit:string):Array&lt;object&gt;<sup>8+</sup> | 依据相对时间格式化对象的Locale及其他格式化属性，返回相对时间格式化表示的各个部分。 |
| RelativeTimeFormat | resolvedOptions():RelativeTimeFormatResolvedOptions<sup>8+</sup> | 获取相对时间格式化对象的相关属性。 |
### 开发步骤
1. 实例化相对时间格式化对象。
1. 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
```js
import Intl from '@ohos.intl'
```
2. 实例化相对时间格式化对象。
一种方法是使用RelativeTimeFormat提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。
```js
var relativeTimeFormat = new intl.RelativeTimeFormat();
let relativeTimeFormat = new Intl.RelativeTimeFormat();
```
另一种方法是使用开发者提供的Locale和格式化参数来创建相对时间格式化对象。其中，格式化参数是可选的，完整的参数列表参见[ RelativeTimeFormatInputOptions](../reference/apis/js-apis-intl.md#relativetimeformatinputoptions9)。
```
var relativeTimeFormat = new intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"});
```js
let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"});
```
2. 相对时间格式化。
3. 相对时间格式化。
使用RelativeTimeFormat的format方法对相对时间进行格式化。方法接收一个表示相对时间长度的数值和表示单位的字符串，其中单位包括："year", "quarter", "month", "week", "day", "hour", "minute", "second"。方法返回一个字符串作为格式化的结果。
```js
var number = 2;
var unit = "year"
var formatResult = relativeTimeFormat.format(number, unit);
let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"});
let number = 2;
let unit = "year"
let formatResult = relativeTimeFormat.format(number, unit); // 2年后
```
3. 获取相对时间格式化结果的各个部分。
4. 获取相对时间格式化结果的各个部分。
获取相对时间格式化结果的各个部分，从而自定义格式化结果。
```js
var number = 2;
var unit = "year"
var formatResult = relativeTimeFormat.formatToParts(number, unit);
let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"});
let number = 2;
let unit = "year"
let formatPartsResult = relativeTimeFormat.formatToParts(number, unit); // formatPartsResult = [{"type": "integer", "value": "2", "unit": "year"}, {"type":"literal", "value": "年后"}]
```
4. 访问相对时间格式化对象的相关属性。
5. 访问相对时间格式化对象的相关属性。
RelativeTimeFormat的resolvedOptions方法会返回一个对象，该对象包含了RelativeTimeFormat对象的所有相关属性及其值，完整的属性列表参见[ RelativeTimeFormatResolvedOptions](../reference/apis/js-apis-intl.md#relativetimeformatresolvedoptions8)。
```js
var options = numberFormat.resolvedOptions();
let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"});
let options = relativeTimeFormat.resolvedOptions(); // options = {"locale": "zh-CN", "style": "long", "numeric": "always", "numberingSystem": "latn"}
```
## 相关实例
......
zh-cn/application-dev/reference/apis/js-apis-i18n.md
浏览文件 @ 31f7aa0b
......@@ -12,7 +12,7 @@
## 导入模块
```js
import i18n from '@ohos.i18n';
import I18n from '@ohos.i18n';
```
......@@ -51,7 +51,7 @@ static getDisplayCountry(country: string, locale: string, sentenceCase?: boolean
**示例：**
```js
try {
var displayCountry = i18n.System.getDisplayCountry("zh-CN", "en-GB");
let displayCountry = I18n.System.getDisplayCountry("zh-CN", "en-GB"); // displayCountry = "China"
} catch(error) {
console.error(`call System.getDisplayCountry failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -90,7 +90,7 @@ static getDisplayLanguage(language: string, locale: string, sentenceCase?: boole
**示例：**
```js
try {
var displayLanguage = i18n.System.getDisplayLanguage("zh", "en-GB");
let displayLanguage = I18n.System.getDisplayLanguage("zh", "en-GB"); // displayLanguage = Chinese
} catch(error) {
console.error(`call System.getDisplayLanguage failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -100,7 +100,7 @@ static getDisplayLanguage(language: string, locale: string, sentenceCase?: boole
static getSystemLanguages(): Array&lt;string&gt;
获取系统支持的语言列表。
获取系统支持的语言列表。语言的详细说明参见[实例化Locale对象](../../internationalization/intl-guidelines.md#开发步骤)。
**系统能力**：SystemCapability.Global.I18n
......@@ -121,7 +121,7 @@ static getSystemLanguages(): Array&lt;string&gt;
**示例：**
```js
try {
var systemLanguages = i18n.System.getSystemLanguages();
let systemLanguages = I18n.System.getSystemLanguages(); // [ "en-Latn-US", "zh-Hans" ]
} catch(error) {
console.error(`call System.getSystemLanguages failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -131,7 +131,7 @@ static getSystemLanguages(): Array&lt;string&gt;
static getSystemCountries(language: string): Array&lt;string&gt;
获取针对输入语言系统支持的区域列表。
获取针对输入语言系统支持的国家或地区列表。国家或地区的详细说明参见[实例化Locale对象](../../internationalization/intl-guidelines.md#开发步骤)。
**系统能力**：SystemCapability.Global.I18n
......@@ -158,7 +158,7 @@ static getSystemCountries(language: string): Array&lt;string&gt;
**示例：**
```js
try {
var systemCountries = i18n.System.getSystemCountries('zh');
let systemCountries = I18n.System.getSystemCountries('zh'); // systemCountries = [ "ZW", "YT", "YE", ..., "ER", "CN", "DE" ]，共计240个国家或地区
} catch(error) {
console.error(`call System.getSystemCountries failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -168,7 +168,7 @@ static getSystemCountries(language: string): Array&lt;string&gt;
static isSuggested(language: string, region?: string): boolean
判断当前语言和区域是否匹配。
判断当前语言和地区是否匹配。
**系统能力**：SystemCapability.Global.I18n
......@@ -196,7 +196,7 @@ static isSuggested(language: string, region?: string): boolean
**示例：**
```js
try {
var res = i18n.System.isSuggested('zh', 'CN');
let res = I18n.System.isSuggested('zh', 'CN'); // res = true
} catch(error) {
console.error(`call System.isSuggested failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -206,7 +206,7 @@ static isSuggested(language: string, region?: string): boolean
static getSystemLanguage(): string
获取系统语言。
获取系统语言。语言的详细说明参见[实例化Locale对象](../../internationalization/intl-guidelines.md#开发步骤)。
**系统能力**：SystemCapability.Global.I18n
......@@ -227,7 +227,7 @@ static getSystemLanguage(): string
**示例：**
```js
try {
var systemLanguage = i18n.System.getSystemLanguage();
let systemLanguage = I18n.System.getSystemLanguage(); // systemLanguage为当前系统语言
} catch(error) {
console.error(`call System.getSystemLanguage failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -262,7 +262,7 @@ static setSystemLanguage(language: string): void
**示例：**
```js
try {
i18n.System.setSystemLanguage('zh');
I18n.System.setSystemLanguage('zh'); // 设置系统当前语言为 "zh"
} catch(error) {
console.error(`call System.setSystemLanguage failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -272,7 +272,7 @@ static setSystemLanguage(language: string): void
static getSystemRegion(): string
获取系统地区。
获取系统地区。地区的详细说明参见[实例化Locale对象](../../internationalization/intl-guidelines.md#开发步骤)。
**系统能力**：SystemCapability.Global.I18n
......@@ -293,7 +293,7 @@ static getSystemRegion(): string
**示例：**
```js
try {
var systemRegion = i18n.System.getSystemRegion();
let systemRegion = I18n.System.getSystemRegion(); // 获取系统当前地区设置
} catch(error) {
console.error(`call System.getSystemRegion failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -328,7 +328,7 @@ static setSystemRegion(region: string): void
**示例：**
```js
try {
i18n.System.setSystemRegion('CN');
I18n.System.setSystemRegion('CN'); // 设置系统当前地区为 "CN"
} catch(error) {
console.error(`call System.setSystemRegion failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -338,7 +338,7 @@ static setSystemRegion(region: string): void
static getSystemLocale(): string
获取系统区域。
获取系统区域。区域的详细说明参见[实例化Locale对象](../../internationalization/intl-guidelines.md#开发步骤)。
**系统能力**：SystemCapability.Global.I18n
......@@ -359,7 +359,7 @@ static getSystemLocale(): string
**示例：**
```js
try {
var systemLocale = i18n.System.getSystemLocale();
let systemLocale = I18n.System.getSystemLocale(); // 获取系统当前Locale
} catch(error) {
console.error(`call System.getSystemLocale failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -394,7 +394,7 @@ static setSystemLocale(locale: string): void
**示例：**
```js
try {
i18n.System.setSystemLocale('zh-CN');
I18n.System.setSystemLocale('zh-CN'); // 设置系统当前Locale为 "zh-CN"
} catch(error) {
console.error(`call System.setSystemLocale failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -425,7 +425,7 @@ static is24HourClock(): boolean
**示例：**
```js
try {
var is24HourClock = i18n.System.is24HourClock();
let is24HourClock = I18n.System.is24HourClock(); // 系统24小时开关是否开启
} catch(error) {
console.error(`call System.is24HourClock failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -461,7 +461,7 @@ static set24HourClock(option: boolean): void
```js
// 将系统时间设置为24小时制
try {
i18n.System.set24HourClock(true);
I18n.System.set24HourClock(true);
} catch(error) {
console.error(`call System.set24HourClock failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -497,10 +497,10 @@ static addPreferredLanguage(language: string, index?: number): void
**示例：**
```js
// 将语言zh-CN添加到系统偏好语言列表中
var language = 'zh-CN';
var index = 0;
let language = 'zh-CN';
let index = 0;
try {
i18n.System.addPreferredLanguage(language, index);
I18n.System.addPreferredLanguage(language, index); // 将zh-CN添加到系统偏好语言列表的第1位
} catch(error) {
console.error(`call System.addPreferredLanguage failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -535,9 +535,9 @@ static removePreferredLanguage(index: number): void
**示例：**
```js
// 删除系统偏好语言列表中的第一个偏好语言
var index = 0;
let index = 0;
try {
i18n.System.removePreferredLanguage(index);
I18n.System.removePreferredLanguage(index);
} catch(error) {
console.error(`call System.removePreferredLanguage failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -568,7 +568,7 @@ static getPreferredLanguageList(): Array&lt;string&gt;
**示例：**
```js
try {
var preferredLanguageList = i18n.System.getPreferredLanguageList();
let preferredLanguageList = I18n.System.getPreferredLanguageList(); // 获取系统当前偏好语言列表
} catch(error) {
console.error(`call System.getPreferredLanguageList failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -599,7 +599,7 @@ static getFirstPreferredLanguage(): string
**示例：**
```js
try {
var firstPreferredLanguage = i18n.System.getFirstPreferredLanguage();
let firstPreferredLanguage = I18n.System.getFirstPreferredLanguage(); // 获取系统当前偏好语言列表中的第一个偏好语言
} catch(error) {
console.error(`call System.getFirstPreferredLanguage failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -630,7 +630,7 @@ static getAppPreferredLanguage(): string
**示例：**
```js
try {
var appPreferredLanguage = i18n.System.getAppPreferredLanguage();
let appPreferredLanguage = I18n.System.getAppPreferredLanguage(); // 获取应用偏好语言
} catch(error) {
console.error(`call System.getAppPreferredLanguage failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -665,7 +665,7 @@ static setUsingLocalDigit(flag: boolean): void
**示例：**
```ts
try {
i18n.System.setUsingLocalDigit(true);
I18n.System.setUsingLocalDigit(true); // 打开本地化数字开关
} catch(error) {
console.error(`call System.setUsingLocalDigit failed, error code: ${error.code}, message: ${error.message}.`)
}
......@@ -696,14 +696,14 @@ static getUsingLocalDigit(): boolean
**示例：**
```ts
try {
var status = i18n.System.getUsingLocalDigit();
let status = I18n.System.getUsingLocalDigit(); // 判断本地化数字开关是否打开
} catch(error) {
console.error(`call System.getUsingLocalDigit failed, error code: ${error.code}, message: ${error.message}.`)
}
```
## i18n.isRTL<sup>7+</sup>
## I18n.isRTL<sup>7+</sup>
isRTL(locale: string): boolean
......@@ -725,12 +725,12 @@ isRTL(locale: string): boolean
**示例：**
```js
i18n.isRTL("zh-CN");// 中文不是RTL语言，返回false
i18n.isRTL("ar-EG");// 阿语是RTL语言，返回true
I18n.isRTL("zh-CN");// 中文不是RTL语言，返回false
I18n.isRTL("ar-EG");// 阿语是RTL语言，返回true
```
## i18n.getCalendar<sup>8+</sup>
## I18n.getCalendar<sup>8+</sup>
getCalendar(locale: string, type? : string): Calendar
......@@ -753,7 +753,7 @@ getCalendar(locale: string, type? : string): Calendar
**示例：**
```js
i18n.getCalendar("zh-Hans", "gregory");
I18n.getCalendar("zh-Hans", "chinese"); // 获取中国农历日历对象
```
......@@ -776,8 +776,8 @@ setTime(date: Date): void
**示例：**
```js
var calendar = i18n.getCalendar("en-US", "gregory");
var date = new Date(2021, 10, 7, 8, 0, 0, 0);
let calendar = I18n.getCalendar("en-US", "gregory");
let date = new Date(2021, 10, 7, 8, 0, 0, 0);
calendar.setTime(date);
```
......@@ -798,7 +798,7 @@ setTime(time: number): void
**示例：**
```js
var calendar = i18n.getCalendar("en-US", "gregory");
let calendar = I18n.getCalendar("en-US", "gregory");
calendar.setTime(10540800000);
```
......@@ -824,7 +824,7 @@ set(year: number, month: number, date:number, hour?: number, minute?: number, se
**示例：**
```js
var calendar = i18n.getCalendar("zh-Hans");
let calendar = I18n.getCalendar("zh-Hans");
calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.10.1 08:00:00
```
......@@ -845,7 +845,7 @@ setTimeZone(timezone: string): void
**示例：**
```js
var calendar = i18n.getCalendar("zh-Hans");
let calendar = I18n.getCalendar("zh-Hans");
calendar.setTimeZone("Asia/Shanghai");
```
......@@ -866,9 +866,9 @@ getTimeZone(): string
**示例：**
```js
var calendar = i18n.getCalendar("zh-Hans");
let calendar = I18n.getCalendar("zh-Hans");
calendar.setTimeZone("Asia/Shanghai");
calendar.getTimeZone(); // Asia/Shanghai"
let timezone = calendar.getTimeZone(); // timezone = "Asia/Shanghai"
```
......@@ -888,8 +888,8 @@ getFirstDayOfWeek(): number
**示例：**
```js
var calendar = i18n.getCalendar("en-US", "gregory");
calendar.getFirstDayOfWeek();
let calendar = I18n.getCalendar("en-US", "gregory");
let firstDayOfWeek = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 1
```
......@@ -909,8 +909,9 @@ setFirstDayOfWeek(value: number): void
**示例：**
```js
var calendar = i18n.getCalendar("zh-Hans");
calendar.setFirstDayOfWeek(0);
let calendar = I18n.getCalendar("zh-Hans");
calendar.setFirstDayOfWeek(3);
let firstDayOfWeek = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 3
```
......@@ -930,8 +931,8 @@ getMinimalDaysInFirstWeek(): number
**示例：**
```js
var calendar = i18n.getCalendar("zh-Hans");
calendar.getMinimalDaysInFirstWeek();
let calendar = I18n.getCalendar("zh-Hans");
let minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 1
```
......@@ -951,8 +952,9 @@ setMinimalDaysInFirstWeek(value: number): void
**示例：**
```js
var calendar = i18n.getCalendar("zh-Hans");
let calendar = I18n.getCalendar("zh-Hans");
calendar.setMinimalDaysInFirstWeek(3);
let minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 3
```
......@@ -978,9 +980,9 @@ get(field: string): number
**示例：**
```js
var calendar = i18n.getCalendar("zh-Hans");
let 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
let hourOfDay = calendar.get("hour_of_day"); // hourOfDay = 8
```
......@@ -1006,8 +1008,8 @@ getDisplayName(locale: string): string
**示例：**
```js
var calendar = i18n.getCalendar("en-US", "buddhist");
calendar.getDisplayName("zh"); // 佛历
let calendar = I18n.getCalendar("en-US", "buddhist");
let calendarName = calendar.getDisplayName("zh"); // calendarName = "佛历"
```
......@@ -1033,10 +1035,10 @@ isWeekend(date?: Date): boolean
**示例：**
```js
var calendar = i18n.getCalendar("zh-Hans");
let 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
var date = new Date(2011, 11, 6, 9, 0, 0);
let date = new Date(2011, 11, 6, 9, 0, 0);
calendar.isWeekend(date); // true
```
......@@ -1057,11 +1059,11 @@ constructor(country: string, options?: PhoneNumberFormatOptions)
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ---------------------------------------- | ---- | ---------------- |
| country | string | 是 | 表示电话号码所属国家或地区代码。 |
| options | [PhoneNumberFormatOptions](#phonenumberformatoptions9) | 否 | 电话号码格式化对象的相关选项。 |
| options | [PhoneNumberFormatOptions](#phonenumberformatoptions8) | 否 | 电话号码格式化对象的相关选项。 |
**示例：**
```js
var phoneNumberFormat= new i18n.PhoneNumberFormat("CN", {"type": "E164"});
let phoneNumberFormat= new I18n.PhoneNumberFormat("CN", {"type": "E164"});
```
......@@ -1087,8 +1089,8 @@ isValidNumber(number: string): boolean
**示例：**
```js
var phonenumberfmt = new i18n.PhoneNumberFormat("CN");
phonenumberfmt.isValidNumber("15812312312");
let phonenumberfmt = new I18n.PhoneNumberFormat("CN");
let isValidNumber = phonenumberfmt.isValidNumber("15812312312"); // isValidNumber = true
```
......@@ -1114,8 +1116,8 @@ format(number: string): string
**示例：**
```js
var phonenumberfmt = new i18n.PhoneNumberFormat("CN");
phonenumberfmt.format("15812312312");
let phonenumberfmt = new I18n.PhoneNumberFormat("CN");
let formattedPhoneNumber = phonenumberfmt.format("15812312312"); // formattedPhoneNumber = "158 1231 2312"
```
......@@ -1142,12 +1144,12 @@ getLocationName(number: string, locale: string): string
**示例：**
```js
var phonenumberfmt = new i18n.PhoneNumberFormat("CN");
phonenumberfmt.getLocationName("15812312345", "zh-CN");
let phonenumberfmt = new I18n.PhoneNumberFormat("CN");
let locationName = phonenumberfmt.getLocationName("15812312345", "zh-CN"); // locationName = "广东省湛江市"
```
## PhoneNumberFormatOptions<sup>9+</sup>
## PhoneNumberFormatOptions<sup>8+</sup>
表示电话号码格式化对象可设置的属性。
......@@ -1192,7 +1194,7 @@ getInstance(locale?:string): IndexUtil
**示例：**
```js
var indexUtil= i18n.getInstance("zh-CN");
let indexUtil= I18n.getInstance("zh-CN");
```
......@@ -1215,8 +1217,10 @@ getIndexList(): Array&lt;string&gt;
**示例：**
```js
var indexUtil = i18n.getInstance("zh-CN");
var indexList = indexUtil.getIndexList();
let indexUtil = I18n.getInstance("zh-CN");
// indexList = [ "...", "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N",
// "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "..." ]
let indexList = indexUtil.getIndexList();
```
......@@ -1236,7 +1240,7 @@ addLocale(locale: string): void
**示例：**
```js
var indexUtil = i18n.getInstance("zh-CN");
let indexUtil = I18n.getInstance("zh-CN");
indexUtil.addLocale("en-US");
```
......@@ -1263,12 +1267,12 @@ getIndex(text: string): string
**示例：**
```js
var indexUtil= i18n.getInstance("zh-CN");
indexUtil.getIndex("hi"); // 返回hi
let indexUtil= I18n.getInstance("zh-CN");
let index = indexUtil.getIndex("hi"); // index = "H"
```
## i18n.getLineInstance<sup>8+</sup>
## I18n.getLineInstance<sup>8+</sup>
getLineInstance(locale: string): BreakIterator
......@@ -1290,7 +1294,7 @@ getLineInstance(locale: string): BreakIterator
**示例：**
```js
var iterator = i18n.getLineInstance("en");
let iterator = I18n.getLineInstance("en");
```
......@@ -1313,8 +1317,8 @@ setLineBreakText(text: string): void
**示例：**
```js
var iterator = i18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
let iterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit."); // 设置短句文本
```
......@@ -1334,9 +1338,9 @@ getLineBreakText(): string
**示例：**
```js
var iterator = i18n.getLineInstance("en");
let iterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.getLineBreakText(); // Apple is my favorite fruit.
let breakText = iterator.getLineBreakText(); // breakText = "Apple is my favorite fruit."
```
......@@ -1356,9 +1360,9 @@ current(): number
**示例：**
```js
var iterator = i18n.getLineInstance("en");
let iterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.current(); // 0
let currentPos = iterator.current(); // currentPos = 0
```
......@@ -1378,9 +1382,9 @@ first(): number
**示例：**
```js
var iterator = i18n.getLineInstance("en");
let iterator = i18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.first(); // 0
let firstPos = iterator.first(); // firstPos = 0
```
......@@ -1400,9 +1404,9 @@ last(): number
**示例：**
```js
var iterator = i18n.getLineInstance("en");
let iterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.last(); // 27
let lastPos = iterator.last(); // lastPos = 27
```
......@@ -1428,11 +1432,11 @@ next(index?: number): number
**示例：**
```js
var iterator = i18n.getLineInstance("en");
let iterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.first(); // 0
iterator.next(); // 6
iterator.next(10); // -1
let pos = iterator.first(); // pos = 0
pos = iterator.next(); // pos = 6
pos = iterator.next(10); // pos = -1
```
......@@ -1452,11 +1456,11 @@ previous(): number
**示例：**
```js
var iterator = i18n.getLineInstance("en");
let iterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.first(); // 0
iterator.next(3); // 12
iterator.previous(); // 9
let pos = iterator.first(); // pos = 0
pos = iterator.next(3); // pos = 12
pos = iterator.previous(); // pos = 9
```
......@@ -1482,11 +1486,11 @@ following(offset: number): number
**示例：**
```js
var iterator = i18n.getLineInstance("en");
let iterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.following(0); // 6
iterator.following(100); // -1
iterator.current(); // 27
let pos = iterator.following(0); // pos = 6
pos = iterator.following(100); // pos = -1
pos = iterator.current(); // pos = 27
```
......@@ -1512,14 +1516,14 @@ isBoundary(offset: number): boolean
**示例：**
```js
var iterator = i18n.getLineInstance("en");
let iterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.isBoundary(0); // true;
iterator.isBoundary(5); // false;
let isBoundary = iterator.isBoundary(0); // isBoundary = true;
isBoundary = iterator.isBoundary(5); // isBoundary = false;
```
## i18n.getTimeZone<sup>7+</sup>
## I18n.getTimeZone<sup>7+</sup>
getTimeZone(zoneID?: string): TimeZone
......@@ -1541,7 +1545,7 @@ getTimeZone(zoneID?: string): TimeZone
**示例：**
```js
var timezone = i18n.getTimeZone();
let timezone = I18n.getTimeZone();
```
......@@ -1564,8 +1568,8 @@ getID(): string
**示例：**
```js
var timezone = i18n.getTimeZone();
timezone.getID();
let timezone = I18n.getTimeZone();
let timezoneID = timezone.getID(); // timezoneID = "Asia/Shanghai"
```
......@@ -1573,7 +1577,7 @@ getID(): string
getDisplayName(locale?: string, isDST?: boolean): string
获取时区对象在指定区域的表示。
获取时区的本地化表示。
**系统能力**：SystemCapability.Global.I18n
......@@ -1592,8 +1596,8 @@ getDisplayName(locale?: string, isDST?: boolean): string
**示例：**
```js
var timezone = i18n.getTimeZone();
timezone.getDisplayName("zh-CN", false);
let timezone = I18n.getTimeZone();
let timezoneName = timezone.getDisplayName("zh-CN", false); // timezoneName = "中国标准时间"
```
......@@ -1613,8 +1617,8 @@ getRawOffset(): number
**示例：**
```js
var timezone = i18n.getTimeZone();
timezone.getRawOffset();
let timezone = I18n.getTimeZone();
let offset = timezone.getRawOffset(); // offset = 28800000
```
......@@ -1634,8 +1638,8 @@ getOffset(date?: number): number
**示例：**
```js
var timezone = i18n.getTimeZone();
timezone.getOffset(1234567890);
let timezone = I18n.getTimeZone();
let offset = timezone.getOffset(1234567890); // offset = 28800000
```
......@@ -1655,7 +1659,8 @@ static getAvailableIDs(): Array&lt;string&gt;
**示例：**
```ts
var ids = i18n.TimeZone.getAvailableIDs();
// ids = ["America/Adak", "America/Anchorage", "America/Bogota", "America/Denver", "America/Los_Angeles", "America/Montevideo", "America/Santiago", "America/Sao_Paulo", "Asia/Ashgabat", "Asia/Hovd", "Asia/Jerusalem", "Asia/Magadan", "Asia/Omsk", "Asia/Shanghai", "Asia/Tokyo", "Asia/Yerevan", "Atlantic/Cape_Verde", "Australia/Lord_Howe", "Europe/Dublin", "Europe/London", "Europe/Moscow", "Pacific/Auckland", "Pacific/Easter", "Pacific/Pago-Pago"], 当前共支持24个时区
let ids = I18n.TimeZone.getAvailableIDs();
```
......@@ -1675,7 +1680,8 @@ static getAvailableZoneCityIDs(): Array&lt;string&gt;
**示例：**
```ts
var cityIDs = i18n.TimeZone.getAvailableZoneCityIDs();
// cityIDs = ["Auckland", "Magadan", "Lord Howe Island", "Tokyo", "Shanghai", "Hovd", "Omsk", "Ashgabat", "Yerevan", "Moscow", "Tel Aviv", "Dublin", "London", "Praia", "Montevideo", "Brasília", "Santiago", "Bogotá", "Easter Island", "Salt Lake City", "Los Angeles", "Anchorage", "Adak", "Pago Pago"]，当前共支持24个时区城市
let cityIDs = I18n.TimeZone.getAvailableZoneCityIDs();
```
......@@ -1702,7 +1708,7 @@ static getCityDisplayName(cityID: string, locale: string): string
**示例：**
```ts
var displayName = i18n.TimeZone.getCityDisplayName("Shanghai", "zh-CN");
let displayName = I18n.TimeZone.getCityDisplayName("Shanghai", "zh-CN"); // displayName = "上海(中国)"
```
......@@ -1728,7 +1734,7 @@ static getTimezoneFromCity(cityID: string): TimeZone
**示例：**
```ts
var timezone = i18n.TimeZone.getTimezoneFromCity("Shanghai");
let timezone = I18n.TimeZone.getTimezoneFromCity("Shanghai");
```
......@@ -1751,7 +1757,9 @@ static getAvailableIDs(): string[]
**示例：**
```ts
i18n.Transliterator.getAvailableIDs();
// ids = ["ASCII-Latin", "Accents-Any", "Amharic-Latin/BGN", ...]，共支持671个id
// 每一个id由使用中划线分割的两部分组成，格式为 source-destination
let ids = I18n.Transliterator.getAvailableIDs();
```
......@@ -1777,7 +1785,7 @@ static getInstance(id: string): Transliterator
**示例：**
```ts
var transliterator = i18n.Transliterator.getInstance("Any-Latn");
let transliterator = I18n.Transliterator.getInstance("Any-Latn");
```
......@@ -1803,8 +1811,8 @@ transform(text: string): string
**示例：**
```ts
var transliterator = i18n.Transliterator.getInstance("Any-Latn");
transliterator.transform("中国");
let transliterator = I18n.Transliterator.getInstance("Any-Latn");
let res = transliterator.transform("中国"); // res = "zhōng guó"
```
......@@ -1833,7 +1841,7 @@ static isDigit(char: string): boolean
**示例：**
```js
var isdigit = i18n.Unicode.isDigit("1"); // 返回true
let isdigit = I18n.Unicode.isDigit("1"); // isdigit = true
```
......@@ -1859,7 +1867,7 @@ static isSpaceChar(char: string): boolean
**示例：**
```js
var isspacechar = i18n.Unicode.isSpaceChar("a"); // 返回false
let isspacechar = I18n.Unicode.isSpaceChar("a"); // isspacechar = false
```
......@@ -1885,7 +1893,7 @@ static isWhitespace(char: string): boolean
**示例：**
```js
var iswhitespace = i18n.Unicode.isWhitespace("a"); // 返回false
let iswhitespace = I18n.Unicode.isWhitespace("a"); // iswhitespace = false
```
......@@ -1911,7 +1919,7 @@ static isRTL(char: string): boolean
**示例：**
```js
var isrtl = i18n.Unicode.isRTL("a"); // 返回false
let isrtl = I18n.Unicode.isRTL("a"); // isrtl = false
```
......@@ -1937,7 +1945,7 @@ static isIdeograph(char: string): boolean
**示例：**
```js
var isideograph = i18n.Unicode.isIdeograph("a"); // 返回false
let isideograph = I18n.Unicode.isIdeograph("a"); // isideograph = false
```
......@@ -1963,7 +1971,7 @@ static isLetter(char: string): boolean
**示例：**
```js
var isletter = i18n.Unicode.isLetter("a"); // 返回true
let isletter = I18n.Unicode.isLetter("a"); // isletter = true
```
......@@ -1989,7 +1997,7 @@ static isLowerCase(char: string): boolean
**示例：**
```js
var islowercase = i18n.Unicode.isLowerCase("a"); // 返回true
let islowercase = I18n.Unicode.isLowerCase("a"); // islowercase = true
```
......@@ -2015,7 +2023,7 @@ static isUpperCase(char: string): boolean
**示例：**
```js
var isuppercase = i18n.Unicode.isUpperCase("a"); // 返回false
let isuppercase = I18n.Unicode.isUpperCase("a"); // isuppercase = false
```
......@@ -2041,7 +2049,7 @@ static getType(char: string): string
**示例：**
```js
var type = i18n.Unicode.getType("a");
let type = I18n.Unicode.getType("a"); // type = "U_LOWERCASE_LETTER"
```
......@@ -2074,7 +2082,7 @@ static unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale:
**示例：**
```js
i18n.I18NUtil.unitConvert({unit: "cup", measureSystem: "US"}, {unit: "liter", measureSystem: "SI"}, 1000, "en-US", "long");
let res = I18n.I18NUtil.unitConvert({unit: "cup", measureSystem: "US"}, {unit: "liter", measureSystem: "SI"}, 1000, "en-US", "long"); // res = 236.588 liters
```
......@@ -2100,11 +2108,11 @@ static getDateOrder(locale: string): string
**示例：**
```js
i18n.I18NUtil.getDateOrder("zh-CN");
let order = I18n.I18NUtil.getDateOrder("zh-CN"); // order = "y-L-d"
```
## i18n.getDisplayCountry<sup>(deprecated)</sup>
## I18n.getDisplayCountry<sup>(deprecated)</sup>
getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string
......@@ -2130,12 +2138,12 @@ getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): stri
**示例：**
```js
i18n.getDisplayCountry("zh-CN", "en-GB", true);
i18n.getDisplayCountry("zh-CN", "en-GB");
let countryName = I18n.getDisplayCountry("zh-CN", "en-GB", true); // countryName = true
countryName = I18n.getDisplayCountry("zh-CN", "en-GB"); // countryName = true
```
## i18n.getDisplayLanguage<sup>(deprecated)</sup>
## I18n.getDisplayLanguage<sup>(deprecated)</sup>
getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string
......@@ -2161,12 +2169,12 @@ getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): st
**示例：**
```js
i18n.getDisplayLanguage("zh", "en-GB", true);
i18n.getDisplayLanguage("zh", "en-GB");
let languageName = I18n.getDisplayLanguage("zh", "en-GB", true); // languageName = "Chinese"
languageName = I18n.getDisplayLanguage("zh", "en-GB"); // languageName = "Chinese"
```
## i18n.getSystemLanguage<sup>(deprecated)</sup>
## I18n.getSystemLanguage<sup>(deprecated)</sup>
getSystemLanguage(): string
......@@ -2184,11 +2192,11 @@ getSystemLanguage(): string
**示例：**
```js
i18n.getSystemLanguage();
let systemLanguage = I18n.getSystemLanguage(); // 返回当前系统语言
```
## i18n.getSystemRegion<sup>(deprecated)</sup>
## I18n.getSystemRegion<sup>(deprecated)</sup>
getSystemRegion(): string
......@@ -2206,11 +2214,11 @@ getSystemRegion(): string
**示例：**
```js
i18n.getSystemRegion();
let region = I18n.getSystemRegion(); // 返回当前系统地区
```
## i18n.getSystemLocale<sup>(deprecated)</sup>
## I18n.getSystemLocale<sup>(deprecated)</sup>
getSystemLocale(): string
......@@ -2228,11 +2236,11 @@ getSystemLocale(): string
**示例：**
```js
i18n.getSystemLocale();
let locale = I18n.getSystemLocale(); // 返回系统Locale
```
## i18n.is24HourClock<sup>(deprecated)</sup>
## I18n.is24HourClock<sup>(deprecated)</sup>
is24HourClock(): boolean
......@@ -2250,11 +2258,11 @@ is24HourClock(): boolean
**示例：**
```js
var is24HourClock = i18n.is24HourClock();
let is24HourClock = I18n.is24HourClock();
```
## i18n.set24HourClock<sup>(deprecated)</sup>
## I18n.set24HourClock<sup>(deprecated)</sup>
set24HourClock(option: boolean): boolean
......@@ -2281,11 +2289,11 @@ set24HourClock(option: boolean): boolean
**示例：**
```js
// 将系统时间设置为24小时制
var success = i18n.set24HourClock(true);
let success = I18n.set24HourClock(true);
```
## i18n.addPreferredLanguage<sup>(deprecated)</sup>
## I18n.addPreferredLanguage<sup>(deprecated)</sup>
addPreferredLanguage(language: string, index?: number): boolean
......@@ -2313,13 +2321,13 @@ addPreferredLanguage(language: string, index?: number): boolean
**示例：**
```js
// 将语言zh-CN添加到系统偏好语言列表中
var language = 'zh-CN';
var index = 0;
var success = i18n.addPreferredLanguage(language, index);
let language = 'zh-CN';
let index = 0;
let success = I18n.addPreferredLanguage(language, index);
```
## i18n.removePreferredLanguage<sup>(deprecated)</sup>
## I18n.removePreferredLanguage<sup>(deprecated)</sup>
removePreferredLanguage(index: number): boolean
......@@ -2346,12 +2354,12 @@ removePreferredLanguage(index: number): boolean
**示例：**
```js
// 删除系统偏好语言列表中的第一个偏好语言
var index = 0;
var success = i18n.removePreferredLanguage(index);
let index = 0;
let success = I18n.removePreferredLanguage(index);
```
## i18n.getPreferredLanguageList<sup>(deprecated)</sup>
## I18n.getPreferredLanguageList<sup>(deprecated)</sup>
getPreferredLanguageList(): Array&lt;string&gt;
......@@ -2369,11 +2377,11 @@ getPreferredLanguageList(): Array&lt;string&gt;
**示例：**
```js
var preferredLanguageList = i18n.getPreferredLanguageList();
let preferredLanguageList = I18n.getPreferredLanguageList(); // 获取系统偏好语言列表
```
## i18n.getFirstPreferredLanguage<sup>(deprecated)</sup>
## I18n.getFirstPreferredLanguage<sup>(deprecated)</sup>
getFirstPreferredLanguage(): string
......@@ -2391,7 +2399,7 @@ getFirstPreferredLanguage(): string
**示例：**
```js
var firstPreferredLanguage = i18n.getFirstPreferredLanguage();
let firstPreferredLanguage = I18n.getFirstPreferredLanguage();
```
......
zh-cn/application-dev/reference/apis/js-apis-intl.md
浏览文件 @ 31f7aa0b
......@@ -14,7 +14,7 @@
```js
import Intl from '@ohos.intl';
```
未正确导入包可能产生不明确的接口行为。
## Locale
......@@ -47,7 +47,10 @@ constructor()
**示例：**
```js
var locale = new Intl.Locale();
// 默认构造函数使用系统当前locale创建Locale对象
let locale = new Intl.Locale()
// 返回系统当前localel
let localeID = locale.toString()
```
......@@ -63,12 +66,14 @@ constructor(locale: string, options?: LocaleOptions)
| 参数名 | 类型 | 必填 | 说明 |
| -------------------- | -------------------------------- | ---- | ---------------------------- |
| locale | string | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 |
| options<sup>9+</sup> | [LocaleOptions](#localeoptions9) | 否 | 用于创建区域对象的选项。 |
| locale | string | 是 | 包含区域信息的字符串，包括语言以、脚本、国家或地区。语言、脚本、国家或地区的国际标准及组合方式请见[Intl开发指导](../../internationalization/intl-guidelines.md#设置区域信息) |
| options<sup>9+</sup> | [LocaleOptions](#localeoptions6) | 否 | 用于创建区域对象的选项。 |
**示例：**
```js
var locale = new Intl.Locale("zh-CN");
// 创建 "zh-CN" Locale对象
let locale = new Intl.Locale("zh-CN")
let 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对象
let locale = new Intl.Locale("en-GB");
let localeID = locale.toString(); // localeID = "en-GB"
```
......@@ -109,8 +115,17 @@ maximize(): Locale
**示例：**
```js
var locale = new Intl.Locale("zh-CN");
locale.maximize();
// 创建 "zh" Locale对象
let locale = new Intl.Locale("zh");
// 补齐Locale对象的脚本和地区
let maximizedLocale = locale.maximize();
let localeID = maximizedLocale.toString(); // localeID = "zh-Hans-CN"
// 创建 "en-US" Locale对象
locale = new Intl.Locale("en-US");
// 补齐Locale对象的脚本
maximizedLocale = locale.maximize();
localeID = maximizedLocale.toString(); // localeID = "en-Latn-US"
```
......@@ -130,12 +145,21 @@ minimize(): Locale
**示例：**
```js
var locale = new Intl.Locale("zh-CN");
locale.minimize();
// 创建 "zh-Hans-CN" Locale对象
let locale = new Intl.Locale("zh-Hans-CN");
// 去除Locale对象的脚本和地区
let minimizedLocale = locale.minimize();
let localeID = minimizedLocale.toString(); // localeID = "zh"
// 创建 "en-US" Locale对象
locale = new Intl.Locale("en-US");
// 去除Locale对象的地区
minimizedLocale = locale.minimize();
localeID = minimizedLocale.toString(); // localeID = "en"
```
## LocaleOptions<sup>9+</sup>
## LocaleOptions<sup>6+</sup>
表示区域初始化选项。
......@@ -164,7 +188,8 @@ constructor()
**示例：**
```js
var datefmt= new Intl.DateTimeFormat();
// 使用系统当前locale创建DateTimeFormat对象
let datefmt= new Intl.DateTimeFormat();
```
......@@ -181,17 +206,19 @@ constructor(locale: string | Array&lt;string&gt;, options?: DateTimeOptions)
| 参数名 | 类型 | 必填 | 说明 |
| -------------------- | ------------------------------------ | ---- | ---------------------------- |
| locale | string \| Array&lt;string&gt; | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 |
| options<sup>9+</sup> | [DateTimeOptions](#datetimeoptions9) | 否 | 用于创建时间日期格式化的选项。 |
| options<sup>9+</sup> | [DateTimeOptions](#datetimeoptions6) | 否 | 用于创建时间日期格式化的选项。 |
**示例：**
```js
var datefmt= new Intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' });
// 使用 "zh-CN" locale创建DateTimeFormat对象，日期风格为full，时间风格为medium
let datefmt= new Intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' });
```
**示例：**
```js
var datefmt= new Intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' });
// 使用 ["ban", "zh"] locale列表创建DateTimeFormat对象，因为ban为非法LocaleID，因此使用zh Locale创建DateTimeFormat对象
let datefmt= new Intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' });
```
......@@ -217,9 +244,14 @@ format(date: Date): string
**示例：**
```js
var date = new Date(2021, 11, 17, 3, 24, 0);
var datefmt = new Intl.DateTimeFormat("en-GB");
datefmt.format(date);
let date = new Date(2021, 11, 17, 3, 24, 0);
// 使用 en-GB locale创建DateTimeFormat对象
let datefmt = new Intl.DateTimeFormat("en-GB");
let 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"
```
......@@ -246,10 +278,11 @@ 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);
var datefmt = new Intl.DateTimeFormat("en-GB");
datefmt.formatRange(startDate, endDate);
let startDate = new Date(2021, 11, 17, 3, 24, 0);
let endDate = new Date(2021, 11, 18, 3, 24, 0);
// 使用 en-GB locale创建DateTimeFormat对象
let datefmt = new Intl.DateTimeFormat("en-GB");
let formattedDateRange = datefmt.formatRange(startDate, endDate); // formattedDateRange = "17/12/2021-18/12/2021"
```
......@@ -265,16 +298,19 @@ resolvedOptions(): DateTimeOptions
| 类型 | 说明 |
| ------------------------------------ | ----------------------------- |
| [DateTimeOptions](#datetimeoptions9) | DateTimeFormat&nbsp;对象的格式化选项。 |
| [DateTimeOptions](#datetimeoptions6) | DateTimeFormat&nbsp;对象的格式化选项。 |
**示例：**
```js
var datefmt = new Intl.DateTimeFormat("en-GB");
datefmt.resolvedOptions();
let datefmt = new Intl.DateTimeFormat("en-GB", { dateStyle: 'full', timeStyle: 'medium' });
// 返回DateTimeFormat对象的配置项
let options = datefmt.resolvedOptions();
let dateStyle = options.dateStyle; // dateStyle = "full"
let timeStyle = options.timeStyle; // timeStyle = "medium"
```
## DateTimeOptions<sup>9+</sup>
## DateTimeOptions<sup>6+</sup>
表示时间日期格式化选项。
......@@ -316,7 +352,8 @@ constructor()
**示例：**
```js
var numfmt = new Intl.NumberFormat();
// 使用系统当前locale创建NumberFormat对象
let numfmt = new Intl.NumberFormat();
```
......@@ -333,11 +370,12 @@ constructor(locale: string | Array&lt;string&gt;, options?: NumberOptions)
| 参数名 | 类型 | 必填 | 说明 |
| -------------------- | -------------------------------- | ---- | ---------------------------- |
| locale | string \| Array&lt;string&gt; | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 |
| options<sup>9+</sup> | [NumberOptions](#numberoptions9) | 否 | 用于创建数字格式化的选项。 |
| options<sup>9+</sup> | [NumberOptions](#numberoptions6) | 否 | 用于创建数字格式化的选项。 |
**示例：**
```js
var numfmt = new Intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"});
// 使用 en-GB locale创建NumberFormat对象，style设置为decimal，notation设置为scientific
let numfmt = new Intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"});
```
......@@ -364,8 +402,9 @@ format(number: number): string;
**示例：**
```js
var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
numfmt.format(1223);
// 使用 ["en-GB", "zh"] locale列表创建NumberFormat对象，因为en-GB为合法LocaleID，因此使用en-GB创建NumberFormat对象
let numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
let formattedNumber = numfmt.format(1223); // formattedNumber = 1.223E3
```
......@@ -381,17 +420,20 @@ resolvedOptions(): NumberOptions
| 类型 | 说明 |
| -------------------------------- | --------------------------- |
| [NumberOptions](#numberoptions9) | NumberFormat&nbsp;对象的格式化选项。 |
| [NumberOptions](#numberoptions6) | NumberFormat&nbsp;对象的格式化选项。 |
**示例：**
```js
var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
numfmt.resolvedOptions();
let numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
// 获取NumberFormat对象配置项
let options = numfmt.resolvedOptions();
let style = options.style; // style = decimal
let notation = options.notation // notation = scientific
```
## NumberOptions<sup>9+</sup>
## NumberOptions<sup>6+</sup>
表示设备支持的能力。
......@@ -433,7 +475,8 @@ constructor()
**示例：**
```js
var collator = new Intl.Collator();
// 使用系统locale创建Collator对象
let collator = new Intl.Collator();
```
......@@ -450,11 +493,12 @@ constructor(locale: string | Array&lt;string&gt;, options?: CollatorOptions)
| 参数名 | 类型 | 必填 | 说明 |
| -------------------- | ------------------------------------ | ---- | ---------------------------- |
| locale | string \| Array&lt;string&gt; | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 |
| options<sup>9+</sup> | [CollatorOptions](#collatoroptions9) | 否 | 用于创建排序对象的选项。 |
| options<sup>9+</sup> | [CollatorOptions](#collatoroptions8) | 否 | 用于创建排序对象的选项。 |
**示例：**
```js
var collator = new Intl.Collator("zh-CN", {localeMatcher: "lookup", usage: "sort"});
// 使用 zh-CN locale创建Collator对象，localeMatcher设置为lookup，usage设置为sort
let 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对象
let collator = new Intl.Collator("en-GB");
// 比较 "first" 和 "second" 的先后顺序
let compareResult = collator.compare("first", "second"); // compareResult = -1
```
......@@ -498,16 +544,19 @@ resolvedOptions(): CollatorOptions
| 类型 | 说明 |
| ------------------------------------ | ----------------- |
| [CollatorOptions](#collatoroptions9) | 返回的Collator对象的属性。 |
| [CollatorOptions](#collatoroptions8) | 返回的Collator对象的属性。 |
**示例：**
```js
var collator = new Intl.Collator("zh-Hans");
var options = collator.resolvedOptions();
let collator = new Intl.Collator("zh-Hans", { usage: 'sort', ignorePunctuation: true });
// 获取Collator对象的配置项
let options = collator.resolvedOptions();
let usage = options.usage; // usage = "sort"
let ignorePunctuation = options.ignorePunctuation // ignorePunctuation = true
```
## CollatorOptions<sup>9+</sup>
## CollatorOptions<sup>8+</sup>
表示Collator可设置的属性。
......@@ -517,7 +566,7 @@ resolvedOptions(): CollatorOptions
| ----------------- | ------- | ---- | ---- | ---------------------------------------- |
| localeMatcher | string | 是 | 是 | locale匹配算法，取值范围："best&nbsp;fit",&nbsp;"lookup"。 |
| usage | string | 是 | 是 | 比较的用途，取值范围："sort",&nbsp;"search"。 |
| sensitivity | string | 是 | 是 | 表示字符串中的哪些差异会导致非零结果值，取值范围："base",&nbsp;"accent",&nbsp;"case",&nbsp;"variant"。 |
| sensitivity | string | 是 | 是 | 表示字符串中的哪些差异会导致非零结果值，取值范围："base",&nbsp;"accent",&nbsp;"case",&nbsp;"letiant"。 |
| ignorePunctuation | boolean | 是 | 是 | 表示是否忽略标点符号，取值范围：true,&nbsp;false。 |
| collation | string | 是 | 是 | 排序规则，取值范围："big5han",&nbsp;"compat",&nbsp;"dict",&nbsp;"direct",&nbsp;"ducet",&nbsp;"eor",&nbsp;"gb2312",&nbsp;"phonebk",&nbsp;"phonetic",&nbsp;"pinyin",&nbsp;"reformed",&nbsp;"searchjl",&nbsp;"stroke",&nbsp;"trad",&nbsp;"unihan",&nbsp;"zhuyin"。 |
| numeric | boolean | 是 | 是 | 是否使用数字排序，取值范围：true,&nbsp;false。 |
......@@ -531,13 +580,14 @@ resolvedOptions(): CollatorOptions
constructor()
创建PluralRules对象。
创建单复数对象来计算数字的单复数类别。
**系统能力**：SystemCapability.Global.I18n
**示例：**
```js
var pluralRules = new Intl.PluralRules();
// 使用系统locale创建PluralRules对象
let pluralRules = new Intl.PluralRules();
```
......@@ -545,7 +595,7 @@ constructor()
constructor(locale: string | Array&lt;string&gt;, options?: PluralRulesOptions)
创建PluralRules对象。
创建单复数对象来计算数字的单复数类别。
**系统能力**：SystemCapability.Global.I18n
......@@ -554,11 +604,12 @@ constructor(locale: string | Array&lt;string&gt;, options?: PluralRulesOptions)
| 参数名 | 类型 | 必填 | 说明 |
| -------------------- | ---------------------------------------- | ---- | ---------------------------- |
| locale | string \| Array&lt;string&gt; | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 |
| options<sup>9+</sup> | [PluralRulesOptions](#pluralrulesoptions9) | 否 | 用于创建单复数对象的选项。 |
| options<sup>9+</sup> | [PluralRulesOptions](#pluralrulesoptions8) | 否 | 用于创建单复数对象的选项。 |
**示例：**
```js
var pluralRules= new Intl.PluralRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"});
// 使用 zh-CN locale创建PluralRules对象，localeMatcher设置为lookup，type设置为cardinal
let pluralRules= new Intl.PluralRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"});
```
......@@ -584,12 +635,19 @@ select(n: number): string
**示例：**
```js
var pluralRules = new Intl.PluralRules("zh-Hans");
pluralRules.select(1);
// 使用 zh-Hans locale创建PluralRules对象
let zhPluralRules = new Intl.PluralRules("zh-Hans");
// 计算 zh-Hans locale中数字1对应的单复数类别
let plural = zhPluralRules.select(1); // plural = other
// 使用 en-US locale创建PluralRules对象
let enPluralRules = new Intl.PluralRules("en-US");
// 计算 en-US locale中数字1对应的单复数类别
plural = enPluralRules.select(1); // plural = one
```
## PluralRulesOptions<sup>9+</sup>
## PluralRulesOptions<sup>8+</sup>
表示PluralRules对象可设置的属性。
......@@ -619,7 +677,8 @@ constructor()
**示例：**
```js
var relativetimefmt = new Intl.RelativeTimeFormat();
// 使用系统locale创建RelativeTimeFormat对象
let relativetimefmt = new Intl.RelativeTimeFormat();
```
......@@ -636,11 +695,12 @@ constructor(locale: string | Array&lt;string&gt;, options?: RelativeTimeFormatIn
| 参数名 | 类型 | 必填 | 说明 |
| -------------------- | ---------------------------------------- | ---- | ---------------------------- |
| locale | string \| Array&lt;string&gt; | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 |
| options<sup>9+</sup> | [RelativeTimeFormatInputOptions](#relativetimeformatinputoptions9) | 否 | 用于创建相对时间格式化对象的选项。 |
| options<sup>9+</sup> | [RelativeTimeFormatInputOptions](#relativetimeformatinputoptions8) | 否 | 用于创建相对时间格式化对象的选项。 |
**示例：**
```js
var relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"});
// 使用 zh-CN locale创建RelativeTimeFormat对象，localeMatcher设置为lookup，numeric设置为always，style设置为long
let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"});
```
......@@ -667,8 +727,10 @@ format(value: number, unit: string): string
**示例：**
```js
var relativetimefmt = new Intl.RelativeTimeFormat("zh-CN");
relativetimefmt.format(3, "quarter")
// 使用 zh-CN locale创建RelativeTimeFormat对象
let relativetimefmt = new Intl.RelativeTimeFormat("zh-CN");
// 计算 zh-CN locale中数字3，单位quarter的本地化表示
let formatResult = relativetimefmt.format(3, "quarter"); // formatResult = "3个季度后"
```
......@@ -695,8 +757,9 @@ formatToParts(value: number, unit: string): Array&lt;object&gt;
**示例：**
```js
var relativetimefmt = new Intl.RelativeTimeFormat("en", {"numeric": "auto"});
var parts = relativetimefmt.format(10, "seconds");
// 使用 en locale创建RelativeTimeFormat对象，numeric设置为auto
let relativetimefmt = new Intl.RelativeTimeFormat("en", {"numeric": "auto"});
let parts = relativetimefmt.formatToParts(10, "seconds"); // parts = [ {type: "literal", value: "in"}, {type: "integer", value: 10, unit: "second"}, {type: "literal", value: "seconds"} ]
```
......@@ -716,12 +779,15 @@ resolvedOptions(): RelativeTimeFormatResolvedOptions
**示例：**
```js
var relativetimefmt= new Intl.RelativeTimeFormat("en-GB");
relativetimefmt.resolvedOptions();
// 使用 en-GB locale创建RelativeTimeFormat对象
let relativetimefmt= new Intl.RelativeTimeFormat("en-GB", { style: "short" });
// 获取RelativeTimeFormat对象配置项
let options = relativetimefmt.resolvedOptions();
let style = options.style; // style = "short"
```
## RelativeTimeFormatInputOptions<sup>9+</sup>
## RelativeTimeFormatInputOptions<sup>8+</sup>
表示RelativeTimeFormat对象可设置的属性。
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或