1# @ohos.app.ability.ActionExtensionAbility (ExtensionAbility for Custom Actions)
2
3The **ActionExtensionAbility** module, inherited from [UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md), provides a custom action service template. An ActionExtensionAbility is used to view and process the content in a host application. For example, you can add a bookmark, translate the selected text into another language, or edit an image on the current page. For details about the inheritance relationship of each ability, see [Inheritance Relationship](./js-apis-app-ability-ability.md#ability-inheritance-relationship).
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> The APIs of this module can be used only in the stage model.
10
11## When to Use
12
13The following uses text translation as an example. You must create a request initiator and then an ActionExtensionAbility. The request initiator sends the text to be translated to the ActionExtensionAbility. The ActionExtensionAbility translates the text and sends the translated text to the request initiator.
14
15## Modules to Import
16
17```ts
18import { ActionExtensionAbility } from '@kit.AbilityKit';
19```
20
21## Properties
22
23**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
24
25| Name| Type| Read-only| Mandatory| Description|
26| -------- | -------- | -------- | -------- | -------- |
27| context | [UIExtensionContext](js-apis-inner-application-uiExtensionContext.md) | No| No| Context.|
28
29## ActionExtensionAbility.onCreate
30
31onCreate(): void
32
33Called to initialize the service logic when an ActionExtensionAbility is being created.
34
35**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
36
37**Example**
38
39See [Creating an ActionExtensionAbility](#creating-an-actionextensionability).
40
41## ActionExtensionAbility.onSessionCreate
42
43onSessionCreate(want: Want, session: UIExtensionContentSession): void
44
45Called when a **UIExtensionContentSession** instance is created for this ActionExtensionAbility.
46
47**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
48
49**Parameters**
50
51| Name| Type| Mandatory| Description|
52| -------- | -------- | -------- | -------- |
53| want | [Want](js-apis-app-ability-want.md) | Yes| Want information related to the ActionExtensionAbility, including the ability name and bundle name.|
54| session | [UIExtensionContentSession](js-apis-app-ability-uiExtensionContentSession.md) | Yes| UI content information related to the ActionExtensionAbility.|
55
56**Example**
57
58See [Creating an ActionExtensionAbility](#creating-an-actionextensionability).
59
60## ActionExtensionAbility.onForeground
61
62onForeground(): void
63
64Called when this ActionExtensionAbility is switched from the background to the foreground.
65
66**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
67
68**Example**
69
70See [Creating an ActionExtensionAbility](#creating-an-actionextensionability).
71
72## ActionExtensionAbility.onBackground
73
74onBackground(): void
75
76Called when this ActionExtensionAbility is switched from the foreground to the background.
77
78**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
79
80**Example**
81
82See [Creating an ActionExtensionAbility](#creating-an-actionextensionability).
83
84## ActionExtensionAbility.onSessionDestroy
85
86onSessionDestroy(session: UIExtensionContentSession): void
87
88Called when a **UIExtensionContentSession** instance is destroyed for this ActionExtensionAbility.
89
90**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
91
92**Parameters**
93
94| Name| Type| Mandatory| Description|
95| -------- | -------- | -------- | -------- |
96| session | [UIExtensionContentSession](js-apis-app-ability-uiExtensionContentSession.md) | Yes| UI content information related to the ActionExtensionAbility.|
97
98**Example**
99
100See [Creating an ActionExtensionAbility](#creating-an-actionextensionability).
101
102## ActionExtensionAbility.onDestroy
103
104onDestroy(): void | Promise<void>
105
106Called when this ActionExtensionAbility is destroyed to clear resources.
107
108After the **onDestroy()** lifecycle callback is executed, the application may exit. Consequently, the asynchronous function (for example, asynchronously writing data to the database) in **onDestroy()** may fail to be executed. You can use the asynchronous lifecycle to ensure that the subsequent lifecycle continues only after the asynchronous function in **onDestroy()** finishes the execution.
109
110**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
111
112**Returns**
113
114| Type                                 | Description                           |
115| ------------------------------------- | ------------------------------- |
116| void \| Promise<void> | No return value or a Promise object that returns no result.|
117
118**Example**
119
120See [Creating an ActionExtensionAbility](#creating-an-actionextensionability).
121
122## Creating an ActionExtensionAbility
123
124To manually create an ActionExtensionAbility in the DevEco Studio project, perform the following steps:
125
1261. In the **ets** directory of a module in the project, right-click and choose **New > Directory** to create a directory named **ActionExtAbility**.
127
1282. In the **actionextability** directory, right-click and choose **New > ArkTS File** to create a file named **ActionExtAbility.ets**.
129
130    ```text
131    ├── ets
132    │ ├── actionextability
133    │ │   ├── ActionExtAbility.ets
134    └
135    ```
136
1373. In the **ActionExtAbility.ets** file, import the ActionExtensionAbility module. Customize a class that inherits from ActionExtensionAbility and implement the lifecycle callbacks.
138
139    ```ts
140    import { ActionExtensionAbility, Want, UIExtensionContentSession } from '@kit.AbilityKit';
141
142    const TAG: string = "[ActionExtAbility]";
143
144    export default class ActionExtAbility extends ActionExtensionAbility {
145      onCreate() {
146        console.info(TAG, `onCreate`);
147      }
148      onSessionCreate(want: Want, session: UIExtensionContentSession) {
149        console.info(TAG, `onSessionCreate, want: ${want.abilityName}`);
150        if (want.parameters) {
151          let obj: Record<string, UIExtensionContentSession | object> = {
152            'session': session,
153            'messages': want.parameters.shareMessages
154          };
155          let storage: LocalStorage = new LocalStorage(obj);
156          session.loadContent('pages/Index', storage);
157        }
158      }
159      onForeground() {
160        console.info(TAG, `ononForeground`);
161      }
162      onBackground() {
163        console.info(TAG, `onBackground`);
164      }
165      onSessionDestroy(session: UIExtensionContentSession) {
166        console.info(TAG, `onSessionDestroy`);
167      }
168      onDestroy() {
169        console.info(TAG, `onDestroy`);
170      }
171    }
172    ```
173
1744. Register the ActionExtensionAbility in the [**module.json5** file](../../quick-start/module-configuration-file.md) of the module in the project. Set **type** to **action** and **srcEntry** to the code path of the ActionExtensionAbility component.
175
176   ```json
177   {
178     "module": {
179       ...
180       "extensionAbilities": [
181         {
182           "name": "ActionExtAbility",
183           "icon": "$media:icon",
184           "description": "action",
185           "type": "action",
186           "exported": true,
187           "srcEntry": "./ets/actionextability/ActionExtAbility.ets"
188         }
189       ]
190     }
191   }
192   ```
193