未验证 提交 c4c41e0a 编写于 作者: O openharmony_ci 提交者: Gitee

!20503 【3.2-Release】翻译完成 19329+20165:优化ArkTS卡片

Merge pull request !20503 from ester.zhou/C2-20165
# Launching a UIAbility in the Background Through the call Event # 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 ```ts
@Entry @Entry
...@@ -37,7 +37,7 @@ Generally, buttons are used to trigger the **call** event. Below is an example. ...@@ -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. 'abilityName': 'EntryAbility', // Only the UIAbility of the current application is allowed.
'params': { 'params': {
'method': 'funB', // Set the name of the method to call in the EntryAbility. '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. ...@@ -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 ```ts
import UIAbility from '@ohos.app.ability.UIAbility'; import UIAbility from '@ohos.app.ability.UIAbility';
function FunACall(data) { function FunACall(data) {
// Obtain all parameters transferred in the call event. // Obtain all parameters passed in the call event.
console.log('FunACall param:' + JSON.stringify(data.readString())); console.log('FunACall param:' + JSON.stringify(data.readString()));
return null; return null;
} }
function FunBCall(data) { function FunBCall(data) {
console.log('FunACall param:' + JSON.stringify(data.readString())); console.log('FunBCall param:' + JSON.stringify(data.readString()));
return null; return null;
} }
export default class CameraAbility extends UIAbility { export default class CameraAbility extends UIAbility {
// If the UIAbility is started for the first time, the onCreate lifecycle callback is triggered after the call event is received. // If the UIAbility is started for the first time, onCreate is triggered afte the call event is received.
onCreate(want, launchParam) { onCreate(want, launchParam) {
try { try {
// Listen for the method required by the call event. // Listen for the method required by the call event.
this.callee.on('funA', FunACall); this.callee.on('funA', FunACall);
this.callee.on('funB', FunBCall); this.callee.on('funB', FunBCall);
} catch (error) { } catch (error) {
console.log('register failed with error. Cause: ' + JSON.stringify(error)); console.log('register failed with error. Cause: ' + JSON.stringify(error));
} }
} }
...
// Deregister the listener when the process exits. // Deregister the listener when the process exits.
onDestroy() { onDestroy() {
try { try {
......
# Widget Event Capability Overview # Widget Event Capability Overview
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.
![WidgetPostCardAction](figures/WidgetPostCardAction.png) ![WidgetPostCardAction](figures/WidgetPostCardAction.png)
...@@ -8,26 +8,28 @@ The ArkTS widget provides the **postCardAction()** API for interaction between t ...@@ -8,26 +8,28 @@ The ArkTS widget provides the **postCardAction()** API for interaction between t
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | 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.| | action | Object | Yes| Action description. For details, see the following table.|
**Description of the action parameter** **Description of the action parameter**
| Key | Value | Description| | 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.| | "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.| | "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.| | "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: Sample code of the **postCardAction()** API:
```typescript ```typescript
Button ('Jump') Button ('Redirect')
.width('40%') .width('40%')
.height('20%') .height('20%')
.onClick(() => { .onClick(() => {
...@@ -51,7 +53,7 @@ Button ('Start in Background') ...@@ -51,7 +53,7 @@ Button ('Start in Background')
'abilityName': 'EntryAbility', 'abilityName': 'EntryAbility',
'params': { 'params': {
'method': 'fun', // Set the name of the method to call. It is mandatory. '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 ...@@ -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 ## 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 ```ts
let storage = new LocalStorage(); let storage = new LocalStorage();
...@@ -16,7 +16,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o ...@@ -16,7 +16,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o
build() { build() {
Column() { Column() {
Button ('Jump') Button ('Redirect')
.margin('20%') .margin('20%')
.onClick(() => { .onClick(() => {
console.info('postCardAction to EntryAbility'); console.info('postCardAction to EntryAbility');
...@@ -45,7 +45,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o ...@@ -45,7 +45,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o
import formInfo from '@ohos.app.form.formInfo'; import formInfo from '@ohos.app.form.formInfo';
export default class EntryAbility extends UIAbility { export default class EntryAbility extends UIAbility {
// 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.
onCreate(want, launchParam) { onCreate(want, launchParam) {
console.info('Want:' + JSON.stringify(want)); console.info('Want:' + JSON.stringify(want));
if (want.parameters[formInfo.FormParam.IDENTITY_KEY] !== undefined) { if (want.parameters[formInfo.FormParam.IDENTITY_KEY] !== undefined) {
...@@ -63,7 +63,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o ...@@ -63,7 +63,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o
}) })
} }
} }
// If the UIAbility is running in the background, the onNewWant lifecycle callback is triggered after the router event is received. // If the UIAbility is running in the background, onNewWant is triggered after the router event is received.
onNewWant(want, launchParam) { onNewWant(want, launchParam) {
console.info('onNewWant Want:' + JSON.stringify(want)); console.info('onNewWant Want:' + JSON.stringify(want));
if (want.parameters[formInfo.FormParam.IDENTITY_KEY] !== undefined) { if (want.parameters[formInfo.FormParam.IDENTITY_KEY] !== undefined) {
...@@ -88,7 +88,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o ...@@ -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 ## 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.
```ts ```ts
import formBindingData from '@ohos.app.form.formBindingData'; import formBindingData from '@ohos.app.form.formBindingData';
...@@ -142,13 +142,12 @@ On the widget page, the **postCardAction** API can be used to trigger a router o ...@@ -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.
```ts ```ts
import UIAbility from '@ohos.app.ability.UIAbility'; import UIAbility from '@ohos.app.ability.UIAbility';
import formBindingData from '@ohos.app.form.formBindingData'; import formBindingData from '@ohos.app.form.formBindingData';
import formProvider from '@ohos.app.form.formProvider'; import formProvider from '@ohos.app.form.formProvider';
import formInfo from '@ohos.app.form.formInfo';
const MSG_SEND_METHOD: string = 'funA' const MSG_SEND_METHOD: string = 'funA'
...@@ -173,7 +172,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o ...@@ -173,7 +172,7 @@ On the widget page, the **postCardAction** API can be used to trigger a router o
return null; return null;
} }
export default class EntryAbility extends UIAbility { export default class EntryAbility extends UIAbility {
// If the UIAbility is started for the first time, the onCreate lifecycle callback is triggered after the call event is received. // If the UIAbility is started for the first time, onCreate is triggered after the call event is received.
onCreate(want, launchParam) { onCreate(want, launchParam) {
console.info('Want:' + JSON.stringify(want)); console.info('Want:' + JSON.stringify(want));
try { try {
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册