提交 e9f90a62 编写于 作者: S shawn_he

update doc

Signed-off-by: Nshawn_he <shawn.he@huawei.com>
上级 af50b0f1
...@@ -455,3 +455,4 @@ Represents a screen hopping message notification. ...@@ -455,3 +455,4 @@ Represents a screen hopping message notification.
| COOPERATE_ACTIVATE_FAIL | 4 | Starting screen hopping fails.| | COOPERATE_ACTIVATE_FAIL | 4 | Starting screen hopping fails.|
| COOPERATE_DEACTIVATE_SUCCESS | 5 | Stopping screen hopping succeeds.| | COOPERATE_DEACTIVATE_SUCCESS | 5 | Stopping screen hopping succeeds.|
| COOPERATE_DEACTIVATE_FAIL | 6 | Stopping screen hopping fails.| | COOPERATE_DEACTIVATE_FAIL | 6 | Stopping screen hopping fails.|
| COOPERATE_SESSION_DISCONNECTED | 7 | The screen hopping session is disconnected.|
# @ohos.hilog (HiLog) # @ohos.hilog (HiLog)
The **hilog** module allows your applications or services to output logs based on the specified type, level, and format string. Such logs help you learn the running status of applications and better debug programs. The HiLog subsystem allows your applications or services to output logs based on the specified type, level, and format string. Such logs help you learn the running status of applications and better debug programs.
> **NOTE**<br> > **NOTE**
>
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Modules to Import
...@@ -23,7 +24,7 @@ Checks whether logs are printable based on the specified service domain, log tag ...@@ -23,7 +24,7 @@ Checks whether logs are printable based on the specified service domain, log tag
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | --------------------- | ---- | ------------------------------------------------------------ | | ------ | --------------------- | ---- | ------------------------------------------------------------ |
| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value within your application as required.| | domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required.|
| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.|
| level | [LogLevel](#loglevel) | Yes | Log level. | | level | [LogLevel](#loglevel) | Yes | Log level. |
...@@ -41,11 +42,11 @@ hilog.isLoggable(0x0001, "testTag", hilog.LogLevel.INFO); ...@@ -41,11 +42,11 @@ hilog.isLoggable(0x0001, "testTag", hilog.LogLevel.INFO);
## LogLevel ## LogLevel
Enumerates the log levels. Log level.
**System capability**: SystemCapability.HiviewDFX.HiLog **System capability**: SystemCapability.HiviewDFX.HiLog
| Name | Value| Description | | Name | Value | Description |
| ----- | ------ | ------------------------------------------------------------ | | ----- | ------ | ------------------------------------------------------------ |
| DEBUG | 3 | Log level used to record more detailed process information than INFO logs to help developers analyze service processes and locate faults.| | DEBUG | 3 | Log level used to record more detailed process information than INFO logs to help developers analyze service processes and locate faults.|
| INFO | 4 | Log level used to record key service process nodes and exceptions that occur during service running,<br>for example, no network signal or login failure.<br>These logs should be recorded by the dominant module in the service to avoid repeated logging conducted by multiple invoked modules or low-level functions.| | INFO | 4 | Log level used to record key service process nodes and exceptions that occur during service running,<br>for example, no network signal or login failure.<br>These logs should be recorded by the dominant module in the service to avoid repeated logging conducted by multiple invoked modules or low-level functions.|
...@@ -67,9 +68,9 @@ DEBUG logs are not recorded in official versions by default. They are available ...@@ -67,9 +68,9 @@ DEBUG logs are not recorded in official versions by default. They are available
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ | | ------ | ------ | ---- | ------------------------------------------------------------ |
| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value within your application as required.| | domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required.|
| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.|
| format | string | Yes | Format string used to output logs in a specified format. It can contain several parameters, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **<private>**.| | format | string | Yes | Format string used to output logs in a specified format. It can contain several elements, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **\<private>**.|
| args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.| | args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.|
**Example** **Example**
...@@ -98,9 +99,9 @@ Prints INFO logs. ...@@ -98,9 +99,9 @@ Prints INFO logs.
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ | | ------ | ------ | ---- | ------------------------------------------------------------ |
| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value within your application as required.| | domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required. |
| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.|
| format | string | Yes | Format string used to output logs in a specified format. It can contain several parameters, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **<private>**.| | format | string | Yes | Format string used to output logs in a specified format. It can contain several elements, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **\<private>**.|
| args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.| | args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.|
**Example** **Example**
...@@ -129,9 +130,9 @@ Prints WARN logs. ...@@ -129,9 +130,9 @@ Prints WARN logs.
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ | | ------ | ------ | ---- | ------------------------------------------------------------ |
| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value within your application as required.| | domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required. |
| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.|
| format | string | Yes | Format string used to output logs in a specified format. It can contain several parameters, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **<private>**.| | format | string | Yes | Format string used to output logs in a specified format. It can contain several elements, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **\<private>**.|
| args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.| | args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.|
**Example** **Example**
...@@ -160,9 +161,9 @@ Prints ERROR logs. ...@@ -160,9 +161,9 @@ Prints ERROR logs.
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ | | ------ | ------ | ---- | ------------------------------------------------------------ |
| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value within your application as required.| | domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required. |
| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.|
| format | string | Yes | Format string used to output logs in a specified format. It can contain several parameters, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **<private>**.| | format | string | Yes | Format string used to output logs in a specified format. It can contain several elements, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **\<private>**.|
| args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.| | args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.|
**Example** **Example**
...@@ -191,9 +192,9 @@ Prints FATAL logs. ...@@ -191,9 +192,9 @@ Prints FATAL logs.
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ | | ------ | ------ | ---- | ------------------------------------------------------------ |
| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value within your application as required.| | domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required. |
| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.|
| format | string | Yes | Format string used to output logs in a specified format. It can contain several parameters, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **<private>**.| | format | string | Yes | Format string used to output logs in a specified format. It can contain several elements, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **\<private>**.|
| args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.| | args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.|
**Example** **Example**
...@@ -209,3 +210,43 @@ If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log ...@@ -209,3 +210,43 @@ If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log
``` ```
08-05 12:21:47.579 2695-2703/com.example.myapplication F 00001/testTag: hello World <private> 08-05 12:21:47.579 2695-2703/com.example.myapplication F 00001/testTag: hello World <private>
``` ```
## Parameter Format
Parameters in the log are printed in the following format:
%[private flag]specifier
| Privacy Flag| Description|
| ------------ | ---- |
| Unspecified | The default value is **private**, indicating that parameters in plaintext are not printed.|
| private | Prints private parameters.|
| public | Prints parameters in plaintext.|
| Specifier| Description| Example|
| ------------ | ---- | ---- |
| d/i | Prints logs of the **number** and **bigint** types.| 123 |
| s | Prints logs of the **string undefined bool** and **null** types.| "123" |
**Example**
```js
let obj2 = new Object({name:"Jack", age:22});
let isBol = true;
let bigNum = BigInt(1234567890123456789);
hilog.info(0x0001, "jsHilogTest", "print object: %{public}s", JSON.stringify(obj2));
hilog.info(0x0001, "jsHilogTest", "private flag: %{private}s %s, print null: %{public}s", "hello", "world", null);
hilog.info(0x0001, "jsHilogTest", "print undefined: %{public}s", undefined);
hilog.info(0x0001, "jsHilogTest", "print number: %{public}d %{public}i", 123, 456);
hilog.info(0x0001, "jsHilogTest", "print bigNum: %{public}d %{public}i", bigNum, bigNum);
hilog.info(0x0001, "jsHilogTest", "print boolean: %{public}s", isBol);
```
Log printing result:
```
08-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: print object: {"name":"Jack","age":22}
08-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: private flag: <private> <private>, print null: null
08-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: print undefined: undefined
08-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: print number: 123 456
08-09 13:26:29.095 2266 2266 I A00001/jsHilogTest: print bigNum: 1234567890123456768 1234567890123456768
08-09 13:26:29.095 2266 2266 I A00001/jsHilogTest: print boolean: true
```
...@@ -1059,7 +1059,7 @@ Creates a **PhoneNumberFormat** object. ...@@ -1059,7 +1059,7 @@ Creates a **PhoneNumberFormat** object.
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ---------------- | | ------- | ---------------------------------------- | ---- | ---------------- |
| country | string | Yes | Country or region to which the phone number to be formatted belongs.| | country | string | Yes | Country or region to which the phone number to be formatted belongs.|
| options | [PhoneNumberFormatOptions](#phonenumberformatoptions9) | No | Options of the **PhoneNumberFormat** object. | | options | [PhoneNumberFormatOptions](#phonenumberformatoptions8) | No | Options of the **PhoneNumberFormat** object. |
**Example** **Example**
```js ```js
...@@ -1149,7 +1149,7 @@ Obtains the home location of a phone number. ...@@ -1149,7 +1149,7 @@ Obtains the home location of a phone number.
``` ```
## PhoneNumberFormatOptions<sup>9+</sup> ## PhoneNumberFormatOptions<sup>8+</sup>
Defines the options for this PhoneNumberFormat object. Defines the options for this PhoneNumberFormat object.
...@@ -1157,7 +1157,7 @@ Defines the options for this PhoneNumberFormat object. ...@@ -1157,7 +1157,7 @@ Defines the options for this PhoneNumberFormat object.
| Name | Type | Readable | Writable | Description | | Name | Type | Readable | Writable | Description |
| ---- | ------ | ---- | ---- | ---------------------------------------- | | ---- | ------ | ---- | ---- | ---------------------------------------- |
| type | string | Yes | Yes | Format type of a phone number. The available options are as follows: E164,&nbsp;INTERNATIONAL,&nbsp;NATIONAL, and&nbsp;RFC3966.| | type | string | Yes | Yes | Format type of a phone number. The available options are as follows: E164,&nbsp;INTERNATIONAL,&nbsp;NATIONAL, and&nbsp;RFC3966.<br>- In API version 8, **type** is mandatory.<br>- In API version 9 or later, **type** is optional.|
## UnitInfo<sup>8+</sup> ## UnitInfo<sup>8+</sup>
...@@ -1786,8 +1786,8 @@ Obtains a list of IDs supported by the **Transliterator** object. ...@@ -1786,8 +1786,8 @@ Obtains a list of IDs supported by the **Transliterator** object.
**Example** **Example**
```ts ```ts
// ids = ["ASCII-Latin", "Accents-Any", "Amharic-Latin/BGN", ...], 671 IDs supported in total // A total of 671 IDs are supported. One ID is comprised of two parts separated by a hyphen (-) in the format of source-destination. For example, in **ids = ["Han-Latin","Latin-ASCII", "Amharic-Latin/BGN","Accents-Any", ...]**, **Han-Latin** indicates conversion from Chinese to Latin, and **Amharic-Latin** indicates conversion from Amharic to Latin.
// Each ID consists of two parts separated by a hyphen (-). The format is source-destination. // For more information, see ISO-15924.
let ids = I18n.Transliterator.getAvailableIDs(); let ids = I18n.Transliterator.getAvailableIDs();
``` ```
...@@ -2210,6 +2210,157 @@ Enumerates text normalization modes. ...@@ -2210,6 +2210,157 @@ Enumerates text normalization modes.
| NFKD | 4 | NFKD.| | NFKD | 4 | NFKD.|
## SystemLocaleManager<sup>10+</sup>
### constructor<sup>10+</sup>
constructor()
Creates a **SystemLocaleManager** object.
**System API**: This is a system API.
**System capability**: SystemCapability.Global.I18n
**Example**
```js
let systemLocaleManager= new I18n.SystemLocaleManager();
```
### getLanguageInfoArray<sup>10+</sup>
getLanguageInfoArray(languages: Array&lt;string&gt;, options?: SortOptions): Array&lt;LocaleItem&gt;
Obtains the language sorting array.
**System API**: This is a system API.
**System capability**: SystemCapability.Global.I18n
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------------- | ---- | ------------- |
| languages | Array&lt;string&gt; | Yes | List of languages to be sorted.|
| options | [SortOptions](#sortoptions10) | No | Language sorting option.|
**Return value**
| Type | Description |
| ----------------- | -------------------- |
| Array&lt;[LocaleItem](#localeitem10)&gt; | Language list after sorting.|
**Error codes**
For details about the error codes, see [I18N Error Codes](../errorcodes/errorcode-i18n.md).
| ID | Error Message |
| ------ | ---------------------- |
| 890001 | param value not valid |
**Example**
```js
// Assume that the system language is zh-Hans, the system region is CN, and the system locale is zh-Hans-CN.
let systemLocaleManager = new I18n.SystemLocaleManager();
var languages = ["zh-Hans", "en-US", "pt", "ar"];
var sortOptions = {locale: "zh-Hans-CN", isUseLocalName: true, isSuggestedFirst: true};
try {
// The language list after sorting is [zh-Hans, en-US, pt, ar].
let sortedLanguages = systemLocaleManager.getLanguageInfoArray(languages, sortOptions);
} catch(error) {
console.error(`call systemLocaleManager.getLanguageInfoArray failed, error code: ${error.code}, message: ${error.message}.`);
}
```
### getRegionInfoArray<sup>10+</sup>
getRegionInfoArray(regions: Array&lt;string&gt;, options?: SortOptions): Array&lt;LocaleItem&gt;
Obtains the country/region sorting array.
**System API**: This is a system API.
**System capability**: SystemCapability.Global.I18n
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------------- | ---- | ------------- |
| regions | Array&lt;string&gt; | Yes | List of countries/regions to be sorted.|
| options | [SortOptions](#sortoptions10) | No | Country/region sorting option.|
**Return value**
| Type | Description |
| ----------------- | -------------------- |
| Array&lt;[LocaleItem](#localeitem10)&gt; | Country/region list after sorting.|
**Error codes**
For details about the error codes, see [I18N Error Codes](../errorcodes/errorcode-i18n.md).
| ID | Error Message |
| ------ | ---------------------- |
| 890001 | param value not valid |
**Example**
```js
// Assume that the system language is zh-Hans, the system region is CN, and the system locale is zh-Hans-CN.
let systemLocaleManager = new I18n.SystemLocaleManager();
var regions = ["CN", "US", "PT", "EG"];
var sortOptions = {locale: "zh-Hans-CN", isUseLocalName: false, isSuggestedFirst: true};
try {
// The country/region list after sorting is [CN, EG, US, PT].
let sortedRegions = systemLocaleManager.getRegionInfoArray(regions, sortOptions);
} catch(error) {
console.error(`call systemLocaleManager.getRegionInfoArray failed, error code: ${error.code}, message: ${error.message}.`);
}
```
## LocaleItem<sup>10+</sup>
Represents the list of languages or countries/regions sorted by **SystemLocaleManager**.
**System capability**: SystemCapability.Global.I18n
| Name | Type | Mandatory | Description |
| --------------- | --------------- | ------ | --------------------------------------- |
| id | string | Yes | Language code or country/region code, for example, **zh** or **CN**. |
| suggestionType | [SuggestionType](#suggestiontype10) | Yes | Language or country/region suggestion type. |
| displayName | string | Yes | Displayed name of the ID in the locale of **SystemLocaleManager**.|
| localName | string | No | Local name of the ID. |
## SuggestionType<sup>10+</sup>
Represents the language or country/region suggestion type.
**System capability**: SystemCapability.Global.I18n
| Name | Value | Description |
| ---------------------- | ---- | ---- |
| SUGGESTION_TYPE_NONE | 0x00 | Not a recommended language or country/region.|
| SUGGESTION_TYPE_RELATED| 0x01 | Country/region recommended by the system language or language recommended by the system country/region.|
| SUGGESTION_TYPE_SIM | 0x02 | Language recommended by the country/region of the SIM card.|
## SortOptions<sup>10+<sup>
Represents the language or country/region sorting option.
**System capability**: SystemCapability.Global.I18n
| Name | Type | Mandatory| Description |
| --------------- | --------------- | ---- | --------------------------------------- |
| locale | string | No | System locale, for example, **zh-Hans-CN**. |
| isUseLocalName | boolean | No | Whether to use the local name for sorting. |
| isSuggestedFirst | boolean | No | Whether to move the recommended language or country/region to the top in the sorting result. |
## I18n.getDisplayCountry<sup>(deprecated)</sup> ## I18n.getDisplayCountry<sup>(deprecated)</sup>
getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册