**Context** provides the capability of obtaining contextual information of an application.
**Context** provides the capability of obtaining contextual information of an application.
The OpenHarmony application framework has two models: Feature Ability (FA) model and stage model. Correspondingly, there are two sets of context mechanisms. **application/BaseContext** is a common context base class. It uses the **stageMode** attribute to specify whether the context is used for the stage model.
The OpenHarmony application framework has two models: Feature Ability (FA) model and stage model. Correspondingly, there are two sets of context mechanisms. **application/BaseContext** is a common context base class. It uses the **stageMode** attribute to specify whether the context is used for the stage model.
- FA model
- FA model
Only the methods in **app/Context** can be used for the context in the FA model. Both the application-level context and ability-level context are instances of this type. If an ability-level method is invoked in the application-level context, an error occurs. Therefore, you must pay attention to the actual meaning of the **Context** instance.
Only the methods in **app/Context** can be used for the context in the FA model. Both the application-level context and ability-level context are instances of this type. If an ability-level method is invoked in the application-level context, an error occurs. Therefore, you must pay attention to the actual meaning of the **Context** instance.
@@ -40,4 +40,4 @@ For details about the project directory structure of the FA model, see [OpenHarm
...
@@ -40,4 +40,4 @@ For details about the project directory structure of the FA model, see [OpenHarm
For details about how to configure the application package structure of the FA model, see [Application Package Structure Configuration File](../quick-start/application-configuration-file-overview-fa.md).
For details about how to configure the application package structure of the FA model, see [Application Package Structure Configuration File](../quick-start/application-configuration-file-overview-fa.md).
@@ -158,7 +158,7 @@ The widget configuration file is named **config.json**. Find the **config.json**
...
@@ -158,7 +158,7 @@ The widget configuration file is named **config.json**. Find the **config.json**
| 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 available in the **supportDimensions** array of the widget.| String | No |
| updateEnabled | Whether the widget can be updated periodically.<br>**true**: The widget can be updated at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** takes precedence over **scheduledUpdateTime**.<br>**false**: The widget cannot be updated periodically.| Boolean | No |
| updateEnabled | Whether the widget can be updated periodically.<br>**true**: The widget can be updated at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** takes precedence over **scheduledUpdateTime**.<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.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| String | Yes (initial value: **0:0**) |
| scheduledUpdateTime | Scheduled time to update the widget. The value is in 24-hour format and accurate to minute.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| 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.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| 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.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| 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 | Link to a specific page of the application. The value is a URI. | 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. | String | No |
| jsComponentName | Component name of the widget. The value is a string with a maximum of 127 bytes. | String | No |
...
@@ -206,7 +206,7 @@ A widget provider is usually started when it is needed to provide information ab
...
@@ -206,7 +206,7 @@ A widget provider is usually started when it is needed to provide information ab
// Persistently store widget information for subsequent use, such as widget instance retrieval or update.
// Persistently store widget data for subsequent use, such as widget instance retrieval or update.
// The storeFormInfo API is not implemented here.
// The storeFormInfo API is not implemented here.
storeFormInfo(formId,formName,tempFlag,want);
storeFormInfo(formId,formName,tempFlag,want);
...
@@ -231,9 +231,9 @@ You should override **onDestroy** to implement widget data deletion.
...
@@ -231,9 +231,9 @@ You should override **onDestroy** to implement widget data deletion.
}
}
```
```
For details about how to implement persistence data storage, see [Lightweight Data Store Development](../database/database-preference-guidelines.md).
For details about how to implement persistent data storage, see [Lightweight Data Store Development](../database/database-preference-guidelines.md).
The **Want**passed by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary.
The **Want**object passed in by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary.
- Normal widget: a widget persistently used by the widget host
- Normal widget: a widget persistently used by the widget host
// Call the updateForm method to update the widget. Only the data passed through the input parameter is updated. Other information remains unchanged.
// Call the updateForm() method to update the widget. Only the data passed through the input parameter is updated. Other information remains unchanged.
You can use HML, CSS, and JSON to develop the UI page for a JavaScript-programmed widget.
You can use HML, CSS, and JSON to develop the UI page for a JavaScript-programmed widget.
...
@@ -335,7 +335,7 @@ You can use HML, CSS, and JSON to develop the UI page for a JavaScript-programme
...
@@ -335,7 +335,7 @@ You can use HML, CSS, and JSON to develop the UI page for a JavaScript-programme
"actions":{
"actions":{
"routerEvent":{
"routerEvent":{
"action":"router",
"action":"router",
"abilityName":"com.example.entry.MainAbility",
"abilityName":"com.example.entry.EntryAbility",
"params":{
"params":{
"message":"add detail"
"message":"add detail"
}
}
...
@@ -353,12 +353,12 @@ Now you've got a widget shown below.
...
@@ -353,12 +353,12 @@ Now you've got a widget shown below.
You can set router and message events for components on a widget. The router event applies to ability redirection, and the message event applies to custom click events. The key steps are as follows:
You can set router and message events for components on a widget. The router event applies to ability redirection, and the message event applies to custom click events. The key steps are as follows:
1. Set the **onclick** field in the HML file to **routerEvent** or **messageEvent**, depending on the **actions** settings in the JSON file.
1. Set the **onclick** field in the HML file to **routerEvent** or **messageEvent**, depending on the **actions** settings in the JSON file.
2.For the router event, set the following attributes:
2.Set the router event.
-**action**: **router**, which indicates a router event.
-**action**: **"router"**, which indicates a router event.
-**abilityName**: target ability name, for example, **com.example.entry.MainAbility**, which is the default main ability name in DevEco Studio for the FA model.
-**abilityName**: target ability name, for example, **com.example.entry.EntryAbility**, which is the default UIAbility name in DevEco Studio for the FA model.
-**params**: custom parameters of the target ability. Set them as required. The value can be obtained from **parameters** in **want** used for starting the target ability. For example, in the lifecycle function **onCreate** of the main ability in the FA model, **featureAbility.getWant()** can be used to obtain **want** and its **parameters** field.
-**params**: custom parameters of the target ability. Set them as required. The value can be obtained from **parameters** in **want** used for starting the target ability. For example, in the lifecycle function **onCreate** of the EntryAbility in the FA model, **featureAbility.getWant()** can be used to obtain **want** and its **parameters** field.
3.For the message event, set the following attributes:
3.Set the message event.
-**action**: **message**, which indicates a message event.
-**action**: **"message"**, which indicates a message event.
-**params**: custom parameters of the message event. Set them as required. The value can be obtained from **message** in the widget lifecycle function **onEvent**.
-**params**: custom parameters of the message event. Set them as required. The value can be obtained from **message** in the widget lifecycle function **onEvent**.
The code snippet is as follows:
The code snippet is as follows:
...
@@ -388,7 +388,7 @@ The code snippet is as follows:
...
@@ -388,7 +388,7 @@ The code snippet is as follows:
@@ -207,8 +207,6 @@ The code snippets provided below are all from [Sample](https://gitee.com/openhar
...
@@ -207,8 +207,6 @@ The code snippets provided below are all from [Sample](https://gitee.com/openhar
```
```
For a singleton ability, use **onNewWant()** to achieve the same implementation.
For a singleton ability, use **onNewWant()** to achieve the same implementation.
### Data Continuation
### Data Continuation
Use distributed objects.
Use distributed objects.
...
@@ -220,12 +218,12 @@ In the ability continuation scenario, the distributed data object is used to syn
...
@@ -220,12 +218,12 @@ In the ability continuation scenario, the distributed data object is used to syn
- In **onContinue()**, the initiator saves the data to be migrated to the distributed object, calls the **save()** API to save the data and synchronize the data to the target device, sets the session ID, and sends the session ID to the target device through **wantParam**.
- In **onContinue()**, the initiator saves the data to be migrated to the distributed object, calls the **save()** API to save the data and synchronize the data to the target device, sets the session ID, and sends the session ID to the target device through **wantParam**.
@@ -256,17 +254,16 @@ In the ability continuation scenario, the distributed data object is used to syn
...
@@ -256,17 +254,16 @@ In the ability continuation scenario, the distributed data object is used to syn
- The target device obtains the session ID from **onCreate()**, creates a distributed object, and associates the distributed object with the session ID. In this way, the distributed object can be synchronized. Before calling **restoreWindowStage**, ensure that all distributed objects required for continuation have been associated.
- The target device obtains the session ID from **onCreate()**, creates a distributed object, and associates the distributed object with the session ID. In this way, the distributed object can be synchronized. Before calling **restoreWindowStage**, ensure that all distributed objects required for continuation have been associated.
// Obtain the session ID of the distributed data object from the want parameter.
// Obtain the session ID of the distributed data object from the want parameter.
this.sessionId=want.parameters.session
this.sessionId=want.parameters.session
...
@@ -309,5 +306,3 @@ In the ability continuation scenario, the distributed data object is used to syn
...
@@ -309,5 +306,3 @@ In the ability continuation scenario, the distributed data object is used to syn
### Best Practice
### Best Practice
For better user experience, you are advised to use the **wantParam** parameter to transmit data smaller than 100 KB and use distributed objects to transmit data larger than 100 KB.
For better user experience, you are advised to use the **wantParam** parameter to transmit data smaller than 100 KB and use distributed objects to transmit data larger than 100 KB.
@@ -56,8 +56,8 @@ The table below describes the APIs provided by the **Ability** class. For detail
...
@@ -56,8 +56,8 @@ The table below describes the APIs provided by the **Ability** class. For detail
### Implementing AbilityStage and Ability Lifecycle Callbacks
### Implementing AbilityStage and Ability Lifecycle Callbacks
To create Page abilities for an application in the stage model, you must implement the **AbilityStage** class and ability lifecycle callbacks, and use the **Window** class to set the pages. The sample code is as follows:
To create Page abilities for an application in the stage model, you must implement the **AbilityStage** class and ability lifecycle callbacks, and use the **Window** class to set the pages. The sample code is as follows:
1. Import the **AbilityStage** module.
1. Import the **AbilityStage** module.
```
```ts
import AbilityStage from "@ohos.application.AbilityStage"
2. Implement the **AbilityStage** class. The default relative path generated by the APIs is **entry\src\main\ets\Application\AbilityStage.ts**.
2. Implement the **AbilityStage** class. The default relative path generated by the APIs is **entry\src\main\ets\Application\AbilityStage.ts**.
```ts
```ts
...
@@ -69,41 +69,41 @@ To create Page abilities for an application in the stage model, you must impleme
...
@@ -69,41 +69,41 @@ To create Page abilities for an application in the stage model, you must impleme
```
```
3. Import the **Ability** module.
3. Import the **Ability** module.
```js
```js
importAbilityfrom'@ohos.application.Ability'
importUIAbilityfrom'@ohos.app.ability.UIAbility';
```
```
4. Implement the lifecycle callbacks of the **Ability** class. The default relative path generated by the APIs is **entry\src\main\ets\MainAbility\MainAbility.ts**.
4. Implement the lifecycle callbacks of the **UIAbility** class. The default relative path generated by the APIs is **entry\src\main\ets\entryability\EntryAbility.ts**.
In the **onWindowStageCreate(windowStage)** API, use **loadContent** to set the application page to be loaded. For details about how to use the **Window** APIs, see [Window Development](../windowmanager/application-window-stage.md).
In the **onWindowStageCreate(windowStage)** API, use **loadContent** to set the application page to be loaded. For details about how to use the **Window** APIs, see [Window Development](../windowmanager/application-window-stage.md).
```ts
```ts
exportdefaultclassMainAbilityextendsAbility{
exportdefaultclassEntryAbilityextendsUIAbility{
onCreate(want,launchParam){
onCreate(want,launchParam){
console.log("MainAbility onCreate")
console.log("EntryAbility onCreate")
}
}
onDestroy(){
onDestroy(){
console.log("MainAbility onDestroy")
console.log("EntryAbility onDestroy")
}
}
onWindowStageCreate(windowStage){
onWindowStageCreate(windowStage){
console.log("MainAbility onWindowStageCreate")
console.log("EntryAbility onWindowStageCreate")
windowStage.loadContent("pages/index").then(()=>{
windowStage.loadContent("pages/index").then(()=>{
console.log("MainAbility load content succeed")
console.log("EntryAbility load content succeed")
}).catch((error)=>{
}).catch((error)=>{
console.error("MainAbility load content failed with error: "+JSON.stringify(error))
console.error("EntryAbility load content failed with error: "+JSON.stringify(error))
})
})
}
}
onWindowStageDestroy(){
onWindowStageDestroy(){
console.log("MainAbility onWindowStageDestroy")
console.log("EntryAbility onWindowStageDestroy")
}
}
onForeground(){
onForeground(){
console.log("MainAbility onForeground")
console.log("EntryAbility onForeground")
}
}
onBackground(){
onBackground(){
console.log("MainAbility onBackground")
console.log("EntryAbility onBackground")
}
}
}
}
```
```
...
@@ -113,7 +113,8 @@ Both the **AbilityStage** and **Ability** classes have the **context** attribute
...
@@ -113,7 +113,8 @@ Both the **AbilityStage** and **Ability** classes have the **context** attribute
The following example shows how an application obtains the bundle code directory, HAP file name, ability name, and system language through the **context** attribute in the **AbilityStage** class. The sample code is as follows:
The following example shows how an application obtains the bundle code directory, HAP file name, ability name, and system language through the **context** attribute in the **AbilityStage** class. The sample code is as follows:
The following example shows how an application obtains the bundle code directory, HAP file name, ability name, and system language through the **context** attribute in the **Ability** class. The sample code is as follows:
The following example shows how an application obtains the bundle code directory, HAP file name, ability name, and system language through the **context** attribute in the **Ability** class. The sample code is as follows:
If an application needs to obtain user privacy information or use system capabilities, for example, obtaining location information or using the camera to take photos or record videos, it must request the respective permission from consumers. During application development, you need to specify the involved sensitive permissions, declare the required permissions in **module.json5**, and use the **requestPermissionsFromUser** API to request the permission from consumers in the form of a dialog box. The following uses the permission for calendar access as an example.
Declare the required permission in the **module.json5** file.
```json
"requestPermissions":[
{
"name":"ohos.permission.READ_CALENDAR"
}
]
```
Request the permission from consumers in the form of a dialog box:
console.log("Succeed to request permission from user with data: "+JSON.stringify(data))
}).catch((error)=>{
console.log("Failed to request permission from user with error: "+JSON.stringify(error))
})
```
### Notifying of Environment Changes
### Notifying of Environment Changes
Environment changes include changes of global configurations and ability configurations. Currently, the global configurations include the system language and color mode. The change of global configurations is generally triggered by configuration items in **Settings** or icons in **Control Panel**. The ability configuration is specific to a single **Ability** instance, including the display ID, screen resolution, and screen orientation. The configuration is related to the display where the ability is located, and the change is generally triggered by the window. For details on the configuration, see [Configuration](../reference/apis/js-apis-configuration.md).
Environment changes include changes of global configurations and ability configurations. Currently, the global configurations include the system language and color mode. The change of global configurations is generally triggered by configuration items in **Settings** or icons in **Control Panel**. The ability configuration is specific to a single **Ability** instance, including the display ID, screen resolution, and screen orientation. The configuration is related to the display where the ability is located, and the change is generally triggered by the window. Before configuring a project, define the project in the [Configuration](../reference/apis/js-apis-application-configuration.md) class.
For an application in the stage model, when the configuration changes, its abilities are not restarted, but the **onConfigurationUpdated(config: Configuration)** callback is triggered. If the application needs to perform processing based on the change, you can overwrite **onConfigurationUpdated**. Note that the **Configuration** object in the callback contains all the configurations of the current ability, not only the changed configurations.
For an application in the stage model, when the configuration changes, its abilities are not restarted, but the **onConfigurationUpdated(config: Configuration)** callback is triggered. If the application needs to perform processing based on the change, you can override **onConfigurationUpdated**. Note that the **Configuration** object in the callback contains all the configurations of the current ability, not only the changed configurations.
The following example shows the implementation of the **onConfigurationUpdated** callback in the **AbilityStage** class. The callback is triggered when the system language and color mode are changed.
The following example shows the implementation of the **onConfigurationUpdated** callback in the **AbilityStage** class. The callback is triggered when the system language and color mode are changed.
The following example shows the implementation of the **onConfigurationUpdated** callback in the **Ability** class. The callback is triggered when the system language, color mode, or display parameters (such as the direction and density) change.
The following example shows the implementation of the **onConfigurationUpdated** callback in the **Ability** class. The callback is triggered when the system language, color mode, or display parameters (such as the direction and density) change.
console.log("MainAbility onButtonClick getRemoteDeviceId err: dmClass is null");
console.log("EntryAbility onButtonClick getRemoteDeviceId err: dmClass is null");
}
}
}
}
```
```
Request the permission **ohos.permission.DISTRIBUTED_DATASYNC** from consumers. This permission is used for data synchronization. For details about the sample code for requesting the permission, see [Requesting Permissions](#requesting-permissions).
Request the permission **ohos.permission.DISTRIBUTED_DATASYNC** from consumers. This permission is used for data synchronization. For details about the sample code for requesting permissions, see [abilityAccessCtrl.requestPermissionsFromUse](../reference/apis/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9).
### Starting an Ability with the Specified Page
### Starting an Ability with the Specified Page
If the launch type of an ability is set to **singleton** and the ability has been started, the **onNewWant** callback is triggered when the ability is started again. You can pass start options through the **want**. For example, to start an ability with the specified page, use the **uri** or **parameters** parameter in the **want** to pass the page information. Currently, the ability in the stage model cannot directly use the **router** capability. You must pass the start options to the custom component and invoke the **router** method to display the specified page during the custom component lifecycle management. The sample code is as follows:
If the launch type of an ability is set to **singleton** and the ability has been started, the **onNewWant** callback is triggered when the ability is started again. You can pass start options through the **want**. For example, to start an ability with the specified page, use the **uri** or **parameters** parameter in the **want** to pass the page information. Currently, the ability in the stage model cannot directly use the **router** capability. You must pass the start options to the custom component and invoke the **router** method to display the specified page during the custom component lifecycle management. The sample code is as follows:
...
@@ -281,7 +262,7 @@ async function reStartAbility() {
...
@@ -281,7 +262,7 @@ async function reStartAbility() {
try{
try{
awaitthis.context.startAbility({
awaitthis.context.startAbility({
bundleName:"com.sample.MyApplication",
bundleName:"com.sample.MyApplication",
abilityName:"MainAbility",
abilityName:"EntryAbility",
uri:"pages/second"
uri:"pages/second"
})
})
console.log('start ability succeed')
console.log('start ability succeed')
...
@@ -293,9 +274,9 @@ async function reStartAbility() {
...
@@ -293,9 +274,9 @@ async function reStartAbility() {
Obtain the **want** parameter that contains the page information from the **onNewWant** callback of the ability.
Obtain the **want** parameter that contains the page information from the **onNewWant** callback of the ability.
@@ -111,4 +111,4 @@ For details about the project directory structure of the stage model, see [OpenH
...
@@ -111,4 +111,4 @@ For details about the project directory structure of the stage model, see [OpenH
For details about how to configure the application package structure of the stage model, see [Application Package Structure Configuration File](../quick-start/application-configuration-file-overview-stage.md).
For details about how to configure the application package structure of the stage model, see [Application Package Structure Configuration File](../quick-start/application-configuration-file-overview-stage.md).
@@ -24,8 +24,10 @@ The ability call process is as follows:
...
@@ -24,8 +24,10 @@ The ability call process is as follows:
- The callee ability, which holds a **Callee** object, uses **on()** of the **Callee** object to register a callback. This callback is invoked when the callee ability receives data from the caller ability.
- The callee ability, which holds a **Callee** object, uses **on()** of the **Callee** object to register a callback. This callback is invoked when the callee ability receives data from the caller ability.
> **NOTE**<br/>
> **NOTE**
>
> The launch type of the callee ability must be **singleton**.
> The launch type of the callee ability must be **singleton**.
>
> Currently, only system applications can use the ability call.
> Currently, only system applications can use the ability call.
## Available APIs
## Available APIs
...
@@ -34,7 +36,7 @@ The table below describes the ability call APIs. For details, see [Ability](../r
...
@@ -34,7 +36,7 @@ The table below describes the ability call APIs. For details, see [Ability](../r
**Table 2** Ability call APIs
**Table 2** Ability call APIs
|API|Description|
|API|Description|
|:------|:------|
|:------|:------|
|startAbilityByCall(want: Want): Promise\<Caller>|Starts an ability in the foreground (through the **want** configuration) or background (default) and obtains the **Caller** object for communication with the ability. For details, see [AbilityContext](../reference/apis/js-apis-ability-context.md#abilitycontextstartabilitybycall) or [ServiceExtensionContext](../reference/apis/js-apis-inner-application-serviceExtensionContext.md#serviceextensioncontextstartabilitybycall).|
|startAbilityByCall(want: Want): Promise\<Caller>|Starts an ability in the foreground (through the **want** configuration) or background (default) and obtains the **Caller** object for communication with the ability. For details, see [AbilityContext](../reference/apis/js-apis-ability-context.md#abilitycontextstartabilitybycall) or **ServiceExtensionContext**.|
|on(method: string, callback: CalleeCallBack): void|Callback invoked when the callee ability registers a method.|
|on(method: string, callback: CalleeCallBack): void|Callback invoked when the callee ability registers a method.|
|off(method: string): void|Callback invoked when the callee ability deregisters a method.|
|off(method: string): void|Callback invoked when the callee ability deregisters a method.|
|call(method: string, data: rpc.Sequenceable): Promise\<void>|Sends agreed sequenceable data to the callee ability.|
|call(method: string, data: rpc.Sequenceable): Promise\<void>|Sends agreed sequenceable data to the callee ability.|
...
@@ -210,22 +212,25 @@ function getRemoteDeviceId() {
...
@@ -210,22 +212,25 @@ function getRemoteDeviceId() {
@@ -42,8 +42,8 @@ OpenHarmony does not support creation of a Service Extension ability for third-p
...
@@ -42,8 +42,8 @@ OpenHarmony does not support creation of a Service Extension ability for third-p
2. Customize a class that inherits from `ServiceExtensionAbility` in the .ts file in the directory where the Service Extension ability is defined (`entry\src\main\ets\ServiceExtAbility\ServiceExtAbility.ts` by default) and override the lifecycle callbacks of the base class. The code sample is as follows:
2. Customize a class that inherits from `ServiceExtensionAbility` in the .ts file in the directory where the Service Extension ability is defined (`entry\src\main\ets\ServiceExtAbility\ServiceExtAbility.ts` by default) and override the lifecycle callbacks of the base class. The code sample is as follows:
```js
```js
import ServiceExtensionAbility from '@ohos.application.ServiceExtensionAbility'
import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
@@ -12,13 +12,13 @@ The **WantAgent** class encapsulates want information that specifies a particula
...
@@ -12,13 +12,13 @@ The **WantAgent** class encapsulates want information that specifies a particula
## How to Develop
## How to Develop
1. Import the **WantAgent** module.
1. Import the **WantAgent** module.
```
```ts
import wantAgent from '@ohos.wantAgent';
importwantAgentfrom'@ohos.app.ability.wantAgent';
```
```
2. Create a **WantAgentInfo** object that will be used for starting an ability. For details about the data types and parameters of **WantAgentInfo**, see [WantAgent](../reference/apis/js-apis-wantAgent.md#wantagentinfo).
2. Create a **WantAgentInfo** object that will be used for starting an ability. For details about the data types and parameters of **WantAgentInfo**, see [WantAgent](../reference/apis/js-apis-wantAgent.md#wantagentinfo).
```
```ts
privatewantAgentObj=null// Save the WantAgent object created. It will be used to complete the trigger operations.
privatewantAgentObj=null// Save the WantAgent object created. It will be used to complete the trigger operations.
// wantAgentInfo
// wantAgentInfo
...
@@ -27,7 +27,7 @@ The **WantAgent** class encapsulates want information that specifies a particula
...
@@ -27,7 +27,7 @@ The **WantAgent** class encapsulates want information that specifies a particula
{
{
deviceId:"",
deviceId:"",
bundleName:"com.example.test",
bundleName:"com.example.test",
abilityName: "com.example.test.MainAbility",
abilityName:"com.example.test.EntryAbility",
action:"",
action:"",
entities:[],
entities:[],
uri:"",
uri:"",
...
@@ -42,7 +42,7 @@ The **WantAgent** class encapsulates want information that specifies a particula
...
@@ -42,7 +42,7 @@ The **WantAgent** class encapsulates want information that specifies a particula
3. Create a **WantAgentInfo** object for publishing a common event.
3. Create a **WantAgentInfo** object for publishing a common event.
```
```ts
privatewantAgentObj=null// Save the WantAgent object created. It will be used to complete the trigger operations.
privatewantAgentObj=null// Save the WantAgent object created. It will be used to complete the trigger operations.
// wantAgentInfo
// wantAgentInfo
...
@@ -61,7 +61,7 @@ The **WantAgent** class encapsulates want information that specifies a particula
...
@@ -61,7 +61,7 @@ The **WantAgent** class encapsulates want information that specifies a particula
4. Create a **WantAgent** object and save the returned **wantAgentObj** for subsequent trigger operations.
4. Create a **WantAgent** object and save the returned **wantAgentObj** for subsequent trigger operations.
@@ -184,7 +184,7 @@ The widget configuration file is named **config.json**. Find the **config.json**
...
@@ -184,7 +184,7 @@ The widget configuration file is named **config.json**. Find the **config.json**
| type | Type of the JavaScript component. The value can be:<br>**normal**: indicates an application instance.<br>**form**: indicates a widget instance.| String| Yes (initial value: **normal**)|
| type | Type of the JavaScript component. The value can be:<br>**normal**: indicates an application instance.<br>**form**: indicates a widget instance.| String| Yes (initial value: **normal**)|
| mode | Development mode of the JavaScript component.| Object| Yes (initial value: left empty)|
| mode | Development mode of the JavaScript component.| Object| Yes (initial value: left empty)|
A configuration example is as follows:
Example configuration:
```json
```json
...
@@ -211,14 +211,14 @@ The widget configuration file is named **config.json**. Find the **config.json**
...
@@ -211,14 +211,14 @@ The widget configuration file is named **config.json**. Find the **config.json**
| 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 available in the **supportDimensions** array of the widget.| String| No|
| updateEnabled | Whether the widget can be updated periodically.<br>**true**: The widget can be updated at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** takes precedence over **scheduledUpdateTime**.<br>**false**: The widget cannot be updated periodically.| Boolean| No|
| updateEnabled | Whether the widget can be updated periodically.<br>**true**: The widget can be updated at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** takes precedence over **scheduledUpdateTime**.<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.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| String| Yes (initial value: **0:0**)|
| scheduledUpdateTime | Scheduled time to update the widget. The value is in 24-hour format and accurate to minute.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| 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 attribute does not take effect.<br>If the value is a positive integer *N*, the interval is calculated by multiplying *N* and 30 minutes.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| 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.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| 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 | Link to a specific page of the application. The value is a URI.| 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.| String| No|
| jsComponentName | Component name of the widget. The value is a string with a maximum of 127 bytes.| String| No|
| metaData | Metadata of the widget. This attribute contains the array of the **customizeData** attribute.| Object| Yes (initial value: left empty)|
| metaData | Metadata of the widget. This field contains the array of the **customizeData** field.| Object| Yes (initial value: left empty)|
| customizeData | Custom information about the widget.| Object array| Yes (initial value: left empty)|
| customizeData | Custom information about the widget.| Object array| Yes (initial value: left empty)|
A configuration example is as follows:
Example configuration:
```json
```json
...
@@ -236,7 +236,7 @@ The widget configuration file is named **config.json**. Find the **config.json**
...
@@ -236,7 +236,7 @@ The widget configuration file is named **config.json**. Find the **config.json**
// Persistently store widget information for subsequent use, such as instance acquisition and update.
// Persistently store widget data for subsequent use, such as instance acquisition and update.
// Implement this API based on project requirements.
// Implement this API based on project requirements.
storeFormInfo(formId,formName,tempFlag);
storeFormInfo(formId,formName,tempFlag);
...
@@ -325,7 +325,7 @@ async function deleteFormInfo(formId: string) {
...
@@ -325,7 +325,7 @@ async function deleteFormInfo(formId: string) {
For details about how to implement persistent data storage, see [Lightweight Data Store Development](../database/database-preference-guidelines.md).
For details about how to implement persistent data storage, see [Lightweight Data Store Development](../database/database-preference-guidelines.md).
The **Want** object passed by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary.
The **Want** object passed in by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary.
- Normal widget: a widget persistently used by the widget host
- Normal widget: a widget persistently used by the widget host
...
@@ -451,12 +451,12 @@ You can set router and message events for components on a widget. The router eve
...
@@ -451,12 +451,12 @@ You can set router and message events for components on a widget. The router eve
1. Set the **onclick** field in the HML file to **routerEvent** or **messageEvent**, depending on the **actions** settings in the JSON file.
1. Set the **onclick** field in the HML file to **routerEvent** or **messageEvent**, depending on the **actions** settings in the JSON file.
2. Set the router event.
2. Set the router event.
-**action**: **router**, which indicates a router event.
-**action**: **"router"**, which indicates a router event.
-**abilityName**: name of the ability to redirect to (PageAbility component in the FA model and UIAbility component in the stage model). For example, the default UIAbility name created by DevEco Studio in the FA model is com.example.entry.EntryAbility.
-**abilityName**: name of the ability to redirect to (PageAbility component in the FA model and UIAbility component in the stage model). For example, the default UIAbility name created by DevEco Studio in the FA model is com.example.entry.EntryAbility.
-**params**: custom parameters passed to the target ability. Set them as required. The value can be obtained from **parameters** in **want** used for starting the target ability. For example, in the lifecycle function **onCreate** of the EntryAbility in the FA model, **featureAbility.getWant()** can be used to obtain **want** and its **parameters** field.
-**params**: custom parameters passed to the target ability. Set them as required. The value can be obtained from **parameters** in **want** used for starting the target ability. For example, in the lifecycle function **onCreate** of the EntryAbility in the FA model, **featureAbility.getWant()** can be used to obtain **want** and its **parameters** field.
3. Set the message event.
3. Set the message event.
-**action**: **message**, which indicates a message event.
-**action**: **"message"**, which indicates a message event.
-**params**: custom parameters of the message event. Set them as required. The value can be obtained from **message** in the widget lifecycle function **onEvent**.
-**params**: custom parameters of the message event. Set them as required. The value can be obtained from **message** in the widget lifecycle function **onEvent**.
@@ -181,7 +181,7 @@ To create a widget in the stage model, implement the lifecycle callbacks of **Fo
...
@@ -181,7 +181,7 @@ To create a widget in the stage model, implement the lifecycle callbacks of **Fo
### Configuring the Widget Configuration File
### Configuring the Widget Configuration File
1. Configure ExtensionAbility information under **extensionAbilities** in the [module.json5 file](../quick-start/module-configuration-file.md). For a FormExtensionAbility, you must specify **metadata**. Specifically, set **name** to **ohos.extension.form** (fixed), and set **resource** to the index of the widget configuration information.
1. Configure ExtensionAbility information under **extensionAbilities** in the [module.json5 file](../quick-start/module-configuration-file.md). For a FormExtensionAbility, you must specify **metadata**. Specifically, set **name** to **ohos.extension.form** (fixed), and set **resource** to the index of the widget configuration information.
A configuration example is as follows:
Example configuration:
```json
```json
...
@@ -222,19 +222,19 @@ To create a widget in the stage model, implement the lifecycle callbacks of **Fo
...
@@ -222,19 +222,19 @@ To create a widget in the stage model, implement the lifecycle callbacks of **Fo
| 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 available in the **supportDimensions** array of the widget.| String| No|
| updateEnabled | Whether the widget can be updated periodically.<br>**true**: The widget can be updated at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** takes precedence over **scheduledUpdateTime**.<br>**false**: The widget cannot be updated periodically.| Boolean| No|
| updateEnabled | Whether the widget can be updated periodically.<br>**true**: The widget can be updated at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** takes precedence over **scheduledUpdateTime**.<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.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| String| Yes (initial value: **0:0**)|
| scheduledUpdateTime | Scheduled time to update the widget. The value is in 24-hour format and accurate to minute.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| 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 attribute does not take effect.<br>If the value is a positive integer *N*, the interval is calculated by multiplying *N* and 30 minutes.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| 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.<br>**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| 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 | Link to a specific page of the application. The value is a URI.| 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)|
| metaData | Metadata of the widget. This attribute contains the array of the **customizeData** attribute.| Object| Yes (initial value: left empty)|
| metaData | Metadata of the widget. This field contains the array of the **customizeData** field.| Object| Yes (initial value: left empty)|
For details about how to implement persistent data storage, see [Lightweight Data Store Development](../database/database-preference-guidelines.md).
For details about how to implement persistent data storage, see [Lightweight Data Store Development](../database/database-preference-guidelines.md).
The **Want** object passed by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary.
The **Want** object passed in by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary.
- Normal widget: a widget persistently used by the widget host
- Normal widget: a widget persistently used by the widget host
...
@@ -462,12 +462,12 @@ The key steps are as follows:
...
@@ -462,12 +462,12 @@ The key steps are as follows:
1. Set the **onclick** field in the HML file to **routerEvent** or **messageEvent**, depending on the **actions** settings in the JSON file.
1. Set the **onclick** field in the HML file to **routerEvent** or **messageEvent**, depending on the **actions** settings in the JSON file.
2. Set the router event.
2. Set the router event.
-**action**: **router**, which indicates a router event.
-**action**: **"router"**, which indicates a router event.
-**abilityName**: name of the ability to redirect to (PageAbility component in the FA model and UIAbility component in the stage model). For example, the default UIAbility name of the stage model created by DevEco Studio is EntryAbility.
-**abilityName**: name of the ability to redirect to (PageAbility component in the FA model and UIAbility component in the stage model). For example, the default UIAbility name of the stage model created by DevEco Studio is EntryAbility.
-**params**: custom parameters passed to the target ability. Set them as required. The value can be obtained from **parameters** in **want** used for starting the target ability. For example, in the lifecycle function **onCreate** of the main ability in the stage model, you can obtain **want** and its **parameters** field.
-**params**: custom parameters passed to the target ability. Set them as required. The value can be obtained from **parameters** in **want** used for starting the target ability. For example, in the lifecycle function **onCreate** of the main ability in the stage model, you can obtain **want** and its **parameters** field.
3. Set the message event.
3. Set the message event.
-**action**: **message**, which indicates a message event.
-**action**: **"message"**, which indicates a message event.
-**params**: custom parameters of the message event. Set them as required. The value can be obtained from **message** in the widget lifecycle function **onFormEvent()**.
-**params**: custom parameters of the message event. Set them as required. The value can be obtained from **message** in the widget lifecycle function **onFormEvent()**.
