Skip to content

D
Docs

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

通知 161
Star 293
Fork 28
D
Docs
提交 f251f0d0 编写于 作者: E ester.zhou
浏览文件
操作

Update docs (9604) 

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 b169e240
隐藏空白更改
内联 并排
Showing with 460 addition and 363 deletion
en/application-dev/faqs/faqs-ui-ets.md
浏览文件 @ f251f0d0
...@@ -202,7 +202,7 @@ struct DialogTest { ...@@ -202,7 +202,7 @@ struct DialogTest {
Applicable to: OpenHarmony SDK 3.2.5.3, stage model of API version 9 Applicable to: OpenHarmony SDK 3.2.5.3, stage model of API version 9
The **\<List>** component is a scrollable container. By default, it taks up the entire screen height. When any component with a fixed height takes up part of the screen height, you need to explicitly specify **layoutWeight(1)** for the parent container of the **\<List>** component to take up the remaining height instead of the entire screen height. The **\<List>** component is a scrollable container. By default, it takes up the entire screen height. When any component with a fixed height takes up part of the screen height, you need to explicitly specify **layoutWeight(1)** for the parent container of the **\<List>** component to take up the remaining height instead of the entire screen height.
## How do I center child components in a grid container? ## How do I center child components in a grid container?
......
en/application-dev/faqs/faqs-ui-js.md
浏览文件 @ f251f0d0
...@@ -30,7 +30,7 @@ let options = {trim : false, declarationKey:"_declaration", ...@@ -30,7 +30,7 @@ let options = {trim : false, declarationKey:"_declaration",
nameKey : "_name", elementsKey : "_elements"} nameKey : "_name", elementsKey : "_elements"}
let result:any = conv.convert(xml, options) // Convert fields in the XML file into JavaScript objects. let result:any = conv.convert(xml, options) // Convert fields in the XML file into JavaScript objects.
console.log('Test: ' + JSON.stringify(result)) console.log('Test: ' + JSON.stringify(result))
console.log('Test: ' + result._declaration._attributes.version) // vesion field in XML file console.log('Test: ' + result._declaration._attributes.version) // version field in XML file
console.log('Test: ' + result._elements[0]._elements[0]._elements[0]._text) // title field in XML file console.log('Test: ' + result._elements[0]._elements[0]._elements[0]._text) // title field in XML file
``` ```
......
en/application-dev/notification/common-event.md
浏览文件 @ f251f0d0
...@@ -13,14 +13,14 @@ Each application can subscribe to common events as required. After your applicat ...@@ -13,14 +13,14 @@ Each application can subscribe to common events as required. After your applicat
## Common Event Subscription Development ## Common Event Subscription Development
### When to Use ### When to Use
You can create a subscriber object to subscribe to a common event to obtain the parameters passed in the event. Certain system common events require specific permissions to subscribe to. For details, see [Required Permissions](../reference/apis/js-apis-commonEvent.md). You can create a subscriber object to subscribe to a common event to obtain the parameters passed in the event. Certain system common events require specific permissions to subscribe to. For details, see [Required Permissions](../reference/apis/js-apis-commonEvent.md#required-permissions).
### Available APIs ### Available APIs
| API | Description| | API | Description|
| ---------------------------------------------------------------------------------------------- | ----------- | | ---------------------------------------------------------------------------------------------- | ----------- |
| commonEvent.createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback) | Creates a subscriber. This API uses a callback to return the result.| | createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback) | Creates a subscriber. This API uses a callback to return the result.|
| commonEvent.createSubscriber(subscribeInfo: CommonEventSubscribeInfo) | Creates a subscriber. This API uses a promise to return the result. | | createSubscriber(subscribeInfo: CommonEventSubscribeInfo) | Creates a subscriber. This API uses a promise to return the result. |
| commonEvent.subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback) | Subscribes to common events.| | subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback) | Subscribes to common events.|
### How to Develop ### How to Develop
1. Import the **commonEvent** module. 1. Import the **commonEvent** module.
...@@ -82,8 +82,8 @@ You can use the **publish** APIs to publish a custom common event, which can car ...@@ -82,8 +82,8 @@ You can use the **publish** APIs to publish a custom common event, which can car
### Available APIs ### Available APIs
| API | Description| | API | Description|
| ---------------------------------- | ------ | | ---------------------------------- | ------ |
| commonEvent.publish(event: string, callback: AsyncCallback) | Publishes a common event.| | publish(event: string, callback: AsyncCallback) | Publishes a common event.|
| commonEvent.publish(event: string, options: CommonEventPublishData, callback: AsyncCallback) | Publishes a common event with given attributes.| | publish(event: string, options: CommonEventPublishData, callback: AsyncCallback) | Publishes a common event with given attributes.|
### How to Develop ### How to Develop
#### Development for Publishing a Common Event #### Development for Publishing a Common Event
...@@ -119,7 +119,7 @@ import commonEvent from '@ohos.commonEvent' ...@@ -119,7 +119,7 @@ import commonEvent from '@ohos.commonEvent'
// Attributes of a common event. // Attributes of a common event.
var options = { var options = {
code: 1, // Result code of the common event code: 1, // Result code of the common event
data: "initial data",// Result data of the common event data: "initial data";// Result data of the common event
} }
``` ```
...@@ -144,7 +144,7 @@ You can use the **unsubscribe** API to unsubscribe from a common event. ...@@ -144,7 +144,7 @@ You can use the **unsubscribe** API to unsubscribe from a common event.
### Available APIs ### Available APIs
| API | Description| | API | Description|
| ---------------------------------- | ------ | | ---------------------------------- | ------ |
| commonEvent.unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback) | Unsubscribes from a common event.| | unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback) | Unsubscribes from a common event.|
### How to Develop ### How to Develop
1. Import the **commonEvent** module. 1. Import the **commonEvent** module.
......
en/application-dev/notification/notification-brief.md
浏览文件 @ f251f0d0
...@@ -7,16 +7,13 @@ Common Event Service (CES) enables applications to publish, subscribe to, and un ...@@ -7,16 +7,13 @@ Common Event Service (CES) enables applications to publish, subscribe to, and un
![ces](figures/ces.png) ![ces](figures/ces.png)
- System common event: sent by the system based on system policies to the applications that have subscribed to the event. This type of event includes the screen-on/off events that the users are aware of and the system events published by key system services, such as USB device attachment or detachment, network connection, and system update events. - System common event: sent by the system based on system policies to the applications that have subscribed to the event. This type of event includes the screen-on/off events that the users are aware of and the system events published by key system services, such as USB device attachment or detachment, network connection, and system update events.
- Custom common event: customized by applications to be received by specific subscribers. This type of event is usually related to the service logic of the sender applications. - Custom common event: customized by applications to be received by specific subscribers. This type of event is usually related to the service logic of the sender applications.
The Advanced Notification Service (ANS) enables applications to publish notifications. Below are some typical use cases for publishing notifications: The Advanced Notification Service (ANS) enables applications to publish notifications. Below are some typical use cases for publishing notifications:
- Display received SMS messages and instant messages. - Display received SMS messages and instant messages.
- Display push messages of applications, such as advertisements, version updates, and news notifications.
- Display push messages of applications, such as advertisements, version updates, and news notifications. - Display ongoing events, such as music playback, navigation information, and download progress.
- Display ongoing events, such as music playback, navigation information, and download progress.
Notifications are displayed in the notification panel. Uses can delete a notification or click the notification to trigger predefined actions. Notifications are displayed in the notification panel. Uses can delete a notification or click the notification to trigger predefined actions.
......
en/application-dev/quick-start/package-structure.md
浏览文件 @ f251f0d0
...@@ -2,19 +2,19 @@ ...@@ -2,19 +2,19 @@
# Application Package Structure Configuration File # Application Package Structure Configuration File
In an application development project, you need to declare the package structure of the application in the **config.json** file. When developing an application in the Feature Ability (FA) model, you must declare the package structure of the application in the **config.json** file.
## Internal Structure of the config.json File ## Internal Structure of the config.json File
The **config.json** file consists of three mandatory tags, namely, **app**, **deviceConfig**, and **module**. See Table 1 for details. The **config.json** file consists of three mandatory tags, namely, **app**, **deviceConfig**, and **module**. For details, see Table 1.
Table 1 Internal structure of the config.json file Table 1 Internal structure of the config.json file
| Tag | Description | Data Type| Initial Value Allowed| | Tag | Description | Data Type| Initial Value Allowed|
| ------------ | ------------------------------------------------------------ | -------- | ---------- | | ------------ | ------------------------------------------------------------ | -------- | ---------- |
| app | Global configuration of an application. Different HAP files of the same application must use the same **app** configuration. For details, see [Internal Structure of the app Tag](#internal-structure-of-the-app-tag).| Object | No | | app | Global configuration of the application. Different HAP files of the same application must use the same **app** configuration. For details, see [Internal Structure of the app Tag](#internal-structure-of-the-app-tag).| Object | No |
| deviceConfig | Application configuration applied to a specific type of device. For details, see [Internal Structure of the deviceconfig Tag](#internal-structure-of-the-deviceconfig-tag).| Object | No | | deviceConfig | Application configuration applied to a specific type of device. For details, see [Internal Structure of the deviceconfig Tag](#internal-structure-of-the-deviceconfig-tag).| Object | No |
| module | Configuration of a HAP file. The **module** configuration is valid only for the current HAP file. For details, see [Internal Structure of the module Tag](#internal-structure-of-the-module-tag).| Object | No | | module | Configuration of a HAP file. It is valid only for the current HAP file. For details, see [Internal Structure of the module Tag](#internal-structure-of-the-module-tag).| Object | No |
Example of the **config.json** file: Example of the **config.json** file:
...@@ -86,12 +86,15 @@ The **app** tag contains the global configuration information of the application ...@@ -86,12 +86,15 @@ The **app** tag contains the global configuration information of the application
Table 2 Internal structure of the app tag Table 2 Internal structure of the app tag
| Attribute | Description | Data Type| Initial Value Allowed | | Attribute | Description | Data Type| Initial Value Allowed |
| ---------- | ------------------------------------------------------------ | -------- | ------------------ | | ----------------- | ------------------------------------------------------------ | -------- | --------------------------- |
| bundleName | Bundle name of the application. It uniquely identifies the application. The bundle name can contain only letters, digits, underscores (_), and periods (.). It must start with a letter. The value is a string with 7 to 127 bytes of a reverse domain name, for example, **com.example.myapplication**. It is recommended that the first level be the domain suffix "com" and the second level be the vendor/individual name. More levels are also accepted.| String | No | | bundleName | Bundle name, which uniquely identifies an application. The bundle name can contain only letters, digits, underscores (_), and periods (.). It must start with a letter. The value is a string with 7 to 127 bytes of a reverse domain name, for example, **com.example.myapplication**. It is recommended that the first level be the domain suffix "com" and the second level be the vendor/individual name. More levels are also accepted.| String | No |
| vendor | Description of the application vendor. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)| | vendor | Description of the application vendor. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty) |
| version | Version information of the application. For details, see Table 3. | Object | No | | version | Version of the application. For details, see Table 3. | Object | No |
| apiVersion | OpenHarmony API version on which the application depends. For details, see Table 4. | Object | Yes (initial value: left empty)| | apiVersion | OpenHarmony API version on which the application depends. For details, see Table 4. | Object | Yes (initial value: left empty) |
| singleton | Whether to enable singleton mode for the application. This attribute applies only to system applications and does not take effect for third-party applications. If this attribute is set to **true**, the application always runs in singleton mode, even in multi-user scenarios. This attribute is supported since API version 8.| Boolean | Yes (initial value: **false**)|
| removable | Whether the application can be uninstalled. This attribute applies only to system applications and does not take effect for third-party applications. It is supported since API version 8. | Boolean | Yes (initial value: **true**) |
| userDataClearable | Whether user data of the application can be cleared. This attribute applies only to system applications and does not take effect for third-party applications. It is supported since API version 8.| Boolean | Yes (initial value: **true**) |
Table 3 Internal structure of version Table 3 Internal structure of version
...@@ -99,7 +102,7 @@ Table 3 Internal structure of version ...@@ -99,7 +102,7 @@ Table 3 Internal structure of version
| ------------------------ | ------------------------------------------------------------ | -------- | -------------------------- | | ------------------------ | ------------------------------------------------------------ | -------- | -------------------------- |
| name | Application version number visible to users. The value can be customized and cannot exceed 127 bytes. The customization rules are as follows:<br>API 5 and earlier versions: A three-segment version number is recommended, for example, A.B.C (also compatible with A.B). In the version number, A, B, and C are integers ranging from 0 to 999. Other formats are not supported.<br> A indicates the major version number. <br> B indicates the minor version number.<br> C indicates the patch version number.<br>API 6 and later versions: A four-segment version number is recommended, for example, A.B.C.D. In the version number, A, B, and C are integers ranging from 0 to 99, and D is an integer ranging from 0 to 999.<br> A indicates the major version number. <br> B indicates the minor version number.<br> C indicates the feature version number.<br> D indicates the patch version number.| Number | No | | name | Application version number visible to users. The value can be customized and cannot exceed 127 bytes. The customization rules are as follows:<br>API 5 and earlier versions: A three-segment version number is recommended, for example, A.B.C (also compatible with A.B). In the version number, A, B, and C are integers ranging from 0 to 999. Other formats are not supported.<br> A indicates the major version number. <br> B indicates the minor version number.<br> C indicates the patch version number.<br>API 6 and later versions: A four-segment version number is recommended, for example, A.B.C.D. In the version number, A, B, and C are integers ranging from 0 to 99, and D is an integer ranging from 0 to 999.<br> A indicates the major version number. <br> B indicates the minor version number.<br> C indicates the feature version number.<br> D indicates the patch version number.| Number | No |
| code | Application version number used only for application management by OpenHarmony. This version number is not visible to users of the application. The value rules are as follows:<br>API 5 and earlier versions: It is a non-negative integer less than 32 bits in binary mode, converted from the value of version.name as follows: The conversion rules are as follows:<br> Value of **code** = A * 1,000,000 + B * 1,000 + C. For example, if the value of **version.name** is 2.2.1, the value of **code** is 2002001.<br> API 6 and later versions: The value of **code** is not associated with the value of **version.name** and can be customized. The value is a non-negative integer ranging from 2 to 31. Note that the value must be updated each time the application version is updated. The value for a later version must be greater than that for an earlier version.| Number | No | | code | Application version number used only for application management by OpenHarmony. This version number is not visible to users of the application. The value rules are as follows:<br>API 5 and earlier versions: It is a non-negative integer less than 32 bits in binary mode, converted from the value of version.name as follows: The conversion rules are as follows:<br> Value of **code** = A * 1,000,000 + B * 1,000 + C. For example, if the value of **version.name** is 2.2.1, the value of **code** is 2002001.<br> API 6 and later versions: The value of **code** is not associated with the value of **version.name** and can be customized. The value is a non-negative integer ranging from 2 to 31. Note that the value must be updated each time the application version is updated. The value for a later version must be greater than that for an earlier version.| Number | No |
| minCompatibleVersionCode | Minimum compatible version of the application. It is used to check whether the application is compatible with the version on other devices in the cross-device scenario.<br> The value rules are the same as those of **version.code**.| Number | No (initial value: **code** attribute value)| | minCompatibleVersionCode | Earliest version compatible with the application. It is used in the cross-device scenario to check whether the application is compatible with a specific version on other devices.<br> The value rules are the same as those of **version.code**.| Number | No (initial value: **code** attribute value)|
Table 4 Internal structure of apiVersion Table 4 Internal structure of apiVersion
...@@ -116,15 +119,15 @@ Example of the app tag structure: ...@@ -116,15 +119,15 @@ Example of the app tag structure:
"bundleName": "com.example.myapplication", "bundleName": "com.example.myapplication",
"vendor": "example", "vendor": "example",
"version": { "version": {
"code": 1, "code": 1,
"name": "1.0" "name": "1.0"
}, },
"apiVersion": { "apiVersion": {
"compatible": 4, "compatible": 4,
"target": 5, "target": 5,
"releaseType": "Beta1" "releaseType": "Beta1"
} }
} }
``` ```
### Internal Structure of the deviceConfig Tag ### Internal Structure of the deviceConfig Tag
...@@ -133,13 +136,13 @@ The **deviceConfig** tag contains the application configuration information on t ...@@ -133,13 +136,13 @@ The **deviceConfig** tag contains the application configuration information on t
Table 5 Internal structure of the deviceConfig tag Table 5 Internal structure of the deviceConfig tag
| Attribute | Description | Data Type| Initial Value Allowed | | Attribute| Description | Data Type| Initial Value Allowed |
| ------------ | ----------------------------------------------- | -------- | ------------------ | | -------- | ----------------------------------------- | -------- | ------------------ |
| default | Application configuration applied to all types of devices. See Table 6. | Object | No | | default | Application configuration applied to all types of devices. For details, see Table 6.| Object | No |
| tablet | Application configuration specific to tablets. See Table 6. | Object | Yes (initial value: left empty)| | tablet | Application configuration specific to tablets. For details, see Table 6. | Object | Yes (initial value: left empty)|
| tv | Application configuration specific to smart TVs. See Table 6. | Object | Yes (initial value: left empty)| | tv | Application configuration specific to smart TVs. For details, see Table 6. | Object | Yes (initial value: left empty)|
| car | Application configuration specific to head units. See Table 6. | Object | Yes (initial value: left empty)| | car | Application configuration specific to head units. For details, see Table 6. | Object | Yes (initial value: left empty)|
| wearable | Application configuration specific to wearables. See Table 6. | Object | Yes (initial value: left empty)| | wearable | Application configuration specific to wearables. For details, see Table 6.| Object | Yes (initial value: left empty)|
For details about the internal structures of device attributes, see Table 6. For details about the internal structures of device attributes, see Table 6.
...@@ -147,12 +150,13 @@ Table 6 Internal structure of device attributes ...@@ -147,12 +150,13 @@ Table 6 Internal structure of device attributes
| Attribute | Description | Data Type| Initial Value Allowed | | Attribute | Description | Data Type| Initial Value Allowed |
| ------------------ | ------------------------------------------------------------ | -------- | ----------------------- | | ------------------ | ------------------------------------------------------------ | -------- | ----------------------- |
| process | Name of the process running the application or ability. If the **process** attribute is configured in the **deviceConfig** tag, all abilities of the application run in this process. You can set the **process** attribute for a specific ability in the **abilities** attribute, so that the ability can run in the particular process. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. The value can contain a maximum of 31 characters.| String | Yes | | process | Process running the application or ability. If the **process** attribute is configured in the **deviceConfig** tag, all abilities of the application run in this process. You can set the **process** attribute for a specific ability in the **abilities** attribute, so that the ability can run in the particular process. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. The value can contain a maximum of 31 characters.| String | Yes |
| keepAlive | Whether the application is always kept alive. This attribute applies only to system applications and does not take effect for third-party applications. The value **true** means that the application is always kept alive: The system automatically launches the application at startup and restarts it after it exits.| Boolean | Yes (initial value: **false**) |
| supportBackup | Whether the application supports backup and restoration. The value **false** means that the application does not support backup or restoration.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean | Yes (initial value: **false**)| | supportBackup | Whether the application supports backup and restoration. The value **false** means that the application does not support backup or restoration.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean | Yes (initial value: **false**)|
| compressNativeLibs | Whether the **libs** libraries are packaged in the HAP file after being compressed. The value **false** means that the **libs** libraries are stored without being compressed and will be directly loaded during the installation of the HAP file.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean | Yes (initial value: **true**) | | compressNativeLibs | Whether the **libs** libraries are packaged in the HAP file after being compressed. The value **false** means that the **libs** libraries are stored without being compressed and will be directly loaded during the installation of the HAP file.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean | Yes (initial value: **true**) |
| directLaunch | Whether the application can be started when the device is locked. The value **true** means that the application can be started when the device is locked. Devices running OpenHarmony do not support this attribute.| Boolean | Yes (initial value: **false**)| | directLaunch | Whether the application can be started when the device is locked. The value **true** means that the application can be started when the device is locked. Devices running OpenHarmony do not support this attribute.| Boolean | Yes (initial value: **false**)|
| ark | Maple configuration. See Table 7. | Object | Yes (initial value: left empty) | | ark | Maple configuration. For details, see Table 7. | Object | Yes (initial value: left empty) |
| network | Network security configuration. You can customize the network security settings of the application in the security statement of the configuration file without modifying the application code. See Table 9.| Object | Yes (initial value: left empty) | | network | Network security configuration. You can customize the network security settings of the application in the security statement of the configuration file without modifying the application code. For details, see Table 9.| Object | Yes (initial value: left empty) |
Table 7 Internal structure of the ark attribute Table 7 Internal structure of the ark attribute
...@@ -179,32 +183,32 @@ Table 10 Internal structure of the securityConfig attribute ...@@ -179,32 +183,32 @@ Table 10 Internal structure of the securityConfig attribute
| Attribute | Sub-attribute | Description | Data Type| Initial Value Allowed | | Attribute | Sub-attribute | Description | Data Type| Initial Value Allowed |
| -------------- | ------------------ | ------------------------------------------------------------ | -------- | ---------------- | | -------------- | ------------------ | ------------------------------------------------------------ | -------- | ---------------- |
| domainSettings | - | Security settings of the custom network domain. This attribute allows nested domains. To be more specific, the **domainSettings** object of a large domain can be nested with the **domainSettings** objects of small network domains.| Object| Yes (initial value: left empty)| | domainSettings | - | Security settings of the custom network domain. This attribute allows nested domains. That is, the **domainSettings** object of a network domain can be nested with the **domainSettings** objects of smaller network domains.| Object| Yes (initial value: left empty)|
| | cleartextPermitted | Whether plaintext traffic can be transmitted in the custom network domain. If both **cleartextTraffic** and **security** are declared, whether plaintext traffic can be transmitted in the custom network domain is determined by the **cleartextPermitted** attribute.<br>**true**: Plaintext traffic can be transmitted.<br>**false**: Plaintext traffic cannot be transmitted.| Boolean| No | | | cleartextPermitted | Whether plaintext traffic can be transmitted in the custom network domain. If both **cleartextTraffic** and **security** are declared, whether plaintext traffic can be transmitted in the custom network domain is determined by the **cleartextPermitted** attribute.<br>**true**: Plaintext traffic can be transmitted.<br>**false**: Plaintext traffic cannot be transmitted.| Boolean| No |
| | domains | Domain name configuration. This attribute consists of the **subdomains** and **name** sub-attributes.<br> **subdomains** (boolean): specifies whether the domain name contains subdomains. If this sub-attribute is set to **true**, the domain naming convention applies to all related domains and subdomains (including the lower-level domains of the subdomains). Otherwise, the convention applies only to exact matches.<br> **name** (string): indicates the domain name.| Object array| No | | | domains | Domain name. This attribute consists of two sub-attributes: **subdomains** and **name**.<br> **subdomains** (boolean): specifies whether the domain name contains subdomains. If this sub-attribute is set to **true**, the domain naming convention applies to all related domains and subdomains (including the lower-level domains of the subdomains). Otherwise, the convention applies only to exact matches.<br> **name** (string): indicates the domain name.| Object array| No |
Example of the deviceConfig tag structure: Example of the deviceConfig tag structure:
```json ```json
"deviceConfig": { "deviceConfig": {
"default": { "default": {
"process": "com.example.test.example", "process": "com.example.test.example",
"supportBackup": false, "supportBackup": false,
"network": { "network": {
"cleartextTraffic": true, "cleartextTraffic": true,
"securityConfig": { "securityConfig": {
"domainSettings": { "domainSettings": {
"cleartextPermitted": true, "cleartextPermitted": true,
"domains": [ "domains": [
{ {
"subdomains": true, "subdomains": true,
"name": "example.ohos.com" "name": "example.ohos.com"
} }
] ]
} }
} }
} }
} }
} }
``` ```
...@@ -214,77 +218,78 @@ The **module** tag contains the configuration information of the HAP file. For d ...@@ -214,77 +218,78 @@ The **module** tag contains the configuration information of the HAP file. For d
Table 11 Internal structure of the module tag Table 11 Internal structure of the module tag
| Attribute | Description | Data Type | Initial Value Allowed | | Attribute | Description | Data Type | Initial Value Allowed |
| --------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ | | ----------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ |
| mainAbility | Ability displayed on the Service Center icon. When the resident process is started, the **mainAbility** is started.| String | No if any ability using the Page template exists | | mainAbility | Ability displayed on the Service Center icon. When the resident process is started, the **mainAbility** is started.| String | No if any ability using the Page template exists |
| package | Structure name of the HAP file, which must be unique in the application. The value is a string with a maximum of 127 bytes, in the reverse domain name notation. It is recommended that the value be the same as the project directory of the HAP file. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | No | | package | Package name of the HAP file, which must be unique in the application. The value is a string with a maximum of 127 bytes, in the reverse domain name notation. It is recommended that the value be the same as the project directory of the HAP file. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. | String | No |
| name | Class name of the HAP file. The value is in the reverse domain name notation. The prefix must be the same as the package name specified by the **package** label at the same level. The value can also start with a period (.). The value is a string with a maximum of 255 bytes.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | No | | name | Class name of the HAP file. The value is in the reverse domain name notation, with the prefix same as the package name specified by **package** at the same level. It can also start with a period (.). The value is a string with a maximum of 255 bytes.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | No |
| description | Description of the HAP file. The value is a string with a maximum of 255 bytes. If the value exceeds the limit or needs to support multiple languages, you can use a resource index to the description. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty) | | description | Description of the HAP file. The value is a string with a maximum of 255 bytes. If the value exceeds the limit or needs to support multiple languages, you can use a resource index to the description. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty) |
| supportedModes | Mode supported by the application. Currently, only the **drive** mode is defined. This attribute applies only to head units.| String array| Yes (initial value: left empty) | | supportedModes | Mode supported by the application. Currently, only the **drive** mode is defined. This attribute applies only to head units.| String array| Yes (initial value: left empty) |
| deviceType | Type of device on which the abilities can run. The device types predefined in the system include **tablet**, **tv**, **car**, and **wearable**.| String array| No | | deviceType | Type of device on which the ability can run. The device types predefined in the system include **tablet**, **tv**, **car**, and **wearable**.| String array| No |
| distro | Distribution description of the current HAP file. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. For details, see Table 12.| Object | No | | distro | Distribution description of the HAP file. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. For details, see Table 12.| Object | No |
| metaData | Metadata of the HAP file. For details, see Table 13. | Object | Yes (initial value: left empty) | | metaData | Metadata of the HAP file. For details, see Table 13. | Object | Yes (initial value: left empty) |
| abilities | All abilities in the current module. The value is an array of objects, each of which represents a shortcut object. For details, see Table 17.| Object array | Yes (initial value: left empty) | | abilities | All abilities in the current module. The value is an array of objects, each of which represents a shortcut object. For details, see Table 17.| Object array | Yes (initial value: left empty) |
| js | A set of JS modules developed using the ArkUI framework. Each element in the set represents the information about a JS module. For details, see Table 22.| Object array | Yes (initial value: left empty) | | js | A set of JS modules developed using ArkUI. Each element in the set represents the information about a JS module. For details, see Table 22.| Object array | Yes (initial value: left empty) |
| shortcuts | Shortcut information of the application. The value is an array of objects, each of which represents a shortcut object. For details, see Table 25.| Object array | Yes (initial value: left empty) | | shortcuts | Shortcuts of the application. The value is an array of objects, each of which represents a shortcut object. For details, see Table 25.| Object array | Yes (initial value: left empty) |
| reqPermissions | Permissions that the application applies for from the system before its running. For details, see Table 21. | Object array | Yes (initial value: left empty) | | reqPermissions | Permissions that the application requests from the system when it is running. For details, see Table 21. | Object array | Yes (initial value: left empty) |
| colorMode | Color mode of the application.<br>**dark**: Resources applicable for the dark mode are selected.<br>**light**: Resources applicable for the light mode are selected.<br>**auto**: Resources are selected based on the color mode of the system.<br>This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. | String | Yes (initial value: **auto**) | | colorMode | Color mode of the application. Available values are as follows:<br>**"dark"**: Resources applicable for the dark mode are selected.<br>**"light"**: Resources applicable for the light mode are selected.<br>**"auto"**: Resources are selected based on the color mode of the system.<br> This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. | String | Yes (initial value: **auto**) |
| distroFilter | Application distribution rules.<br>AppGallery uses these rules to distribute HAP files to the matching devices. Distribution rules cover three factors: API version, screen shape, and screen resolution. AppGallery distributes a HAP file to the device whose on the mapping between **deviceType** and these three factors. For details, see Table 29. | Object | Yes (initial value: left empty)<br/>Set this attribute when an application has multiple entry modules. | | distroFilter | Distribution rules of the application.<br> AppGallery uses these rules to distribute HAP files to the matching devices. Distribution rules cover three factors: API version, screen shape, and screen resolution. AppGallery distributes a HAP file to the device whose on the mapping between **deviceType** and these three factors. For details, see Table 29.| Object | Yes (initial value: left empty) Set this attribute when an application has multiple entry modules.|
| reqCapabilities | Device capabilities required for running the application. | String array| Yes (initial value: left empty) | | reqCapabilities | Device capabilities required for running the application. | String array| Yes (initial value: left empty) |
| commonEvents | Static broadcast. For details, see Table 35. | Object array | Yes (initial value: left empty) | | commonEvents | Static broadcast. For details, see Table 35. | Object array | Yes (initial value: left empty) |
| allowClassMap | Metadata of the HAP file. The value can be **true** or **false**. If the value is **true**, the HAP file uses the Java object proxy mechanism provided by the OpenHarmony framework. | Boolean | No (initial value: **false**) | | entryTheme | Keyword of an OpenHarmony internal theme. Set it to the resource index of the name.| String | Yes (initial value: left empty) |
| entryTheme | Keyword of an OpenHarmony internal theme. Set it to the resource index of the name.| String | Yes (initial value: left empty) | | testRunner | Test runner configuration. For details, see Table 36. | Object | Yes (initial value: left empty) |
| definePermissions | Permissions defined for the HAP file. This attribute applies only to system applications and does not take effect for third-party applications. The caller of the application must have these permissions to properly call the app. For details, see Table 37.| Object | Yes (initial value: left empty) |
Example of the **module** tag structure: Example of the **module** tag structure:
```json ```json
"module": { "module": {
"mainAbility": "MainAbility", "mainAbility": "MainAbility",
"package": "com.example.myapplication.entry", "package": "com.example.myapplication.entry",
"name": ".MyOHOSAbilityPackage", "name": ".MyOHOSAbilityPackage",
"description": "$string:description_application", "description": "$string:description_application",
"supportModes": [ "supportModes": [
"drive" "drive"
], ],
"deviceType": [ "deviceType": [
"car" "car"
], ],
"distro": { "distro": {
"moduleName": "ohos_entry", "moduleName": "ohos_entry",
"moduleType": "entry" "moduleType": "entry"
}, },
"abilities": [ "abilities": [
... ...
], ],
"shortcuts": [ "shortcuts": [
... ...
], ],
"js": [ "js": [
... ...
], ],
"reqPermissions": [ "reqPermissions": [
... ...
], ],
"colorMode": "light" "colorMode": "light"
} }
``` ```
Table 12 Internal structure of the distro attribute Table 12 Internal structure of the distro attribute
| Attribute | Description | Data Type| Initial Value Allowed| | Attribute | Description | Data Type| Initial Value Allowed|
| ---------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- | ---------- | | ---------------- | ------------------------------------------------------------ | -------- | ---------- |
| moduleName | Name of the current HAP file. The maximum length is 31 characters. | String | No | | moduleName | Name of the HAP file. The maximum length is 31 characters. | String | No |
| moduleType | Type of the current HAP file. The value can be **entry** or **feature**. For the HAR type, set this attribute to **har**. | String | No | | moduleType | Type of the HAP file. The value can be **entry** or **feature**. For the HAR type, set this attribute to **har**.| String | No |
| installationFree | Whether the HAP file supports the installation-free feature.<br> **true**: The HAP file supports the installation-free feature and meets installation-free constraints.<br> **false**: The HAP file does not support the installation-free feature.<br> Pay attention to the following:<br> When **entry.hap** is set to **true**, all **feature.hap** fields related to **entry.hap **must be **true**.<br> When **entry.hap** is set to **false**, **feature.hap** related to **entry.hap** can be set to **true** or **false** based on service requirements. | Boolean | No | | installationFree | Whether the HAP file supports the installation-free feature.<br> **true**: The HAP file supports the installation-free feature and meets installation-free constraints.<br> **false**: The HAP file does not support the installation-free feature.<br>Pay attention to the following:<br>- When **entry.hap** is set to **true**, all **feature.hap** fields related to **entry.hap **must be **true**.<br>- When **entry.hap** is set to **false**, **feature.hap** related to **entry.hap** can be set to **true** or **false** based on service requirements. | Boolean | No |
| deliveryWithInstall | Whether the HAP file supports the installation with application.<br /> **true**: The HAP file supports the installation with application.<br /> **false**: The HAP file does not support the installation with application. | Boolean | No | | deliveryWithInstall | Whether the HAP file is installed with application.<br> **true**: The HAP file is installed together with the application.<br> **false**: The HAP file is not installed together with the application.| Boolean| No|
Example of the **distro** attribute structure: Example of the **distro** attribute structure:
```json ```json
"distro": { "distro": {
"moduleName": "ohos_entry", "moduleName": "ohos_entry",
"moduleType": "entry", "moduleType": "entry",
"installationFree": true, "installationFree": true,
"deliveryWithInstall": true "deliveryWithInstall": true
} }
``` ```
...@@ -301,9 +306,9 @@ Table 14 Internal structure of the parameters attribute ...@@ -301,9 +306,9 @@ Table 14 Internal structure of the parameters attribute
| Attribute | Description | Data Type| Initial Value Allowed | | Attribute | Description | Data Type| Initial Value Allowed |
| ----------- | ------------------------------------------------------------ | -------- | ------------------ | | ----------- | ------------------------------------------------------------ | -------- | ------------------ |
| description | Description of the parameter. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty)| | description | Description of the parameter passed for calling the ability. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty)|
| name | Name of the parameter. The value can contain a maximum of 255 characters. | String | Yes (initial value: left empty)| | name | Name of the parameter passed for calling the ability. The value can contain a maximum of 255 characters. | String | Yes (initial value: left empty)|
| type | Type of the parameter, for example, **Integer**. | String | No | | type | Type of the parameter passed for calling the ability, for example, **Integer**. | String | No |
Table 15 Internal structure of the results attribute Table 15 Internal structure of the results attribute
...@@ -311,15 +316,15 @@ Table 15 Internal structure of the results attribute ...@@ -311,15 +316,15 @@ Table 15 Internal structure of the results attribute
| ----------- | ------------------------------------------------------------ | -------- | -------------------- | | ----------- | ------------------------------------------------------------ | -------- | -------------------- |
| description | Description of the return value. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty)| | description | Description of the return value. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty)|
| name | Name of the return value. The value can contain a maximum of 255 characters. | String | Yes (initial value: left empty)| | name | Name of the return value. The value can contain a maximum of 255 characters. | String | Yes (initial value: left empty)|
| type | Type of the return value, for example, **Integer**. | String | No | | type | Type of the return value, for example, **Integer**. | String | No |
Table 16 Internal structure of the customizeData attribute Table 16 Internal structure of the customizeData attribute
| Attribute| Description | Data Type| Initial Value Allowed | | Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ---------------------------------------------------------- | -------- | -------------------- | | -------- | ---------------------------------------------------------- | -------- | -------------------- |
| name | Key of a data element. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)| | name | Key of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| value | Value of a data element. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)| | value | Value of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| extra | Custom format of the data element. The value is an index to the resource that identifies the data.| String | Yes (initial value: left empty)| | extra | Custom format of the data item. The value is an index to the resource that identifies the data.| String | Yes (initial value: left empty)|
Example of the **metaData** attribute structure: Example of the **metaData** attribute structure:
...@@ -348,19 +353,19 @@ Table 17 Internal structure of the abilities attribute ...@@ -348,19 +353,19 @@ Table 17 Internal structure of the abilities attribute
| Attribute | Description | Data Type | Initial Value Allowed | | Attribute | Description | Data Type | Initial Value Allowed |
| ---------------- | ------------------------------------------------------------ | ---------- | -------------------------------------------------------- | | ---------------- | ------------------------------------------------------------ | ---------- | -------------------------------------------------------- |
| process | Name of the process running the application or ability. If the **process** attribute is configured in the **deviceConfig** tag, all abilities of the application run in this process. You can set the **process** attribute for a specific ability in the **abilities** attribute, so that the ability can run in the particular process. If this attribute is set to the name of the process running other applications, all these applications can run in the same process, provided they have the same unified user ID and the same signature. Devices running OpenHarmony do not support this attribute.| String | Yes (initial value: left empty) | | process | Name of the process running the application or ability. If the **process** attribute is configured in the **deviceConfig** tag, all abilities of the application run in this process. You can set the **process** attribute for a specific ability in the **abilities** attribute, so that the ability can run in the particular process. If this attribute is set to the name of the process running other applications, all these applications can run in the same process, provided they have the same unified user ID and the same signature. Devices running OpenHarmony do not support this attribute.| String | Yes (initial value: left empty) |
| name | Name of the ability. The value is a reverse domain name, in the format of "*Bundle name*.*Class name*", for example, **"com.example.myapplication.MainAbility"**. Alternatively, the value can start with a period (.) followed by the class name, for example, **".MainAbility"**.<br> The ability name must be unique in an application. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.<br> Note: When you use DevEco Studio to create a project, the configuration of the first ability is generated by default, including the **MainAbility.java** file and the class name **MainAbility** defaulted in the **name** string for the **abilities** attribute in **config.json**. The value of this attribute can be customized if you use other IDE tools. The value can contain a maximum of 127 characters.| String | No | | name | Ability name. The value can be a reverse domain name, in the format of "*Bundle name*.*Class name*", for example, **"com.example.myapplication.MainAbility"**. Alternatively, the value can start with a period (.) followed by the class name, for example, **".MainAbility"**.<br> The ability name must be unique in an application. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.<br>Note: If you use DevEco Studio to create the project, an ability named **MainAbility** will be created together with the default configuration in the **config.json** file. The value of this attribute can be customized if you use other IDEs. The value can contain a maximum of 127 characters. | String | No |
| description | Description of the ability. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty) | | description | Description of the ability. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty) |
| icon | Index to the ability icon file. Example value: **$media:ability_icon**. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the icon of the ability is also used as the icon of the application. If multiple abilities address this condition, the icon of the first candidate ability is used as the application icon.<br> Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels.| String | Yes (initial value: left empty) | | icon | Index to the ability icon file. Example value: **$media:ability_icon**. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the icon of the ability is also used as the icon of the application. If multiple abilities address this condition, the icon of the first candidate ability is used as the application icon.<br>Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels. | String | Yes (initial value: left empty) |
| label | Ability name visible to users. The value can be a name string or a resource index to names in multiple languages. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the label of the ability is also used as the label of the application. If multiple abilities address this condition, the label of the first candidate ability is used as the application label.<br> Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels. The value can be a reference to a string defined in a resource file or a string enclosed in brackets ({}). The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty) | | label | Ability name visible to users. The value can be a name string or a resource index to names in multiple languages. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the label of the ability is also used as the label of the application. If multiple abilities address this condition, the label of the first candidate ability is used as the application label.<br>Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels. The value can be a reference to a string defined in a resource file or a string enclosed in brackets ({}). The value can contain a maximum of 255 characters. | String | Yes (initial value: left empty) |
| uri | Uniform Resource Identifier (URI) of the ability. The value can contain a maximum of 255 characters. | String | Yes (No for abilities using the Data template) | | uri | Uniform Resource Identifier (URI) of the ability. The value can contain a maximum of 255 characters. | String | Yes (No for abilities using the Data template) |
| launchType | Startup type of the ability. The value can be **standard** or **singleton**.<br>**standard**: Multiple **Ability** instances can be created during startup. Most abilities can use this type.<br>**singleton**: Only a single **Ability** instance can be created across all task stacks during startup. For example, a globally unique incoming call screen uses the singleton startup type. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: **"singleton"**) | | launchType | Launch type of the ability. Available values are as follows:<br>**"standard"**: Multiple **Ability** instances can be created during startup. Most abilities can use this type.<br>**"singleton"**: Only a single **Ability** instance can be created across all task stacks during startup. For example, a globally unique incoming call screen uses the singleton startup type. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. | String | Yes (initial value: **"singleton"**) |
| visible | Whether the ability can be called by other applications.<br>**true**: The ability can be called by other applications.<br>**false**: The ability cannot be called by other applications.| Boolean | Yes (initial value: **false**) | | visible | Whether the ability can be called by other applications.<br>**true**: The ability can be called by other applications.<br>**false**: The ability cannot be called by other applications.| Boolean | Yes (initial value: **false**) |
| permissions | Permissions required for abilities of another application to call the current ability, generally in the format of a reverse domain name. The value can be either the permissions predefined in the OS or your custom permissions.| String array| Yes (initial value: left empty) | | permissions | Permissions required for abilities of another application to call the current ability. The value is an array of permission names predefined by the system, generally in the format of a reverse domain name the reverse domain name format (a maximum of 255 bytes).| String array| Yes (initial value: left empty) |
| skills | Types of the **want** that can be accepted by the ability. | Object array | Yes (initial value: left empty) | | skills | Types of the **want** that can be accepted by the ability. | Object array | Yes (initial value: left empty) |
| deviceCapability | Device capabilities required to run the ability.| String array| Yes (initial value: left empty) | | deviceCapability | Device capabilities required to run the ability.| String array| Yes (initial value: left empty) |
| metaData | Metadata. For details, see Table 13. | Object | Yes (initial value: left empty) | | metaData | Metadata. For details, see Table 13. | Object | Yes (initial value: left empty) |
| type | Type of the ability. Available values are as follows:<br>**page**: FA developed using the Page template to provide the capability of interacting with users.<br>**service**: PA developed using the Service template to provide the capability of running tasks in the background.<br>**data**: PA developed using the Data template to provide unified data access for external systems.<br>**CA**: ability that can be started by other applications as a window.| String | No | | type | Ability type. Available values are as follows:<br>**"page"**: FA developed using the Page template to provide the capability of interacting with users.<br>**"service"**: PA developed using the Service template to provide the capability of running tasks in the background.<br>**"data"**: PA developed using the Data template to provide unified data access for external systems.<br>**"CA"**: ability that can be started by other applications as a window. | String | No |
| orientation | Display orientation of the ability. This attribute applies only to the ability using the Page template. Available values are as follows:<br>unspecified: indicates that the system automatically determines the display orientation of the ability.<br>**landscape**: indicates the landscape orientation.<br>**portrait**: indicates the portrait orientation.<br>**followRecent**: indicates that the orientation follows the most recent application in the stack.| String | Yes (initial value: **"unspecified"**) | | orientation | Display orientation of the ability. This attribute applies only to the ability using the Page template. Available values are as follows:<br>**"unspecified"**: indicates that the system automatically determines the display orientation of the ability.<br>**"landscape"**: indicates the landscape orientation.<br>**"portrait"**: indicates the portrait orientation.<br>**"followRecent"**: indicates that the orientation follows the most recent application in the stack. | String | Yes (initial value: **"unspecified"**) |
| backgroundModes | Background service type of the ability. You can assign multiple background service types to a specific ability. This attribute applies only to the ability using the Service template. Available values are as follows:<br>**dataTransfer**: service for downloading, backing up, sharing, or transferring data from the network or peer devices<br>**audioPlayback**: audio playback service<br>**audioRecording**: audio recording service<br>**pictureInPicture**: picture in picture (PiP) and small-window video playback services<br>**voip**: voice/video call and VoIP services<br>**location**: location and navigation services<br>**bluetoothInteraction**: Bluetooth scanning, connection, and transmission services<br>**wifiInteraction**: WLAN scanning, connection, and transmission services<br>**screenFetch**: screen recording and screenshot services<br>**multiDeviceConnection**: multi-device interconnection service| String array| Yes (initial value: left empty) | | backgroundModes | Background service type of the ability. You can assign multiple background service types to a specific ability. This attribute applies only to the ability using the Service template. Available values are as follows:<br>**dataTransfer**: service for downloading, backing up, sharing, or transferring data from the network or peer devices<br>**audioPlayback**: audio playback service<br>**audioRecording**: audio recording service<br>**pictureInPicture**: picture in picture (PiP) and small-window video playback services<br>**voip**: voice/video call and VoIP services<br>**location**: location and navigation services<br>**bluetoothInteraction**: Bluetooth scanning, connection, and transmission services<br>**wifiInteraction**: WLAN scanning, connection, and transmission services<br>**screenFetch**: screen recording and screenshot services<br>**multiDeviceConnection**: multi-device interconnection service| String array| Yes (initial value: left empty) |
| grantPermission | Whether permissions can be granted for any data in the ability. | Boolean | Yes (initial value: left empty) | | grantPermission | Whether permissions can be granted for any data in the ability. | Boolean | Yes (initial value: left empty) |
| readPermission | Permission required for reading data in the ability. This attribute applies only to the ability using the Data template. The value is a string with a maximum of 255 bytes. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty) | | readPermission | Permission required for reading data in the ability. This attribute applies only to the ability using the Data template. The value is a string with a maximum of 255 bytes. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty) |
...@@ -368,15 +373,16 @@ Table 17 Internal structure of the abilities attribute ...@@ -368,15 +373,16 @@ Table 17 Internal structure of the abilities attribute
| configChanges | System configurations that the ability concerns. Upon any changes on the concerned configurations, the **onConfigurationUpdated** callback will be invoked to notify the ability. Available values are as follows:<br>**mcc**: indicates that the mobile country code (MCC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MCC is updated.<br>**mnc**: indicates that the mobile network code (MNC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MNC is updated.<br>**locale**: indicates that the locale is changed. Typical scenario: The user has selected a new language for the text display of the device.<br>**layout**: indicates that the screen layout is changed. Typical scenario: Currently, different display forms are all in the active state.<br>**fontSize**: indicates that font size is changed. Typical scenario: A new global font size is set.<br>**orientation**: indicates that the screen orientation is changed. Typical scenario: The user rotates the device.<br>**density**: indicates that the display density is changed. Typical scenario: The user may specify different display ratios, or different display forms are active at the same time.<br>**size**: indicates that the size of the display window is changed.<br>**smallestSize**: indicates that the length of the shorter side of the display window is changed.<br>**colorMode**: indicates that the color mode is changed.| String array| Yes (initial value: left empty) | | configChanges | System configurations that the ability concerns. Upon any changes on the concerned configurations, the **onConfigurationUpdated** callback will be invoked to notify the ability. Available values are as follows:<br>**mcc**: indicates that the mobile country code (MCC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MCC is updated.<br>**mnc**: indicates that the mobile network code (MNC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MNC is updated.<br>**locale**: indicates that the locale is changed. Typical scenario: The user has selected a new language for the text display of the device.<br>**layout**: indicates that the screen layout is changed. Typical scenario: Currently, different display forms are all in the active state.<br>**fontSize**: indicates that font size is changed. Typical scenario: A new global font size is set.<br>**orientation**: indicates that the screen orientation is changed. Typical scenario: The user rotates the device.<br>**density**: indicates that the display density is changed. Typical scenario: The user may specify different display ratios, or different display forms are active at the same time.<br>**size**: indicates that the size of the display window is changed.<br>**smallestSize**: indicates that the length of the shorter side of the display window is changed.<br>**colorMode**: indicates that the color mode is changed.| String array| Yes (initial value: left empty) |
| mission | Task stack of the ability. This attribute applies only to the ability using the Page template. By default, all abilities in an application belong to the same task stack. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: bundle name of the application) | | mission | Task stack of the ability. This attribute applies only to the ability using the Page template. By default, all abilities in an application belong to the same task stack. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: bundle name of the application) |
| targetAbility | Target ability that this ability alias points to. This attribute applies only to the ability using the Page template. If the **targetAbility** attribute is set, only **name**, **icon**, **label**, **visible**, **permissions**, and **skills** take effect in the current ability (ability alias). Other attributes use the values of the **targetAbility** attribute. The target ability must belong to the same application as the alias and must be declared in **config.json** ahead of the alias. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty, indicating that the current ability is not an alias)| | targetAbility | Target ability that this ability alias points to. This attribute applies only to the ability using the Page template. If the **targetAbility** attribute is set, only **name**, **icon**, **label**, **visible**, **permissions**, and **skills** take effect in the current ability (ability alias). Other attributes use the values of the **targetAbility** attribute. The target ability must belong to the same application as the alias and must be declared in **config.json** ahead of the alias. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty, indicating that the current ability is not an alias)|
| multiUserShared | Whether the ability supports data sharing among multiple users. This attribute applies only to the ability using the Data template. If this attribute is set to **true**, only one copy of data is stored for multiple users. Note that this attribute will invalidate the **visible** attribute. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean | Yes (initial value: **false**) | | multiUserShared | Whether the ability supports data sharing among multiple users. This attribute applies only to the ability using the Data template. If this attribute is set to **true**, only one copy of data is stored for multiple users. Note that this attribute will invalidate the **visible** attribute. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean| Yes (initial value: **false**) |
| supportPipMode | Whether the ability allows the user to enter the Picture in Picture (PiP) mode. The PiP mode enables the user to watch a video in a small window that hovers on top of a full screen window (main window). This attribute applies only to the ability using the Page template. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean | Yes (initial value: **false**) | | supportPipMode | Whether the ability allows the user to enter the Picture in Picture (PiP) mode. The PiP mode enables the user to watch a video in a small window that hovers on top of a full screen window (main window). This attribute applies only to the ability using the Page template. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean| Yes (initial value: **false**) |
| formsEnabled | Whether the ability can provide forms. This attribute applies only to the ability using the Page template.<br>**true**: This ability can provide forms.<br>**false**: This ability cannot provide forms.| Boolean | Yes (initial value: **false**) | | formsEnabled | Whether the ability can provide forms. This attribute applies only to the ability using the Page template.<br>**true**: This ability can provide forms.<br>**false**: This ability cannot provide forms.| Boolean| Yes (initial value: **false**) |
| forms | Details about the forms used by the ability. This attribute is valid only when **formsEnabled** is set to **true**. For details, see Table 27.| Object array | Yes (initial value: left empty) | | forms | Information about the forms used by the ability. This attribute is valid only when **formsEnabled** is set to **true**. For details, see Table 27.| Object array | Yes (initial value: left empty) |
| srcLanguage | Programming language used to develop the ability. | String | The value can be **java**, **js**, or **ets**. | | srcLanguage | Programming language used to develop the ability. The value can be **"js"** or **"ets"**. | String | Yes |
| srcPath | Path of the JS code and components corresponding to the ability. | String | Yes (initial value: left empty) | | srcPath | Path of the JS component code corresponding to the ability. | String | Yes (initial value: left empty) |
| uriPermission | Application data that the ability can access. This attribute consists of the **mode** and **path** sub-attributes. This attribute is valid only for the capability of the type provider. Devices running OpenHarmony do not support this attribute. For details, see Table 18.| Object | Yes (initial value: left empty) | | uriPermission | Application data that the ability can access. This attribute consists of the **mode** and **path** sub-attributes. This attribute is valid only for the capability of the type provider. Devices running OpenHarmony do not support this attribute. For details, see Table 18.| Object | Yes (initial value: left empty) |
| startWindowIcon | Index to the icon file of the ability startup page. Example value: **$media:icon**. | String | Yes (initial value: left empty) | | startWindowIcon | Index to the icon file of the ability startup page. This attribute applies only to the ability using the Page template. Example: **$media:icon**.| String | Yes (initial value: left empty)|
| startWindowBackground | Index to the background color resource file of the ability startup page. Example value: **$color:red**. | String | Yes (initial value: left empty) | | startWindowBackground | Index to the background color resource file of the ability startup page. This attribute applies only to the ability using the Page template. Example: **$color:red**.| String | Yes (initial value: left empty)|
| removeMissionAfterTerminate | Whether to remove the relevant task from the task list after the ability is destroyed. This attribute applies only to the ability using the Page template. The value **true** means to remove the relevant task from the task list after the ability is destroyed, and **false** means the opposite.| Boolean | Yes (initial value: **false**)|
Table 18 Internal structure of the uriPermission attribute Table 18 Internal structure of the uriPermission attribute
...@@ -396,8 +402,7 @@ Example of the **abilities** attribute structure: ...@@ -396,8 +402,7 @@ Example of the **abilities** attribute structure:
"label": "$media:example", "label": "$media:example",
"launchType": "standard", "launchType": "standard",
"orientation": "unspecified", "orientation": "unspecified",
"permissions": [ "permissions": [],
],
"visible": true, "visible": true,
"skills": [ "skills": [
{ {
...@@ -417,7 +422,8 @@ Example of the **abilities** attribute structure: ...@@ -417,7 +422,8 @@ Example of the **abilities** attribute structure:
], ],
"type": "page", "type": "page",
"startWindowIcon": "$media:icon", "startWindowIcon": "$media:icon",
"startWindowBackground": "$color:red" "startWindowBackground": "$color:red",
"removeMissionAfterTerminate": true
}, },
{ {
"name": ".PlayService", "name": ".PlayService",
...@@ -457,20 +463,20 @@ Table 19 Internal structure of the skills attribute ...@@ -457,20 +463,20 @@ Table 19 Internal structure of the skills attribute
| Attribute| Description | Data Type | Initial Value Allowed | | Attribute| Description | Data Type | Initial Value Allowed |
| -------- | ------------------------------------------------------------ | ---------- | -------------------- | | -------- | ------------------------------------------------------------ | ---------- | -------------------- |
| actions | Actions of the **want** that can be accepted by the ability. Generally, the value is an **action** value predefined in the system.| String array| Yes (initial value: left empty)| | actions | Actions of the **want** that can be accepted by the ability. Generally, the value is an **action** value predefined in the system.| String array| Yes (initial value: left empty)|
| entities | Entities of the **want** that can be accepted by the ability, such as video and Home application.| String array| Yes (initial value: left empty)| | entities | Entities of the **want** that can be accepted by the ability, such as video and home applications.| String array| Yes (initial value: left empty)|
| uris | URIs of the **want** that can be accepted by the ability. For details, see Table 20.| Object array | Yes (initial value: left empty)| | uris | URIs of the **want** that can be accepted by the ability. For details, see Table 20.| Object array | Yes (initial value: left empty)|
Table 20 Internal structure of the uris attribute Table 20 Internal structure of the uris attribute
| Attribute | Description | Data Type| Initial Value Allowed | | Attribute | Description | Data Type| Initial Value Allowed |
| ------------- | -------------------------- | -------- | -------------------- | | ------------- | -------------------------- | -------- | -------------------- |
| scheme | Scheme in the URI. | String | No | | scheme | Scheme of the URI. | String | No |
| host | Host in the URI. | String | Yes (initial value: left empty)| | host | Host value of the URI. | String | Yes (initial value: left empty)|
| port | Port number in the URI. | String | Yes (initial value: left empty)| | port | Port number of the URI. | String | Yes (initial value: left empty)|
| pathStartWith | **pathStartWith** value in the URI.| String | String | | pathStartWith | **pathStartWith** value of the URI.| String | Yes (initial value: left empty)|
| path | Path in the URI. | String | Yes (initial value: left empty)| | path | **path** value of the URI. | String | Yes (initial value: left empty)|
| pathRegx | **pathRegx** value in the URI. | String | Yes (initial value: left empty)| | pathRegx | **pathRegx** value of the URI. | String | Yes (initial value: left empty)|
| type | Type of the URI. | String | Yes (initial value: left empty)| | type | **type** value of the URI. | String | Yes (initial value: left empty)|
Example of the **skills** attribute structure: Example of the **skills** attribute structure:
...@@ -485,48 +491,49 @@ Example of the **skills** attribute structure: ...@@ -485,48 +491,49 @@ Example of the **skills** attribute structure:
], ],
"uris": [ "uris": [
{ {
"scheme": "http", "scheme": "http",
"host": "www.example.com", "host": "www.example.com",
"port": "8080", "port": "8080",
"path": "query/student/name", "path": "query/student/name",
"type": "text/*" "type": "text/*"
} }
] ]
} }
] ]
``` ```
Table 21 reqPermissions Table 21 reqPermissions
| Attribute | Description | **Type**| **Value Range** | **Default Value** | **Restrictions** | | Attribute | Description | Data Type| Initial Value Allowed |
| --------- | ------------------------------------------------------------ | -------- | ----------------------------------------------------------- | ---------------------- | ------------------------------------------------------------ | | ---------- | ------------------------------------------------------------ | -------- | ------------------ |
| name | Permission name, which is mandatory. | String | Custom | None | Parsing will fail if this field is not set. | | name | Name of the permission to request.| String| No|
| reason | Reason for applying for the permission, which is mandatory only when applying for the **user_grant** permission.| String | The displayed text cannot exceed 256 bytes. | Empty | If the requested permission is **user_grant**, this attribute is required for the application to be released to AppGallery. Multi-language adaptation is required.| | reason | Reason for requesting the permission. The value cannot exceed 256 bytes. Multi-language adaptation is required.| String| No if the requested permission is **user_grant** (if it is left empty, application release will be rejected)|
| usedScene | Application scenario and timing for using the permission, which is mandatory when the requested permission is **user_grant**. This attribute consists of the **ability** and **when** sub-attributes. Multiple abilities can be configured.| Object | **ability**: ability name; **when**: **inuse** or **always**| **ability**: left empty; **when**: **inuse**| If the requested permission is **user_grant**, the **ability** sub-attribute is mandatory and **when** is optional. | | usedScene | Application scenario and timing for using the permission. This attribute consists of the **ability** and **when** sub-attributes. **ability**: ability name. Multiple ability names can be configured. **when**: time for using the permission. The options are **inuse** and **always**.| Object| **ability**: mandatory for the **user_grant** permission and can be left empty in other cases<br> **when**: initial value allowed (initial value: **inuse**)|
For details, see [Access Control (Permission) Development](../security/accesstoken-guidelines.md#fa-model).
Table 22 Internal structure of the js attribute Table 22 Internal structure of the js attribute
| Attribute| Description | Data Type| Initial Value Allowed | | Attribute| Description | Data Type| Initial Value Allowed |
| -------- | ------------------------------------------------------------ | -------- | ------------------------ | | -------- | ------------------------------------------------------------ | -------- | ------------------------ |
| name | Name of a JavaScript component. The default value is **default**. | String | No | | name | Name of the JS component. The default value is **default**. | String | No |
| pages | Route information about all pages in the JavaScript component, including the page path and page name. The value is an array, in which each element represents a page. The first element in the array represents the home page of the JavaScript FA.| Array | No | | pages | Route information about all pages in the JS component, including the page path and page name. The value is an array, in which each element represents a page. The first element in the array represents the home page of the JavaScript FA.| Array | No |
| window | Window-related configurations. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. For details, see Table 23.| Object | Yes | | window | Window-related configurations. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. For details, see Table 23.| Object | Yes |
| type | Type of the JavaScript component. Available values are as follows:<br>**normal**: indicates that the JavaScript component is an application instance.<br>**form**: indicates that the JavaScript component is a widget instance.| String | Yes (initial value: **normal**)| | type | Type of the JS component. Available values are as follows:<br>**"normal"**: indicates that the JavaScript component is an application instance.<br>**"form"**: indicates that the JavaScript component is a widget instance. | String | Yes (initial value: **"normal"**) |
| mode | Development mode of the JavaScript component. For details, see Table 24. | Object | Yes (initial value: left empty) | | mode | Development mode of the JS component. For details, see Table 24. | Object | Yes (initial value: left empty) |
Table 23 Internal structure of the window attribute Table 23 Internal structure of the window attribute
| Attribute | Description | Data Type| Initial Value Allowed | | Attribute | Description | Data Type| Initial Value Allowed |
| --------------- | ------------------------------------------------------------ | -------- | ----------------------- | | --------------- | ------------------------------------------------------------ | -------- | ----------------------- |
| designWidth | Baseline width for page design, in pixels. The size of an element is scaled by the actual device width.| Number | Yes (initial value: 720px) | | designWidth | Baseline width for page design. The size of an element is scaled by the actual device width.| Number | Yes (initial value: 720px) |
| autoDesignWidth | Whether to automatically calculate the baseline width for page design. If it is set to **true**, the **designWidth** attribute becomes invalid. The baseline width is calculated based on the device width and screen density.| Boolean| Yes (initial value: **false**)| | autoDesignWidth | Whether to automatically calculate the baseline width for page design. If it is set to **true**, the **designWidth** attribute becomes invalid. The baseline width is calculated based on the device width and screen density.| Boolean | Yes (initial value: **false**)|
Table 24 Internal structure of the mode attribute Table 24 Internal structure of the mode attribute
| Attribute| Description | Data Type | Initial Value Allowed | | Attribute| Description | Data Type | Initial Value Allowed |
| -------- | -------------------- | ----------------------------------- | --------------------------- | | -------- | -------------------- | ----------------------------------- | --------------------------- |
| type | Type of the JavaScript component.| String. The value can be **pageAbility** or **form**.| Yes (initial value: **pageAbility**)| | type | Type of the JS component. The value can be **"pageAbility"** or **"form"**. | String | Yes (initial value: **"pageAbility"**) |
| syntax | Syntax type of the JavaScript component.| String. The value can be **hml** or **ets**. | Yes (initial value: **hml**) | | syntax | Syntax type of the JS component. The value can be **"hml"** or **"ets"**. | String | Yes (initial value: **"hml"**) |
Example of the **js** attribute structure: Example of the **js** attribute structure:
...@@ -551,8 +558,8 @@ Table 25 Internal structure of the shortcuts attribute ...@@ -551,8 +558,8 @@ Table 25 Internal structure of the shortcuts attribute
| Attribute | Description | Data Type| Initial Value Allowed | | Attribute | Description | Data Type| Initial Value Allowed |
| ---------- | ------------------------------------------------------------ | -------- | ------------------ | | ---------- | ------------------------------------------------------------ | -------- | ------------------ |
| shortcutId | Shortcut ID. The value is a string with a maximum of 63 bytes. | String | No | | shortcutId | ID of the shortcut. The value is a string with a maximum of 63 bytes. | String | No |
| label | Label of the shortcut, that is, the text description displayed by the shortcut. The value can be a string or a resource index to the description. The value is a string with a maximum of 63 bytes.| String | Yes (initial value: left empty)| | label | Label of the shortcut, that is, the text description displayed for the shortcut. The value can be a string or a resource index to the description. The value is a string with a maximum of 63 bytes.| String | Yes (initial value: left empty)|
| icon | Icon of the shortcut. The value is a resource index to the description. | String | Yes (initial value: left empty)| | icon | Icon of the shortcut. The value is a resource index to the description. | String | Yes (initial value: left empty)|
| intents | Intents to which the shortcut points. The attribute consists of the **targetClass** and **targetBundle** sub-attributes. For details, see Table 26.| Object array| Yes (initial value: left empty)| | intents | Intents to which the shortcut points. The attribute consists of the **targetClass** and **targetBundle** sub-attributes. For details, see Table 26.| Object array| Yes (initial value: left empty)|
...@@ -560,7 +567,7 @@ Table 26 Internal structure of the intents attribute ...@@ -560,7 +567,7 @@ Table 26 Internal structure of the intents attribute
| Attribute | Description | Data Type| Initial Value Allowed | | Attribute | Description | Data Type| Initial Value Allowed |
| ------------ | --------------------------------------- | -------- | -------------------- | | ------------ | --------------------------------------- | -------- | -------------------- |
| targetClass | Class name for the target ability of the shortcut. | String | Yes (initial value: left empty)| | targetClass | Target class of the shortcut. | String | Yes (initial value: left empty)|
| targetBundle | Application bundle name for the target ability of the shortcut.| String | Yes (initial value: left empty)| | targetBundle | Application bundle name for the target ability of the shortcut.| String | Yes (initial value: left empty)|
Example of the **shortcuts** attribute structure: Example of the **shortcuts** attribute structure:
...@@ -584,31 +591,29 @@ Table 27 Internal structure of the forms attribute ...@@ -584,31 +591,29 @@ Table 27 Internal structure of the forms attribute
| Attribute | Description | Data Type | Initial Value Allowed | | Attribute | Description | Data Type | Initial Value Allowed |
| ------------------- | ------------------------------------------------------------ | ---------- | ------------------------ | | ------------------- | ------------------------------------------------------------ | ---------- | ------------------------ |
| name | Class name of the widget. The value is a string with a maximum of 127 bytes. | String | No | | name | Class name of the widget. The value is a string with a maximum of 127 bytes. | String | No |
| description | Description of the widget. The value can be a string or a resource index to descriptions in multiple languages. The value is a string with a maximum of 255 bytes.| String | Yes (initial value: left empty) | | description | Description of the widget. The value can be a string or a resource index to descriptions in multiple languages. The value is a string with a maximum of 255 bytes.| String | Yes (initial value: left empty) |
| isDefault | Whether the widget is a default one. Each ability has only one default widget.<br>**true**: The widget is the default one.<br>**false**: The widget is not the default one.| Boolean | No | | isDefault | Whether the widget is a default one. Each ability has only one default widget.<br>**true**: The widget is the default one.<br>**false**: The widget is not the default one.| Boolean | No |
| type | Type of the widget. Available values are as follows:<br>**Java**: indicates a Java-programmed widget.<br>**JS**: indicates a JavaScript-programmed widget.| String | No | | type | Type of the widget. Available values are as follows:<br>**JS**: indicates a JavaScript-programmed widget. | String | No |
| colorMode | Color mode of the widget. Available values are as follows:<br>**auto**: The widget adopts the auto-adaptive color mode.<br>**dark**: The widget adopts the dark color mode.<br>**light**: The widget adopts the light color mode.| String | Yes (initial value: **auto**)| | colorMode | Color mode of the widget. Available values are as follows:<br>**auto**: The widget adopts the auto-adaptive color mode.<br>**dark**: The widget adopts the dark color mode.<br>**light**: The widget adopts the light color mode.| String | Yes (initial value: **auto**)|
| supportDimensions | Grid styles supported by the widget. Available values are as follows:<br>1 * 2: indicates a grid with one row and two columns.<br>2 * 2: indicates a grid with two rows and two columns.<br>2 * 4: indicates a grid with two rows and four columns.<br>4 * 4: indicates a grid with four rows and four columns.| String array| No | | supportDimensions | Grid styles supported by the widget. Available values are as follows:<br>1 * 2: indicates a grid with one row and two columns.<br>2 * 1: indicates a grid with two rows and one column.<br>2 * 2: indicates a grid with two rows and two columns.<br>2 * 4: indicates a grid with two rows and four columns.<br>4 * 4: indicates a grid with four rows and four columns.| String array| No |
| defaultDimension | Default grid style of the widget. The value must be available in the **supportDimensions** array of the widget.| String | No | | defaultDimension | Default grid style of the widget. The value must be from the **supportDimensions** array of the widget.| String | No |
| landscapeLayouts | Landscape layouts for the grid styles. Values in this array must correspond to the values in the **supportDimensions** array. This field is required only by Java-programmed widgets.| String array| No | | updateEnabled | Whether the widget can be updated periodically. Available values are as follows:<br>**true**: The widget can be updated periodically, depending on the update way you select, either at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** is preferentially recommended.<br>**false**: The widget cannot be updated periodically.| Boolean | No |
| portraitLayouts | Portrait layouts for the grid styles. Values in this array must correspond to the values in the **supportDimensions** array. This field is required only by Java-programmed widgets.| String array| No |
| updateEnabled | Whether the widget can be updated periodically. Available values are as follows:<br>**true**: The widget can be updated periodically, depending on the update way you select, either at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** is preferentially recommended.<br>**false**: The widget cannot be updated periodically.| Boolean | No |
| scheduledUpdateTime | Scheduled time to update the widget. The value is in 24-hour format and accurate to minute. | String | Yes (initial value: **0:0**) | | scheduledUpdateTime | Scheduled time to update the widget. The value is in 24-hour format and accurate to minute. | String | Yes (initial value: **0:0**) |
| updateDuration | Interval to update the widget. The value is a natural number, in the unit of 30 minutes.<br>If the value is **0**, this field does not take effect.<br>If the value is a positive integer ***N***, the interval is calculated by multiplying ***N*** and 30 minutes.| Number | Yes (initial value: **0**) | | updateDuration | Interval to update the widget. The value is a natural number, in the unit of 30 minutes.<br>If the value is **0**, this field does not take effect.<br>If the value is a positive integer ***N***, the interval is calculated by multiplying ***N*** and 30 minutes.| Number | Yes (initial value: **0**) |
| formConfigAbility | Link to a specific page of the application. The value is a URI. | String | Yes (initial value: left empty) | | formConfigAbility | Name of the facility or activity used to adjust the ability. | String | Yes (initial value: left empty) |
| formVisibleNotify | Whether the widget is allowed to use the widget visibility notification. | String | Yes (initial value: left empty) | | formVisibleNotify | Whether the widget is allowed to use the widget visibility notification. | String | Yes (initial value: left empty) |
| jsComponentName | Component name of the widget. The value is a string with a maximum of 127 bytes. This attribute is required only by JavaScript-programmed widgets.| String | No | | jsComponentName | Component name of the widget. The value is a string with a maximum of 127 bytes. This attribute is required only by JavaScript-programmed widgets.| String | No |
| metaData | Metadata of the widget. This attribute contains the array of the **customizeData** attribute. For details, see Table 13. | Object | Yes (initial value: left empty) | | metaData | Metadata of the widget. The value contains value of the **customizeData** attribute. For details, see Table 13. | Object | Yes (initial value: left empty) |
| customizeData | Custom information about the widget. For details, see Table 28. | Object array | Yes (initial value: left empty) | | customizeData | Custom information of the widget. For details, see Table 28. | Object array | Yes (initial value: left empty) |
Table 28 Internal structure of the customizeData attribute Table 28 Internal structure of the customizeData attribute
| Attribute| Description | Data Type| Initial Value Allowed | | Attribute| Description | Data Type| Initial Value Allowed |
| -------- | --------------------------------------------------- | -------- | -------------------- | | -------- | --------------------------------------------------- | -------- | -------------------- |
| name | Name in the custom name-value pair. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)| | name | Key name that identifies a data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| value | Value in the custom name-value pair. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)| | value | Value of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)|
| extra | Format of the current custom data. The value is the resource value of **extra**.| String | Yes (initial value: left empty)| | extra | Current format of the custom data. The value indicates the resource.| String | Yes (initial value: left empty)|
Example of the **forms** attribute structure: Example of the **forms** attribute structure:
...@@ -632,9 +637,9 @@ Example of the **forms** attribute structure: ...@@ -632,9 +637,9 @@ Example of the **forms** attribute structure:
] ]
}, },
{ {
"name": "Form_Java", "name": "Form_Js",
"description": "It's Java Form", "description": "It's JS Form",
"type": "Java", "type": "Js",
"colorMode": "auto", "colorMode": "auto",
"isDefault": false, "isDefault": false,
"updateEnabled": true, "updateEnabled": true,
...@@ -665,13 +670,13 @@ Example of the **forms** attribute structure: ...@@ -665,13 +670,13 @@ Example of the **forms** attribute structure:
Table 29 Internal structure of the distroFilter attribute Table 29 Internal structure of the distroFilter attribute
| Attribute | Description | Data Type| Initial Value Allowed| | Attribute | Description | Data Type| Initial Value Allowed |
| ------------- | ------------------------------------------------------------ | -------- | ---------- | | ------------- | ------------------------------------------------------------ | -------- | -------------------- |
| apiVersion | Supported API versions. For details, see Table 30. | Object | No | | apiVersion | Supported API versions. For details, see Table 30. | Object | Yes (initial value: left empty)|
| screenShape | Supported screen shapes. For details, see Table 31. | Object array| No | | screenShape | Supported screen shapes. For details, see Table 31. | Object array| Yes (initial value: left empty)|
| screenWindow | Supported window resolutions when the application is running. This attribute applies only to the lite wearables. For details, see Table 32.| Object array| No | | screenWindow | Supported window resolutions for when the application is running. This attribute applies only to the lite wearables. For details, see Table 32.| Object array| Yes (initial value: left empty)|
| screenDensity | Pixel density of the screen, in dots per inch (DPI). For details, see Table 33. | Object array| No | | screenDensity | Pixel density of the screen, in dots per inch (dpi). For details, see Table 33. | Object array| Yes (initial value: left empty)|
| countryCode | Country code used during application distribution. For details, see the ISO-3166-1 standard. Multiple enumerated values of countries and regions are supported. For details, see Table 34.| Object array| No | | countryCode | Country code used for distributing the application. For details, see the ISO-3166-1 standard. Multiple enumerated values of countries and regions are supported. For details, see Table 34.| Object array| Yes (initial value: left empty)|
Table 30 Internal structure of the apiVersion attribute Table 30 Internal structure of the apiVersion attribute
...@@ -730,7 +735,7 @@ Example of the **distroFilter** attribute structure: ...@@ -730,7 +735,7 @@ Example of the **distroFilter** attribute structure:
}, },
"countryCode": { "countryCode": {
"policy":"include", "policy":"include",
"value":["CN", "HK"] "value":["CN","HK"]
} }
} }
``` ```
...@@ -741,7 +746,7 @@ Table 35 Internal structure of the commonEvents attribute ...@@ -741,7 +746,7 @@ Table 35 Internal structure of the commonEvents attribute
| ---------- | ------------------------------------------------------------ | ---------- | ------------------ | | ---------- | ------------------------------------------------------------ | ---------- | ------------------ |
| name | Name of a static broadcast. | String | No | | name | Name of a static broadcast. | String | No |
| permission | Permission needed to implement the static common event. | String array| Yes (initial value: left empty)| | permission | Permission needed to implement the static common event. | String array| Yes (initial value: left empty)|
| data | Additional data array to be carried by the current static common event. | String array| Yes (initial value: left empty)| | data | Additional data array to be carried by the current static common event. | String array| Yes (initial value: left empty)|
| type | Type array of the current static common event. | String array| Yes (initial value: left empty)| | type | Type array of the current static common event. | String array| Yes (initial value: left empty)|
| events | A set of events for the wants that can be received. The value can be system predefined or custom.| String array| No | | events | A set of events for the wants that can be received. The value can be system predefined or custom.| String array| No |
...@@ -749,17 +754,44 @@ Example of the **commonEvents** attribute structure: ...@@ -749,17 +754,44 @@ Example of the **commonEvents** attribute structure:
```json ```json
"commonEvents": [ "commonEvents": [
{ {
"name":"MainAbility", "name":"MainAbility",
"permission": "string", "permission": "string",
"data":[ "data":[
"string", "string",
"string" "string"
], ],
"events": [ "events": [
"string", "string",
"string" "string"
] ]
} }
] ]
``` ```
Table 36 Internal structure of the testRunner attribute
| Attribute| Description | Data Type| Initial Value Allowed|
| -------- | -------------------- | -------- | ---------- |
| name | Name of the test runner object.| String | No |
| srcPath | Path of the test runner code.| String | No |
```json
"testRunner": {
"name": "myTestRUnnerName",
"srcPath": "etc/test/TestRunner.ts"
}
```
Table 37 Internal structure of the definePermissions attribute
**definePermission** applies only to system applications and does not take effect for third-party applications.
| Attribute | Description | Data Type| Initial Value Allowed|
| ----------------------- | ------------------------------------------------------------ | -------- | ---------- |
| name | Permission name. | String | No |
| grantMode | Permission grant mode.<br>Available values are as follows:<br>**"system_grant"**: The permission is automatically granted by the system after the application is installed.<br>**"user_grant"**: The permission must be dynamically requested and can be used only after being granted by the user. | String | Yes (initial value: **"system_grant"**) |
| availableLevel | Permission level. Available values are as follows:<br>**"system_core"**: core system permission.<br>**"system_basic"**: basic system permission.<br>**"normal"**: normal permission, which is open to all applications. | String | Yes (initial value: **"normal"**) |
| provisionEnable | Whether the permission can be requested in provision mode. | Boolean | Yes (initial value: **true**) |
| distributedSceneEnabled | Whether the permission can be used in distributed scenarios. | Boolean | Yes (initial value: **false**) |
| label | Brief description of the permission. The value is a resource index. | String | Yes |
| description | Detailed description of the permission, which can be a string or a resource index.| String | Yes |
en/application-dev/reference/apis/js-apis-emitter.md
浏览文件 @ f251f0d0
...@@ -16,19 +16,6 @@ import emitter from '@ohos.events.emitter' ...@@ -16,19 +16,6 @@ import emitter from '@ohos.events.emitter'
None None
## EventPriority
Enumerates the event emit priority levels.
**System capability**: SystemCapability.Notification.Emitter
| Name | Value | Description |
| --------- | ---- | ------------------------------------------------- |
| IMMEDIATE | 0 | The event will be emitted immediately. |
| HIGH | 1 | The event will be emitted before low-priority events. |
| LOW | 2 | The event will be emitted before idle-priority events. By default, an event is in LOW priority. |
| IDLE | 3 | The event will be emitted after all the other events. |
## emitter.on ## emitter.on
on(event: [InnerEvent](#innerevent), callback: Callback\<[EventData](#eventdata)\>): void on(event: [InnerEvent](#innerevent), callback: Callback\<[EventData](#eventdata)\>): void
...@@ -47,13 +34,13 @@ Subscribes to an event in persistent manner. This API uses a callback to return ...@@ -47,13 +34,13 @@ Subscribes to an event in persistent manner. This API uses a callback to return
**Example** **Example**
```javascript ```javascript
var innerEvent = { let innerEvent = {
eventId: 1 eventId: 1
}; };
var callback = (eventData) => { function EmitterCallback(eventData) {
console.info('callback'); console.info('callback');
}; }
emitter.on(innerEvent, callback); emitter.on(innerEvent, EmitterCallback);
``` ```
## emitter.once ## emitter.once
...@@ -74,13 +61,13 @@ Subscribes to an event in one-shot manner and unsubscribes from it after the eve ...@@ -74,13 +61,13 @@ Subscribes to an event in one-shot manner and unsubscribes from it after the eve
**Example** **Example**
```javascript ```javascript
var innerEvent = { let innerEvent = {
eventId: 1 eventId: 1
}; };
var callback = (eventData) => { function EmitterCallback(eventData) {
console.info('once callback'); console.info('once callback');
}; };
emitter.once(innerEvent, callback); emitter.once(innerEvent, EmitterCallback);
``` ```
## emitter.off ## emitter.off
...@@ -121,18 +108,31 @@ Emits an event to the event queue. ...@@ -121,18 +108,31 @@ Emits an event to the event queue.
**Example** **Example**
```javascript ```javascript
var eventData = { let eventData = {
data: { data: {
"content": "c", "content": "c",
"id": 1, "id": 1,
}}; }};
var innerEvent = { let innerEvent = {
eventId: 1, eventId: 1,
priority: emitter.EventPriority.HIGH priority: emitter.EventPriority.HIGH
}; };
emitter.emit(innerEvent, eventData); emitter.emit(innerEvent, eventData);
``` ```
## EventPriority
Enumerates the event emit priority levels.
**System capability**: SystemCapability.Notification.Emitter
| Name | Value | Description |
| --------- | ---- | --------------------------------------------------- |
| IMMEDIATE | 0 | The event will be emitted immediately. |
| HIGH | 1 | The event will be emitted before low-priority events. |
| LOW | 2 | The event will be emitted before idle-priority events. By default, an event is in LOW priority.|
| IDLE | 3 | The event will be emitted after all the other events. |
## InnerEvent ## InnerEvent
Describes an in-process event. Describes an in-process event.
...@@ -141,7 +141,7 @@ Describes an in-process event. ...@@ -141,7 +141,7 @@ Describes an in-process event.
| Name | Type | Readable| Writable| Description | | Name | Type | Readable| Writable| Description |
| -------- | ------------------------------- | ---- | ---- | ---------------------------------- | | -------- | ------------------------------- | ---- | ---- | ---------------------------------- |
| eventId | number | Yes | Yes | Event ID, which is used to identify an event.| | eventId | number | Yes | Yes | Event ID. |
| priority | [EventPriority](#eventpriority) | Yes | Yes | Emit priority of the event. | | priority | [EventPriority](#eventpriority) | Yes | Yes | Emit priority of the event. |
## EventData ## EventData
......
en/application-dev/reference/apis/js-apis-screen-lock.md
浏览文件 @ f251f0d0
...@@ -233,61 +233,46 @@ Locks the screen. This API uses a promise to return the result. ...@@ -233,61 +233,46 @@ Locks the screen. This API uses a promise to return the result.
}); });
``` ```
## EventType
## screenlock.on<sup>9+</sup> Defines the system event type.
on(type: 'beginWakeUp' | 'endWakeUp' | 'beginScreenOn' | 'endScreenOn' | 'beginScreenOff' | 'endScreenOff' | 'unlockScreen' | 'beginExitAnimation', callback: Callback\<void\>): void
Subscribes to screen lock status changes.
**System capability**: SystemCapability.MiscServices.ScreenLock **System capability**: SystemCapability.MiscServices.ScreenLock
**System API**: This is a system API and cannot be called by third-party applications. | Name| Description|
| -------- | -------- |
**Parameters** | beginWakeUp | Wakeup starts when the event starts.|
| endWakeUp | Wakeup ends when the event ends.|
| Name| Type| Mandatory| Description| | beginScreenOn | Screen turn-on starts when the event starts.|
| -------- | -------- | -------- | -------- | | endScreenOn | Screen turn-on ends when the event ends.|
| type | string | Yes| Event type.<br>- **"beginWakeUp"**: Wakeup starts.<br>- **"endWakeUp"**: Wakeup ends.<br>- **"beginScreenOn"**: Screen turn-on starts.<br>- **"endScreenOn"**: Screen turn-on ends.<br>- **"beginScreenOff"**: Screen turn-off starts.<br>- **"endScreenOff"**: Screen turn-off ends.<br>- **"unlockScreen"**: The screen is unlocked.<br>- **"beginExitAnimation"**: Animation starts to exit.| | beginScreenOff | Screen turn-off starts when the event starts.|
| callback | Callback\<void\> | Yes| Callback used to return the result.| | endScreenOff | Screen turn-off ends when the event ends.|
| unlockScreen | The screen is unlocked.|
**Example** | lockScreen | The screen is locked.|
| beginExitAnimation | Animation starts to exit.|
```js | beginSleep | The screen enters sleep mode.|
screenlock.on('beginWakeUp', () => { | endSleep | The screen exits sleep mode.|
console.log('beginWakeUp triggered'); | changeUser | The user is switched.|
}); | screenlockEnabled | Screen lock is enabled.|
``` | serviceRestart | The screen lock service is restarted.|
## screenlock.on<sup>9+</sup>
## SystemEvent
on(type: 'beginSleep' | 'endSleep' | 'changeUser', callback: Callback\<number\>): void
Defines the structure of the system event callback.
Subscribes to screen lock status changes.
**System capability**: SystemCapability.MiscServices.ScreenLock **System capability**: SystemCapability.MiscServices.ScreenLock
**System API**: This is a system API and cannot be called by third-party applications. | Name| Description|
| -------- | -------- |
**Parameters** | eventType | System event type.|
| params | System event parameters.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type.<br>- **"beginSleep"**: The screen enters sleep mode.<br>- **"endSleep"**: The screen exits sleep mode.<br>- **"changeUser"**: The user is switched.|
| callback | Callback\<number\> | Yes| Callback used to return the result. |
**Example**
```js ## screenlock.onSystemEvent<sup>9+</sup>
screenlock.on('beginSleep', (why) => {
console.log('beginSleep triggered:' + why);
});
```
## screenlock.on<sup>9+</sup>
on(type: 'screenlockEnabled', callback: Callback\<boolean\>): void onSystemEvent(callback: Callback\<SystemEvent\>): boolean
Subscribes to screen lock status changes. Registers a callback for system events related to screen locking.
**System capability**: SystemCapability.MiscServices.ScreenLock **System capability**: SystemCapability.MiscServices.ScreenLock
...@@ -297,41 +282,26 @@ Subscribes to screen lock status changes. ...@@ -297,41 +282,26 @@ Subscribes to screen lock status changes.
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| type | string | Yes| Event type.<br>- **"screenlockEnabled"**: Screen lock is enabled.| | callback | Callback\<SystemEvent\> | Yes| Callback for system events related to screen locking|
| callback | Callback\<boolean\> | Yes| Callback used to return the result. |
**Example**
```js
screenlock.on('screenlockEnabled', (isEnabled) => {
console.log('screenlockEnabled triggered, result:' + isEnabled);
});
```
## screenlock.off<sup>9+</sup>
off(type: 'beginWakeUp' | 'endWakeUp' | 'beginScreenOn' | 'endScreenOn' | 'beginScreenOff' | 'endScreenOff' **Return value**
| 'unlockScreen' | 'beginExitAnimation' | 'screenlockEnabled' | 'beginSleep' | 'endSleep' | 'changeUser', callback: Callback\<void\>): void
Unsubscribes from screen lock status changes.
**System capability**: SystemCapability.MiscServices.ScreenLock
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description| | Type | Description |
| -------- | -------- | -------- | -------- | | ------- | -------------------------------------------- |
| type | string | Yes| Event type.<br>- **"beginWakeUp"**: Wakeup starts.<br>- **"endWakeUp"**: Wakeup ends.<br>- **"beginScreenOn"**: Screen turn-on starts.<br>- **"endScreenOn"**: Screen turn-on ends.<br>- **"beginScreenOff"**: Screen turn-off starts.<br>- **"endScreenOff"**: Screen turn-off ends.<br>- **"unlockScreen"**: The screen is unlocked.<br>- **"beginExitAnimation"**: Animation starts to exit.<br>- **"screenlockEnabled"**: Screen lock is enabled.<br>- **"beginSleep"**: The screen enters sleep mode.<br>- **"endSleep"**: The screen exits sleep mode.<br>- **"changeUser"**: The user is switched.| | boolean | The value **true** means that the callback is registered successfully, and **false** means the opposite.|
| callback | Callback\<void\> | Yes| Callback used to return the result.|
**Example** **Example**
```js ```js
screenlock.off('beginWakeUp', () => { let isSuccess = screenlock.onSystemEvent((err, event)=>{
console.log("callback"); console.log(`onSystemEvent:callback:${event.eventType}`)
}); if (err) {
console.log(`onSystemEvent callback error -> ${JSON.stringify(err)}`);
}
});
if (!isSuccess) {
console.log(`onSystemEvent result is false`)
}
``` ```
## screenlock.sendScreenLockEvent<sup>9+</sup> ## screenlock.sendScreenLockEvent<sup>9+</sup>
...@@ -375,7 +345,7 @@ Sends an event to the screen lock service. This API uses a promise to return the ...@@ -375,7 +345,7 @@ Sends an event to the screen lock service. This API uses a promise to return the
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| event | String | Yes| Event type.<br>- **"unlockScreenResult"**: Screen unlock result.<br>- **"screenDrawDone"**: Screen drawing is complete.| | event | String | Yes| Event type.<br>- **"unlockScreenResult"**: Screen unlock result.<br>- **"screenDrawDone"**: Screen drawing is complete.|
| parameter | number | Yes| Screen unlock status.<br>- **0**: The unlock is successful.<br>- **1**: The unlock failed.<br>- **2**: The unlock was canceled.| | parameter | number | Yes| Screen unlock status.<br>- **0**: The unlock is successful.<br>- **1**: The unlock fails.<br>- **2**: The unlock is canceled.|
**Return value** **Return value**
......
en/application-dev/reference/apis/js-apis-system-time.md
浏览文件 @ f251f0d0
...@@ -3,8 +3,8 @@ ...@@ -3,8 +3,8 @@
The **systemTime** module provides system time and time zone features. You can use the APIs of this module to set and obtain the system time and time zone. The **systemTime** module provides system time and time zone features. You can use the APIs of this module to set and obtain the system time and time zone.
> **NOTE** > **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 APIs of this module are system APIs and cannot be called by third-party applications. > - 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
...@@ -60,7 +60,7 @@ Sets the system time. This API uses a promise to return the result. ...@@ -60,7 +60,7 @@ Sets the system time. This API uses a promise to return the result.
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------ | | ------ | ------ | ---- | ------------------ |
| time | number | Yes | Timestamp to set, in milliseconds. | | time | number | Yes | Timestamp to set, in milliseconds.|
**Return value** **Return value**
...@@ -83,7 +83,7 @@ Sets the system time. This API uses a promise to return the result. ...@@ -83,7 +83,7 @@ Sets the system time. This API uses a promise to return the result.
## systemTime.getCurrentTime<sup>8+</sup> ## systemTime.getCurrentTime<sup>8+</sup>
getCurrentTime(isNano?: boolean, callback: AsyncCallback&lt;number&gt;): void getCurrentTime(isNano: boolean, callback: AsyncCallback&lt;number&gt;): void
Obtains the time elapsed since the Unix epoch. This API uses an asynchronous callback to return the result. Obtains the time elapsed since the Unix epoch. This API uses an asynchronous callback to return the result.
...@@ -93,7 +93,7 @@ Obtains the time elapsed since the Unix epoch. This API uses an asynchronous cal ...@@ -93,7 +93,7 @@ Obtains the time elapsed since the Unix epoch. This API uses an asynchronous cal
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ | | -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds.<br>- **false**: in milliseconds. | | isNano | boolean | Yes | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds.<br>- **false**: in milliseconds. |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the time. | | callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the time. |
**Example** **Example**
...@@ -109,6 +109,33 @@ Obtains the time elapsed since the Unix epoch. This API uses an asynchronous cal ...@@ -109,6 +109,33 @@ Obtains the time elapsed since the Unix epoch. This API uses an asynchronous cal
``` ```
## systemTime.getCurrentTime<sup>8+</sup>
getCurrentTime(callback: AsyncCallback&lt;number&gt;): void
Obtains the time elapsed since the Unix epoch. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Time
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the time. |
**Example**
```js
systemTime.getCurrentTime((error, data) => {
if (error) {
console.error(`failed to systemTime.getCurrentTime because ` + JSON.stringify(error));
return;
}
console.log(`systemTime.getCurrentTime success data : ` + JSON.stringify(data));
});
```
## systemTime.getCurrentTime<sup>8+</sup> ## systemTime.getCurrentTime<sup>8+</sup>
getCurrentTime(isNano?: boolean): Promise&lt;number&gt; getCurrentTime(isNano?: boolean): Promise&lt;number&gt;
...@@ -121,7 +148,7 @@ Obtains the time elapsed since the Unix epoch. This API uses a promise to return ...@@ -121,7 +148,7 @@ Obtains the time elapsed since the Unix epoch. This API uses a promise to return
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ | | ------ | ------- | ---- | ------------------------------------------------------------ |
| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds.<br>- **false**: in milliseconds. | | isNano | boolean | No | Whether the time to return is in nanoseconds.<br/>- **true**: in nanoseconds.<br>- **false**: in milliseconds. |
**Return value** **Return value**
...@@ -142,7 +169,7 @@ Obtains the time elapsed since the Unix epoch. This API uses a promise to return ...@@ -142,7 +169,7 @@ Obtains the time elapsed since the Unix epoch. This API uses a promise to return
## systemTime.getRealActiveTime<sup>8+</sup> ## systemTime.getRealActiveTime<sup>8+</sup>
getRealActiveTime(isNano?: boolean, callback: AsyncCallback&lt;number&gt;): void getRealActiveTime(isNano: boolean, callback: AsyncCallback&lt;number&gt;): void
Obtains the time elapsed since system start, excluding the deep sleep time. This API uses an asynchronous callback to return the result. Obtains the time elapsed since system start, excluding the deep sleep time. This API uses an asynchronous callback to return the result.
...@@ -152,7 +179,7 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This ...@@ -152,7 +179,7 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ | | -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds.<br>- **false**: in milliseconds. | | isNano | boolean | Yes | Whether the time to return is in nanoseconds.<br/>- **true**: in nanoseconds.<br>- **false**: in milliseconds. |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the time.| | callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the time.|
**Example** **Example**
...@@ -168,6 +195,33 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This ...@@ -168,6 +195,33 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This
``` ```
## systemTime.getRealActiveTime<sup>8+</sup>
getRealActiveTime(callback: AsyncCallback&lt;number&gt;): void
Obtains the time elapsed since system start, excluding the deep sleep time. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Time
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the time.|
**Example**
```js
systemTime.getRealActiveTime((error, data) => {
if (error) {
console.error(`failed to systemTime.getRealActiveTimebecause ` + JSON.stringify(error));
return;
}
console.log(`systemTime.getRealActiveTime success data : ` + JSON.stringify(data));
});
```
## systemTime.getRealActiveTime<sup>8+</sup> ## systemTime.getRealActiveTime<sup>8+</sup>
getRealActiveTime(isNano?: boolean): Promise&lt;number&gt; getRealActiveTime(isNano?: boolean): Promise&lt;number&gt;
...@@ -180,7 +234,7 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This ...@@ -180,7 +234,7 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ | | ------ | ------- | ---- | ------------------------------------------------------------ |
| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds.<br>- **false**: in milliseconds. | | isNano | boolean | No | Whether the time to return is in nanoseconds.<br/>- **true**: in nanoseconds.<br>- **false**: in milliseconds. |
**Return value** **Return value**
...@@ -201,7 +255,7 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This ...@@ -201,7 +255,7 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This
## systemTime.getRealTime<sup>8+</sup> ## systemTime.getRealTime<sup>8+</sup>
getRealTime(isNano?: boolean, callback: AsyncCallback&lt;number&gt;): void getRealTime(isNano: boolean, callback: AsyncCallback&lt;number&gt;): void
Obtains the time elapsed since system start, including the deep sleep time. This API uses an asynchronous callback to return the result. Obtains the time elapsed since system start, including the deep sleep time. This API uses an asynchronous callback to return the result.
...@@ -211,7 +265,7 @@ Obtains the time elapsed since system start, including the deep sleep time. This ...@@ -211,7 +265,7 @@ Obtains the time elapsed since system start, including the deep sleep time. This
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ | | -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds.<br>- **false**: in milliseconds. | | isNano | boolean | Yes | Whether the time to return is in nanoseconds.<br/>- **true**: in nanoseconds.<br>- **false**: in milliseconds. |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the time. | | callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the time. |
**Example** **Example**
...@@ -229,6 +283,32 @@ Obtains the time elapsed since system start, including the deep sleep time. This ...@@ -229,6 +283,32 @@ Obtains the time elapsed since system start, including the deep sleep time. This
## systemTime.getRealTime<sup>8+</sup> ## systemTime.getRealTime<sup>8+</sup>
getRealTime(callback: AsyncCallback&lt;number&gt;): void
Obtains the time elapsed since system start, including the deep sleep time. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Time
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the time. |
**Example**
```js
systemTime.getRealTime((error, data) => {
if (error) {
console.error(`failed to systemTime.getRealTime because ` + JSON.stringify(error));
return;
}
console.log(`systemTime.getRealTime success data: ` + JSON.stringify(data));
});
```
## systemTime.getRealTime<sup>8+</sup>
getRealTime(isNano?: boolean): Promise&lt;number&gt; getRealTime(isNano?: boolean): Promise&lt;number&gt;
Obtains the time elapsed since system start, including the deep sleep time. This API uses a promise to return the result. Obtains the time elapsed since system start, including the deep sleep time. This API uses a promise to return the result.
...@@ -239,7 +319,7 @@ Obtains the time elapsed since system start, including the deep sleep time. This ...@@ -239,7 +319,7 @@ Obtains the time elapsed since system start, including the deep sleep time. This
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ | | ------ | ------- | ---- | ------------------------------------------------------------ |
| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds.<br>- **false**: in milliseconds. | | isNano | boolean | No | Whether the time to return is in nanoseconds.<br/>- **true**: in nanoseconds.<br>- **false**: in milliseconds. |
**Return value** **Return value**
...@@ -278,7 +358,7 @@ Sets the system date. This API uses an asynchronous callback to return the resul ...@@ -278,7 +358,7 @@ Sets the system date. This API uses an asynchronous callback to return the resul
**Example** **Example**
```js ```js
var data = new Date("October 13, 2020 11:13:00"); var data = new Date();
systemTime.setDate(data,(error, data) => { systemTime.setDate(data,(error, data) => {
if (error) { if (error) {
console.error('failed to systemTime.setDate because ' + JSON.stringify(error)); console.error('failed to systemTime.setDate because ' + JSON.stringify(error));
...@@ -314,7 +394,7 @@ Sets the system date. This API uses a promise to return the result. ...@@ -314,7 +394,7 @@ Sets the system date. This API uses a promise to return the result.
**Example** **Example**
```js ```js
var data = new Date("October 13, 2020 11:13:00"); var data = new Date();
systemTime.setDate(data).then((value) => { systemTime.setDate(data).then((value) => {
console.log(`systemTime.setDate success data : ` + JSON.stringify(value)); console.log(`systemTime.setDate success data : ` + JSON.stringify(value));
}).catch((error) => { }).catch((error) => {
......
en/application-dev/reference/apis/js-apis-system-timer.md
浏览文件 @ f251f0d0
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
The **systemTimer** module provides system timer features. You can use the APIs of this module to implement the alarm clock and other timer services. The **systemTimer** module provides system timer features. You can use the APIs of this module to implement the alarm clock and other timer services.
> **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.
>- The APIs of this module are system APIs and cannot be called by third-party applications. >- The APIs of this module are system APIs and cannot be called by third-party applications.
...@@ -24,12 +24,9 @@ Creates a timer. This API uses an asynchronous callback to return the result. ...@@ -24,12 +24,9 @@ Creates a timer. This API uses an asynchronous callback to return the result.
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------ | ---- | --------------------------------------------------------------------------------------- | | ------- | ---------------------------------| ---- | --------------------------------------------------------------------------- |
| options | TimerOptions | Yes | Timer options.<br>**TIMER_TYPE_REALTIME**: sets the timer to the real-time type. If it is not specified, the timer is of the non-real-time type.<br>**TIMER_TYPE_WAKEUP**: sets the timer to the wakeup type. If it is not specified, the timer is of the non-wakeup type.<br>**TIMER_TYPE_EXACT**: sets the timer to the exact type. If it is not specified, the timer is of the non-exact type.<br>**TIMER_TYPE_IDLE: number**: sets the timer to the idle type. If it is not specified, the timer is of the non-idle type (not yet supported).| | options | [TimerOptions](#timeroptions) | Yes | Timer options. |
| repeat | boolean | Yes | Whether the timer is a repeating timer. The value **true** means that the timer is a repeating timer, and **false** means that the timer is a one-shot timer. |
| interval | number | No | Repeat interval. For a repeating timer, the value must be greater than 5000 ms. For a one-shot timer, the value is **0**. |
| wantAgent| wantAgent | No | **wantAgent** object of the notification to be sent when the timer expires. (An OpenHarmony application MainAbility can be started, but not an SA service.) |
**Return value** **Return value**
...@@ -68,12 +65,9 @@ Creates a timer. This API uses a promise to return the result. ...@@ -68,12 +65,9 @@ Creates a timer. This API uses a promise to return the result.
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------ | ---- | --------------------------------------------------------------------------------------- | | ------- | ---------------------------------| ---- | --------------------------------------------------------------------------- |
| options | TimerOptions | Yes | Timer options.<br>**TIMER_TYPE_REALTIME**: sets the timer to the real-time type. If it is not specified, the timer is of the non-real-time type.<br>**TIMER_TYPE_WAKEUP**: sets the timer to the wakeup type. If it is not specified, the timer is of the non-wakeup type.<br>**TIMER_TYPE_EXACT**: sets the timer to the exact type. If it is not specified, the timer is of the non-exact type.<br>**TIMER_TYPE_IDLE: number**: sets the timer to the idle type. If it is not specified, the timer is of the non-idle type (not yet supported).| | options | [TimerOptions](#timeroptions) | Yes | Timer options. |
| repeat | boolean | Yes | Whether the timer is a repeating timer. The value **true** means that the timer is a repeating timer, and **false** means that the timer is a one-shot timer. |
| interval | number | No | Repeat interval. For a repeating timer, the value must be greater than 5000 ms. For a one-shot timer, the value is **0**. |
| wantAgent| wantAgent | No | **wantAgent** object of the notification to be sent when the timer expires. (An OpenHarmony application MainAbility can be started, but not an SA service.) |
**Return value** **Return value**
...@@ -112,7 +106,7 @@ Starts a timer. This API uses an asynchronous callback to return the result. ...@@ -112,7 +106,7 @@ Starts a timer. This API uses an asynchronous callback to return the result.
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | | ----------- | --------------------------- | ---- | ------------------------------------------------------------ |
| timer | number | Yes | ID of the timer. | | timer | number | Yes | ID of the timer. |
| triggerTime | number | Yes | Time when the timer is triggered, in milliseconds. | | triggerTime | number | Yes | Time when the timer is triggered, in milliseconds. |
...@@ -125,8 +119,10 @@ export default { ...@@ -125,8 +119,10 @@ export default {
type: systemTimer.TIMER_TYPE_REALTIME, type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false repeat:false
} }
let timerId = systemTimer.Timer(options) let timerId = systemTimer.createTimer(options)
systemTimer.startTimer(timerId, 10000, (error, data) => { let triggerTime = new Date().getTime()
triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime, (error, data) => {
if (error) { if (error) {
console.error(`failed to systemTime.startTimer ` + JSON.stringify(error)); console.error(`failed to systemTime.startTimer ` + JSON.stringify(error));
return; return;
...@@ -136,7 +132,7 @@ export default { ...@@ -136,7 +132,7 @@ export default {
} }
} }
``` ```
## systemTime.startTimer ## systemTime.startTimer
startTimer(timer: number, triggerTime: number): Promise&lt;void&gt; startTimer(timer: number, triggerTime: number): Promise&lt;void&gt;
...@@ -149,9 +145,7 @@ Starts a timer. This API uses a promise to return the result. ...@@ -149,9 +145,7 @@ Starts a timer. This API uses a promise to return the result.
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | | ----------- | --------------------------- | ---- | ------------------------------------------------------------ |
| timer | number | Yes | ID of the timer. | | timer | number | Yes | ID of the timer. | | triggerTime | number | Yes | Time when the timer is triggered, in milliseconds. |
| triggerTime | number | Yes | Time when the timer is triggered, in milliseconds. |
**Example** **Example**
...@@ -162,8 +156,10 @@ export default { ...@@ -162,8 +156,10 @@ export default {
type: systemTimer.TIMER_TYPE_REALTIME, type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false repeat:false
} }
let timerId = systemTimer.Timer(options) let timerId = systemTimer.createTimer(options)
systemTimer.startTimer(timerId, 10000).then((data) => { let triggerTime = new Date().getTime()
triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime).then((data) => {
console.log(`systemTime.startTimer success data : ` + JSON.stringify(data)); console.log(`systemTime.startTimer success data : ` + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
console.error(`failed to systemTime.startTimer because ` + JSON.stringify(error)); console.error(`failed to systemTime.startTimer because ` + JSON.stringify(error));
...@@ -196,9 +192,11 @@ export default { ...@@ -196,9 +192,11 @@ export default {
type: systemTimer.TIMER_TYPE_REALTIME, type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false repeat:false
} }
let timerId = systemTimer.Timer(options) let timerId = systemTimer.createTimer(options)
systemTimer.startTimer(timerId, 100000) let triggerTime = new Date().getTime()
systemTimer.stoptTimer(timerId, 10000, (error, data) => { triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime)
systemTimer.stoptTimer(timerId, (error, data) => {
if (error) { if (error) {
console.error(`failed to systemTime.startTimer ` + JSON.stringify(error)); console.error(`failed to systemTime.startTimer ` + JSON.stringify(error));
return; return;
...@@ -222,7 +220,7 @@ Stops a timer. This API uses a promise to return the result. ...@@ -222,7 +220,7 @@ Stops a timer. This API uses a promise to return the result.
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ | | ------ | ------- | ---- | ------------------------------------------------------------ |
| timer | number | Yes | ID of the timer. | | timer | number | Yes | ID of the timer. |
**Example** **Example**
...@@ -233,9 +231,11 @@ export default { ...@@ -233,9 +231,11 @@ export default {
type: systemTimer.TIMER_TYPE_REALTIME, type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false repeat:false
} }
let timerId = systemTimer.Timer(options) let timerId = systemTimer.createTimer(options)
systemTimer.startTimer(timerId, 100000) let triggerTime = new Date().getTime()
systemTimer.stoptTimer(timerId, 10000).then((data) => { triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime)
systemTimer.stoptTimer(timerId).then((data) => {
console.log(`systemTime.startTimer success data : ` + JSON.stringify(data)); console.log(`systemTime.startTimer success data : ` + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
console.error(`failed to systemTime.startTimer because ` + JSON.stringify(error)); console.error(`failed to systemTime.startTimer because ` + JSON.stringify(error));
...@@ -268,8 +268,10 @@ export default { ...@@ -268,8 +268,10 @@ export default {
type: systemTimer.TIMER_TYPE_REALTIME, type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false repeat:false
} }
let timerId = systemTimer.Timer(options) let timerId = systemTimer.createTimer(options)
systemTimer.startTimer(timerId, 100000) let triggerTime = new Date().getTime()
triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime)
systemTimer.stopTimer(timerId) systemTimer.stopTimer(timerId)
systemTimer.destroyTimer(timerId, (error, data) => { systemTimer.destroyTimer(timerId, (error, data) => {
if (error) { if (error) {
...@@ -306,10 +308,12 @@ export default { ...@@ -306,10 +308,12 @@ export default {
type: systemTimer.TIMER_TYPE_REALTIME, type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false repeat:false
} }
let timerId = systemTimer.Timer(options) let timerId = systemTimer.createTimer(options)
systemTimer.startTimer(timerId, 100000) let triggerTime = new Date().getTime()
triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime)
systemTimer.stopTimer(timerId) systemTimer.stopTimer(timerId)
systemTimer.destroytTimer(timerId, 10000).then((data) => { systemTimer.destroyTimer(timerId, 10000).then((data) => {
console.log(`systemTime.startTimer success data : ` + JSON.stringify(data)); console.log(`systemTime.startTimer success data : ` + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
console.error(`failed to systemTime.startTimer because ` + JSON.stringify(error)); console.error(`failed to systemTime.startTimer because ` + JSON.stringify(error));
...@@ -317,3 +321,17 @@ export default { ...@@ -317,3 +321,17 @@ export default {
} }
} }
``` ```
## TimerOptions
Defines the initialization options for **createTimer**.
**System capability**: SystemCapability.MiscServices.Time
| Name | Type | Mandatory| Description |
| -------- | ------------------| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | number | Yes | **const TIMER_TYPE_REALTIME**: sets the timer to the CPU time type. If it is not specified, the timer is of the wall-time type.<br>**const TIMER_TYPE_WAKEUP**: sets the timer to the wakeup type. If it is not specified, the timer is of the non-wakeup type.<br>**const TIMER_TYPE_EXACT**: sets the timer to the exact type. If it is not specified, the timer is of the non-exact type.<br>**const TIMER_TYPE_IDLE: number**: sets the timer to the idle type. If it is not specified, the timer is of the non-idle type (not yet supported). |
| repeat | boolean | Yes | Whether the timer is a repeating timer. The value **true** means that the timer is a repeating timer, and **false** means that the timer is a one-shot timer. |
| interval | number | No | Repeat interval. For a repeating timer, the value must be greater than 5000 ms. For a one-shot timer, the value is **0**. |
| wantAgent| wantAgent | No | **wantAgent** object of the notification to be sent when the timer expires. (An application MainAbility can be started, but not a Service ability.) |
| callback | number | Yes | Callback used to return the timer ID. |
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或