• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Widget Event Capability Overview
2
3The 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.
4
5![WidgetPostCardAction](figures/WidgetPostCardAction.png)
6
7**Definition**: postCardAction(component: Object, action: Object): void
8
9**Parameters**
10
11
12| Name| Type| Mandatory| Description|
13| -------- | -------- | -------- | -------- |
14| component | Object | Yes| Instance of the current custom component. Generally, **this** is passed in.|
15| action | Object | Yes| Action description. For details, see the following table.|
16
17**Description of the action parameter**
18
19
20| Key | Value | Description|
21| -------- | -------- | -------- |
22| "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.|
23| "bundleName" | string | Name of the target bundle when **action** is **"router"** or **"call"**. This parameter is optional.|
24| "moduleName" | string | Name of the target module when **action** is **"router"** or **"call"**. This parameter is optional.|
25| "abilityName" | string | Name of the target UIAbility when **action** is **"router"** or **"call"**. This parameter is mandatory.|
26| "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.|
27
28
29Sample code of the **postCardAction()** API:
30
31```typescript
32Button ('Redirect')
33  .width('40%')
34  .height('20%')
35  .onClick(() => {
36    postCardAction(this, {
37      'action': 'router',
38      'bundleName': 'com.example.myapplication',
39      'abilityName': 'EntryAbility',
40      'params': {
41        'message': 'testForRouter' // Customize the message to send.
42      }
43    });
44  })
45
46Button ('Start in Background')
47  .width('40%')
48  .height('20%')
49  .onClick(() => {
50    postCardAction(this, {
51      'action': 'call',
52      'bundleName': 'com.example.myapplication',
53      'abilityName': 'EntryAbility',
54      'params': {
55        'method': 'fun', // Set the name of the method to call. It is mandatory.
56        'message': 'testForCall' // Customize the message to send.
57      }
58    });
59  })
60```
61
62
63Read on to learn the typical widget development scenarios that can be implemented through widget events.
64