# Launching a UIAbility in the Background Through the call Event
There may be cases you want to provide in a widget access to features available in your application when it is running in the foreground, for example, the play, pause, and stop buttons in a music application widget. This is where the **call** capability of the **postCardAction** API comes in handy. This capability, when used in a widget, can start the specified UIAbility of the widget provider in the background. It also allows the widget to call the specified method of the application and transfer data so that the application, while in the background, can behave accordingly in response to touching of the buttons on the widget.
There may be cases you want to provide in a widget access to features available in your application running in the foreground, for example, the play, pause, and stop buttons in a music application widget. This is where the **call** capability of the **postCardAction** API comes in handy. This capability, when used in a widget, can start the specified UIAbility of the widget provider in the background. It also allows the widget to call the specified method of the application and transfer data so that the application, while in the background, can behave accordingly in response to touching of the buttons on the widget.
Generally, buttons are used to trigger the **call** event. Below is an example.
Typically, the call event is triggered for touching of buttons. Below is an example.
- In this example, two buttons are laid out on the widget page. When one button is clicked, the **postCardAction** API is called to send a **call** event to the target UIAbility. Note that the **method** parameter in the API indicates the method to call in the target UIAbility. It is mandatory and of the string type.
- In this example, two buttons are laid out on the widget page. When one button is clicked, the **postCardAction** API is called to send a call event to the target UIAbility. Note that the **method** parameter in the API indicates the method to call in the target UIAbility. It is mandatory and of the string type.
```ts
@Entry
...
...
@@ -37,7 +37,7 @@ Generally, buttons are used to trigger the **call** event. Below is an example.
'abilityName':'EntryAbility',// Only the UIAbility of the current application is allowed.
'params':{
'method':'funB',// Set the name of the method to call in the EntryAbility.
'num':1// Set other parameters to be transferred.
'num':1// Set other parameters to be passed in.
}
});
})
...
...
@@ -48,34 +48,36 @@ Generally, buttons are used to trigger the **call** event. Below is an example.
}
```
- The UIAbility receives the **call** event and obtains the transferred parameters. It then executes the target method specified by the **method** parameter. Other data can be obtained in readString mode. Listen for the method required by the **call** event in the **onCreate** callback of the UIAbility.
- The UIAbility receives the call event and obtains the transferred parameters. It then executes the target method specified by the **method** parameter. Other data can be obtained in readString mode. Listen for the method required by the call event in the **onCreate** callback of the UIAbility.
```ts
importUIAbilityfrom'@ohos.app.ability.UIAbility';
functionFunACall(data){
// Obtain all parameters transferred in the call event.
// Obtain all parameters passed in the call event.
The ArkTS widget provides the **postCardAction()** API for interaction between the widget internal and the provider application. Currently, this API supports the router, message, and call events and can be called only in the widget.
The ArkTS widget provides the **postCardAction()** API for interaction between the widget internal and the widget provider. Currently, this API supports the router, message, and call events and can be called only in the widget.
@@ -8,26 +8,28 @@ The ArkTS widget provides the **postCardAction()** API for interaction between t
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| component | Object | Yes| Instance of the current custom component. Generally, **this** is transferred.|
| component | Object | Yes| Instance of the current custom component. Generally, **this** is passed in.|
| action | Object | Yes| Action description. For details, see the following table.|
**Description of the action parameter**
| Key | Value | Description|
| -------- | -------- | -------- |
| "action" | string | Action type.<br>- **"router"**: redirection to the specified UIAbility of the widget provider.<br>- **"message"**: custom message. If this type of action is triggered, the [onFormEvent()](../reference/apis/js-apis-app-form-formExtensionAbility.md#onformevent) lifecycle callback of the provider FormExtensionAbility is called.<br>- **"call"**: launch of the widget provider in the background. If this type of action is triggered, the specified UIAbility of the widget provider is started in the background, but not displayed in the foreground. This action type requires that the widget provider should have the [ohos.permission.KEEP_BACKGROUND_RUNNING](../security/permission-list.md#ohospermissionkeep_background_running) permission.|
| "action" | string | Action type.<br>- **"router"**: redirection to the specified UIAbility of the widget provider.<br>- **"message"**: custom message. If this type of action is triggered, the [onFormEvent()](../reference/apis/js-apis-app-form-formExtensionAbility.md#onformevent) lifecycle callback of the provider FormExtensionAbility is called.<br>- **"call"**: launch of the widget provider in the background. If this type of action is triggered, the specified UIAbility (whose [launch type](uiability-launch-type.md) must be singleton) of the widget provider is started in the background, but not displayed in the foreground. This action type requires that the widget provider should have the [ohos.permission.KEEP_BACKGROUND_RUNNING](../security/permission-list.md#ohospermissionkeep_background_running) permission.|
| "bundleName" | string | Name of the target bundle when **action** is **"router"** or **"call"**. This parameter is optional.|
| "moduleName" | string | Name of the target module when **action** is **"router"** or **"call"**. This parameter is optional.|
| "abilityName" | string | Name of the target UIAbility when **action** is **"router"** or **"call"**. This parameter is mandatory.|
| "params" | Object | Additional parameters carried in the current action. The value is a key-value pair in JSON format. For the **"call"** action type, the **method** parameter must be set and its value type must be string. This parameter is mandatory.|
| "params" | Object | Additional parameters carried in the current action. The value is a key-value pair in JSON format. For the **"call"** action type, the **method** parameter (mandatory) must be set and its value type must be string.|
Sample code of the **postCardAction()** API:
```typescript
Button('Jump')
Button('Redirect')
.width('40%')
.height('20%')
.onClick(()=>{
...
...
@@ -51,7 +53,7 @@ Button ('Start in Background')
'abilityName':'EntryAbility',
'params':{
'method':'fun',// Set the name of the method to call. It is mandatory.
'message':'testForcall'// Customize the message to send.
'message':'testForCall'// Customize the message to send.
@@ -5,7 +5,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o
## Updating Widget Content Through the router Event
- On the widget page, register the **onClick** event callback of the button and call the **postCardAction** API in the callback to trigger the **router** event to the FormExtensionAbility.
- On the widget page, register the **onClick** event callback of the button and call the **postCardAction** API in the callback to trigger the router event to the FormExtensionAbility.
```ts
letstorage=newLocalStorage();
...
...
@@ -16,7 +16,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o
build(){
Column(){
Button('Jump')
Button('Redirect')
.margin('20%')
.onClick(()=>{
console.info('postCardAction to EntryAbility');
...
...
@@ -45,7 +45,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o
importformInfofrom'@ohos.app.form.formInfo';
exportdefaultclassEntryAbilityextendsUIAbility{
// If the UIAbility is started for the first time, the onCreate lifecycle callback is triggered after the router event is received.
// If the UIAbility is started for the first time, onCreate is triggered after the router event is received.
@@ -88,7 +88,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o
## Updating Widget Content Through the call Event
- When using the **call** event of the **postCardAction** API, the value of **formId** must be updated in the **onAddForm** callback of the FormExtensionAbility.
- When using the call event of the **postCardAction** API, the value of **formId** must be updated in the **onAddForm** callback of the FormExtensionAbility.
@@ -142,13 +142,12 @@ On the widget page, the **postCardAction** API can be used to trigger a router o
}
```
- Listen for the method required by the **call** event in the **onCreate** callback of the UIAbility, and then call the [updateForm](../reference/apis/js-apis-app-form-formProvider.md#updateform) API in the corresponding method to update the widget.
- Listen for the method required by the call event in the **onCreate** callback of the UIAbility, and then call the [updateForm](../reference/apis/js-apis-app-form-formProvider.md#updateform) API in the corresponding method to update the widget.
