提交 5074e141 编写于 作者: W wusongqing

update docs against 5743+5151+6108+5322+6179+6090+6316+6342

Signed-off-by: Nwusongqing <wusongqing@huawei.com>
上级 cf8034d0
# Context # Context
The **Context** module provides context for abilities or applications. It allows access to application-specific resources, as well as permission requests and verification.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>
> The APIs of this module can be used only in the FA model. > The APIs of this module can be used only in the FA model.
## Modules to Import
```js
import featureAbility from '@ohos.ability.featureAbility'
```
## Usage ## Usage
The **Context** object is created in a **featureAbility** and returned through its **getContext()** API. Therefore, you must import the **@ohos.ability.featureAbility** package before using the Context module. An example is as follows: The **Context** object is created in a **featureAbility** and returned through its **getContext()** API. Therefore, you must import the **@ohos.ability.featureAbility** package before using the **Context** module. An example is as follows:
```js ```js
import featureAbility from '@ohos.ability.featureAbility' import featureAbility from '@ohos.ability.featureAbility'
...@@ -91,7 +88,7 @@ Verifies whether a specific PID and UID have the given permission. This API uses ...@@ -91,7 +88,7 @@ Verifies whether a specific PID and UID have the given permission. This API uses
| ---------- | --------------------------------------- | ---- | ------------------------------------- | | ---------- | --------------------------------------- | ---- | ------------------------------------- |
| permission | string | Yes | Name of the permission to verify. | | permission | string | Yes | Name of the permission to verify. |
| options | [PermissionOptions](#permissionoptions) | Yes | Permission options. | | options | [PermissionOptions](#permissionoptions) | Yes | Permission options. |
| callback | AsyncCallback\<number> | Yes | Callback used to return the permission verification result. The value **0** indicates that the PID and UID have the given permission, and the value **-1** indicates that the PID and UID do not have the given permission.| | callback | AsyncCallback\<number> | Yes | Callback used to return the permission verification result. The value **0** means that the PID and UID have the given permission, and the value **-1** means the opposite.|
**Example** **Example**
...@@ -119,7 +116,7 @@ Verifies whether the current PID and UID have the given permission. This API use ...@@ -119,7 +116,7 @@ Verifies whether the current PID and UID have the given permission. This API use
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| ---------- | ---------------------- | ---- | ------------------------------------- | | ---------- | ---------------------- | ---- | ------------------------------------- |
| permission | string | Yes | Name of the permission to verify. | | permission | string | Yes | Name of the permission to verify. |
| callback | AsyncCallback\<number> | Yes | Callback used to return the permission verification result. The value **0** indicates that the PID and UID have the given permission, and the value **-1** indicates that the PID and UID do not have the given permission.| | callback | AsyncCallback\<number> | Yes | Callback used to return the permission verification result. The value **0** means that the PID and UID have the given permission, and the value **-1** means the opposite.|
**Example** **Example**
...@@ -148,7 +145,7 @@ Verifies whether a specific PID and UID have the given permission. This API uses ...@@ -148,7 +145,7 @@ Verifies whether a specific PID and UID have the given permission. This API uses
| Type | Description | | Type | Description |
| ---------------- | ----------------------------------------------------------- | | ---------------- | ----------------------------------------------------------- |
| Promise\<number> | Promise used to return the permission verification result. The value **0** indicates that the PID and UID have the given permission, and the value **-1** indicates that the PID and UID do not have the given permission.| | Promise\<number> | Promise used to return the permission verification result. The value **0** means that the PID and UID have the given permission, and the value **-1** means the opposite.|
**Example** **Example**
...@@ -255,7 +252,7 @@ context.getApplicationInfo().then((data) => { ...@@ -255,7 +252,7 @@ context.getApplicationInfo().then((data) => {
getBundleName(callback: AsyncCallback\<string>): void getBundleName(callback: AsyncCallback\<string>): void
Obtains the bundle name of the current ability. This API uses an asynchronous callback to return the result. Obtains the bundle name of this ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -279,7 +276,7 @@ context.getBundleName() ...@@ -279,7 +276,7 @@ context.getBundleName()
getBundleName(): Promise\<string> getBundleName(): Promise\<string>
Obtains the bundle name of the current ability. This API uses a promise to return the result. Obtains the bundle name of this ability. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -300,6 +297,225 @@ context.getBundleName().then((data) => { ...@@ -300,6 +297,225 @@ context.getBundleName().then((data) => {
}); });
``` ```
## Context.getDisplayOrientation<sup>7+</sup>
getDisplayOrientation(callback: AsyncCallback\<bundle.DisplayOrientation>): void
Obtains the display orientation of this ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ----------------------------- |
| callback | AsyncCallback\<[bundle.DisplayOrientation](js-apis-bundle.md#displayorientation)> | Yes | Callback used to return the display orientation.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
var context = featureAbility.getContext();
context.getDisplayOrientation()
```
## Context.getDisplayOrientation<sup>7+</sup>
getDisplayOrientation(): Promise\<bundle.DisplayOrientation>;
Obtains the display orientation of this ability. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Return value**
| Type | Description |
| ---------------- | ------------------------- |
| Promise\<[bundle.DisplayOrientation](js-apis-bundle.md#displayorientation)> | Promise used to return the display orientation.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
var context = featureAbility.getContext();
context.getDisplayOrientation().then((data) => {
console.info("=======================>getDisplayOrientationCallback====================>");
console.info("====>data====>" + JSON.stringify(data));
});
```
## Context.setDisplayOrientation<sup>7+</sup>
setDisplayOrientation(orientation: bundle.DisplayOrientation, callback: AsyncCallback\<void>): void
Obtains the display orientation for this ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ----------------------------- |
| orientation | [bundle.DisplayOrientation](js-apis-bundle.md#displayorientation) | Yes | Display orientation to set.|
| callback | AsyncCallback\<[bundle.DisplayOrientation](js-apis-bundle.md#displayorientation)> | Yes | Callback used to return the display orientation.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
import bundle from '@ohos.bundle'
var context = featureAbility.getContext();
var orientation=bundle.DisplayOrientation.UNSPECIFIED
context.setDisplayOrientation(orientation, (err) => {
console.log('---------- setDisplayOrientation fail, err: -----------', err);
});
```
## Context.setDisplayOrientation<sup>7+</sup>
setDisplayOrientation(orientation: bundle.DisplayOrientation): Promise\<void>;
Obtains the display orientation for this ability. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Return value**
| Type | Description |
| ---------------- | ------------------------- |
| orientation | [bundle.DisplayOrientation](js-apis-bundle.md#displayorientation) | Yes | Display orientation to set.|
| Promise\<[bundle.DisplayOrientation](js-apis-bundle.md#displayorientation)> | Promise used to return the display orientation.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
import bundle from '@ohos.bundle'
var context = featureAbility.getContext();
var orientation=bundle.DisplayOrientation.UNSPECIFIED
context.setDisplayOrientation(orientation).then((data) => {
console.info("=======================>setDisplayOrientationCallback====================>");
console.info("====>data====>" + JSON.stringify(data));
});
```
## Context.setShowOnLockScreen<sup>7+</sup>
setShowOnLockScreen(show: boolean, callback: AsyncCallback\<void>): void
Sets whether to show this feature at the top of the lock screen each time the lock screen is displayed so that the feature remains activated. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ----------------------------- |
| show | boolean | Yes | Whether to show this feature at the top of the lock screen. The value **true** means to show this feature at the top of the lock screen, and **false** means the opposite.|
| callback | AsyncCallback\<void> | Yes | Callback used to return the result.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
var context = featureAbility.getContext();
var show=true
context.setShowOnLockScreen(show, (err) => {
console.log('---------- setShowOnLockScreen fail, err: -----------', err);
});
```
## Context.setShowOnLockScreen<sup>7+</sup>
setShowOnLockScreen(show: boolean): Promise\<void>;
Sets whether to show this feature at the top of the lock screen each time the lock screen is displayed so that the feature remains activated. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ----------------------------- |
| show | boolean | Yes | Whether to show this feature at the top of the lock screen. The value **true** means to show this feature at the top of the lock screen, and **false** means the opposite.|
**Return value**
| Type | Description |
| ---------------- | ------------------------- |
| Promise\<void>| Promise used to return the result.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
var context = featureAbility.getContext();
var show=true
context.setShowOnLockScreen(show).then((data) => {
console.info("=======================>setShowOnLockScreenCallback====================>");
console.info("====>data====>" + JSON.stringify(data));
});
```
## Context.setWakeUpScreen<sup>7+</sup>
setWakeUpScreen(wakeUp: boolean, callback: AsyncCallback\<void>): void
Sets whether to wake up the screen when this feature is restored. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ----------------------------- |
| wakeUp | boolean | Yes | Whether to wake up the screen. The value **true** means to wake up the screen, and **false** means the opposite.|
| callback | AsyncCallback\<void> | Yes | Callback used to return the result.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
var context = featureAbility.getContext();
var wakeUp=true
context.setWakeUpScreen(wakeUp, (err) => {
console.log('---------- setWakeUpScreen fail, err: -----------', err);
});
```
## Context.setWakeUpScreen<sup>7+</sup>
setWakeUpScreen(wakeUp: boolean): Promise\<void>;
Sets whether to wake up the screen when this feature is restored. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ----------------------------- |
| wakeUp | boolean | Yes | Whether to wake up the screen. The value **true** means to wake up the screen, and **false** means the opposite.|
**Return value**
| Type | Description |
| ---------------- | ------------------------- |
| Promise\<void>| Promise used to return the result.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
var context = featureAbility.getContext();
var wakeUp=true
context.setWakeUpScreen(wakeUp).then((data) => {
console.info("=======================>setWakeUpScreenCallback====================>");
console.info("====>data====>" + JSON.stringify(data));
});
```
## Context.getProcessInfo<sup>7+</sup> ## Context.getProcessInfo<sup>7+</sup>
...@@ -357,7 +573,7 @@ context.getProcessInfo().then((data) => { ...@@ -357,7 +573,7 @@ context.getProcessInfo().then((data) => {
getElementName(callback: AsyncCallback\<ElementName>): void getElementName(callback: AsyncCallback\<ElementName>): void
Obtains the **ohos.bundle.ElementName** object of the current ability. This API uses an asynchronous callback to return the result. Obtains the **ohos.bundle.ElementName** object of this ability. This API uses an asynchronous callback to return the result.
This API is available only to Page abilities. This API is available only to Page abilities.
...@@ -383,7 +599,7 @@ context.getElementName() ...@@ -383,7 +599,7 @@ context.getElementName()
getElementName(): Promise\<ElementName> getElementName(): Promise\<ElementName>
Obtains the **ohos.bundle.ElementName** object of the current ability. This API uses a promise to return the result. Obtains the **ohos.bundle.ElementName** object of this ability. This API uses a promise to return the result.
This API is available only to Page abilities. This API is available only to Page abilities.
...@@ -510,7 +726,7 @@ context.getCallingBundle().then((data) => { ...@@ -510,7 +726,7 @@ context.getCallingBundle().then((data) => {
getCacheDir(callback: AsyncCallback\<string>): void getCacheDir(callback: AsyncCallback\<string>): void
Obtains the cache directory of the application on the internal storage. This API uses an asynchronous callback to return the result. Obtains the cache directory of the application in the internal storage. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -538,7 +754,7 @@ context.getCacheDir((err, data) => { ...@@ -538,7 +754,7 @@ context.getCacheDir((err, data) => {
getCacheDir(): Promise\<string> getCacheDir(): Promise\<string>
Obtains the cache directory of the application on the internal storage. This API uses a promise to return the result. Obtains the cache directory of the application in the internal storage. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -563,7 +779,7 @@ context.getCacheDir().then((data) => { ...@@ -563,7 +779,7 @@ context.getCacheDir().then((data) => {
getFilesDir(callback: AsyncCallback\<string>): void getFilesDir(callback: AsyncCallback\<string>): void
Obtains the file directory of the application on the internal storage. This API uses an asynchronous callback to return the result. Obtains the file directory of the application in the internal storage. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -591,7 +807,7 @@ context.getFilesDir((err, data) => { ...@@ -591,7 +807,7 @@ context.getFilesDir((err, data) => {
getFilesDir(): Promise\<string> getFilesDir(): Promise\<string>
Obtains the file directory of the application on the internal storage. This API uses a promise to return the result. Obtains the file directory of the application in the internal storage. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -732,7 +948,7 @@ Obtains the **ModuleInfo** object of the application. This API uses an asynchron ...@@ -732,7 +948,7 @@ Obtains the **ModuleInfo** object of the application. This API uses an asynchron
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ------------------------- | | -------- | ---------------------- | ---- | ------------------------- |
| callback | AsyncCallback\<[HapModuleInfo](#hapmoduleinfo)> | Yes | Callback used to return the **ModuleInfo** object.| | callback | AsyncCallback\<[HapModuleInfo](js-apis-bundle-HapModuleInfo.md)> | Yes | Callback used to return the **ModuleInfo** object.|
**Example** **Example**
...@@ -760,7 +976,7 @@ Obtains the **ModuleInfo** object of the application. This API uses a promise to ...@@ -760,7 +976,7 @@ Obtains the **ModuleInfo** object of the application. This API uses a promise to
| Type | Description | | Type | Description |
| --------------- | ------------------------- | | --------------- | ------------------------- |
| Promise\<[HapModuleInfo](#hapmoduleinfo)> | Promise used to return the **ModuleInfo** object.| | Promise\<[HapModuleInfo](js-apis-bundle-HapModuleInfo.md)> | Promise used to return the **ModuleInfo** object.|
**Example** **Example**
...@@ -774,9 +990,9 @@ context.getHapModuleInfo().then((data) => { ...@@ -774,9 +990,9 @@ context.getHapModuleInfo().then((data) => {
## Context.getAppVersionInfo<sup>7+</sup> ## Context.getAppVersionInfo<sup>7+</sup>
getAppVersionInfo(callback: AsyncCallback\<HapModuleInfo>): void getAppVersionInfo(callback: AsyncCallback\<AppVersionInfo>): void
Obtains the version information of the application. This API uses an asynchronous callback to return the result. Obtains the version information of this application. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -804,7 +1020,7 @@ context.getAppVersionInfo((err, data) => { ...@@ -804,7 +1020,7 @@ context.getAppVersionInfo((err, data) => {
getAppVersionInfo(): Promise\<AppVersionInfo> getAppVersionInfo(): Promise\<AppVersionInfo>
Obtains the version information of the application. This API uses a promise to return the result. Obtains the version information of this application. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -828,7 +1044,7 @@ context.getAppVersionInfo().then((data) => { ...@@ -828,7 +1044,7 @@ context.getAppVersionInfo().then((data) => {
getAbilityInfo(callback: AsyncCallback\<AbilityInfo>): void getAbilityInfo(callback: AsyncCallback\<AbilityInfo>): void
Obtains information of the current ability. This API uses an asynchronous callback to return the result. Obtains information about this ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -856,7 +1072,7 @@ context.getAbilityInfo((err, data) => { ...@@ -856,7 +1072,7 @@ context.getAbilityInfo((err, data) => {
getAbilityInfo(): Promise\<AbilityInfo> getAbilityInfo(): Promise\<AbilityInfo>
Obtains information of the current ability. This API uses a promise to return the result. Obtains information about this ability. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -897,6 +1113,111 @@ import featureAbility from '@ohos.ability.featureAbility' ...@@ -897,6 +1113,111 @@ import featureAbility from '@ohos.ability.featureAbility'
var context = featureAbility.getContext().getApplicationContext(); var context = featureAbility.getContext().getApplicationContext();
``` ```
## Context.isUpdatingConfigurations<sup>7+</sup>
isUpdatingConfigurations(callback: AsyncCallback\<boolean>): void;
Checks whether the configuration of this ability is being changed. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ------------------------- |
| callback | AsyncCallback\<boolean> | Yes | Returns **true** if the configuration of the capability is being changed; returns **false** otherwise.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
var context = featureAbility.getContext();
context.isUpdatingConfigurations((err, data) => {
if (err) {
console.error('Operation failed. Cause: ' + JSON.stringify(err));
return;
}
console.info('Operation successful. Data:' + JSON.stringify(data));
});
```
## Context.isUpdatingConfigurations<sup>7+</sup>
isUpdatingConfigurations(): Promise\<boolean>;
Checks whether the configuration of this ability is being changed. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Return value**
| Type | Description |
| --------------- | ------------------------- |
|Promise\<boolean> | Returns **true** if the configuration of the capability is being changed; returns **false** otherwise.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
var context = featureAbility.getContext();
context.isUpdatingConfigurations().then((data) => {
console.info("====>data====>" + JSON.stringify(data));
});
```
## Context.printDrawnCompleted<sup>7+</sup>
printDrawnCompleted(callback: AsyncCallback\<void>): void;
Notifies the system of the time required to draw this page function. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ------------------------- |
| callback | AsyncCallback\<void> | Yes | Callback used to return the result.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
var context = featureAbility.getContext();
context.printDrawnCompleted((err, data) => {
if (err) {
console.error('Operation failed. Cause: ' + JSON.stringify(err));
return;
}
console.info('Operation successful. Data:' + JSON.stringify(data));
});
```
## Context.printDrawnCompleted<sup>7+</sup>
printDrawnCompleted(): Promise\<void>;
Notifies the system of the time required to draw this page function. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Return value**
| Type | Description |
| --------------- | ------------------------- |
|Promise\<void> | Promise used to return the result.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility'
var context = featureAbility.getContext();
context.printDrawnCompleted().then((data) => {
console.info("====>data====>" + JSON.stringify(data));
});
```
## PermissionOptions<sup>7+</sup> ## PermissionOptions<sup>7+</sup>
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -916,31 +1237,10 @@ var context = featureAbility.getContext().getApplicationContext(); ...@@ -916,31 +1237,10 @@ var context = featureAbility.getContext().getApplicationContext();
| permissions | Read-only | Array\<string> | Yes | Permissions requested. | | permissions | Read-only | Array\<string> | Yes | Permissions requested. |
| authResults | Read-only | Array\<number> | Yes | Permission request result. | | authResults | Read-only | Array\<number> | Yes | Permission request result. |
## HapModuleInfo<sup>7+</sup>
Describes the HAP module information.
| Name | Type| Readable| Writable| Description|
| ------ | ------ | ------ | ------ | ------ |
| name | string | Yes | No | Module name. |
| description | string | Yes | No | Module description. |
| descriptionId | number | Yes | No | Module description ID. |
| icon | string | Yes | No | Module icon. |
| label | string | Yes | No | Module label. |
| labelId | number | Yes | No | Module label ID. |
| iconId | number | Yes | No | Module icon ID. |
| backgroundImg | string | Yes | No | Module background image. |
| supportedModes | number | Yes | No | Running modes supported by the module. |
| reqCapabilities | Array\<string> | Yes | No | Capabilities required for module running.|
| deviceTypes | Array\<string> | Yes | No | Device types supported by the module.|
| abilityInfo | Array\<AbilityInfo> | Yes | No | Ability information. |
| moduleName | string | Yes | No | Module name. |
| mainAbilityName | string | Yes | No | Name of the main ability. |
| installationFree | boolean | Yes | No | Whether installation-free is supported. |
| mainElementName | string | Yes| No| Information about the main ability.|
## AppVersionInfo<sup>7+</sup> ## AppVersionInfo<sup>7+</sup>
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name | Type| Readable | Writable | Description| | Name | Type| Readable | Writable | Description|
| ------ | ------ | ------| ------ | ------ | | ------ | ------ | ------| ------ | ------ |
| appName | string | Yes | No | Module name. | | appName | string | Yes | No | Module name. |
......
# DataUriUtils Module # DataUriUtils
The **DataUriUtils** module provides APIs to handle utility classes for objects using the **DataAbilityHelper** schema. You can use the APIs to attach an ID to the end of a given URI and obtain, delete, or update the ID attached to the end of a given URI.
> **NOTE** > **NOTE**
> >
......
# AbilityContext # AbilityContext
The **AbilityContext** module, inherited from **Context**, implements the context for abilities.
This module provides APIs for accessing ability-specific resources. You can use the APIs to start and terminate an ability, obtain the caller interface, and request permissions from users by displaying a pop-up window.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Implements the ability context. This module is inherited from **Context**.
## Modules to Import
```js
import Ability from '@ohos.application.Ability'
```
## Usage ## Usage
Before using the **AbilityContext** module, you must define a child class that inherits from **Ability**. Before using the **AbilityContext** module, you must define a child class that inherits from **Ability**.
...@@ -25,7 +22,6 @@ class MainAbility extends Ability { ...@@ -25,7 +22,6 @@ class MainAbility extends Ability {
} }
``` ```
## Attributes ## Attributes
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -34,16 +30,18 @@ class MainAbility extends Ability { ...@@ -34,16 +30,18 @@ class MainAbility extends Ability {
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| abilityInfo | AbilityInfo | Yes| No| Ability information.| | abilityInfo | AbilityInfo | Yes| No| Ability information.|
| currentHapModuleInfo | HapModuleInfo | Yes| No| Information about the current HAP.| | currentHapModuleInfo | HapModuleInfo | Yes| No| Information about the current HAP.|
| config | [Configuration](js-apis-configuration.md) | Yes| No| Configuration information.|
## AbilityContext.startAbility ## AbilityContext.startAbility
startAbility(want: Want, callback: AsyncCallback&lt;void&gt;): void startAbility(want: Want, callback: AsyncCallback&lt;void&gt;): void
Starts an ability. This API uses a callback to return the result. Starts an ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -69,10 +67,12 @@ Starts an ability. This API uses a callback to return the result. ...@@ -69,10 +67,12 @@ Starts an ability. This API uses a callback to return the result.
startAbility(want: Want, options: StartOptions, callback: AsyncCallback&lt;void&gt;): void startAbility(want: Want, options: StartOptions, callback: AsyncCallback&lt;void&gt;): void
Starts an ability. This API uses a callback to return the result. Starts an ability with start options specified. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -106,6 +106,8 @@ Starts an ability. This API uses a promise to return the result. ...@@ -106,6 +106,8 @@ Starts an ability. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -143,7 +145,7 @@ Starts an ability. This API uses a promise to return the result. ...@@ -143,7 +145,7 @@ Starts an ability. This API uses a promise to return the result.
startAbilityForResult(want: Want, callback: AsyncCallback&lt;AbilityResult&gt;): void; startAbilityForResult(want: Want, callback: AsyncCallback&lt;AbilityResult&gt;): void;
Starts an ability. This API uses a callback to return the result when the ability is terminated. Starts an ability. This API uses an asynchronous callback to return the result when the ability is terminated.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -171,7 +173,7 @@ Starts an ability. This API uses a callback to return the result when the abilit ...@@ -171,7 +173,7 @@ Starts an ability. This API uses a callback to return the result when the abilit
startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback&lt;AbilityResult&gt;): void; startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback&lt;AbilityResult&gt;): void;
Starts an ability. This API uses a callback to return the result when the ability is terminated. Starts an ability with start options specified. This API uses an asynchronous callback to return the result when the ability is terminated.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -235,12 +237,134 @@ Starts an ability. This API uses a promise to return the result when the ability ...@@ -235,12 +237,134 @@ Starts an ability. This API uses a promise to return the result when the ability
}) })
``` ```
## AbilityContext.startAbilityForResultWithAccount
startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncCallback<AbilityResult>): void;
Starts an ability. This API uses an asynchronous callback to return the result when the account of the ability is destroyed.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| callback | AsyncCallback\<AbilityResult\> | Yes| Callback used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
this.context.startAbilityWithAccount(want, accountId, (err, data) => {
console.log('---------- startAbilityWithAccount fail, err: -----------', err);
console.log('---------- startAbilityWithAccount success, data: -----------', data);
});
```
## AbilityContext.startAbilityForResultWithAccount
startAbilityForResultWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\<void\>): void;
Starts an ability with start options specified. This API uses an asynchronous callback to return the result when the account of the ability is destroyed.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
var options = {
windowMode: 0,
};
this.context.startAbilityForResultWithAccount(want, accountId, options, (err) => {
console.log('---------- startAbilityForResultWithAccount fail, err: -----------', err);
});
```
## AbilityContext.startAbilityForResultWithAccount
startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\<AbilityResult\>;
Starts an ability with start options specified. This API uses a promise to return the result when the account of the ability is destroyed.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;AbilityResult&gt; | Promise used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
var options = {
windowMode: 0,
};
this.context.startAbilityForResultWithAccount(want, accountId, options)
.then((data) => {
console.log('---------- startAbilityForResultWithAccount success, data: -----------', data);
})
.catch((err) => {
console.log('---------- startAbilityForResultWithAccount fail, err: -----------', err);
})
```
## AbilityContext.terminateSelf ## AbilityContext.terminateSelf
terminateSelf(callback: AsyncCallback&lt;void&gt;): void; terminateSelf(callback: AsyncCallback&lt;void&gt;): void;
Terminates this ability. This API uses a callback to return the result. Terminates this ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -248,7 +372,7 @@ Terminates this ability. This API uses a callback to return the result. ...@@ -248,7 +372,7 @@ Terminates this ability. This API uses a callback to return the result.
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result indicating whether the API is successfully called.| | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
**Example** **Example**
...@@ -271,12 +395,12 @@ Terminates this ability. This API uses a promise to return the result. ...@@ -271,12 +395,12 @@ Terminates this ability. This API uses a promise to return the result.
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result indicating whether the API is successfully called.| | Promise&lt;void&gt; | Promise used to return the result.|
**Example** **Example**
```js ```js
this.context.terminateSelf(want).then((data) => { this.context.terminateSelf().then((data) => {
console.log('success:' + JSON.stringify(data)); console.log('success:' + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
console.log('failed:' + JSON.stringify(error)); console.log('failed:' + JSON.stringify(error));
...@@ -288,7 +412,7 @@ Terminates this ability. This API uses a promise to return the result. ...@@ -288,7 +412,7 @@ Terminates this ability. This API uses a promise to return the result.
terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback&lt;void&gt;): void; terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback&lt;void&gt;): void;
Terminates this ability. This API uses a callback to return the information to the caller of **startAbilityForResult**. Terminates this ability. This API uses an asynchronous callback to return the information to the caller of **startAbilityForResult**.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -346,6 +470,149 @@ Terminates this ability. This API uses a promise to return information to the ca ...@@ -346,6 +470,149 @@ Terminates this ability. This API uses a promise to return information to the ca
) )
``` ```
## AbilityContext.connectAbility
connectAbility(want: Want, options: ConnectOptions): number;
Uses the **AbilityInfo.AbilityType.SERVICE** template to connect this ability to another ability.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| options | [ConnectOptions](js-apis-featureAbility.md#connectoptions) | No| Remote object instance.|
**Return value**
| Type| Description|
| -------- | -------- |
| number | Result code of the ability connection.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var options = {
onConnect(elementName, remote) { console.log('----------- onConnect -----------') },
onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
onFailed(code) { console.log('----------- onFailed -----------') }
}
const result = this.context.connectAbility(want, options);
console.log('----------- connectAbilityResult: ------------', result);
```
## AbilityContext.connectAbilityWithAccount
connectAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number;
Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect this ability to another ability.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| options | [ConnectOptions](js-apis-featureAbility.md#connectoptions) | No| Parameters for the connection.|
**Return value**
| Type| Description|
| -------- | -------- |
| number | Result code of the ability connection.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
var options = {
onConnect(elementName, remote) { console.log('----------- onConnect -----------') },
onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
onFailed(code) { console.log('----------- onFailed -----------') }
}
const result = this.context.connectAbilityWithAccount(want, accountId, options);
console.log('----------- connectAbilityResult: ------------', result);
```
## AbilityContext.disconnectAbility
disconnectAbility(connection: number): Promise\<void>;
Disconnects a connection. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| connection | number | Yes| Result code of the ability connection.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise\<void> | Promise used to return the result.|
**Example**
```js
var connectionNumber = 0;
this.context.disconnectAbility(connectionNumber).then((data) => {
console.log('disconnectAbility success, data: ', data);
}).catch((err) => {
console.log('disconnectAbility fail, err: ', err);
});
```
## AbilityContext.disconnectAbility
disconnectAbility(connection: number, callback:AsyncCallback\<void>): void;
Disconnects a connection. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| connection | number | Yes| Result code of the ability connection.|
| callback | AsyncCallback\<void> | Yes| Callback used to return the result.|
**Example**
```js
var connectionNumber = 0;
this.context.disconnectAbility(connectionNumber, (err) => {
console.log('---------- disconnectAbility fail, err: -----------', err);
});
```
## AbilityContext.startAbilityByCall ## AbilityContext.startAbilityByCall
...@@ -388,12 +655,126 @@ Obtains the caller interface of the specified ability, and if the specified abil ...@@ -388,12 +655,126 @@ Obtains the caller interface of the specified ability, and if the specified abil
} }
``` ```
## AbilityContext.startAbilityWithAccount
startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void\>): void;
Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
this.context.startAbilityWithAccount(want, accountId, (err) => {
console.log('---------- startAbilityWithAccount fail, err: -----------', err);
});
```
## AbilityContext.startAbilityWithAccount
startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\<void\>): void;
Starts an ability with the account ID and start options specified. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
var options = {
windowMode: 0,
};
this.context.startAbilityWithAccount(want, accountId, options, (err) => {
console.log('---------- startAbilityWithAccount fail, err: -----------', err);
});
```
## AbilityContext.startAbilityWithAccount
startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\<void\>;
Starts an ability with the account ID specified. This API uses a promise to return the result.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
var options = {
windowMode: 0,
};
this.context.startAbilityWithAccount(want, accountId, options)
.then((data) => {
console.log('---------- startAbilityWithAccount success, data: -----------', data);
})
.catch((err) => {
console.log('---------- startAbilityWithAccount fail, err: -----------', err);
})
```
## AbilityContext.requestPermissionsFromUser ## AbilityContext.requestPermissionsFromUser
requestPermissionsFromUser(permissions: Array&lt;string&gt;, requestCallback: AsyncCallback&lt;PermissionRequestResult&gt;) : void; requestPermissionsFromUser(permissions: Array&lt;string&gt;, requestCallback: AsyncCallback&lt;PermissionRequestResult&gt;) : void;
Requests permissions from the user by displaying a pop-up window. This API uses a callback to return the result. Requests permissions from the user by displaying a pop-up window. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -402,7 +783,7 @@ Requests permissions from the user by displaying a pop-up window. This API uses ...@@ -402,7 +783,7 @@ Requests permissions from the user by displaying a pop-up window. This API uses
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| permissions | Array&lt;string&gt; | Yes| Permissions to request.| | permissions | Array&lt;string&gt; | Yes| Permissions to request.|
| callback | AsyncCallback&lt;[PermissionRequestResult](js-apis-permissionrequestresult.md)&gt; | Yes| Callback used to return the result indicating whether the API is successfully called.| | callback | AsyncCallback&lt;[PermissionRequestResult](js-apis-permissionrequestresult.md)&gt; | Yes| Callback used to return the permission request result.|
**Example** **Example**
...@@ -433,7 +814,7 @@ Requests permissions from the user by displaying a pop-up window. This API uses ...@@ -433,7 +814,7 @@ Requests permissions from the user by displaying a pop-up window. This API uses
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;[PermissionRequestResult](js-apis-permissionrequestresult.md)&gt; | Promise used to return the result indicating whether the API is successfully called.| | Promise&lt;[PermissionRequestResult](js-apis-permissionrequestresult.md)&gt; | Promise used to return the permission request result.|
**Example** **Example**
...@@ -452,7 +833,7 @@ Requests permissions from the user by displaying a pop-up window. This API uses ...@@ -452,7 +833,7 @@ Requests permissions from the user by displaying a pop-up window. This API uses
setMissionLabel(label: string, callback:AsyncCallback&lt;void&gt;): void; setMissionLabel(label: string, callback:AsyncCallback&lt;void&gt;): void;
Sets the label of the ability in the mission. This API uses an asynchronous callback to return the result. Sets a label for this ability in the mission. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -461,7 +842,7 @@ Sets the label of the ability in the mission. This API uses an asynchronous call ...@@ -461,7 +842,7 @@ Sets the label of the ability in the mission. This API uses an asynchronous call
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| label | string | Yes| Label of the ability to set.| | label | string | Yes| Label of the ability to set.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result indicating whether the API is successfully called.| | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
**Example** **Example**
...@@ -476,7 +857,7 @@ Sets the label of the ability in the mission. This API uses an asynchronous call ...@@ -476,7 +857,7 @@ Sets the label of the ability in the mission. This API uses an asynchronous call
setMissionLabel(label: string): Promise&lt;void&gt; setMissionLabel(label: string): Promise&lt;void&gt;
Sets the label of the ability in the mission. This API uses a promise to return the result. Sets a label for this ability in the mission. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -490,7 +871,7 @@ Sets the label of the ability in the mission. This API uses a promise to return ...@@ -490,7 +871,7 @@ Sets the label of the ability in the mission. This API uses a promise to return
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result indicating whether the API is successfully called.| | Promise&lt;void&gt; | Promise used to return the result.|
**Example** **Example**
...@@ -501,6 +882,117 @@ Sets the label of the ability in the mission. This API uses a promise to return ...@@ -501,6 +882,117 @@ Sets the label of the ability in the mission. This API uses a promise to return
console.log('failed:' + JSON.stringify(error)); console.log('failed:' + JSON.stringify(error));
}); });
``` ```
## AbilityContext.setMissionIcon
setMissionIcon(icon: image.PixelMap, callback:AsyncCallback\<void>): void;
Sets an icon for this ability in the mission. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| icon | image.PixelMap | Yes| Icon of the ability to set.|
| callback | AsyncCallback\<void> | Yes| Callback used to return the result.|
**Example**
```js
import image from '@ohos.multimedia.image'
var imagePixelMap;
var color = new ArrayBuffer(0);
var initializationOptions = {
size: {
height: 100,
width: 100
}
};
image.createPixelMap(color, initializationOptions)
.then((data) => {
imagePixelMap = data;
})
.catch((err) => {
console.log('--------- createPixelMap fail, err: ---------', err)
});
this.context.setMissionIcon(imagePixelMap, (err) => {
console.log('---------- setMissionIcon fail, err: -----------', err);
})
```
## AbilityContext.setMissionIcon
setMissionIcon(icon: image.PixelMap): Promise\<void>;
Sets an icon for this ability in the mission. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| icon | image.PixelMap | Yes| Icon of the ability to set.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
```js
import image from '@ohos.multimedia.image'
var imagePixelMap;
var color = new ArrayBuffer(0);
var initializationOptions = {
size: {
height: 100,
width: 100
}
};
image.createPixelMap(color, initializationOptions)
.then((data) => {
imagePixelMap = data;
})
.catch((err) => {
console.log('--------- createPixelMap fail, err: ---------', err)
});
this.context.setMissionIcon(imagePixelMap)
.then((data) => {
console.log('-------------- setMissionIcon success, data: -------------', data);
})
.catch((err) => {
console.log('-------------- setMissionIcon fail, err: -------------', err);
});
```
## AbilityContext.restoreWindowStage
restoreWindowStage(localStorage: LocalStorage) : void;
Restores the window stage data for this ability.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| localStorage | image.LocalStorage | Yes| Storage used to store the restored window stage.|
**Example**
```js
var storage = new LocalStorage();
this.context.restoreWindowStage(storage);
```
## AbilityContext.isTerminating ## AbilityContext.isTerminating
......
# ErrorCode # ErrorCode
The **ErrorCode** module defines the error codes that can be used when the ability is started.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Modules to Import
...@@ -12,7 +14,7 @@ import errorCode from '@ohos.ability.errorCode' ...@@ -12,7 +14,7 @@ import errorCode from '@ohos.ability.errorCode'
## ErrorCode ## ErrorCode
Defines the error code used when the ability is started. Defines the error codes used when the ability is started.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
......
# wantConstant # wantConstant
The **wantConstant** module provides the action, entity, and flags used in **Want** objects.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Modules to Import
...@@ -12,73 +14,75 @@ import wantConstant from '@ohos.ability.wantConstant' ...@@ -12,73 +14,75 @@ import wantConstant from '@ohos.ability.wantConstant'
## wantConstant.Action ## wantConstant.Action
**System capability**: SystemCapability.Ability.AbilityBase Enumerates the action constants of the **Want** object.
Lists the permissions. **System capability**: SystemCapability.Ability.AbilityBase
| Common Event Macro | Common Event Name | Subscriber Permission | | Name | Value | Description |
| ------------ | ------------------ | ---------------------- | | ------------ | ------------------ | ---------------------- |
| ACTION_HOME | ohos.want.action.home | None | | ACTION_HOME | ohos.want.action.home | Action of returning to the home page. |
| ACTION_DIAL | ohos.want.action.dial | None | | ACTION_DIAL | ohos.want.action.dial | Action of launching the numeric keypad. |
| ACTION_SEARCH | ohos.want.action.search | None | | ACTION_SEARCH | ohos.want.action.search | Action of launching the search function. |
| ACTION_WIRELESS_SETTINGS | ohos.settings.wireless | None | | ACTION_WIRELESS_SETTINGS | ohos.settings.wireless | Action of launching the UI that provides radio network settings, for example, Wi-Fi option. |
| ACTION_MANAGE_APPLICATIONS_SETTINGS | ohos.settings.manage.applications | None | | ACTION_MANAGE_APPLICATIONS_SETTINGS | ohos.settings.manage.applications | Action of launching the UI for managing installed applications. |
| ACTION_APPLICATION_DETAILS_SETTINGS | ohos.settings.application.details | None | | ACTION_APPLICATION_DETAILS_SETTINGS | ohos.settings.application.details | Action of launching the UI that displays the details of an application. |
| ACTION_SET_ALARM | ohos.want.action.setAlarm | None | | ACTION_SET_ALARM | ohos.want.action.setAlarm | Action of launching the UI for setting the alarm clock. |
| ACTION_SHOW_ALARMS | ohos.want.action.showAlarms | None | | ACTION_SHOW_ALARMS | ohos.want.action.showAlarms | Action of launching the UI that displays all clock alarms. |
| ACTION_SNOOZE_ALARM | ohos.want.action.snoozeAlarm | None | | ACTION_SNOOZE_ALARM | ohos.want.action.snoozeAlarm | Action of launching the UI for snoozing an alarm. |
| ACTION_DISMISS_ALARM | ohos.want.action.dismissAlarm | None | | ACTION_DISMISS_ALARM | ohos.want.action.dismissAlarm | Action of launching the UI for deleting an alarm. |
| ACTION_DISMISS_TIMER | ohos.want.action.dismissTimer | None | | ACTION_DISMISS_TIMER | ohos.want.action.dismissTimer | Action of launching the UI for dismissing a timer. |
| ACTION_SEND_SMS | ohos.want.action.sendSms | None | | ACTION_SEND_SMS | ohos.want.action.sendSms | Action of launching the UI for sending an SMS. |
| ACTION_CHOOSE | ohos.want.action.choose | None | | ACTION_CHOOSE | ohos.want.action.choose | Action of launching the UI for openning a contact or picture. |
| ACTION_IMAGE_CAPTURE<sup>8+</sup> | ohos.want.action.imageCapture | None | | ACTION_IMAGE_CAPTURE<sup>8+</sup> | ohos.want.action.imageCapture | Action of launching the UI for photographing. |
| ACTION_VIDEO_CAPTUR<sup>8+</sup> | ohos.want.action.videoCapture | None | | ACTION_VIDEO_CAPTURE<sup>8+</sup> | ohos.want.action.videoCapture | Action of launching the UI for shooting a video. |
| ACTION_SELECT | ohos.want.action.select | None | | ACTION_SELECT | ohos.want.action.select | Action of launching the UI for application selection. |
| ACTION_SEND_DATA | ohos.want.action.sendData | None | | ACTION_SEND_DATA | ohos.want.action.sendData | Action of launching the UI for sending a single data record. |
| ACTION_SEND_MULTIPLE_DATA | ohos.want.action.sendMultipleData | None | | ACTION_SEND_MULTIPLE_DATA | ohos.want.action.sendMultipleData | Action of launching the UI for sending multiple data records. |
| ACTION_SCAN_MEDIA_FILE | ohos.want.action.scanMediaFile | None | | ACTION_SCAN_MEDIA_FILE | ohos.want.action.scanMediaFile | Action of requesting a media scanner to scan a file and add the file to the media library. |
| ACTION_VIEW_DATA | ohos.want.action.viewData | None | | ACTION_VIEW_DATA | ohos.want.action.viewData | Action of viewing data. |
| ACTION_EDIT_DATA | ohos.want.action.editData | None | | ACTION_EDIT_DATA | ohos.want.action.editData | Action of editing data. |
| INTENT_PARAMS_INTENT | ability.want.params.INTENT | None | | INTENT_PARAMS_INTENT | ability.want.params.INTENT | Action of displaying selection options with an action selector. |
| INTENT_PARAMS_TITLE | ability.want.params.TITLE | None | | INTENT_PARAMS_TITLE | ability.want.params.TITLE | Title of the character sequence dialog box used with the action selector. |
| ACTION_FILE_SELECT<sup>7+</sup> | ohos.action.fileSelect | None | | ACTION_FILE_SELECT<sup>7+</sup> | ohos.action.fileSelect | Action of selecting a file. |
| PARAMS_STREAM<sup>7+</sup> | ability.params.stream | None | | PARAMS_STREAM<sup>7+</sup> | ability.params.stream | URI of the data stream associated with the target when the data is sent. |
| ACTION_APP_ACCOUNT_OAUTH <sup>8+</sup> | ohos.account.appAccount.action.oauth | None | | ACTION_APP_ACCOUNT_OAUTH <sup>8+</sup> | ohos.account.appAccount.action.oauth | Action of providing the OAuth service. |
| ACTION_MARKER_DOWNLOAD <sup>9+</sup> | ohos.want.action.marketDownload | Action of downloading an application from the application market.<br>**System API**: This is a system API and cannot be called by third-party applications. |
## wantConstant.Entity ## wantConstant.Entity
**System capability**: SystemCapability.Ability.AbilityBase Enumerates the entity constants of the **Want** object.
Lists the permissions. **System capability**: SystemCapability.Ability.AbilityBase
| Common Event Macro | Common Event Name | Subscriber Permission | | Name | Value | Description |
| ------------ | ------------------ | ---------------------- | | ------------ | ------------------ | ---------------------- |
| ENTITY_DEFAULT | entity.system.default | None | | ENTITY_DEFAULT | entity.system.default | Default entity. The default entity is used if no entity is specified. |
| ENTITY_HOME | entity.system.homel | None | | ENTITY_HOME | entity.system.home | Home screen entity. |
| ENTITY_VOICE | ENTITY_VOICE | None | | ENTITY_VOICE | entity.system.voice | Voice interaction entity. |
| ENTITY_BROWSABLE | entity.system.browsable | None | | ENTITY_BROWSABLE | entity.system.browsable | Browser type entity. |
| ENTITY_VIDEO | entity.system.video | None | | ENTITY_VIDEO | entity.system.video | Video type entity. |
| ACTION_APPLICATION_DETAILS_SETTINGS | ohos.settings.application.details | None |
## wantConstant.Flags
## flags Describes flags.
**System capability**: SystemCapability.Ability.AbilityBase **System capability**: SystemCapability.Ability.AbilityBase
| Name | Value | Description | | Name | Value | Description |
| ------------------------------------ | ---------- | ------------------------------------------------------------ | | ------------------------------------ | ---------- | ------------------------------------------------------------ |
| FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | Indicates the permission to read the URI. | | FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | Indicates the permission to read the URI. |
| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Indicates the permission to write the URI. | | FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Indicates the permission to write data to the URI. |
| FLAG_ABILITY_FORWARD_RESULT | 0x00000004 | Returns the result to the ability. | | FLAG_ABILITY_FORWARD_RESULT | 0x00000004 | Returns the result to the ability. |
| FLAG_ABILITY_CONTINUATION | 0x00000008 | Indicates whether the ability on the local device can be continued on a remote device. | | FLAG_ABILITY_CONTINUATION | 0x00000008 | Indicates whether the ability on the local device can be continued on a remote device. |
| FLAG_NOT_OHOS_COMPONENT | 0x00000010 | Indicates that a component does not belong to OHOS. | | FLAG_NOT_OHOS_COMPONENT | 0x00000010 | Indicates that a component does not belong to OHOS. |
| FLAG_ABILITY_FORM_ENABLED | 0x00000020 | Indicates that an ability is enabled. | | FLAG_ABILITY_FORM_ENABLED | 0x00000020 | Indicates that an ability is enabled. |
| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | Indicates the permission to make the URI persistent. | | FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | Indicates the permission to make the URI persistent.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | Indicates the permission to verify URIs by prefix matching. | | FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | Indicates the permission to verify URIs by prefix matching.<br>**System API**: This is a system API and cannot be called by third-party applications.|
| FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | Supports cross-device startup in a distributed scheduler. | | FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | Supports cross-device startup in a distributed scheduler. |
| FLAG_START_FOREGROUND_ABILITY | 0x00000200 | Indicates that the Service ability is started regardless of whether the host application has been started. | | FLAG_START_FOREGROUND_ABILITY | 0x00000200 | Indicates that the Service ability is started regardless of whether the host application has been started. |
| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that ability continuation is reversible. | | FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that ability continuation is reversible.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_INSTALL_ON_DEMAND | 0x00000800 | Indicates that the specific ability will be installed if it has not been installed. | | FLAG_INSTALL_ON_DEMAND | 0x00000800 | Indicates that the specific ability will be installed if it has not been installed. |
| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | Indicates that the specific ability will be installed in the background if it has not been installed. | | FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | Indicates that the specific ability will be installed in the background if it has not been installed. |
| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | Clears other operation missions. This flag can be set for the **Want** object in the **startAbility** API passed to [ohos.app.Context](js-apis-ability-context.md) and must be used together with **flag_ABILITY_NEW_MISSION**.| | FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | Clears other operation missions. This flag can be set for the **Want** object in the **startAbility** API passed to [ohos.app.Context](js-apis-ability-context.md) and must be used together with **flag_ABILITY_NEW_MISSION**.|
......
# AbilityDelegatorRegistry # AbilityDelegatorRegistry
The **AbilityDelegatorRegistry** module provides APIs for storing the global registers of the registered **AbilityDelegator** and **AbilityDelegatorArgs** objects. You can use the APIs to obtain the **AbilityDelegator** and **AbilityDelegatorArgs** objects of an application.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
...@@ -24,8 +26,6 @@ Enumerates the ability lifecycle states. ...@@ -24,8 +26,6 @@ Enumerates the ability lifecycle states.
| BACKGROUND | 3 | The ability is running in the background. | | BACKGROUND | 3 | The ability is running in the background. |
| DESTROY | 4 | The ability is destroyed.| | DESTROY | 4 | The ability is destroyed.|
## AbilityDelegatorRegistry.getAbilityDelegator ## AbilityDelegatorRegistry.getAbilityDelegator
getAbilityDelegator(): AbilityDelegator getAbilityDelegator(): AbilityDelegator
......
# AbilityRunningInfo # AbilityRunningInfo
The **AbilityRunningInfo** module implements ability running information and ability states.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Provides ability running information.
## Modules to Import
```js
import abilitymanager from '@ohos.application.abilityManager';
```
## Usage ## Usage
The ability running information is obtained by using the **getAbilityRunningInfos** API in **abilityManager**. The ability running information is obtained by using the **getAbilityRunningInfos** API in **abilityManager**.
...@@ -27,6 +21,8 @@ abilitymanager.getAbilityRunningInfos((err,data) => { ...@@ -27,6 +21,8 @@ abilitymanager.getAbilityRunningInfos((err,data) => {
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
| Name| Type| Readable| Writable| Description| | Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| ability | ElementName | Yes| No| Information that matches an ability. | | ability | ElementName | Yes| No| Information that matches an ability. |
...@@ -34,19 +30,4 @@ abilitymanager.getAbilityRunningInfos((err,data) => { ...@@ -34,19 +30,4 @@ abilitymanager.getAbilityRunningInfos((err,data) => {
| uid | number | Yes| No| User ID. | | uid | number | Yes| No| User ID. |
| processName | string | Yes| No| Process name. | | processName | string | Yes| No| Process name. |
| startTime | number | Yes| No| Ability start time. | | startTime | number | Yes| No| Ability start time. |
| abilityState | [abilityManager.AbilityState](#abilitymanagerabilitystate) | Yes| No| Ability state. | | abilityState | [abilityManager.AbilityState](js-apis-abilityManager.md#abilityState) | Yes| No| Ability state. |
## abilityManager.AbilityState
Enumerates the ability states.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| INITIAL | 0 | The ability is in the initial state.|
| FOREGROUND | 9 | The ability is in the foreground state. |
| BACKGROUND | 10 | The ability is in the background state. |
| FOREGROUNDING | 11 | The ability is in the foregrounding state. |
| BACKGROUNDING | 12 | The ability is in the backgrounding state. |
# AbilityStageContext # AbilityStageContext
The **AbilityStageContext** module, inherited from [Context](js-apis-application-context.md), implements the context of an ability stage.
This module provides APIs for accessing a specific ability stage. You can use the APIs to obtain the **ModuleInfo** object and environment configuration of an ability stage.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Implements the context of an ability stage. This module is inherited from [Context](js-apis-application-context.md).
## Modules to Import
```js
import AbilityStage from '@ohos.application.AbilityStage';
```
## Usage ## Usage
The ability stage context is obtained through an **AbilityStage** instance. The ability stage context is obtained through an **AbilityStage** instance.
......
# StartOptions # StartOptions
The **StartOptions** module implements ability startup options.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
**StartOptions** is the basic communication component of the system.
## Modules to Import ## Modules to Import
``` ```
...@@ -15,10 +15,9 @@ import StartOptions from '@ohos.application.StartOptions'; ...@@ -15,10 +15,9 @@ import StartOptions from '@ohos.application.StartOptions';
## Attributes ## Attributes
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name| Readable| Writable| Type| Mandatory| Description| | Name| Readable| Writable| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- | -------- |
| [windowMode](js-apis-window.md#windowmode) | Yes| No| number | No| Window mode.| | windowMode | Yes| No| number | No| Window mode.|
| displayId | Yes| No| number | No| Display ID.| | displayId | Yes| No| number | No| Display ID.|
# Want # Want
The **Want** module provides the basic communication component of the system.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
**Want** is the basic communication component of the system.
## Modules to Import ## Modules to Import
``` ```
...@@ -20,11 +20,26 @@ import Want from '@ohos.application.Want'; ...@@ -20,11 +20,26 @@ import Want from '@ohos.application.Want';
| ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ | | ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ |
| deviceId | Read only | string | No | ID of the device running the ability. | | deviceId | Read only | string | No | ID of the device running the ability. |
| bundleName | Read only | string | No | Bundle name of the ability. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability.| | bundleName | Read only | string | No | Bundle name of the ability. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability.|
| abilityName | Read only | string | No | Name of the ability. If both **package** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability.| | abilityName | Read only | string | No | Name of the ability. If both **package** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability. The value of **abilityName** must be unique in an application.|
| uri | Read only | string | No | URI information to match. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.| | uri | Read only | string | No | URI information to match. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.|
| type | Read only | string | No | MIME type, for example, **text/plain** or **image/***. | | type | Read only | string | No | MIME type, for example, **text/plain** or **image/***. |
| flags | Read only | number | No | How the **Want** object will be handled. By default, numbers are passed in. For details, see [flags](js-apis-featureAbility.md#flags).| | flags | Read only | number | No | How the **Want** object will be handled. By default, numbers are passed in. For details, see [flags](js-apis-featureAbility.md#flags).|
| action | Read only | string | No | Action option. | | action | Read only | string | No | Action option. |
| parameters | Read only | {[key: string]: any} | No | List of parameters in the **Want** object. | | parameters | Read only | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:<br>**ohos.aafwk.callerPid**: PID of the caller.<br>**ohos.aafwk.param.callerToken**: token of the caller.<br>**ohos.aafwk.param.callerUid**: UID of the caller. The **userId** parameter in the [Bundle](js-apis-Bundle.js) module can be used to obtain application and bundle information. |
| entities | Read only | Array\<string> | No | List of entities. | | entities | Read only | Array\<string> | No | List of entities. |
| moduleName<sup>9+</sup> | Read only | string | No | Module to which the ability belongs. Different abilities among HAP files in an application may use the same name. If the abilities cannot be distinguished by the combination of **bundleName** and **abilityName**, you can set **moduleName** for better distinguishing.| | | moduleName<sup>9+</sup> | Read only | string | No | Module to which the ability belongs.|
**Example**
``` js
var want = {
"deviceId": "", // An empty deviceId indicates the local device.
"bundleName": "com.extreme.test",
"abilityName": "MainAbility",
"moduleName": "entry" // moduleName is optional.
};
this.context.startAbility(want, (error) => {
// Start an ability explicitly. The bundleName, abilityName, and moduleName parameters uniquely identify an ability.
console.log("error.code = " + error.code)
})
```
# Ability # Ability
The **Ability** module manages the ability lifecycle and context, such as creating and destroying an ability, and dumping client information.
This module provides the following common ability-related functions:
- [Caller](#caller): implements sending of sequenceable data to the target ability when an ability (caller) invokes the target ability (callee).
- [Callee](#callee): implements callbacks for registration and deregistration of caller notifications.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Manages the ability lifecycle and context.
## Modules to Import ## Modules to Import
``` ```
...@@ -17,14 +22,12 @@ import Ability from '@ohos.application.Ability'; ...@@ -17,14 +22,12 @@ import Ability from '@ohos.application.Ability';
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
| Name| Type| Readable| Writable| Description| | Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| context | [AbilityContext](js-apis-ability-context.md) | Yes| No| Context of an ability.| | context | [AbilityContext](js-apis-ability-context.md) | Yes| No| Context of an ability.|
| launchWant | [Want](js-apis-application-Want.md) | Yes| No| Parameters for starting the ability.| | launchWant | [Want](js-apis-application-Want.md) | Yes| No| Parameters for starting the ability.|
| lastRequestWant | [Want](js-apis-application-Want.md) | Yes| No| Parameters used when the ability was started last time.| | lastRequestWant | [Want](js-apis-application-Want.md) | Yes| No| Parameters used when the ability was started last time.|
| callee | [Callee](#callee) | Yes| No| Object that invokes the stub service.| | callee | [Callee](#callee) | Yes| No| Object that invokes the stub service.|
## Ability.onCreate ## Ability.onCreate
...@@ -36,13 +39,13 @@ Called to initialize the service logic when an ability is created. ...@@ -36,13 +39,13 @@ Called to initialize the service logic when an ability is created.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information related to this ability, including the ability name and bundle name.| | want | [Want](js-apis-application-Want.md) | Yes| Information related to this ability, including the ability name and bundle name.|
| param | AbilityConstant.LaunchParam | Yes| Parameters for starting the ability, and the reason for the last abnormal exit.| | param | AbilityConstant.LaunchParam | Yes| Parameters for starting the ability, and the reason for the last abnormal exit.|
**Example**
**Example**
```js ```js
class myAbility extends Ability { class myAbility extends Ability {
onCreate(want, param) { onCreate(want, param) {
...@@ -62,12 +65,12 @@ Called when a **WindowStage** is created for this ability. ...@@ -62,12 +65,12 @@ Called when a **WindowStage** is created for this ability.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| windowStage | window.WindowStage | Yes| **WindowStage** information.| | windowStage | window.WindowStage | Yes| **WindowStage** information.|
**Example**
**Example**
```js ```js
class myAbility extends Ability { class myAbility extends Ability {
onWindowStageCreate(windowStage) { onWindowStageCreate(windowStage) {
...@@ -85,8 +88,8 @@ Called when the **WindowStage** is destroyed for this ability. ...@@ -85,8 +88,8 @@ Called when the **WindowStage** is destroyed for this ability.
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
**Example** **Example**
```js ```js
class myAbility extends Ability { class myAbility extends Ability {
onWindowStageDestroy() { onWindowStageDestroy() {
...@@ -106,12 +109,12 @@ Called when the **WindowStage** is restored during the migration of this ability ...@@ -106,12 +109,12 @@ Called when the **WindowStage** is restored during the migration of this ability
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| windowStage | window.WindowStage | Yes| **WindowStage** information.| | windowStage | window.WindowStage | Yes| **WindowStage** information.|
**Example**
**Example**
```js ```js
class myAbility extends Ability { class myAbility extends Ability {
onWindowStageRestore(windowStage) { onWindowStageRestore(windowStage) {
...@@ -129,8 +132,8 @@ Called when this ability is destroyed to clear resources. ...@@ -129,8 +132,8 @@ Called when this ability is destroyed to clear resources.
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
**Example** **Example**
```js ```js
class myAbility extends Ability { class myAbility extends Ability {
onDestroy() { onDestroy() {
...@@ -148,8 +151,8 @@ Called when this ability is switched from the background to the foreground. ...@@ -148,8 +151,8 @@ Called when this ability is switched from the background to the foreground.
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
**Example** **Example**
```js ```js
class myAbility extends Ability { class myAbility extends Ability {
onForeground() { onForeground() {
...@@ -167,8 +170,8 @@ Called when this ability is switched from the foreground to the background. ...@@ -167,8 +170,8 @@ Called when this ability is switched from the foreground to the background.
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
**Example** **Example**
```js ```js
class myAbility extends Ability { class myAbility extends Ability {
onBackground() { onBackground() {
...@@ -188,18 +191,18 @@ Called to save data during the ability migration preparation process. ...@@ -188,18 +191,18 @@ Called to save data during the ability migration preparation process.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| wantParam | {[key:&nbsp;string]:&nbsp;any} | Yes| **want** parameter.| | wantParam | {[key:&nbsp;string]:&nbsp;any} | Yes| **want** parameter.|
**Return value** **Return value**
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| AbilityConstant.OnContinueResult | Continuation result.| | AbilityConstant.OnContinueResult | Continuation result.|
**Example**
**Example**
```js ```js
import AbilityConstant from "@ohos.application.AbilityConstant" import AbilityConstant from "@ohos.application.AbilityConstant"
class myAbility extends Ability { class myAbility extends Ability {
...@@ -222,13 +225,13 @@ Called when the ability startup mode is set to singleton. ...@@ -222,13 +225,13 @@ Called when the ability startup mode is set to singleton.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Want parameters, such as the ability name and bundle name.| | want | [Want](js-apis-application-Want.md) | Yes| Want parameters, such as the ability name and bundle name.|
| launchParams | AbilityConstant.LaunchParam | Yes| Reason for the ability startup and the last abnormal exit.| | launchParams | AbilityConstant.LaunchParam | Yes| Reason for the ability startup and the last abnormal exit.|
**Example**
**Example**
```js ```js
class myAbility extends Ability { class myAbility extends Ability {
onNewWant(want, launchParams) { onNewWant(want, launchParams) {
...@@ -251,12 +254,12 @@ Called when the configuration of the environment where the ability is running is ...@@ -251,12 +254,12 @@ Called when the configuration of the environment where the ability is running is
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| config | [Configuration](js-apis-configuration.md) | Yes| New configuration.| | config | [Configuration](js-apis-configuration.md) | Yes| New configuration.|
**Example**
**Example**
```js ```js
class myAbility extends Ability { class myAbility extends Ability {
onConfigurationUpdated(config) { onConfigurationUpdated(config) {
...@@ -269,18 +272,18 @@ Called when the configuration of the environment where the ability is running is ...@@ -269,18 +272,18 @@ Called when the configuration of the environment where the ability is running is
dump(params: Array\<string>): Array\<string>; dump(params: Array\<string>): Array\<string>;
Called when the client information is dumped. Dumps client information.
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| params | Array\<string> | Yes| Parameters in the form of a command.| | params | Array\<string> | Yes| Parameters in the form of a command.|
**Example**
**Example**
```js ```js
class myAbility extends Ability { class myAbility extends Ability {
dump(params) { dump(params) {
...@@ -307,19 +310,19 @@ Sends sequenceable data to the target ability. ...@@ -307,19 +310,19 @@ Sends sequenceable data to the target ability.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.| | method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.|
| data | rpc.Sequenceable | Yes| Sequenceable data. You need to customize the data.| | data | rpc.Sequenceable | Yes| Sequenceable data. You need to customize the data.|
**Return value** **Return value**
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;void&gt; | Promise used to return a response.| | Promise&lt;void&gt; | Promise used to return a response.|
**Example**
**Example**
```js ```js
import Ability from '@ohos.application.Ability'; import Ability from '@ohos.application.Ability';
class MyMessageAble{ // Custom sequenceable data structure class MyMessageAble{ // Custom sequenceable data structure
...@@ -380,19 +383,19 @@ Sends sequenceable data to the target ability and obtains the sequenceable data ...@@ -380,19 +383,19 @@ Sends sequenceable data to the target ability and obtains the sequenceable data
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.| | method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.|
| data | rpc.Sequenceable | Yes| Sequenceable data. You need to customize the data.| | data | rpc.Sequenceable | Yes| Sequenceable data. You need to customize the data.|
**Return value** **Return value**
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;rpc.MessageParcel&gt; | Promise used to return the sequenceable data from the target ability.| | Promise&lt;rpc.MessageParcel&gt; | Promise used to return the sequenceable data from the target ability.|
**Example**
**Example**
```js ```js
import Ability from '@ohos.application.Ability'; import Ability from '@ohos.application.Ability';
class MyMessageAble{ class MyMessageAble{
...@@ -452,8 +455,8 @@ Releases the caller interface of the target ability. ...@@ -452,8 +455,8 @@ Releases the caller interface of the target ability.
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
**Example** **Example**
```js ```js
import Ability from '@ohos.application.Ability'; import Ability from '@ohos.application.Ability';
var caller; var caller;
...@@ -489,12 +492,12 @@ Registers a callback that is invoked when the stub on the target ability is disc ...@@ -489,12 +492,12 @@ Registers a callback that is invoked when the stub on the target ability is disc
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| callback | OnReleaseCallBack | Yes| Callback used for the **onRelease** API.| | callback | OnReleaseCallBack | Yes| Callback used for the **onRelease** API.|
**Example**
**Example**
```js ```js
import Ability from '@ohos.application.Ability'; import Ability from '@ohos.application.Ability';
var caller; var caller;
...@@ -529,7 +532,7 @@ Implements callbacks for caller notification registration and deregistration. ...@@ -529,7 +532,7 @@ Implements callbacks for caller notification registration and deregistration.
## Callee.on ## Callee.on
on(method: string, callback: CaleeCallBack): void; on(method: string, callback: CalleeCallBack): void;
Registers a caller notification callback, which is invoked when the target ability registers a function. Registers a caller notification callback, which is invoked when the target ability registers a function.
...@@ -537,13 +540,12 @@ Registers a caller notification callback, which is invoked when the target abili ...@@ -537,13 +540,12 @@ Registers a caller notification callback, which is invoked when the target abili
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| method | string | Yes| Notification message string negotiated between the two abilities.| | method | string | Yes| Notification message string negotiated between the two abilities.|
| callback | CaleeCallBack | Yes| JS notification synchronization callback of the **rpc.MessageParcel** type. The callback must return at least one empty **rpc.Sequenceable** object. Otherwise, the function execution fails.| | callback | CalleeCallBack | Yes| JS notification synchronization callback of the **rpc.MessageParcel** type. The callback must return at least one empty **rpc.Sequenceable** object. Otherwise, the function execution fails.|
**Example** **Example**
```js ```js
import Ability from '@ohos.application.Ability'; import Ability from '@ohos.application.Ability';
class MyMessageAble{ class MyMessageAble{
...@@ -593,9 +595,9 @@ Deregisters a caller notification callback, which is invoked when the target abi ...@@ -593,9 +595,9 @@ Deregisters a caller notification callback, which is invoked when the target abi
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| method | string | Yes| Registered notification message string.| | method | string | Yes| Registered notification message string.|
**Example** **Example**
...@@ -616,17 +618,17 @@ Deregisters a caller notification callback, which is invoked when the target abi ...@@ -616,17 +618,17 @@ Deregisters a caller notification callback, which is invoked when the target abi
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
| Name| Type| Readable| Writable| Description| | Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| (msg: string) | function | Yes| No| Prototype of the listener function interface registered by the caller.| | (msg: string) | function | Yes| No| Prototype of the listener function registered by the caller.|
## CaleeCallBack ## CalleeCallBack
(indata: rpc.MessageParcel): rpc.Sequenceable; (indata: rpc.MessageParcel): rpc.Sequenceable;
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
| Name| Type| Readable| Writable| Description| | Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| (indata: rpc.MessageParcel) | rpc.Sequenceable | Yes| No| Prototype of the message listener function interface registered by the callee.| | (indata: rpc.MessageParcel) | rpc.Sequenceable | Yes| No| Prototype of the listener function registered by the callee.|
# AbilityConstant # AbilityConstant
The **AbilityConstant** module provides ability launch parameters.
The parameters include the initial launch reasons, reasons for the last exit, and ability continuation results.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Provides parameters related to ability launch.
## Modules to Import ## Modules to Import
```js ```js
...@@ -17,10 +19,10 @@ import AbilityConstant from '@ohos.application.AbilityConstant'; ...@@ -17,10 +19,10 @@ import AbilityConstant from '@ohos.application.AbilityConstant';
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name| Type| Readable| Writable| Description| | Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| launchReason | LaunchReason| Yes| Yes| Ability launch reason.| | launchReason | LaunchReason| Yes| Yes| Ability launch reason.|
| lastExitReason | LastExitReason | Yes| Yes| Reason for the last exit.| | lastExitReason | LastExitReason | Yes| Yes| Reason for the last exit.|
## AbilityConstant.LaunchReason ## AbilityConstant.LaunchReason
......
# AbilityDelegator # AbilityDelegator
The **AbilityDelegator** module provides APIs for managing **AbilityMonitor** instances that are used to monitor the lifecycle state changes of a specified ability. You can use the APIs to add and remove **AbilityMonitor** instances, wait for an ability to reach the **OnCreate** lifecycle state, set the waiting time, obtain the lifecycle state of an ability, obtain the top ability of the current application, and start an ability.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Usage
The ability delegator can be obtained by calling **getAbilityDelegator** in **AbilityDelegatorRegistry**.
```js ```js
import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
var abilityDelegator;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
``` ```
## AbilityDelegator ## AbilityDelegator
...@@ -174,7 +182,7 @@ abilityDelegator.removeAbilityMonitor(monitor).then(() => { ...@@ -174,7 +182,7 @@ abilityDelegator.removeAbilityMonitor(monitor).then(() => {
waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<Ability>): void waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<Ability>): void
Waits for the ability that matches the **AbilityMonitor** instance to reach the **OnCreate** lifecycle and returns the **Ability** instance. This API uses an asynchronous callback to return the result. Waits for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **OnCreate** lifecycle state and returns the **Ability** instance. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -211,7 +219,7 @@ abilityDelegator.waitAbilityMonitor(monitor, (err : any, data : any) => { ...@@ -211,7 +219,7 @@ abilityDelegator.waitAbilityMonitor(monitor, (err : any, data : any) => {
waitAbilityMonitor(monitor: AbilityMonitor, timeout: number, callback: AsyncCallback\<Ability>): void waitAbilityMonitor(monitor: AbilityMonitor, timeout: number, callback: AsyncCallback\<Ability>): void
Waits a period of time for the ability that matches the **AbilityMonitor** instance to reach the **OnCreate** lifecycle and returns the **Ability** instance. This API uses an asynchronous callback to return the result. Waits a period of time for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **OnCreate** lifecycle state and returns the **Ability** instance. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -250,7 +258,7 @@ abilityDelegator.waitAbilityMonitor(monitor, timeout, (err : any, data : any) => ...@@ -250,7 +258,7 @@ abilityDelegator.waitAbilityMonitor(monitor, timeout, (err : any, data : any) =>
waitAbilityMonitor(monitor: AbilityMonitor, timeout?: number): Promise\<Ability> waitAbilityMonitor(monitor: AbilityMonitor, timeout?: number): Promise\<Ability>
Waits a period of time for the ability that matches the **AbilityMonitor** instance to reach the **OnCreate** lifecycle and returns the **Ability** instance. This API uses a promise to return the result. Waits a period of time for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **OnCreate** lifecycle state and returns the **Ability** instance. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -355,7 +363,7 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => { ...@@ -355,7 +363,7 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
getCurrentTopAbility(callback: AsyncCallback\<Ability>): void getCurrentTopAbility(callback: AsyncCallback\<Ability>): void
Obtains the top ability of the application. This API uses an asynchronous callback to return the result. Obtains the top ability of this application. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -384,7 +392,7 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => { ...@@ -384,7 +392,7 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
getCurrentTopAbility(): Promise\<Ability> getCurrentTopAbility(): Promise\<Ability>
Obtains the top ability of the application. This API uses a promise to return the result. Obtains the top ability of this application. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
...@@ -491,7 +499,7 @@ Schedules the lifecycle state of an ability to **Foreground**. This API uses an ...@@ -491,7 +499,7 @@ Schedules the lifecycle state of an ability to **Foreground**. This API uses an
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ----------------------- | ---- | ------------------------------------------------------- | | -------- | ----------------------- | ---- | ------------------------------------------------------- |
| ability | Ability | Yes | Target ability. | | ability | Ability | Yes | Target ability. |
| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation fails.| | callback | AsyncCallback\<boolean> | Yes | Callback used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.|
**Example** **Example**
...@@ -529,7 +537,7 @@ Schedules the lifecycle state of an ability to **Foreground**. This API uses a p ...@@ -529,7 +537,7 @@ Schedules the lifecycle state of an ability to **Foreground**. This API uses a p
| Type | Description | | Type | Description |
| ----------------- | ------------------------------------------------------------ | | ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | Promise used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation fails.| | Promise\<boolean> | Promise used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.|
**Example** **Example**
...@@ -562,7 +570,7 @@ Schedules the lifecycle state of an ability to **Background**. This API uses an ...@@ -562,7 +570,7 @@ Schedules the lifecycle state of an ability to **Background**. This API uses an
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ----------------------- | ---- | ------------------------------------------------------- | | -------- | ----------------------- | ---- | ------------------------------------------------------- |
| ability | Ability | Yes | Target ability. | | ability | Ability | Yes | Target ability. |
| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation fails.| | callback | AsyncCallback\<boolean> | Yes | Callback used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.|
**Example** **Example**
...@@ -600,7 +608,7 @@ Schedules the lifecycle state of an ability to **Background**. This API uses a p ...@@ -600,7 +608,7 @@ Schedules the lifecycle state of an ability to **Background**. This API uses a p
| Type | Description | | Type | Description |
| ----------------- | ------------------------------------------------------------ | | ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | Promise used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation fails.| | Promise\<boolean> | Promise used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.|
**Example** **Example**
...@@ -620,6 +628,32 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => { ...@@ -620,6 +628,32 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
### printSync<sup>9+</sup>
printSync(msg: string): void
Prints log information to the unit test console.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------- |
| msg | string | Yes | Log string.|
**Example**
```js
var abilityDelegator;
var msg = "msg";
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.printSync(msg);
```
### print ### print
print(msg: string, callback: AsyncCallback\<void>): void print(msg: string, callback: AsyncCallback\<void>): void
......
# AbilityDelegatorArgs # AbilityDelegatorArgs
The **AbilityDelegatorArgs** module provides a global register to store the registered **AbilityDelegator** and **AbilityDelegatorArgs** instances during application startup.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Usage
The ability delegator arguments are obtained by calling **getArguments** in **AbilityDelegatorRegistry**.
```js ```js
import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
var args = AbilityDelegatorRegistry.getArguments();
``` ```
## AbilityDelegatorArgs ## AbilityDelegatorArgs
Describes the test parameters. Describes the ability delegator arguments.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name | Type | Readable| Writable| Description | | Name | Type | Readable| Writable| Description |
| ------------------- | ---------------------- | ---- | ---- | ------------------------------------------------------------ | | ------------------- | ---------------------- | ---- | ---- | ------------------------------------------------------------ |
| bundleName | string | Yes | Yes | Bundle name of the application to test.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | bundleName | string | Yes | Yes | Bundle name of the application to test. |
| parameters | {[key:string]: string} | Yes | Yes | Parameters of the unit test that is started currently.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | parameters | {[key:string]: string} | Yes | Yes | Parameters of the unit test that is started currently. |
| testCaseNames | string | Yes | Yes | Test case names.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | testCaseNames | string | Yes | Yes | Test case names. |
| testRunnerClassName | string | Yes | Yes | Names of the test executors that execute the test cases.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | testRunnerClassName | string | Yes | Yes | Names of the test case executors. |
# AbilityLifecycleCallback # AbilityLifecycleCallback
The **AbilityLifecycleCallback** module provides callbacks, such as **onAbilityCreate**, **onAbilityWindowStageCreate**, and **onAbilityWindowStageDestroy**, to receive lifecycle state changes in the application context.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
A callback class that provides APIs, such as **onAbilityCreate**, **onAbilityWindowStageCreate**, and **onAbilityWindowStageDestroy**, to listen for the lifecycle of the application context.
## Modules to Import ## Modules to Import
```js ```js
import AbilityLifecycleCallback from "@ohos.application.abilityLifecycleCallback"; import AbilityLifecycleCallback from "@ohos.application.AbilityLifecycleCallback";
``` ```
......
# AbilityMonitor # AbilityMonitor
The **AbilityMonitor** module provides monitors for abilities that meet specified conditions. The latest matched abilities are stored in an **AbilityMonitor** object.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Usage
The ability monitor is set by calling **addAbilityMonitor** in **abilityDelegator**.
```js ```js
import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
var abilityDelegator;
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.addAbilityMonitor(monitor, (err : any) => {
console.info("addAbilityMonitor callback");
});
``` ```
## AbilityMonitor ## AbilityMonitor
Describes an ability monitor. Describes an ability monitor.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name | Type | Readable| Writable| Description | | Name | Type | Readable| Writable| Description |
| ------------------------------------------------------------ | -------- | ---- | ---- | ------------------------------------------------------------ | | ------------------------------------------------------------ | -------- | ---- | ---- | ------------------------------------------------------------ |
| abilityName | string | Yes | Yes | Name of the ability bound to the ability monitor.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | abilityName | string | Yes | Yes | Name of the ability bound to the ability monitor. |
| onAbilityCreate?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability is created.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | onAbilityCreate?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability is created.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received. |
| onAbilityForeground?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability starts to run in the foreground.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | onAbilityForeground?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability starts to run in the foreground.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received. |
| onAbilityBackground?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability starts to run in the background.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | onAbilityBackground?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability starts to run in the background.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received. |
| onAbilityDestroy?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability is destroyed.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | onAbilityDestroy?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability is destroyed.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received. |
| onWindowStageCreate?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the window stage is created.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | onWindowStageCreate?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the window stage is created.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received. |
| onWindowStageRestore?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the window stage is restored.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | onWindowStageRestore?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the window stage is restored.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received. |
| onWindowStageDestroy?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the window stage is destroyed.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | onWindowStageDestroy?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the window stage is destroyed.<br>If this attribute is not set, the corresponding lifecycle callback cannot be received. |
# AbilityStage # AbilityStage
**AbilityStage** is a runtime class for HAP files.
The **AbilityStage** module notifies you of when you can perform HAP initialization such as resource pre-loading and thread creation during the HAP loading.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Runtime class for HAP files. It provides APIs to notify you when a HAP file starts loading. You can then initialize the HAP file, for example, pre-load resources and create threads.
## Modules to Import ## Modules to Import
```js ```js
......
# ApplicationContext # ApplicationContext
The **ApplicationContext** module provides application-level context. You can use the APIs of this module to register and deregister the ability lifecycle listener in an application.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Provides application-level context and APIs for registering and deregistering the ability lifecycle listener in an application.
## Modules to Import
```
import Ability from '@ohos.application.Ability';
```
## How to Use ## How to Use
Before calling any APIs in **ApplicationContext**, obtain an **ApplicationContext** instance through the **context** instance. Before calling any APIs in **ApplicationContext**, obtain an **ApplicationContext** instance through the **context** instance.
...@@ -42,6 +36,54 @@ Registers a listener to monitor the ability lifecycle of the application. ...@@ -42,6 +36,54 @@ Registers a listener to monitor the ability lifecycle of the application.
| ------ | ------------------------------ | | ------ | ------------------------------ |
| number | ID of the registered listener. The ID is incremented by 1 each time the listener is registered. When the ID exceeds 2^63-1, **-1** is returned.| | number | ID of the registered listener. The ID is incremented by 1 each time the listener is registered. When the ID exceeds 2^63-1, **-1** is returned.|
**Example**
```js
import AbilityStage from "@ohos.application.AbilityStage";
var lifecycleId;
export default class MyAbilityStage extends AbilityStage {
onCreate() {
console.log("MyAbilityStage onCreate")
let AbilityLifecycleCallback = {
onAbilityCreate(ability){
console.log("AbilityLifecycleCallback onAbilityCreate ability:" + JSON.stringify(ability));
},
onAbilityWindowStageCreate(ability){
console.log("AbilityLifecycleCallback onAbilityWindowStageCreate ability:" + JSON.stringify(ability));
},
onAbilityWindowStageDestroy(ability){
console.log("AbilityLifecycleCallback onAbilityWindowStageDestroy ability:" + JSON.stringify(ability));
},
onAbilityDestroy(ability){
console.log("AbilityLifecycleCallback onAbilityDestroy ability:" + JSON.stringify(ability));
},
onAbilityForeground(ability){
console.log("AbilityLifecycleCallback onAbilityForeground ability:" + JSON.stringify(ability));
},
onAbilityBackground(ability){
console.log("AbilityLifecycleCallback onAbilityBackground ability:" + JSON.stringify(ability));
},
onAbilityContinue(ability){
console.log("AbilityLifecycleCallback onAbilityContinue ability:" + JSON.stringify(ability));
}
}
// 1. Obtain applicationContext through the context attribute.
let applicationContext = this.context.getApplicationContext();
// 2. Use applicationContext to register a listener for the ability lifecycle in the application.
lifecycleId = applicationContext.registerAbilityLifecycleCallback(AbilityLifecycleCallback);
console.log("registerAbilityLifecycleCallback number: " + JSON.stringify(lifecycleId));
}
onDestroy() {
let applicationContext = this.context.getApplicationContext();
applicationContext.unregisterAbilityLifecycleCallback(lifecycleId, (error, data) => {
console.log("unregisterAbilityLifecycleCallback success, err: " + JSON.stringify(error));
});
}
}
```
## ApplicationContext.unregisterAbilityLifecycleCallback ## ApplicationContext.unregisterAbilityLifecycleCallback
...@@ -61,47 +103,86 @@ Deregisters the listener that monitors the ability lifecycle of the application. ...@@ -61,47 +103,86 @@ Deregisters the listener that monitors the ability lifecycle of the application.
**Example** **Example**
```js ```js
import AbilityStage from "@ohos.application.AbilityStage"; let applicationContext = this.context.getApplicationContext();
let lifecycleId = 1;
var lifecycleid; console.log("stage applicationContext: " + JSON.stringify(applicationContext));
applicationContext.unregisterAbilityLifecycleCallback(lifecycleId, (error, data) => {
export default class MyAbilityStage extends AbilityStage { console.log("unregisterAbilityLifecycleCallback success, err: " + JSON.stringify(error));
onCreate() { });
console.log("MyAbilityStage onCreate") ```
let AbilityLifecycleCallback = {
onAbilityCreate(ability){ ## ApplicationContext.registerEnvironmentCallback
console.log("AbilityLifecycleCallback onAbilityCreate ability:" + JSON.stringify(ability));
}, registerEnvironmentCallback(callback: EnvironmentCallback): **number**;
onAbilityWindowStageCreate(ability){
console.log("AbilityLifecycleCallback onAbilityWindowStageCreate ability:" + JSON.stringify(ability)); Registers a listener for system environment changes. This API uses an asynchronous callback to return the result.
},
onAbilityWindowStageDestroy(ability){ **System capability**: SystemCapability.Ability.AbilityRuntime.Core
console.log("AbilityLifecycleCallback onAbilityWindowStageDestroy ability:" + JSON.stringify(ability));
}, **Parameters**
onAbilityDestroy(ability){
console.log("AbilityLifecycleCallback onAbilityDestroy ability:" + JSON.stringify(ability)); | Name | Type | Mandatory| Description |
}, | ------------------------ | -------- | ---- | ------------------------------ |
onAbilityForeground(ability){ | [EnvironmentCallback](js-apis-application-EnvironmentCallback.md) | callback | Yes | Callback used to return the ID of the registered listener.|
console.log("AbilityLifecycleCallback onAbilityForeground ability:" + JSON.stringify(ability));
}, **Return value**
onAbilityBackground(ability){
console.log("AbilityLifecycleCallback onAbilityBackground ability:" + JSON.stringify(ability)); | Type | Description |
}, | ------ | ------------------------------ |
onAbilityContinue(ability){ | number | ID of the registered listener. The ID is incremented by 1 each time the listener is registered. When the ID exceeds 2^63-1, **-1** is returned.|
console.log("AbilityLifecycleCallback onAbilityContinue ability:" + JSON.stringify(ability));
} **Example**
}
// 1. Obtain applicationContext through the context attribute. ```js
let applicationContext = this.context.getApplicationContext(); import AbilityStage from "@ohos.application.AbilityStage";
// 2. Use applicationContext to register a listener for the ability lifecycle in the application.
lifecycleid = applicationContext.registerAbilityLifecycleCallback(AbilityLifecycleCallback); var callbackId;
console.log("registerAbilityLifecycleCallback number: " + JSON.stringify(lifecycleid));
} export default class MyAbilityStage extends AbilityStage {
onDestroy() { onCreate() {
let applicationContext = this.context.getApplicationContext(); console.log("MyAbilityStage onCreate")
applicationContext.unregisterAbilityLifecycleCallback(lifecycleid, (error, data) => { globalThis.applicationContext = this.context.getApplicationContext();
console.log("unregisterAbilityLifecycleCallback success, err: " + JSON.stringify(error)); let EnvironmentCallback = {
}); onConfigurationUpdated(config){
} console.log("onConfigurationUpdated config:" + JSON.stringify(config));
} },
}
// 1. Obtain an applicationContext object.
let applicationContext = globalThis.applicationContext;
// 2. Use applicationContext to register a listener for the ability lifecycle in the application.
callbackId = applicationContext.registerEnvironmentCallback(EnvironmentCallback);
console.log("registerEnvironmentCallback number: " + JSON.stringify(callbackId));
}
onDestroy() {
let applicationContext = globalThis.applicationContext;
applicationContext.unregisterEnvironmentCallback(callbackId, (error, data) => {
console.log("unregisterEnvironmentCallback success, err: " + JSON.stringify(error));
});
}
}
```
## ApplicationContext.unregisterEnvironmentCallback
unregisterEnvironmentCallback(callbackId: **number**, callback: AsyncCallback<**void**>): **void**;
Deregisters the listener for system environment changes. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------- | -------- | ---- | -------------------------- |
| callbackId | number | Yes | ID of the listener to deregister. |
| AsyncCallback | callback | Yes | Callback used to return the result. |
**Example**
```js
let applicationContext = this.context.getApplicationContext();
let callbackId = 1;
applicationContext.unregisterEnvironmentCallback(callbackId, (error, data) => {
console.log("unregisterEnvironmentCallback success, err: " + JSON.stringify(error));
});
``` ```
# Context # Context
The **Context** module provides the context for running code. You can use the APIs to query and set the application information and resource manager.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Provides the context for running code, including **applicationInfo** and **resourceManager**.
## Modules to Import
```
import AbilityContext from '@ohos.application.Ability';
```
## Usage ## Usage
You must extend **AbilityContext** to implement this module. You must extend **AbilityContext** to implement this module.
```js
import AbilityContext from '@ohos.application.Ability'
class MainAbility extends AbilityContext {
onWindowStageCreate(windowStage) {
let test = "com.example.test";
let context = this.context.createBundleContext(test);
}
}
```
## Attributes ## Attributes
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name| Type| Readable| Writable| Description| | Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| resourceManager | ResourceManager | Yes| No| **ResourceManager** object.| | resourceManager | resmgr.ResourceManager; | Yes| No| **ResourceManager** object.|
| applicationInfo | ApplicationInfo | Yes| No| Information about the application.| | applicationInfo | ApplicationInfo | Yes| No| Information about the application.|
| cacheDir | string | Yes| No| Cache directory of the application on the internal storage.| | cacheDir | string | Yes| No| Cache directory of the application on the internal storage.|
| tempDir | string | Yes| No| Temporary file directory of the application.| | tempDir | string | Yes| No| Temporary file directory of the application.|
| filesDir | string | Yes| No| File directory of the application on the internal storage.| | filesDir | string | Yes| No| File directory of the application on the internal storage.|
| databaseDir | string | Yes| No| Storage directory of local data.| | databaseDir | string | Yes| No| Storage directory of local data.|
| storageDir | string | Yes| No| Storage directory of lightweight data.|
| bundleCodeDir | string | Yes| No| Application installation path.| | bundleCodeDir | string | Yes| No| Application installation path.|
| distributedFilesDir | string | Yes| No| Storage directory of distributed application data files.| | distributedFilesDir | string | Yes| No| Storage directory of distributed application data files.|
| eventHub | [EventHub](js-apis-eventhub.md) | Yes| No| Event hub information.| | eventHub | [EventHub](js-apis-eventhub.md) | Yes| No| Event hub information.|
| area | [AreaMode](#areamode) | Yes| Yes| Area in which the file to be access is located.| | area | [AreaMode](#areamode) | Yes| Yes| Area in which the file to be access is located.|
| preferencesDir | string | Yes| Yes| Preferences directory of the application.|
## Context.createBundleContext ## Context.createBundleContext
...@@ -41,19 +45,23 @@ createBundleContext(bundleName: string): Context; ...@@ -41,19 +45,23 @@ createBundleContext(bundleName: string): Context;
Creates a context for a given application. Creates a context for a given application.
**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| bundleName | string | Yes| Application bundle name.| | bundleName | string | Yes| Application bundle name.|
**Return value** **Return value**
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| Context | Context created.| | Context | Context created.|
**Example** **Example**
...@@ -79,15 +87,15 @@ Creates a context for a given HAP. ...@@ -79,15 +87,15 @@ Creates a context for a given HAP.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| moduleName | string | Yes| HAP name in the application.| | moduleName | string | Yes| HAP name in the application.|
**Return value** **Return value**
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| Context | Context created.| | Context | Context created.|
**Example** **Example**
...@@ -111,18 +119,20 @@ Creates a context for a given HAP in an application. ...@@ -111,18 +119,20 @@ Creates a context for a given HAP in an application.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| bundleName | string | Yes| Application bundle name.| | bundleName | string | Yes| Application bundle name.|
| moduleName | string | Yes| HAP name in the application.| | moduleName | string | Yes| HAP name in the application.|
**Return value** **Return value**
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| Context | Context created.| | Context | Context created.|
**Example** **Example**
......
# ShellCmdResult # ShellCmdResult
The **ShellCmdResult** module provides the shell command execution result.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Usage
The result is obtained by calling **executeShellCommand** in **abilityDelegator**.
```js ```js
import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
var abilityDelegator;
var cmd = "cmd";
var timeout = 100;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.executeShellCommand(cmd, timeout).then((data : any) => {
console.info("executeShellCommand promise");
});
``` ```
## ShellCmdResult ## ShellCmdResult
Describes the shell command execution result. Describes the shell command execution result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name | Type | Readable| Writable| Description | | Name | Type | Readable| Writable| Description |
| --------- | ------ | ---- | ---- | ------------------------------------------------------------ | | --------- | ------ | ---- | ---- | ------------------------------------------------------------ |
| stdResult | string | Yes | Yes | Standard output content.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | stdResult | string | Yes | Yes | Standard output content. |
| exitCode | number | Yes | Yes | Result code.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core| | exitCode | number | Yes | Yes | Result code. |
# StaticSubscriberExtensionAbility # StaticSubscriberExtensionAbility
The **StaticSubscriberExtensionAbility** module provides Extension abilities for static subscribers.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
...@@ -16,13 +18,15 @@ onReceiveEvent(event: CommonEventData): void; ...@@ -16,13 +18,15 @@ onReceiveEvent(event: CommonEventData): void;
Callback of the common event of a static subscriber. Callback of the common event of a static subscriber.
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| event | CommonEventData | Yes| Callback of the common event of a static subscriber.| | event | CommonEventData | Yes| Common event of a static subscriber.|
**Example** **Example**
......
# appManager # appManager
The **appManager** module implements application management. You can use the APIs of this module to query whether the application is undergoing a stability test, whether the application is running on a RAM constrained device, the memory size of the application, and information about the running process.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Implements application management.
## Modules to Import ## Modules to Import
```js ```js
import app from '@ohos.application.appManager'; import app from '@ohos.application.appManager';
``` ```
## appManager.isRunningInStabilityTest<sup>8+</sup> ## appManager.isRunningInStabilityTest<sup>8+</sup>
static isRunningInStabilityTest(callback: AsyncCallback&lt;boolean&gt;): void static isRunningInStabilityTest(callback: AsyncCallback&lt;boolean&gt;): void
...@@ -165,6 +161,8 @@ getProcessRunningInfos(): Promise\<Array\<ProcessRunningInfo>>; ...@@ -165,6 +161,8 @@ getProcessRunningInfos(): Promise\<Array\<ProcessRunningInfo>>;
Obtains information about the running processes. This API uses a promise to return the result. Obtains information about the running processes. This API uses a promise to return the result.
**Required permissions**: ohos.permission.GET_RUNNING_INFO
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Return value** **Return value**
...@@ -189,6 +187,8 @@ getProcessRunningInfos(callback: AsyncCallback\<Array\<ProcessRunningInfo>>): vo ...@@ -189,6 +187,8 @@ getProcessRunningInfos(callback: AsyncCallback\<Array\<ProcessRunningInfo>>): vo
Obtains information about the running processes. This API uses an asynchronous callback to return the result. Obtains information about the running processes. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.GET_RUNNING_INFO
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**Parameters** **Parameters**
...@@ -206,13 +206,533 @@ Obtains information about the running processes. This API uses an asynchronous c ...@@ -206,13 +206,533 @@ Obtains information about the running processes. This API uses an asynchronous c
}) })
``` ```
## ProcessRunningInfo ## appManager.registerApplicationStateObserver<sup>8+</sup>
registerApplicationStateObserver(observer: ApplicationStateObserver): number;
Registers the application state observer.
**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| observer | ApplicationStateObserver | No| Numeric code of the observer.|
**Example**
```js
var applicationStateObserver = {
onForegroundApplicationChanged(appStateData) {
console.log('------------ onForegroundApplicationChanged -----------', appStateData);
},
onAbilityStateChanged(abilityStateData) {
console.log('------------ onAbilityStateChanged -----------', abilityStateData);
},
onProcessCreated(processData) {
console.log('------------ onProcessCreated -----------', processData);
},
onProcessDied(processData) {
console.log('------------ onProcessDied -----------', processData);
}
}
const observerCode = app.registerApplicationStateObserver(applicationStateObserver);
console.log('-------- observerCode: ---------', observerCode);
```
## appManager.unregisterApplicationStateObserver<sup>8+</sup>
unregisterApplicationStateObserver(observerId: number, callback: AsyncCallback\<void>): void;
Deregisters the application state observer. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| observerId | number | No| Numeric code of the observer.|
| callback | AsyncCallback\<void> | No| Callback used to return the result.|
**Example**
```js
var observerId = 100;
function unregisterApplicationStateObserverCallback(err) {
if (err) {
console.log('------------ unregisterApplicationStateObserverCallback ------------', err);
}
}
app.unregisterApplicationStateObserver(observerId, unregisterApplicationStateObserverCallback);
```
## appManager.unregisterApplicationStateObserver<sup>8+</sup>
unregisterApplicationStateObserver(observerId: number): Promise\<void>;
Deregisters the application state observer. This API uses a promise to return the result.
**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| observerId | number | No| Numeric code of the observer.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise\<void> | Promise used to return the result.|
**Example**
```js
var observerId = 100;
app.unregisterApplicationStateObserver(observerId)
.then((data) => {
console.log('----------- unregisterApplicationStateObserver success ----------', data);
})
.catch((err) => {
console.log('----------- unregisterApplicationStateObserver fail ----------', err);
})
```
## appManager.getForegroundApplications<sup>8+</sup>
getForegroundApplications(callback: AsyncCallback\<Array\<AppStateData>>): void;
Obtains applications that run in the foreground. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.GET_RUNNING_INFO
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback\<Array\<AppStateData>> | No| Callback used to return the application state data.|
**Example**
```js
function getForegroundApplicationsCallback(err, data) {
if (err) {
console.log('--------- getForegroundApplicationsCallback fail ---------', err);
} else {
console.log('--------- getForegroundApplicationsCallback success ---------', data)
}
}
app.getForegroundApplications(getForegroundApplicationsCallback);
```
## appManager.getForegroundApplications<sup>8+</sup>
getForegroundApplications(): Promise\<Array\<AppStateData>>;
Obtains applications that run in the foreground. This API uses a promise to return the result.
**Required permissions**: ohos.permission.GET_RUNNING_INFO
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Return value**
| Type| Description|
| -------- | -------- |
| Promise\<Array\<ProcessRunningInfo>> | Promise used to return the application state data.|
**Example**
```js
app.getForegroundApplications()
.then((data) => {
console.log('--------- getForegroundApplications success -------', data);
})
.catch((err) => {
console.log('--------- getForegroundApplications fail -------', err);
})
```
## appManager.killProcessWithAccount<sup>8+</sup>
killProcessWithAccount(bundleName: string, accountId: number): Promise\<void\>
Kills the process by bundle name and account ID. This API uses a promise to return the result.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.CLEAN_BACKGROUND_PROCESSES
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | Yes| Bundle name of an application.|
| accountId | number | Yes| Account ID.|
**Example**
```js
var bundleName = 'bundleName';
var accountId = 0;
app.killProcessWithAccount(bundleName, accountId)
.then((data) => {
console.log('------------ killProcessWithAccount success ------------', data);
})
.catch((err) => {
console.log('------------ killProcessWithAccount fail ------------', err);
})
```
## appManager.killProcessWithAccount<sup>8+</sup>
killProcessWithAccount(bundleName: string, accountId: number, callback: AsyncCallback\<void\>): void
Kills the process by bundle name and account ID. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.CLEAN_BACKGROUND_PROCESSES
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | Yes| Bundle name of an application.|
| accountId | number | Yes| Account ID.|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Example**
```js
var bundleName = 'bundleName';
var accountId = 0;
function killProcessWithAccountCallback(err, data) {
if (err) {
console.log('------------- killProcessWithAccountCallback fail, err: --------------', err);
} else {
console.log('------------- killProcessWithAccountCallback success, data: --------------', data);
}
}
app.killProcessWithAccount(bundleName, accountId, killProcessWithAccountCallback);
```
## appManager.killProcessesByBundleName<sup>8+</sup>
killProcessesByBundleName(bundleName: string, callback: AsyncCallback\<void>);
Kills a process by bundle name. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.CLEAN_BACKGROUND_PROCESSES
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | No| Bundle name of an application.|
| callback | AsyncCallback\<void> | No| Callback used to return the result.|
**Example**
```js
var bundleName = 'bundleName';
function killProcessesByBundleNameCallback(err, data) {
if (err) {
console.log('------------- killProcessesByBundleNameCallback fail, err: --------------', err);
} else {
console.log('------------- killProcessesByBundleNameCallback success, data: --------------', data);
}
}
app.killProcessesByBundleName(bundleName, killProcessesByBundleNameCallback);
```
## appManager.killProcessesByBundleName<sup>8+</sup>
killProcessesByBundleName(bundleName: string): Promise\<void>;
Kills a process by bundle name. This API uses a promise to return the result.
**Required permissions**: ohos.permission.CLEAN_BACKGROUND_PROCESSES
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | No| Bundle name of an application.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise\<void> | Promise used to return the result.|
**Example**
```js
var bundleName = 'bundleName';
app.killProcessesByBundleName(bundleName)
.then((data) => {
console.log('------------ killProcessesByBundleName success ------------', data);
})
.catch((err) => {
console.log('------------ killProcessesByBundleName fail ------------', err);
})
```
## appManager.clearUpApplicationData<sup>8+</sup>
clearUpApplicationData(bundleName: string, callback: AsyncCallback\<void>);
Clears application data by bundle name. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.CLEAN_APPLICATION_DATA
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | No| Bundle name of an application.|
| callback | AsyncCallback\<void> | No| Callback used to return the result.|
**Example**
```js
var bundleName = 'bundleName';
function clearUpApplicationDataCallback(err, data) {
if (err) {
console.log('------------- clearUpApplicationDataCallback fail, err: --------------', err);
} else {
console.log('------------- clearUpApplicationDataCallback success, data: --------------', data);
}
}
app.clearUpApplicationData(bundleName, clearUpApplicationDataCallback);
```
## appManager.clearUpApplicationData<sup>8+</sup>
clearUpApplicationData(bundleName: string): Promise\<void>;
Clears application data by bundle name. This API uses a promise to return the result.
**Required permissions**: ohos.permission.CLEAN_APPLICATION_DATA
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | No| Bundle name of an application.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise\<void> | Promise used to return the result.|
**Example**
```js
var bundleName = 'bundleName';
app.clearUpApplicationData(bundleName)
.then((data) => {
console.log('------------ clearUpApplicationData success ------------', data);
})
.catch((err) => {
console.log('------------ clearUpApplicationData fail ------------', err);
})
```
## ApplicationStateObserver.onForegroundApplicationChanged<sup>8+</sup>
onForegroundApplicationChanged(appStateData: AppStateData): void;
Called when the application state changes.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| appStateData | [AppStateData](#appstatedata) | No| Information about the application whose state is changed.|
**Example**
```js
import ApplicationStateObserver from '@ohos.application.ApplicationStateObserver'
const foregroundApplicationInfo = ApplicationStateObserver.onForegroundApplicationChanged();
console.log('-------- foregroundApplicationInfo: ---------', foregroundApplicationInfo);
```
## ApplicationStateObserver.onAbilityStateChanged<sup>8+</sup>
onAbilityStateChanged(abilityStateData: AbilityStateData): void;
Called when the ability state changes.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| abilityStateData | [AbilityStateData](#abilitystatedata) | No| Information about the ability whose state is changed.|
**Example**
```js
import ApplicationStateObserver from '@ohos.application.ApplicationStateObserver'
const abilityStateChangedInfo = ApplicationStateObserver.onAbilityStateChanged();
console.log('-------- abilityStateChangedInfo: ---------', abilityStateChangedInfo);
```
## ApplicationStateObserver.onProcessCreated<sup>8+</sup>
onProcessCreated(processData: ProcessData): void;
Called when a process is created.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| processData | [ProcessData](#processdata) | No| Process information.|
**Example**
```js
import ApplicationStateObserver from '@ohos.application.ApplicationStateObserver'
const processCreatedInfo = ApplicationStateObserver.onProcessCreated();
console.log('-------- processCreatedInfo: ---------', processCreatedInfo);
```
## ApplicationStateObserver.onProcessDied<sup>8+</sup>
onProcessDied(processData: ProcessData): void;
Called when a process is terminated.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| processData | ProcessData | No| Process information.|
**Example**
```js
import ApplicationStateObserver from '@ohos.application.ApplicationStateObserver'
const processDiedInfo = ApplicationStateObserver.onProcessDied();
console.log('-------- processDiedInfo: ---------', processDiedInfo);
```
## AppStateData
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
| Name | Readable/Writable| Type | Mandatory| Description | | Name | Readable/Writable| Type | Mandatory| Description |
| ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ | | ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ |
| pid<sup>8+</sup> | Read only | number | No | Process ID. | | bundleName<sup>8+</sup> | Read only | string | No | Bundle name of an application. |
| uid<sup>8+</sup> | Read only | number | No | User ID.| | uid<sup>8+</sup> | Read only | number | No | User ID.|
| processName<sup>8+</sup> | Read only | string | No | Process name.| | state<sup>8+</sup> | Read only | number | No | Application state.|
| bundleNames<sup>8+</sup> | Read only | Array\<string> | No | **bundleName** array in the running processes.|
## AbilityStateData
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
| Name | Type | Readable| Writable| Description |
| ----------------------- | ---------| ---- | ---- | ------------------------- |
| pid<sup>8+</sup> | number | Yes | No | Process ID. |
| bundleName<sup>8+</sup> | string | Yes | No | Bundle name of an application. |
| abilityName<sup>8+</sup> | string | Yes | No | Ability name. |
| uid<sup>8+</sup> | number | Yes | No | User ID. |
| state<sup>8+</sup> | number | Yes | No | Application information. |
| moduleName<sup>9+</sup> | string | Yes | No | Name of the HAP file to which the ability belongs. |
| abilityType<sup>8+</sup> | string | Yes | No | Ability type. |
## ProcessData
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
| Name | Type | Readable| Writable| Description |
| ----------------------- | ---------| ---- | ---- | ------------------------- |
| pid<sup>8+</sup> | number | Yes | No | Process ID. |
| bundleName<sup>8+</sup> | string | Yes | No | Bundle name of an application. |
| uid<sup>8+</sup> | number | Yes | No | User ID. |
## ProcessRunningInfo
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name | Readable/Writable| Type | Mandatory| Description |
| ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ |
| pid<sup>9+</sup> | Read only | number | No | Process ID. |
| uid<sup>9+</sup> | Read only | number | No | User ID.|
| processName<sup>9+</sup> | Read only | string | No | Process name.|
| bundleNames<sup>9+</sup> | Read only | Array\<string> | No | **bundleName** array in the running processes.|
# Configuration # Configuration
The **Configuration** module provides environment configuration information.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Provides the configuration for the environment where the ability is running.
## Modules to Import ## Modules to Import
```js ```js
...@@ -23,3 +23,4 @@ import Configuration from '@ohos.application.Configuration'; ...@@ -23,3 +23,4 @@ import Configuration from '@ohos.application.Configuration';
| direction<sup>9+</sup> | Direction | Yes| No| Screen orientation, which can be **DIRECTION_HORIZONTAL** or **DIRECTION_VERTICAL**.| | direction<sup>9+</sup> | Direction | Yes| No| Screen orientation, which can be **DIRECTION_HORIZONTAL** or **DIRECTION_VERTICAL**.|
| screenDensity<sup>9+</sup> | ScreenDensity | Yes| No| Screen resolution, which can be **SCREEN_DENSITY_SDPI** (120), **SCREEN_DENSITY_MDPI** (160), **SCREEN_DENSITY_LDPI** (240), **SCREEN_DENSITY_XLDPI** (320), **SCREEN_DENSITY_XXLDPI** (480), or **SCREEN_DENSITY_XXXLDPI** (640).| | screenDensity<sup>9+</sup> | ScreenDensity | Yes| No| Screen resolution, which can be **SCREEN_DENSITY_SDPI** (120), **SCREEN_DENSITY_MDPI** (160), **SCREEN_DENSITY_LDPI** (240), **SCREEN_DENSITY_XLDPI** (320), **SCREEN_DENSITY_XXLDPI** (480), or **SCREEN_DENSITY_XXXLDPI** (640).|
| displayId<sup>9+</sup> | number | Yes| No| ID of the display where the application is located.| | displayId<sup>9+</sup> | number | Yes| No| ID of the display where the application is located.|
| hasPointerDevice<sup>9+</sup> | boolean | Yes| No| Whether the pointer device is connected.|
# ConfigurationConstant # ConfigurationConstant
The **ConfigurationConstant** module provides the enumerated values of the environment configuration information.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Defines enumerated values of the configuration for the environment where the ability is running.
## Modules to Import ## Modules to Import
...@@ -15,7 +13,6 @@ Defines enumerated values of the configuration for the environment where the abi ...@@ -15,7 +13,6 @@ Defines enumerated values of the configuration for the environment where the abi
import ConfigurationConstant from '@ohos.application.ConfigurationConstant'; import ConfigurationConstant from '@ohos.application.ConfigurationConstant';
``` ```
## ConfigurationConstant.ColorMode ## ConfigurationConstant.ColorMode
You can obtain the value of this constant by calling the **ConfigurationConstant.ColorMode** API. You can obtain the value of this constant by calling the **ConfigurationConstant.ColorMode** API.
......
# EventHub # EventHub
The **EventHub** module provides APIs to subscribe to, unsubscribe from, and trigger events.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Implements event subscription, unsubscription, and triggering.
## Modules to Import
```js
import Ability from '@ohos.application.Ability'
```
## Usage ## Usage
​Before using any APIs in the **EventHub**, you must obtain an **EventHub** instance through the member variable **context** of the **Ability** instance. ​Before using any APIs in the **EventHub**, you must obtain an **EventHub** instance through the member variable **context** of the **Ability** instance.
......
# ExtensionContext # ExtensionContext
The **ExtensionContext** module, inherited from **Context**, implements the context for Extension abilities.
This module allows access to Extension abilities.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Implements the extension context. This module is inherited from **Context**.
## Modules to Import
```js
import DataShareExtensionAbility from '@ohos.application.DataShareExtensionAbility';
```
## Attributes ## Attributes
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name| Type| Readable| Writable| Description| | Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| currentHapModuleInfo | HapModuleInfo | Yes| No| Information about the current HAP. | | currentHapModuleInfo | HapModuleInfo | Yes| No| Information about the current HAP. |
| config | Configuration | Yes| No| Module configuration information.| | config | Configuration | Yes| No| Module configuration information.|
| extensionAbilityInfo | [ExtensionAbilityInfo](js-apis-bundle-ExtensionAbilityInfo.md) | Yes| No| Extension ability information.|
# ExtensionRunningInfo # ExtensionRunningInfo
The **ExtensionRunningInfo** module provides running information and states for Extension abilities.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module are system APIs and cannot be called by third-party applications.
Provides extension running information.
## Modules to Import
```js
import abilitymanager from '@ohos.application.abilityManager';
```
## Usage ## Usage
The extension running information is obtained through an **abilityManager** instance. The Extension ability running information is obtained through an **abilityManager** instance.
```js ```js
import abilitymanager from '@ohos.application.abilityManager'; import abilitymanager from '@ohos.application.abilityManager';
...@@ -24,37 +19,16 @@ abilitymanager.getExtensionRunningInfos(upperLimit, (err,data) => { ...@@ -24,37 +19,16 @@ abilitymanager.getExtensionRunningInfos(upperLimit, (err,data) => {
}); });
``` ```
## Attributes
### Attributes
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name| Type| Readable| Writable| Description| | Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| extension | ElementName | Yes| No| Information that matches an extension.| | extension | ElementName | Yes| No| Information that matches an Extension ability.|
| pid | number | Yes| No| Process ID.| | pid | number | Yes| No| Process ID.|
| uid | number | Yes| No| User ID.| | uid | number | Yes| No| User ID.|
| processName | string | Yes| No| Process name.| | processName | string | Yes| No| Process name.|
| startTime | number | Yes| No| Extension start time.| | startTime | number | Yes| No| Start time of the Extension ability.|
| clientPackage | Array&lt;String&gt; | Yes| No| Names of all packages in the process.| | clientPackage | Array&lt;String&gt; | Yes| No| Names of all packages in the process.|
| type | [bundle.ExtensionAbilityType](#bundleextensionabilitytype) | Yes| No| Extension type.| | type | [bundle.ExtensionAbilityType](js-apis-Bundle.md#extensionabilitytype9) | Yes| No| Extension ability type.|
## bundle.ExtensionAbilityType
Enumerates extension types.
**System capability**: SystemCapability.BundleManager.BundleFramework
| Name| Value| Description|
| -------- | -------- | -------- |
| FORM | 0 | Extension information of the form type.< |
| WORK_SCHEDULER | 1 | Extension information of the work scheduler type.< |
| INPUT_METHOD | 2 | Extension information of the input method type.< |
| SERVICE | 3 | Extension information of the service type.< |
| ACCESSIBILITY | 4 | Extension information of the accessibility type.< |
| DATA_SHARE | 5 | Extension information of the data share type.< |
| FILE_SHARE | 6 | Extension information of the file share type.< |
| STATIC_SUBSCRIBER | 7 | Extension information of the static subscriber type.< |
| WALLPAPER | 8 | Extension information of the wallpaper type.< |
| UNSPECIFIED | 9 | Extension information of the unspecified type.< |
# FeatureAbility # FeatureAbility
The **FeatureAbility** module provides a UI for interacting with users. You can use APIs of this module to start a new ability, obtain the **dataAbilityHelper**, set a Page ability, obtain the window corresponding to this ability, and connecting to a Service ability.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
...@@ -19,7 +21,7 @@ import featureAbility from '@ohos.ability.featureAbility' ...@@ -19,7 +21,7 @@ import featureAbility from '@ohos.ability.featureAbility'
startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\<number>): void startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\<number>): void
Starts an ability. This API uses a callback to return the result. Starts an ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel **System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
...@@ -127,7 +129,7 @@ featureAbility.acquireDataAbilityHelper( ...@@ -127,7 +129,7 @@ featureAbility.acquireDataAbilityHelper(
startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback\<AbilityResult>): void startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback\<AbilityResult>): void
Starts an ability. This API uses a callback to return the execution result when the ability is destroyed. Starts an ability. This API uses an asynchronous callback to return the execution result when the ability is destroyed.
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel **System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
...@@ -214,7 +216,6 @@ featureAbility.startAbilityForResult( ...@@ -214,7 +216,6 @@ featureAbility.startAbilityForResult(
mykey7: true, mykey7: true,
}, },
}, },
requestCode: 2,
}, },
).then((data) => { ).then((data) => {
console.info("==========================>startAbilityForResult=======================>"); console.info("==========================>startAbilityForResult=======================>");
...@@ -225,7 +226,7 @@ featureAbility.startAbilityForResult( ...@@ -225,7 +226,7 @@ featureAbility.startAbilityForResult(
terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback\<void>): void terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback\<void>): void
Destroys this Page ability, with the result code and data sent to the caller. This API uses a callback to return the result. Destroys this Page ability, with the result code and data sent to the caller. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel **System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
...@@ -326,13 +327,11 @@ featureAbility.terminateSelfWithResult( ...@@ -326,13 +327,11 @@ featureAbility.terminateSelfWithResult(
}); });
``` ```
## featureAbility.hasWindowFocus<sup>7+<sup> ## featureAbility.hasWindowFocus<sup>7+<sup>
hasWindowFocus(callback: AsyncCallback\<boolean>): void hasWindowFocus(callback: AsyncCallback\<boolean>): void
Checks whether the main window of this ability has the focus. This API uses a callback to return the result. Checks whether the main window of this ability has the focus. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel **System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
...@@ -349,8 +348,6 @@ import featureAbility from '@ohos.ability.featureAbility'; ...@@ -349,8 +348,6 @@ import featureAbility from '@ohos.ability.featureAbility';
featureAbility.hasWindowFocus() featureAbility.hasWindowFocus()
``` ```
## featureAbility.hasWindowFocus<sup>7+<sup> ## featureAbility.hasWindowFocus<sup>7+<sup>
hasWindowFocus(): Promise\<boolean> hasWindowFocus(): Promise\<boolean>
...@@ -368,19 +365,17 @@ Checks whether the main window of this ability has the focus. This API uses a pr ...@@ -368,19 +365,17 @@ Checks whether the main window of this ability has the focus. This API uses a pr
**Example** **Example**
```javascript ```javascript
import featureAbility from '@ohos.ability.featureability'; import featureAbility from '@ohos.ability.featureAbility';
featureAbility.hasWindowFocus().then((data) => { featureAbility.hasWindowFocus().then((data) => {
console.info("==========================>hasWindowFocus=======================>"); console.info("==========================>hasWindowFocus=======================>");
}); });
``` ```
## featureAbility.getWant ## featureAbility.getWant
getWant(callback: AsyncCallback\<Want>): void getWant(callback: AsyncCallback\<Want>): void
Obtains the **Want** object sent from this ability. This API uses a callback to return the result. Obtains the **Want** object sent from this ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel **System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
...@@ -397,8 +392,6 @@ import featureAbility from '@ohos.ability.featureAbility'; ...@@ -397,8 +392,6 @@ import featureAbility from '@ohos.ability.featureAbility';
featureAbility.getWant() featureAbility.getWant()
``` ```
## featureAbility.getWant ## featureAbility.getWant
getWant(): Promise\<Want> getWant(): Promise\<Want>
...@@ -444,13 +437,11 @@ var context = featureAbility.getContext() ...@@ -444,13 +437,11 @@ var context = featureAbility.getContext()
context.getBundleName() context.getBundleName()
``` ```
## featureAbility.terminateSelf<sup>7+</sup> ## featureAbility.terminateSelf<sup>7+</sup>
terminateSelf(callback: AsyncCallback\<void>): void terminateSelf(callback: AsyncCallback\<void>): void
Destroys this Page ability, with the result code and data sent to the caller. This API uses a callback to return the result. Destroys this Page ability, with the result code and data sent to the caller. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel **System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
...@@ -467,8 +458,6 @@ import featureAbility from '@ohos.ability.featureAbility'; ...@@ -467,8 +458,6 @@ import featureAbility from '@ohos.ability.featureAbility';
featureAbility.terminateSelf() featureAbility.terminateSelf()
``` ```
## featureAbility.terminateSelf<sup>7+</sup> ## featureAbility.terminateSelf<sup>7+</sup>
terminateSelf(): Promise\<void> terminateSelf(): Promise\<void>
...@@ -496,7 +485,7 @@ featureAbility.terminateSelf().then((data) => { ...@@ -496,7 +485,7 @@ featureAbility.terminateSelf().then((data) => {
connectAbility(request: Want, options:ConnectOptions): number connectAbility(request: Want, options:ConnectOptions): number
Connects this ability to a specific Service ability. This API uses a callback to return the result. Connects this ability to a specific Service ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel **System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
...@@ -505,17 +494,9 @@ Connects this ability to a specific Service ability. This API uses a callback to ...@@ -505,17 +494,9 @@ Connects this ability to a specific Service ability. This API uses a callback to
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ------- | -------------- | ---- | --------------------- | | ------- | -------------- | ---- | --------------------- |
| request | [Want](js-apis-application-Want.md) | Yes | Service ability to connect.| | request | [Want](js-apis-application-Want.md) | Yes | Service ability to connect.|
| options | ConnectOptions | Yes | Callback used to return the result. | | options | [ConnectOptions](#connectoptions) | Yes | Callback used to return the result. |
Want ## ConnectOptions
**System capability**: SystemCapability.Ability.AbilityBase
| Name | Readable/Writable| Type | Mandatory | Description |
| ----------- | ---- | ------ | ---- | ---------------------------------------- |
| deviceId | Read-only | string | No | Device ID of the Service ability to connect. The default value is the local device ID.|
| bundleName | Read-only | string | Yes | Bundle name of the Service ability to connect. |
| abilityName | Read-only | string | Yes | Class name of the Service ability to connect. |
ConnectOptions ConnectOptions
...@@ -523,9 +504,9 @@ ConnectOptions ...@@ -523,9 +504,9 @@ ConnectOptions
| Name | Readable/Writable| Type | Mandatory | Description | | Name | Readable/Writable| Type | Mandatory | Description |
| ------------ | ---- | -------- | ---- | ------------------------- | | ------------ | ---- | -------- | ---- | ------------------------- |
| onConnect | Read-only | function | Yes | Callback invoked when the connection is successful. | | onConnect<sup>7+</sup> | Read-only | function | Yes | Callback invoked when the connection is successful. |
| onDisconnect | Read-only | function | Yes | Callback invoked when the connection fails. | | onDisconnect<sup>7+</sup> | Read-only | function | Yes | Callback invoked when the connection fails. |
| onFailed | Read-only | function | Yes | Callback invoked when **connectAbility** fails to be called.| | onFailed<sup>7+</sup> | Read-only | function | Yes | Callback invoked when **connectAbility** fails to be called.|
**Return value** **Return value**
...@@ -565,7 +546,7 @@ var connId = featureAbility.connectAbility( ...@@ -565,7 +546,7 @@ var connId = featureAbility.connectAbility(
disconnectAbility(connection: number, callback:AsyncCallback\<void>): void disconnectAbility(connection: number, callback:AsyncCallback\<void>): void
Disconnects this ability from a specific Service ability. This API uses a callback to return the result. Disconnects this ability from a specific Service ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel **System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
...@@ -654,8 +635,10 @@ var connId = featureAbility.connectAbility( ...@@ -654,8 +635,10 @@ var connId = featureAbility.connectAbility(
}, },
); );
featureAbility.disconnectAbility(connId).then((error,data) => { featureAbility.disconnectAbility(connId).then((data) => {
console.log('featureAbilityTest result errCode : ' + error.code + " data: " + data); console.log('data : ' + data);
}).catch((error)=>{
console.log('featureAbilityTest result errCode : ' + error.code);
}); });
``` ```
...@@ -664,7 +647,7 @@ featureAbility.disconnectAbility(connId).then((error,data) => { ...@@ -664,7 +647,7 @@ featureAbility.disconnectAbility(connId).then((error,data) => {
getWindow(callback: AsyncCallback\<window.Window>): void getWindow(callback: AsyncCallback\<window.Window>): void
Obtains the window corresponding to this ability. This API uses a callback to return the result. Obtains the window corresponding to this ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel **System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
...@@ -914,7 +897,7 @@ Enumerates operation types of the Data ability. ...@@ -914,7 +897,7 @@ Enumerates operation types of the Data ability.
## StartAbilityParameter ## StartAbilityParameter
**System capability**: SystemCapability.AbilityRuntime.FAModel **System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
| Name | Readable/Writable| Type | Mandatory | Description | | Name | Readable/Writable| Type | Mandatory | Description |
| ------------------- | ---- | -------------------- | ---- | -------------------------------------- | | ------------------- | ---- | -------------------- | ---- | -------------------------------------- |
...@@ -925,7 +908,7 @@ Enumerates operation types of the Data ability. ...@@ -925,7 +908,7 @@ Enumerates operation types of the Data ability.
**System capability**: SystemCapability.Ability.AbilityBase **System capability**: SystemCapability.Ability.AbilityBase
| Name | Value | Description | | Name | Name | Description |
| ------------------------------------ | ---------- | ---------------------------------------- | | ------------------------------------ | ---------- | ---------------------------------------- |
| FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | Indicates the permission to read the URI. | | FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | Indicates the permission to read the URI. |
| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Indicates the permission to write the URI. | | FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Indicates the permission to write the URI. |
...@@ -933,10 +916,10 @@ Enumerates operation types of the Data ability. ...@@ -933,10 +916,10 @@ Enumerates operation types of the Data ability.
| FLAG_ABILITY_CONTINUATION | 0x00000008 | Indicates whether the ability on the local device can be migrated to a remote device. | | FLAG_ABILITY_CONTINUATION | 0x00000008 | Indicates whether the ability on the local device can be migrated to a remote device. |
| FLAG_NOT_OHOS_COMPONENT | 0x00000010 | Indicates that a component does not belong to OHOS. | | FLAG_NOT_OHOS_COMPONENT | 0x00000010 | Indicates that a component does not belong to OHOS. |
| FLAG_ABILITY_FORM_ENABLED | 0x00000020 | Indicates whether to enable an ability. | | FLAG_ABILITY_FORM_ENABLED | 0x00000020 | Indicates whether to enable an ability. |
| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | Indicates the permission to make the URI persistent. | | FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | Indicates the permission to make the URI persistent.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | Indicates the permission to verify URIs by prefix matching. | | FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | Indicates the permission to verify URIs by prefix matching.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | Supports cross-device startup in a distributed scheduler. | | FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | Supports cross-device startup in a distributed scheduler. |
| FLAG_START_FOREGROUND_ABILITY | 0x00000200 | Indicates that the Service ability is started regardless of whether the host application has been started. | | FLAG_START_FOREGROUND_ABILITY | 0x00000200 | Indicates that the Service ability is started regardless of whether the host application has been started.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that the migration is reversible. | | FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that the migration is reversible. |
| FLAG_INSTALL_ON_DEMAND | 0x00000800 | Indicates that the specific ability will be installed if it has not been installed. | | FLAG_INSTALL_ON_DEMAND | 0x00000800 | Indicates that the specific ability will be installed if it has not been installed. |
| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | Indicates that the specific ability will be installed in the background if it has not been installed. | | FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | Indicates that the specific ability will be installed in the background if it has not been installed. |
......
# FormInfo # FormInfo
The **FormInfo** module provides widget information and state.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Provides widget information.
## Modules to Import ## Modules to Import
``` ```
...@@ -14,15 +14,13 @@ import formInfo from '@ohos.application.formInfo'; ...@@ -14,15 +14,13 @@ import formInfo from '@ohos.application.formInfo';
## Required Permissions ## Required Permissions
None. None
## FormInfo ## FormInfo
Describes widget information. Describes widget information.
**System capability** **System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form
| Name | Readable/Writable| Type | Description | | Name | Readable/Writable| Type | Description |
| ----------- | -------- | -------------------- | ------------------------------------------------------------ | | ----------- | -------- | -------------------- | ------------------------------------------------------------ |
...@@ -43,15 +41,13 @@ SystemCapability.Ability.Form ...@@ -43,15 +41,13 @@ SystemCapability.Ability.Form
| updateDuration | Read only | string | Widget update period.| | updateDuration | Read only | string | Widget update period.|
| defaultDimension | Read only | number | Default dimension of the widget. | | defaultDimension | Read only | number | Default dimension of the widget. |
| supportDimensions | Read only | Array&lt;number&gt; | Dimensions supported by the widget. | | supportDimensions | Read only | Array&lt;number&gt; | Dimensions supported by the widget. |
| customizeData | Read only | {[key: string]: [value: string]} | Custom data of the widget. | | customizeData | Read only | {[key: string]: [value: string]} | Custom data of the widget. |
## FormType ## FormType
Enumerates the widget types. Enumerates the widget types.
**System capability** **System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form
| Name | Value | Description | | Name | Value | Description |
| ----------- | ---- | ------------ | | ----------- | ---- | ------------ |
...@@ -61,13 +57,11 @@ SystemCapability.Ability.Form ...@@ -61,13 +57,11 @@ SystemCapability.Ability.Form
Enumerates the color modes supported by the widget. Enumerates the color modes supported by the widget.
**System capability** **System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form
| Name | Value | Description | | Name | Value | Description |
| ----------- | ---- | ------------ | | ----------- | ---- | ------------ |
| MODE_AUTO | -1 | Automatic mode. | | MODE_AUTO | -1 | Auto mode. |
| MODE_DARK | 0 | Dark mode. | | MODE_DARK | 0 | Dark mode. |
| MODE_LIGHT | 1 | Light mode. | | MODE_LIGHT | 1 | Light mode. |
...@@ -75,22 +69,18 @@ SystemCapability.Ability.Form ...@@ -75,22 +69,18 @@ SystemCapability.Ability.Form
Describes the widget state information. Describes the widget state information.
**System capability** **System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form
| Name | Readable/Writable| Type | Description | | Name | Readable/Writable| Type | Description |
| ----------- | -------- | -------------------- | ------------------------------------------------------------ | | ----------- | -------- | -------------------- | ------------------------------------------------------------ |
| formState | Read only | [FormState](#formstate) | Widget state. | | formState | Read only | [FormState](#formstate) | Widget state. |
| want | Read only | Want | Want text. | | want | Read only | Want | Want text. |
## FormState ## FormState
Enumerates the widget states. Enumerates the widget states.
**System capability** **System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form
| Name | Value | Description | | Name | Value | Description |
| ----------- | ---- | ------------ | | ----------- | ---- | ------------ |
...@@ -102,13 +92,11 @@ SystemCapability.Ability.Form ...@@ -102,13 +92,11 @@ SystemCapability.Ability.Form
Enumerates the widget parameters. Enumerates the widget parameters.
**System capability** **System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form
| Name | Value | Description | | Name | Value | Description |
| ----------- | ---- | ------------ | | ----------- | ---- | ------------ |
| IDENTITY_KEY | "ohos.extra.param.key.form_identity" | ID of a widget. | | IDENTITY_KEY | "ohos.extra.param.key.form_identity" | ID of a widget.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| DIMENSION_KEY | "ohos.extra.param.key.form_dimension" | Widget dimension. | | DIMENSION_KEY | "ohos.extra.param.key.form_dimension" | Widget dimension. |
| NAME_KEY | "ohos.extra.param.key.form_name" | Widget name. | | NAME_KEY | "ohos.extra.param.key.form_name" | Widget name. |
| MODULE_NAME_KEY | "ohos.extra.param.key.module_name" | Name of the module to which the widget belongs. | | MODULE_NAME_KEY | "ohos.extra.param.key.module_name" | Name of the module to which the widget belongs. |
......
# FormBindingData # FormBindingData
The **FormBindingData** module provides APIs for widget data binding. You can use the APIs to create a **FormBindingData** object and obtain related information.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
...@@ -26,7 +28,7 @@ Creates a **FormBindingData** object. ...@@ -26,7 +28,7 @@ Creates a **FormBindingData** object.
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | -------------- | ---- | ------------------------------------------------------------ | | ------ | -------------- | ---- | ------------------------------------------------------------ |
| obj | Object or string| No | Data to be displayed on the JS service widget. The value can be an object containing multiple key-value pairs or a string in JSON format. The image data is identified by "formImages", and the content is multiple key-value pairs, each of which consists of an image identifier and image file descriptor. The final format is {"formImages": {"key1": fd1, "key2": fd2}}.| | obj | Object or string| No | Data to be displayed on the JS widget. The value can be an object containing multiple key-value pairs or a string in JSON format. The image data is identified by "formImages", and the content is multiple key-value pairs, each of which consists of an image identifier and image file descriptor. The final format is {"formImages": {"key1": fd1, "key2": fd2}}.|
**Return value** **Return value**
...@@ -63,4 +65,4 @@ Describes a **FormBindingData** object. ...@@ -63,4 +65,4 @@ Describes a **FormBindingData** object.
| Name| Readable| Writable| Type| Mandatory| Description| | Name| Readable| Writable| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- | -------- |
| data | Yes| No| Object | Yes| Data to be displayed on the JS service widget. The value can be an object containing multiple key-value pairs or a string in JSON format.| | data | Yes| No| Object | Yes| Data to be displayed on the JS widget. The value can be an object containing multiple key-value pairs or a string in JSON format.|
# FormError # FormError
The **FormError** module provides error codes for widgets.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Provides widget-related error codes.
## Modules to Import ## Modules to Import
``` ```
......
# FormExtension # FormExtension
The **FormExtension** module provides APIs related to Form Extension abilities.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Provides **FormExtension** APIs.
## Modules to Import ## Modules to Import
``` ```
...@@ -35,15 +35,15 @@ Called to notify the widget provider that a **Form** instance (widget) has been ...@@ -35,15 +35,15 @@ Called to notify the widget provider that a **Form** instance (widget) has been
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | | ------ | -------------------------------------- | ---- | ------------------------------------------------------------ |
| want | [Want](js-apis-application-Want.md) | Yes | Information related to the extension, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.| | want | [Want](js-apis-application-Want.md) | Yes | Information related to the extension, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ------------------------------------------------------------ | ----------------------------------------------------------- | | ------------------------------------------------------------ | ----------------------------------------------------------- |
| [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.| | [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.|
**Example** **Example**
...@@ -72,9 +72,9 @@ Called to notify the widget provider that a temporary widget has been converted ...@@ -72,9 +72,9 @@ Called to notify the widget provider that a temporary widget has been converted
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------ | | ------ | ------ | ---- | ------------------------ |
| formId | string | Yes | ID of the widget that requests to be converted to a normal one.| | formId | string | Yes | ID of the widget that requests to be converted to a normal one.|
**Example** **Example**
...@@ -96,9 +96,9 @@ Called to notify the widget provider that a widget has been updated. After obtai ...@@ -96,9 +96,9 @@ Called to notify the widget provider that a widget has been updated. After obtai
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------ | | ------ | ------ | ---- | ------------------ |
| formId | string | Yes | ID of the widget that requests to be updated.| | formId | string | Yes | ID of the widget that requests to be updated.|
**Example** **Example**
...@@ -127,9 +127,9 @@ Called to notify the widget provider of the change of visibility. ...@@ -127,9 +127,9 @@ Called to notify the widget provider of the change of visibility.
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| --------- | ------------------------- | ---- | ---------------------------- | | --------- | ------------------------- | ---- | ---------------------------- |
| newStatus | { [key: string]: number } | Yes | ID and visibility status of the widget to be changed.| | newStatus | { [key: string]: number } | Yes | ID and visibility status of the widget to be changed.|
**Example** **Example**
...@@ -162,10 +162,10 @@ Called to instruct the widget provider to receive and process the widget event. ...@@ -162,10 +162,10 @@ Called to instruct the widget provider to receive and process the widget event.
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| ------- | ------ | ---- | ---------------------- | | ------- | ------ | ---- | ---------------------- |
| formId | string | Yes | ID of the widget that requests the event.| | formId | string | Yes | ID of the widget that requests the event.|
| message | string | Yes | Event message. | | message | string | Yes | Event message. |
**Example** **Example**
...@@ -187,9 +187,9 @@ Called to notify the widget provider that a **Form** instance (widget) has been ...@@ -187,9 +187,9 @@ Called to notify the widget provider that a **Form** instance (widget) has been
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------ | | ------ | ------ | ---- | ------------------ |
| formId | string | Yes | ID of the widget to be destroyed.| | formId | string | Yes | ID of the widget to be destroyed.|
**Example** **Example**
...@@ -211,9 +211,9 @@ Called when the configuration of the environment where the ability is running is ...@@ -211,9 +211,9 @@ Called when the configuration of the environment where the ability is running is
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| config | [Configuration](js-apis-configuration.md) | Yes| New configuration.| | config | [Configuration](js-apis-configuration.md) | Yes| New configuration.|
**Example** **Example**
...@@ -225,28 +225,28 @@ Called when the configuration of the environment where the ability is running is ...@@ -225,28 +225,28 @@ Called when the configuration of the environment where the ability is running is
} }
``` ```
## FormExtension.onAcquireFormState ## FormExtension.onAcquireFormState
onAcquireFormState?(want: Want): formInfo.FormState; onAcquireFormState?(want: Want): formInfo.FormState;
Called when the widget provider receives the status query result of a specified service widget. By default, the initial state is returned. Called when the widget provider receives the status query result of a widget. By default, the initial state is returned.
**System capability**: SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | No| Description of the widget state, including the bundle name, ability name, module name, widget name, and widget dimension.| | want | [Want](js-apis-application-Want.md) | No| Description of the widget state, including the bundle name, ability name, module name, widget name, and widget dimension.|
**Example** **Example**
```js ```js
import fromInfo from '@ohos.application.fromInfo' import formInfo from '@ohos.application.formInfo'
class MyFormExtension extends FormExtension { class MyFormExtension extends FormExtension {
onAcquireFormState(want) { onAcquireFormState(want) {
console.log('FormExtension onAcquireFormState, want:' + want); console.log('FormExtension onAcquireFormState, want:' + want);
return fromInfo.FormState.UNKNOWN; return formInfo.FormState.UNKNOWN;
} }
} }
``` ```
# FormExtensionContext # FormExtensionContext
> **NOTE** The **FormExtensionContext** module, inherited from **ExtensionContext**, provides context for Form Extension abilities.
>
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model.
Implements the context that provides the capabilities and APIs of **FormExtension**. This class is inherited from **ExtensionContext**. You can use the APIs of this module to start abilities.
## Modules to Import > **NOTE**
>
```js > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
import FormExtension from '@ohos.application.FormExtension'; > The APIs of this module can be used only in the stage model.
```
## FormExtensionContext.updateForm ## FormExtensionContext.startAbility
updateForm(formId: string, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\<void>): void startAbility(want: Want, callback: AsyncCallback&lt;void&gt;): void
Updates a widget. This method uses a callback to return the result. Starts an ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| --------------- | ------------------------------------------------------------ | ---- | -------------------------------------- | | ------| --------------------------------- | ---- | -------------------------------------- |
| formId | string | Yes | ID of the widget that requests to be updated. | | want| [Want](js-apis-application-Want.md) | Yes | Information about the ability to start, such as the ability name and bundle name.|
| formBindingData | [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | New data of the widget. | | callback| AsyncCallback&lt;void&gt; | Yes | Callback used to return the result.|
| callback | AsyncCallback\<void> | Yes | Callback used to return the result indicating whether the method is successfully called.|
**Example** **Example**
```js ```js
import formBindingData from '@ohos.application.formBindingData' var want = {
export default class MyFormExtension extends FormExtension { deviceId: "",
onUpdate(formId) { bundleName: "com.example.formstartability",
console.log('FormExtension onUpdate, formId:' + formId); abilityName: "MainAbility",
let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); action: "action1",
this.context.updateForm(formId, obj2, (data)=>{ entities: ["entity1"],
console.log('FormExtension context updateForm, data:' + data); type: "MIMETYPE",
}); uri: "key={true,true,false}",
} parameters: {}
} }
this.context.startAbility(want, function(err) {
console.info(err.code);
``` })
```
## FormExtensionContext.updateForm ## FormExtensionContext.startAbility
updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise\<void> startAbility(want: Want): Promise&lt;void&gt;
Updates a widget. This method uses a promise to return the result. Starts an ability. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| --------------- | ------------------------------------------------------------ | ---- | ------------------ | | ------| --------------------------------- | ---- | -------------------------------------- |
| formId | string | Yes | ID of the widget that requests to be updated.| | want| [Want](js-apis-application-Want.md) | Yes | Information about the ability to start, such as the ability name and bundle name.|
| formBindingData | [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | New data of the widget. |
**Return value** **Return value**
| Type | Description | | Type | Description |
| -------------- | --------------------------------- | | ------------ | ---------------------------------- |
| Promise\<void> | Promise returned with the result indicating whether the method is successfully called.| | Promise\<void> | Promise used to return the result.|
**Example** **Example**
```js ```js
import formBindingData from '@ohos.application.formBindingData' var want = {
export default class MyFormExtension extends FormExtension { deviceId: "",
onUpdate(formId) { bundleName: "com.example.formstartability",
console.log('FormExtension onUpdate, formId:' + formId); abilityName: "MainAbility",
let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); action: "action1",
this.context.updateForm(formId, obj2) entities: ["entity1"],
.then((data)=>{ type: "MIMETYPE",
console.log('FormExtension context updateForm, data:' + data); uri: "key={true,true,false}",
}).catch((error) => { parameters: {}
console.error('Operation updateForm failed. Cause: ' + error);}); }
} this.context.startAbility(want).then(() => {
} console.info("StartAbility Success");
}).catch((error) => {
``` console.info("StartAbility failed");
});
```
# FormHost # FormHost
The **FormHost** module provides APIs related to the widget host, which is an application that displays the widget content and controls the position where the widget is displayed. You can use the APIs to delete, release, and update widgets, send notifications to widgets, and obtain widget information and status.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Provides APIs related to the widget host.
## Modules to Import ## Modules to Import
``` ```
...@@ -24,9 +24,11 @@ deleteForm(formId: string, callback: AsyncCallback&lt;void&gt;): void; ...@@ -24,9 +24,11 @@ deleteForm(formId: string, callback: AsyncCallback&lt;void&gt;): void;
Deletes a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. Deletes a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -52,9 +54,11 @@ deleteForm(formId: string): Promise&lt;void&gt;; ...@@ -52,9 +54,11 @@ deleteForm(formId: string): Promise&lt;void&gt;;
Deletes a widget. This API uses a promise to return the result. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. Deletes a widget. This API uses a promise to return the result. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -85,9 +89,11 @@ releaseForm(formId: string, callback: AsyncCallback&lt;void&gt;): void; ...@@ -85,9 +89,11 @@ releaseForm(formId: string, callback: AsyncCallback&lt;void&gt;): void;
Releases a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager still retains the widget cache and storage information. Releases a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager still retains the widget cache and storage information.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -113,9 +119,11 @@ releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback&lt; ...@@ -113,9 +119,11 @@ releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback&lt;
Releases a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. Releases a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -142,9 +150,11 @@ releaseForm(formId: string, isReleaseCache?: boolean): Promise&lt;void&gt;; ...@@ -142,9 +150,11 @@ releaseForm(formId: string, isReleaseCache?: boolean): Promise&lt;void&gt;;
Releases a widget. This API uses a promise to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. Releases a widget. This API uses a promise to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -176,9 +186,11 @@ requestForm(formId: string, callback: AsyncCallback&lt;void&gt;): void; ...@@ -176,9 +186,11 @@ requestForm(formId: string, callback: AsyncCallback&lt;void&gt;): void;
Requests a widget update. This API uses an asynchronous callback to return the result. Requests a widget update. This API uses an asynchronous callback to return the result.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -204,9 +216,11 @@ requestForm(formId: string): Promise&lt;void&gt;; ...@@ -204,9 +216,11 @@ requestForm(formId: string): Promise&lt;void&gt;;
Requests a widget update. This API uses a promise to return the result. Requests a widget update. This API uses a promise to return the result.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -237,9 +251,11 @@ castTempForm(formId: string, callback: AsyncCallback&lt;void&gt;): void; ...@@ -237,9 +251,11 @@ castTempForm(formId: string, callback: AsyncCallback&lt;void&gt;): void;
Converts a temporary widget to a normal one. This API uses an asynchronous callback to return the result. Converts a temporary widget to a normal one. This API uses an asynchronous callback to return the result.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -265,9 +281,11 @@ castTempForm(formId: string): Promise&lt;void&gt;; ...@@ -265,9 +281,11 @@ castTempForm(formId: string): Promise&lt;void&gt;;
Converts a temporary widget to a normal one. This API uses a promise to return the result. Converts a temporary widget to a normal one. This API uses a promise to return the result.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -298,9 +316,11 @@ notifyVisibleForms(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;void ...@@ -298,9 +316,11 @@ notifyVisibleForms(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;void
Instructs the widget framework to make a widget visible. This API uses an asynchronous callback to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. Instructs the widget framework to make a widget visible. This API uses an asynchronous callback to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -326,9 +346,11 @@ notifyVisibleForms(formIds: Array&lt;string&gt;): Promise&lt;void&gt;; ...@@ -326,9 +346,11 @@ notifyVisibleForms(formIds: Array&lt;string&gt;): Promise&lt;void&gt;;
Instructs the widget framework to make a widget visible. This API uses a promise to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. Instructs the widget framework to make a widget visible. This API uses a promise to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -359,9 +381,11 @@ notifyInvisibleForms(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;vo ...@@ -359,9 +381,11 @@ notifyInvisibleForms(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;vo
Instructs the widget framework to make a widget invisible. This API uses an asynchronous callback to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. Instructs the widget framework to make a widget invisible. This API uses an asynchronous callback to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -387,9 +411,11 @@ notifyInvisibleForms(formIds: Array&lt;string&gt;): Promise&lt;void&gt;; ...@@ -387,9 +411,11 @@ notifyInvisibleForms(formIds: Array&lt;string&gt;): Promise&lt;void&gt;;
Instructs the widget framework to make a widget invisible. This API uses a promise to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. Instructs the widget framework to make a widget invisible. This API uses a promise to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -420,9 +446,11 @@ enableFormsUpdate(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;void& ...@@ -420,9 +446,11 @@ enableFormsUpdate(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;void&
Instructs the widget framework to make a widget updatable. This API uses an asynchronous callback to return the result. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. Instructs the widget framework to make a widget updatable. This API uses an asynchronous callback to return the result. After this API is called, the widget is in the enabled state and can receive updates from the widget provider.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -448,9 +476,11 @@ enableFormsUpdate(formIds: Array&lt;string&gt;): Promise&lt;void&gt;; ...@@ -448,9 +476,11 @@ enableFormsUpdate(formIds: Array&lt;string&gt;): Promise&lt;void&gt;;
Instructs the widget framework to make a widget updatable. This API uses a promise to return the result. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. Instructs the widget framework to make a widget updatable. This API uses a promise to return the result. After this API is called, the widget is in the enabled state and can receive updates from the widget provider.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -481,9 +511,11 @@ disableFormsUpdate(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;void ...@@ -481,9 +511,11 @@ disableFormsUpdate(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;void
Instructs the widget framework to make a widget not updatable. This API uses an asynchronous callback to return the result. After this API is called, the widget cannot receive updates from the widget provider. Instructs the widget framework to make a widget not updatable. This API uses an asynchronous callback to return the result. After this API is called, the widget cannot receive updates from the widget provider.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -509,9 +541,11 @@ disableFormsUpdate(formIds: Array&lt;string&gt;): Promise&lt;void&gt;; ...@@ -509,9 +541,11 @@ disableFormsUpdate(formIds: Array&lt;string&gt;): Promise&lt;void&gt;;
Instructs the widget framework to make a widget not updatable. This API uses a promise to return the result. After this API is called, the widget cannot receive updates from the widget provider. Instructs the widget framework to make a widget not updatable. This API uses a promise to return the result. After this API is called, the widget cannot receive updates from the widget provider.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -542,9 +576,9 @@ isSystemReady(callback: AsyncCallback&lt;void&gt;): void; ...@@ -542,9 +576,9 @@ isSystemReady(callback: AsyncCallback&lt;void&gt;): void;
Checks whether the system is ready. This API uses an asynchronous callback to return the result. Checks whether the system is ready. This API uses an asynchronous callback to return the result.
**System capability** **System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -569,9 +603,9 @@ isSystemReady(): Promise&lt;void&gt;; ...@@ -569,9 +603,9 @@ isSystemReady(): Promise&lt;void&gt;;
Checks whether the system is ready. This API uses a promise to return the result. Checks whether the system is ready. This API uses a promise to return the result.
**System capability** **System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Return value** **Return value**
...@@ -596,9 +630,11 @@ getAllFormsInfo(callback: AsyncCallback&lt;Array&lt;formInfo.FormInfo&gt;&gt;): ...@@ -596,9 +630,11 @@ getAllFormsInfo(callback: AsyncCallback&lt;Array&lt;formInfo.FormInfo&gt;&gt;):
Obtains the widget information provided by all applications on the device. This API uses an asynchronous callback to return the result. Obtains the widget information provided by all applications on the device. This API uses an asynchronous callback to return the result.
**System capability** **Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -625,9 +661,11 @@ getAllFormsInfo(): Promise&lt;Array&lt;formInfo.FormInfo&gt;&gt;; ...@@ -625,9 +661,11 @@ getAllFormsInfo(): Promise&lt;Array&lt;formInfo.FormInfo&gt;&gt;;
Obtains the widget information provided by all applications on the device. This API uses a promise to return the result. Obtains the widget information provided by all applications on the device. This API uses a promise to return the result.
**System capability** **Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Return value** **Return value**
...@@ -652,9 +690,11 @@ getFormsInfo(bundleName: string, callback: AsyncCallback&lt;Array&lt;formInfo.Fo ...@@ -652,9 +690,11 @@ getFormsInfo(bundleName: string, callback: AsyncCallback&lt;Array&lt;formInfo.Fo
Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result.
**System capability** **Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -682,9 +722,11 @@ getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback&lt; ...@@ -682,9 +722,11 @@ getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback&lt;
Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result.
**System capability** **Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -713,9 +755,11 @@ getFormsInfo(bundleName: string, moduleName?: string): Promise&lt;Array&lt;formI ...@@ -713,9 +755,11 @@ getFormsInfo(bundleName: string, moduleName?: string): Promise&lt;Array&lt;formI
Obtains the widget information provided by a given application on the device. This API uses a promise to return the result. Obtains the widget information provided by a given application on the device. This API uses a promise to return the result.
**System capability** **Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -746,9 +790,11 @@ deleteInvalidForms(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;numb ...@@ -746,9 +790,11 @@ deleteInvalidForms(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;numb
Deletes invalid widgets from the list. This API uses an asynchronous callback to return the result. Deletes invalid widgets from the list. This API uses an asynchronous callback to return the result.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -776,9 +822,11 @@ deleteInvalidForms(formIds: Array&lt;string&gt;): Promise&lt;number&gt;; ...@@ -776,9 +822,11 @@ deleteInvalidForms(formIds: Array&lt;string&gt;): Promise&lt;number&gt;;
Deletes invalid widgets from the list. This API uses a promise to return the result. Deletes invalid widgets from the list. This API uses a promise to return the result.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -809,9 +857,11 @@ acquireFormState(want: Want, callback: AsyncCallback&lt;formInfo.FormStateInfo&g ...@@ -809,9 +857,11 @@ acquireFormState(want: Want, callback: AsyncCallback&lt;formInfo.FormStateInfo&g
Obtains the widget state. This API uses an asynchronous callback to return the result. Obtains the widget state. This API uses an asynchronous callback to return the result.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -848,6 +898,12 @@ acquireFormState(want: Want): Promise&lt;formInfo.FormStateInfo&gt;; ...@@ -848,6 +898,12 @@ acquireFormState(want: Want): Promise&lt;formInfo.FormStateInfo&gt;;
Obtains the widget state. This API uses a promise to return the result. Obtains the widget state. This API uses a promise to return the result.
**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
**System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
...@@ -860,10 +916,6 @@ Obtains the widget state. This API uses a promise to return the result. ...@@ -860,10 +916,6 @@ Obtains the widget state. This API uses a promise to return the result.
| :------------ | :---------------------------------- | | :------------ | :---------------------------------- |
| Promise&lt;[FormStateInfo](js-apis-formInfo.md#formstateinfo)&gt; | Promise used to return the widget state.| | Promise&lt;[FormStateInfo](js-apis-formInfo.md#formstateinfo)&gt; | Promise used to return the widget state.|
**System capability**
SystemCapability.Ability.Form
**Example** **Example**
```js ```js
...@@ -890,9 +942,9 @@ on(type: "formUninstall", callback: Callback&lt;string&gt;): void; ...@@ -890,9 +942,9 @@ on(type: "formUninstall", callback: Callback&lt;string&gt;): void;
Subscribes to widget uninstall events. Subscribes to widget uninstall events.
**System capability** **System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -916,9 +968,9 @@ off(type: "formUninstall", callback?: Callback&lt;string&gt;): void; ...@@ -916,9 +968,9 @@ off(type: "formUninstall", callback?: Callback&lt;string&gt;): void;
Unsubscribes from widget uninstall events. Unsubscribes from widget uninstall events.
**System capability** **System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -942,9 +994,11 @@ notifyFormsVisible(formIds: Array&lt;string&gt;, isVisible: boolean, callback: A ...@@ -942,9 +994,11 @@ notifyFormsVisible(formIds: Array&lt;string&gt;, isVisible: boolean, callback: A
Instructs the widgets to make themselves visible. This API uses an asynchronous callback to return the result. Instructs the widgets to make themselves visible. This API uses an asynchronous callback to return the result.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -971,9 +1025,11 @@ notifyFormsVisible(formIds: Array&lt;string&gt;, isVisible: boolean): Promise&lt ...@@ -971,9 +1025,11 @@ notifyFormsVisible(formIds: Array&lt;string&gt;, isVisible: boolean): Promise&lt
Instructs the widgets to make themselves visible. This API uses a promise to return the result. Instructs the widgets to make themselves visible. This API uses a promise to return the result.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -1005,9 +1061,11 @@ notifyFormsEnableUpdate(formIds: Array&lt;string&gt;, isEnableUpdate: boolean, c ...@@ -1005,9 +1061,11 @@ notifyFormsEnableUpdate(formIds: Array&lt;string&gt;, isEnableUpdate: boolean, c
Instructs the widgets to enable or disable updates. This API uses an asynchronous callback to return the result. Instructs the widgets to enable or disable updates. This API uses an asynchronous callback to return the result.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
SystemCapability.Ability.Form **System capability**: SystemCapability.Ability.Form
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
...@@ -1034,9 +1092,11 @@ notifyFormsEnableUpdate(formIds: Array&lt;string&gt;, isEnableUpdate: boolean): ...@@ -1034,9 +1092,11 @@ notifyFormsEnableUpdate(formIds: Array&lt;string&gt;, isEnableUpdate: boolean):
Instructs the widgets to enable or disable updates. This API uses a promise to return the result. Instructs the widgets to enable or disable updates. This API uses a promise to return the result.
**System capability** **Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
SystemCapability.Ability.Form **System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
......
# FormProvider # FormProvider
The **FormProvider** module provides APIs related to the widget provider. You can use the APIs to update a widget, set the next refresh time for a widget, obtain widget information, and release a widget release. The **FormProvider** module provides APIs related to the widget provider. You can use the APIs to update a widget, set the next refresh time for a widget, obtain widget information, and request a widget release.
> **NOTE** > **NOTE**
> >
...@@ -28,11 +28,11 @@ SystemCapability.Ability.Form ...@@ -28,11 +28,11 @@ SystemCapability.Ability.Form
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------- | | ------ | ------ | ---- | ------------------------------------- |
| formId | string | Yes | ID of a widget. | | formId | string | Yes | ID of a widget. |
| minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | | minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. |
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.| | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
**Example** **Example**
...@@ -57,16 +57,16 @@ SystemCapability.Ability.Form ...@@ -57,16 +57,16 @@ SystemCapability.Ability.Form
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------- | | ------ | ------ | ---- | ------------------------------------- |
| formId | string | Yes | ID of a widget. | | formId | string | Yes | ID of a widget. |
| minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | | minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. |
**Return value** **Return value**
| Type | Description | | Type | Description |
| ------------- | ---------------------------------- | | ------------- | ---------------------------------- |
| Promise\<void> |Promise used to return the result. | | Promise\<void> |Promise used to return the result. |
**Example** **Example**
...@@ -91,11 +91,11 @@ SystemCapability.Ability.Form ...@@ -91,11 +91,11 @@ SystemCapability.Ability.Form
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | | ------ | ---------------------------------------------------------------------- | ---- | ---------------- |
| formId | string | Yes | ID of the widget to update.| | formId | string | Yes | ID of the widget to update.|
| formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data to be used for the update. | | formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data to be used for the update. |
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.| | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
**Example** **Example**
...@@ -122,10 +122,10 @@ SystemCapability.Ability.Form ...@@ -122,10 +122,10 @@ SystemCapability.Ability.Form
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | | ------ | ---------------------------------------------------------------------- | ---- | ---------------- |
| formId | string | Yes | ID of the widget to update.| | formId | string | Yes | ID of the widget to update.|
| formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data to be used for the update. | | formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data to be used for the update. |
**Return value** **Return value**
......
# missionManager # missionManager
The **missionManager** module provides APIs to lock, unlock, and clear missions, and switch a mission to the foreground.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
missionManager provides APIs to lock, unlock, and clear missions, and switch a mission to the foreground.
## Modules to Import ## Modules to Import
``` ```
...@@ -23,8 +22,12 @@ registerMissionListener(listener: MissionListener): number; ...@@ -23,8 +22,12 @@ registerMissionListener(listener: MissionListener): number;
Registers a listener to observe the mission status. Registers a listener to observe the mission status.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -59,8 +62,12 @@ unregisterMissionListener(listenerId: number, callback: AsyncCallback&lt;void&gt ...@@ -59,8 +62,12 @@ unregisterMissionListener(listenerId: number, callback: AsyncCallback&lt;void&gt
Deregisters a mission status listener. This API uses an asynchronous callback to return the result. Deregisters a mission status listener. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -93,8 +100,12 @@ unregisterMissionListener(listenerId: number): Promise&lt;void&gt;; ...@@ -93,8 +100,12 @@ unregisterMissionListener(listenerId: number): Promise&lt;void&gt;;
Deregisters a mission status listener. This API uses a promise to return the result. Deregisters a mission status listener. This API uses a promise to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -132,8 +143,12 @@ getMissionInfo(deviceId: string, missionId: number, callback: AsyncCallback&lt;M ...@@ -132,8 +143,12 @@ getMissionInfo(deviceId: string, missionId: number, callback: AsyncCallback&lt;M
Obtains the information about a given mission. This API uses an asynchronous callback to return the result. Obtains the information about a given mission. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -166,8 +181,12 @@ getMissionInfo(deviceId: string, missionId: number): Promise&lt;MissionInfo&gt;; ...@@ -166,8 +181,12 @@ getMissionInfo(deviceId: string, missionId: number): Promise&lt;MissionInfo&gt;;
Obtains the information about a given mission. This API uses a promise to return the result. Obtains the information about a given mission. This API uses a promise to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -198,8 +217,12 @@ getMissionInfos(deviceId: string, numMax: number, callback: AsyncCallback&lt;Arr ...@@ -198,8 +217,12 @@ getMissionInfos(deviceId: string, numMax: number, callback: AsyncCallback&lt;Arr
Obtains information about all missions. This API uses an asynchronous callback to return the result. Obtains information about all missions. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -227,8 +250,12 @@ getMissionInfos(deviceId: string, numMax: number): Promise&lt;Array&lt;MissionIn ...@@ -227,8 +250,12 @@ getMissionInfos(deviceId: string, numMax: number): Promise&lt;Array&lt;MissionIn
Obtains information about all missions. This API uses a promise to return the result. Obtains information about all missions. This API uses a promise to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -259,8 +286,12 @@ getMissionSnapShot(deviceId: string, missionId: number, callback: AsyncCallback& ...@@ -259,8 +286,12 @@ getMissionSnapShot(deviceId: string, missionId: number, callback: AsyncCallback&
Obtains the snapshot of a given mission. This API uses an asynchronous callback to return the result. Obtains the snapshot of a given mission. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -294,8 +325,12 @@ getMissionSnapShot(deviceId: string, missionId: number): Promise&lt;MissionSnaps ...@@ -294,8 +325,12 @@ getMissionSnapShot(deviceId: string, missionId: number): Promise&lt;MissionSnaps
Obtains the snapshot of a given mission. This API uses a promise to return the result. Obtains the snapshot of a given mission. This API uses a promise to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -334,8 +369,12 @@ lockMission(missionId: number, callback: AsyncCallback&lt;void&gt;): void; ...@@ -334,8 +369,12 @@ lockMission(missionId: number, callback: AsyncCallback&lt;void&gt;): void;
Locks a given mission. This API uses an asynchronous callback to return the result. Locks a given mission. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -367,8 +406,12 @@ lockMission(missionId: number): Promise&lt;void&gt;; ...@@ -367,8 +406,12 @@ lockMission(missionId: number): Promise&lt;void&gt;;
Locks a given mission. This API uses a promise to return the result. Locks a given mission. This API uses a promise to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -405,8 +448,12 @@ unlockMission(missionId: number, callback: AsyncCallback&lt;void&gt;): void; ...@@ -405,8 +448,12 @@ unlockMission(missionId: number, callback: AsyncCallback&lt;void&gt;): void;
Unlocks a given mission. This API uses an asynchronous callback to return the result. Unlocks a given mission. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -438,8 +485,12 @@ unlockMission(missionId: number): Promise&lt;void&gt;; ...@@ -438,8 +485,12 @@ unlockMission(missionId: number): Promise&lt;void&gt;;
Unlocks a given mission. This API uses a promise to return the result. Unlocks a given mission. This API uses a promise to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -480,8 +531,12 @@ clearMission(missionId: number, callback: AsyncCallback&lt;void&gt;): void; ...@@ -480,8 +531,12 @@ clearMission(missionId: number, callback: AsyncCallback&lt;void&gt;): void;
Clears a given mission, regardless of whether it is locked. This API uses an asynchronous callback to return the result. Clears a given mission, regardless of whether it is locked. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -513,8 +568,12 @@ clearMission(missionId: number): Promise&lt;void&gt;; ...@@ -513,8 +568,12 @@ clearMission(missionId: number): Promise&lt;void&gt;;
Clears a given mission, regardless of whether it is locked. This API uses a promise to return the result. Clears a given mission, regardless of whether it is locked. This API uses a promise to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -552,8 +611,12 @@ clearAllMissions(callback: AsyncCallback&lt;void&gt;): void; ...@@ -552,8 +611,12 @@ clearAllMissions(callback: AsyncCallback&lt;void&gt;): void;
Clears all unlocked missions. This API uses an asynchronous callback to return the result. Clears all unlocked missions. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Example** **Example**
```js ```js
...@@ -571,8 +634,12 @@ clearAllMissions(): Promise&lt;void&gt;; ...@@ -571,8 +634,12 @@ clearAllMissions(): Promise&lt;void&gt;;
Clears all unlocked missions. This API uses a promise to return the result. Clears all unlocked missions. This API uses a promise to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Return value** **Return value**
| Type| Description| | Type| Description|
...@@ -595,8 +662,12 @@ moveMissionToFront(missionId: number, callback: AsyncCallback&lt;void&gt;): void ...@@ -595,8 +662,12 @@ moveMissionToFront(missionId: number, callback: AsyncCallback&lt;void&gt;): void
Switches a given mission to the foreground. This API uses an asynchronous callback to return the result. Switches a given mission to the foreground. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -628,8 +699,12 @@ moveMissionToFront(missionId: number, options: StartOptions, callback: AsyncCall ...@@ -628,8 +699,12 @@ moveMissionToFront(missionId: number, options: StartOptions, callback: AsyncCall
Switches a given mission to the foreground, with the startup parameters for the switching specified. This API uses an asynchronous callback to return the result. Switches a given mission to the foreground, with the startup parameters for the switching specified. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -662,8 +737,12 @@ moveMissionToFront(missionId: number, options?: StartOptions): Promise&lt;void&g ...@@ -662,8 +737,12 @@ moveMissionToFront(missionId: number, options?: StartOptions): Promise&lt;void&g
Switches a given mission to the foreground, with the startup parameters for the switching specified. This API uses a promise to return the result. Switches a given mission to the foreground, with the startup parameters for the switching specified. This API uses a promise to return the result.
**Required permission**: ohos.permission.MANAGE_MISSIONS
**System capability**: SystemCapability.Ability.AbilityRuntime.Mission **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -699,7 +778,9 @@ Switches a given mission to the foreground, with the startup parameters for the ...@@ -699,7 +778,9 @@ Switches a given mission to the foreground, with the startup parameters for the
Describes the mission information. Describes the mission information.
**System capability**: SystemCapability.Ability.AbilityBase **System capability**: SystemCapability.Ability.AbilityRuntime.Mission
**System API**: This is a system API and cannot be called by third-party applications.
| Name| Type| Readable| Writable| Description| | Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
...@@ -710,4 +791,4 @@ Describes the mission information. ...@@ -710,4 +791,4 @@ Describes the mission information.
| want | [Want](js-apis-application-Want.md) | Yes| Yes| **Want** information of the mission.| | want | [Want](js-apis-application-Want.md) | Yes| Yes| **Want** information of the mission.|
| label | string | Yes| Yes| Label of the mission.| | label | string | Yes| Yes| Label of the mission.|
| iconPath | string | Yes| Yes| Path of the mission icon.| | iconPath | string | Yes| Yes| Path of the mission icon.|
| continuable | boolean | Yes| Yes| Whether the mission can be continued on another device. | | continuable | boolean | Yes| Yes| Whether the mission can be continued on another device.|
# ParticleAbility # particleAbility
The **particleAbility** module provides APIs for Service abilities. You can use the APIs to start and terminate a Particle ability, obtain a **dataAbilityHelper** object, connect the current ability to a specific Service ability, and disconnect the current ability from a specific Service ability.
> **NOTE** > **NOTE**
> >
......
# PermissionRequestResult # PermissionRequestResult
The **PermissionRequestResult** module provides the result of a permission request.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Provides the permission request result. ## Usage
## Modules to Import
```js
import Ability from '@ohos.application.Ability'
```
## How to Use
The permission request result is obtained through an **AbilityStage** instance. The permission request result is obtained through an **AbilityStage** instance.
......
# ProcessRunningInfo # ProcessRunningInfo
The **ProcessRunningInfo** module provides process running information.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Provides process running information.
## Modules to Import
```js
import appManager from '@ohos.application.appManager'
```
## Usage ## Usage
...@@ -23,7 +17,6 @@ appManager.getProcessRunningInfos((error,data) => { ...@@ -23,7 +17,6 @@ appManager.getProcessRunningInfos((error,data) => {
}); });
``` ```
## Attributes ## Attributes
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
......
# ServiceExtensionAbility # ServiceExtensionAbility
The **ServiceExtensionAbility** module provides APIs for Service Extension abilities.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Provides APIs related to **ServiceExtension**.
## Modules to Import ## Modules to Import
``` ```
...@@ -21,24 +21,28 @@ None. ...@@ -21,24 +21,28 @@ None.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name| Type| Readable| Writable| Description| **System API**: This is a system API and cannot be called by third-party applications.
| Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| context | [ServiceExtensionContext](js-apis-service-extension-context.md) | Yes| No| Service extension context, which is inherited from **ExtensionContext**.| | context | [ServiceExtensionContext](js-apis-service-extension-context.md) | Yes| No| Service Extension context, which is inherited from **ExtensionContext**.|
## ServiceExtensionAbility.onCreate ## ServiceExtensionAbility.onCreate
onCreate(want: Want): void; onCreate(want: Want): void;
Called when an extension is created to initialize the service logic. Called when a Service Extension ability is created to initialize the service logic.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information related to this extension, including the ability name and bundle name.| | want | [Want](js-apis-application-Want.md) | Yes| Information related to this Service Extension ability, including the ability name and bundle name.|
**Example** **Example**
...@@ -55,10 +59,12 @@ Called when an extension is created to initialize the service logic. ...@@ -55,10 +59,12 @@ Called when an extension is created to initialize the service logic.
onDestroy(): void; onDestroy(): void;
Called when this extension is destroyed to clear resources. Called when this Service Extension ability is destroyed to clear resources.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Example** **Example**
```js ```js
...@@ -74,16 +80,18 @@ Called when this extension is destroyed to clear resources. ...@@ -74,16 +80,18 @@ Called when this extension is destroyed to clear resources.
onRequest(want: Want, startId: number): void; onRequest(want: Want, startId: number): void;
Called after **onCreate** is invoked when an ability is started by calling **startAbility**. The value of **startId** is incremented for each ability that is started. Called after **onCreate** is invoked when a Service Extension ability is started by calling **startAbility**. The value of **startId** is incremented for each ability that is started.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information related to this extension, including the ability name and bundle name.| | want | [Want](js-apis-application-Want.md) | Yes| Information related to this Service Extension ability, including the ability name and bundle name.|
| startId | number | Yes| Number of ability start times. The initial value is **1**, and the value is automatically incremented for each ability started.| | startId | number | Yes| Number of ability start times. The initial value is **1**, and the value is automatically incremented for each ability started.|
**Example** **Example**
...@@ -100,21 +108,23 @@ Called after **onCreate** is invoked when an ability is started by calling **sta ...@@ -100,21 +108,23 @@ Called after **onCreate** is invoked when an ability is started by calling **sta
onConnect(want: Want): rpc.RemoteObject; onConnect(want: Want): rpc.RemoteObject;
Called after **onCreate** is invoked when an ability is started by calling **connectAbility**. A **RemoteObject** object is returned for communication with the client. Called after **onCreate** is invoked when a Service Extension ability is started by calling **connectAbility**. A **RemoteObject** object is returned for communication with the client.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md)| Yes| Information related to this extension, including the ability name and bundle name.| | want | [Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.|
**Return value** **Return value**
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| rpc.RemoteObject | A **RemoteObject** object used for communication with the client.| | rpc.RemoteObject | A **RemoteObject** object used for communication with the client.|
**Example** **Example**
...@@ -140,15 +150,17 @@ Called after **onCreate** is invoked when an ability is started by calling **con ...@@ -140,15 +150,17 @@ Called after **onCreate** is invoked when an ability is started by calling **con
onDisconnect(want: Want): void; onDisconnect(want: Want): void;
Called when the ability is disconnected. Called when this Service Extension ability is disconnected.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| want |[Want](js-apis-application-Want.md)| Yes| Information related to this extension, including the ability name and bundle name.| | want |[Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.|
**Example** **Example**
...@@ -159,3 +171,82 @@ Called when the ability is disconnected. ...@@ -159,3 +171,82 @@ Called when the ability is disconnected.
} }
} }
``` ```
## ServiceExtensionAbility.onReconnect
onReconnect(want: Want): void;
Called when this Service Extension ability is reconnected.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want |[Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.|
**Example**
```js
class ServiceExt extends ServiceExtension {
onDisconnect(want) {
console.log('onDisconnect, want:' + want.abilityName);
}
}
```
## ServiceExtensionAbility.onConfigurationUpdated
onConfigurationUpdated(config: Configuration): void;
Called when the configuration of this Service Extension ability is updated.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| config | [Configuration](js-apis-configuration.md) | Yes| New configuration.|
**Example**
```js
class ServiceExt extends ServiceExtension {
onConfigurationUpdated(config) {
console.log('onConfigurationUpdated, config:' + JSON.stringify(config));
}
}
```
## ServiceExtensionAbility.dump
dump(params: Array\<string>): Array\<string>;
Dumps the client information.
**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| params | Array\<string> | Yes| Parameters in the form of a command.|
**Example**
```js
class ServiceExt extends ServiceExtension {
dump(params) {
console.log('dump, params:' + JSON.stringify(params));
return ["params"]
}
}
```
# ServiceExtensionContext # ServiceExtensionContext
The **ServiceExtensionContext** module, inherited from **ExtensionContext**, provides context for Service Extension abilities.
You can use the APIs of this module to start, terminate, connection, and disconnect abilities.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model. > The APIs of this module can be used only in the stage model.
Implements the context that provides the capabilities and APIs of **ServiceExtension**. This class is inherited from **ExtensionContext**. ## Usage
## Modules to Import Before using the **ServiceExtensionContext** module, you must define a child class that inherits from **ServiceExtensionAbility**.
``` ```js
import ExtensionContext from '@ohos.application.ServiceExtensionAbility'; import ServiceExtensionAbility from '@ohos.application.ServiceExtensionAbility';
class MainAbility extends ServiceExtensionAbility {
onCreate() {
let context = this.context;
}
}
``` ```
## startAbility ## startAbility
...@@ -21,6 +30,8 @@ Starts an ability. This API uses a callback to return the result. ...@@ -21,6 +30,8 @@ Starts an ability. This API uses a callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -31,34 +42,30 @@ Starts an ability. This API uses a callback to return the result. ...@@ -31,34 +42,30 @@ Starts an ability. This API uses a callback to return the result.
**Example** **Example**
```js ```js
import ExtensionContext from '@ohos.application.ServiceExtensionAbility'; let want = {
class MainAbility extends ExtensionContext { "bundleName": "com.example.myapp",
onWindowStageCreate(windowStage) { "abilityName": "MyAbility"};
let want = { this.context.startAbility(want, (err) => {
"bundleName": "com.example.myapp", console.log('startAbility result:' + JSON.stringify(err));
"abilityName": "MyAbility"}; });
this.context.startAbility(want, (err) => {
console.log('startAbility result:' + JSON.stringify(err));
});
}
}
``` ```
## startAbility
## ServiceExtensionContext.startAbility startAbility(want: Want, options?: StartOptions): Promise\<void>;
startAbility(want: Want): Promise&lt;void&gt;;
Starts an ability. This API uses a promise to return the result. Starts an ability. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the ability to start, such as the ability name and bundle name.| | want | [Want](js-apis-application-Want.md) | Yes| Information about the ability to start, such as the ability name and bundle name.|
| options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.|
**Return value** **Return value**
...@@ -69,24 +76,428 @@ Starts an ability. This API uses a promise to return the result. ...@@ -69,24 +76,428 @@ Starts an ability. This API uses a promise to return the result.
**Example** **Example**
```js ```js
import ExtensionContext from '@ohos.application.ServiceExtensionAbility'; let want = {
class MainAbility extends ExtensionContext { "bundleName": "com.example.myapp",
onWindowStageCreate(windowStage) { "abilityName": "MyAbility"
let want = { };
"bundleName": "com.example.myapp", this.context.startAbility(want).then((data) => {
"abilityName": "MyAbility" console.log('success:' + JSON.stringify(data));
}; }).catch((error) => {
this.context.startAbility(want).then((data) => { console.log('failed:' + JSON.stringify(error));
console.log('success:' + JSON.stringify(data)); });
}).catch((error) => {
console.log('failed:' + JSON.stringify(error)); ```
});
} ## startAbility
}
startAbility(want: Want, options: StartOptions, callback: AsyncCallback&lt;void&gt;): void
Starts an ability. This API uses a callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var options = {
windowMode: 0,
};
this.context.startAbility(want, options, (error) => {
console.log("error.code = " + error.code)
})
```
## ServiceExtensionContext.startAbilityWithAccount
startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void;
Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
this.context.startAbilityWithAccount(want, accountId, (err) => {
console.log('---------- startAbilityWithAccount fail, err: -----------', err);
});
```
## ServiceExtensionContext.startAbilityWithAccount
startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\<void\>): void;
Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
var options = {
windowMode: 0,
};
this.context.startAbilityWithAccount(want, accountId, options, (err) => {
console.log('---------- startAbilityWithAccount fail, err: -----------', err);
});
```
## ServiceExtensionContext.startAbilityWithAccount
startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\<void>;
Starts an ability with the account ID specified. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
var options = {
windowMode: 0,
};
this.context.startAbilityWithAccount(want, accountId, options)
.then((data) => {
console.log('---------- startAbilityWithAccount success, data: -----------', data);
})
.catch((err) => {
console.log('---------- startAbilityWithAccount fail, err: -----------', err);
})
``` ```
## ServiceExtensionContext.startServiceExtensionAbility
startServiceExtensionAbility(want: Want, callback: AsyncCallback\<void>): void;
Starts a new Service Extension ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
this.context.startServiceExtensionAbility(want, (err) => {
console.log('---------- startServiceExtensionAbility fail, err: -----------', err);
});
```
## ServiceExtensionContext.startServiceExtensionAbility
startServiceExtensionAbility(want: Want): Promise\<void>;
Starts a new Service Extension ability. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
this.context.startServiceExtensionAbility(want)
.then((data) => {
console.log('---------- startServiceExtensionAbility success, data: -----------', data);
})
.catch((err) => {
console.log('---------- startServiceExtensionAbility fail, err: -----------', err);
})
```
## ServiceExtensionContext.startServiceExtensionAbilityWithAccount
startServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void;
Starts a new Service Extension ability with the account ID specified. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
this.context.startServiceExtensionAbilityWithAccount(want,accountId, (err) => {
console.log('---------- startServiceExtensionAbilityWithAccount fail, err: -----------', err);
});
```
## ServiceExtensionContext.startServiceExtensionAbilityWithAccount
startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void>;
Starts a new Service Extension ability with the account ID specified. This API uses a promise to return the result.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
this.context.startServiceExtensionAbilityWithAccount(want,accountId)
.then((data) => {
console.log('---------- startServiceExtensionAbilityWithAccount success, data: -----------', data);
})
.catch((err) => {
console.log('---------- startServiceExtensionAbilityWithAccount fail, err: -----------', err);
})
```
## ServiceExtensionContext.stopServiceExtensionAbility
stopServiceExtensionAbility(want: Want, callback: AsyncCallback\<void>): void;
Stops Service Extension abilities in the same application. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
this.context.stopServiceExtensionAbility(want, (err) => {
console.log('---------- stopServiceExtensionAbility fail, err: -----------', err);
});
```
## ServiceExtensionContext.stopServiceExtensionAbility
stopServiceExtensionAbility(want: Want): Promise\<void>;
Stops Service Extension abilities in the same application. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
this.context.stopServiceExtensionAbility(want)
.then((data) => {
console.log('---------- stopServiceExtensionAbility success, data: -----------', data);
})
.catch((err) => {
console.log('---------- stopServiceExtensionAbility fail, err: -----------', err);
})
```
## ServiceExtensionContext.stopServiceExtensionAbilityWithAccount
stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void;
Stops Service Extension abilities in the same application with the account ID specified. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
this.context.stopServiceExtensionAbilityWithAccount(want,accountId, (err) => {
console.log('---------- stopServiceExtensionAbilityWithAccount fail, err: -----------', err);
});
```
## ServiceExtensionContext.stopServiceExtensionAbilityWithAccount
stopServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void>;
Stops Service Extension abilities in the same application with the account ID specified. This API uses a promise to return the result.
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
this.context.stopServiceExtensionAbilityWithAccount(want,accountId)
.then((data) => {
console.log('---------- stopServiceExtensionAbilityWithAccount success, data: -----------', data);
})
.catch((err) => {
console.log('---------- stopServiceExtensionAbilityWithAccount fail, err: -----------', err);
})
```
## ServiceExtensionContext.terminateSelf ## ServiceExtensionContext.terminateSelf
...@@ -96,6 +507,8 @@ Terminates this ability. This API uses a callback to return the result. ...@@ -96,6 +507,8 @@ Terminates this ability. This API uses a callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -105,19 +518,11 @@ Terminates this ability. This API uses a callback to return the result. ...@@ -105,19 +518,11 @@ Terminates this ability. This API uses a callback to return the result.
**Example** **Example**
```js ```js
import ExtensionContext from '@ohos.application.ServiceExtensionAbility'; this.context.terminateSelf((err) => {
class MainAbility extends ExtensionContext { console.log('terminateSelf result:' + JSON.stringify(err));
onWindowStageCreate(windowStage) { });
this.context.terminateSelf((err) => {
console.log('terminateSelf result:' + JSON.stringify(err));
});
}
}
``` ```
## ServiceExtensionContext.terminateSelf ## ServiceExtensionContext.terminateSelf
terminateSelf(): Promise&lt;void&gt;; terminateSelf(): Promise&lt;void&gt;;
...@@ -126,6 +531,8 @@ Terminates this ability. This API uses a promise to return the result. ...@@ -126,6 +531,8 @@ Terminates this ability. This API uses a promise to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Return value** **Return value**
| Type| Description| | Type| Description|
...@@ -135,20 +542,13 @@ Terminates this ability. This API uses a promise to return the result. ...@@ -135,20 +542,13 @@ Terminates this ability. This API uses a promise to return the result.
**Example** **Example**
```js ```js
import ExtensionContext from '@ohos.application.ServiceExtensionAbility'; this.context.terminateSelf().then((data) => {
class MainAbility extends ExtensionContext { console.log('success:' + JSON.stringify(data));
onWindowStageCreate(windowStage) { }).catch((error) => {
this.context.terminateSelf().then((data) => { console.log('failed:' + JSON.stringify(error));
console.log('success:' + JSON.stringify(data)); });
}).catch((error) => {
console.log('failed:' + JSON.stringify(error));
});
}
}
``` ```
## ServiceExtensionContext.connectAbility ## ServiceExtensionContext.connectAbility
connectAbility(want: Want, options: ConnectOptions): number; connectAbility(want: Want, options: ConnectOptions): number;
...@@ -157,12 +557,14 @@ Connects this ability to a Service ability. ...@@ -157,12 +557,14 @@ Connects this ability to a Service ability.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the ability to connect to, such as the ability name and bundle name.| | want | [Want](js-apis-application-Want.md) | Yes| Information about the ability to connect to, such as the ability name and bundle name.|
| options | [ConnectOptions](#connectoptions) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.| | options | [ConnectOptions](js-apis-featureAbility.md#connectoptions) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.|
**Return value** **Return value**
...@@ -174,17 +576,58 @@ Connects this ability to a Service ability. ...@@ -174,17 +576,58 @@ Connects this ability to a Service ability.
```js ```js
let want = { let want = {
"bundleName": "com.example.myapp", "bundleName": "com.example.myapp",
"abilityName": "MyAbility" "abilityName": "MyAbility"
}; };
let options = { let options = {
onConnect: function(elementName, proxy) {}, onConnect(elementName, remote) { console.log('----------- onConnect -----------') },
onDisConnect: function(elementName) {}, onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
onFailed: function(code) {} onFailed(code) { console.log('----------- onFailed -----------') }
} }
let connection = this.context.connectAbility(want,options); let connection = this.context.connectAbility(want,options);
``` ```
## ServiceExtensionContext.connectAbilityWithAccount
connectAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number;
Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect this ability to another ability.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.|
| accountId | number | Yes| ID of the account.|
| options | ConnectOptions | No| Remote object instance.|
**Return value**
| Type| Description|
| -------- | -------- |
| number | Result code of the ability connection.|
**Example**
```js
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var accountId = 100;
var options = {
onConnect(elementName, remote) { console.log('----------- onConnect -----------') },
onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
onFailed(code) { console.log('----------- onFailed -----------') }
}
const result = this.context.connectAbilityWithAccount(want, accountId, options);
console.log('----------- connectAbilityResult: ------------', result);
```
## ServiceExtensionContext.disconnectAbility ## ServiceExtensionContext.disconnectAbility
...@@ -194,6 +637,8 @@ Disconnects this ability from the Service ability. This API uses a callback to r ...@@ -194,6 +637,8 @@ Disconnects this ability from the Service ability. This API uses a callback to r
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -204,21 +649,13 @@ Disconnects this ability from the Service ability. This API uses a callback to r ...@@ -204,21 +649,13 @@ Disconnects this ability from the Service ability. This API uses a callback to r
**Example** **Example**
```js ```js
import ExtensionContext from '@ohos.application.ServiceExtensionAbility'; let connection=1
class MainAbility extends ExtensionContext { this.context.disconnectAbility(connection, (err) => {
onWindowStageCreate(windowStage) {
let connection=1
this.context.disconnectAbility(connection, (err) => {
// connection is the return value of connectAbility. // connection is the return value of connectAbility.
console.log('terminateSelf result:' + JSON.stringify(err)); console.log('terminateSelf result:' + JSON.stringify(err));
}); });
}
}
``` ```
## ServiceExtensionContext.disconnectAbility ## ServiceExtensionContext.disconnectAbility
disconnectAbility(connection: number): Promise&lt;void&gt;; disconnectAbility(connection: number): Promise&lt;void&gt;;
...@@ -227,6 +664,8 @@ Disconnects this ability from the Service ability. This API uses a promise to re ...@@ -227,6 +664,8 @@ Disconnects this ability from the Service ability. This API uses a promise to re
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
...@@ -242,29 +681,11 @@ Disconnects this ability from the Service ability. This API uses a promise to re ...@@ -242,29 +681,11 @@ Disconnects this ability from the Service ability. This API uses a promise to re
**Example** **Example**
```js ```js
import ExtensionContext from '@ohos.application.ServiceExtensionAbility'; let connection=1
class MainAbility extends ExtensionContext { this.context.disconnectAbility(connection).then((data) => {
onWindowStageCreate(windowStage) { // connection is the return value of connectAbility.
let connection=1
this.context.disconnectAbility(connection).then((data) => { // connection is the return value of connectAbility.
console.log('success:' + JSON.stringify(data)); console.log('success:' + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
console.log('failed:' + JSON.stringify(error)); console.log('failed:' + JSON.stringify(error));
}); });
}
}
``` ```
## ConnectOptions
Defines the **ConnectOptions** data structure.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
| Name| Description|
| -------- | -------- |
| onConnect(elementName:ElementName,&nbsp;remote:IRemoteObject) | Called when this ability is connected to a Service ability.|
| onDisconnect(elementName:ElementName) | Called when the peer service is abnormal or killed.|
| onFailed(code:&nbsp;number) | Called when the connection fails.|
# TestRunner # TestRunner
The **TestRunner** module provides a test framework. You can use the APIs of this module to prepare the unit test environment and run test cases.
To implement your own unit test framework, extend this class and override its APIs.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
...@@ -10,8 +14,6 @@ ...@@ -10,8 +14,6 @@
import TestRunner from '@ohos.application.testRunner' import TestRunner from '@ohos.application.testRunner'
``` ```
## TestRunner.onPrepare ## TestRunner.onPrepare
onPrepare(): void onPrepare(): void
...@@ -23,10 +25,11 @@ Prepares the unit test environment to run test cases. ...@@ -23,10 +25,11 @@ Prepares the unit test environment to run test cases.
**Example** **Example**
```js ```js
export default class UserTestRunner extends TestRunner { export default class UserTestRunner implements TestRunner {
onPrepare() { onPrepare() {
console.log("Trigger onPrepare") console.log("Trigger onPrepare")
} }
onRun(){}
}; };
``` ```
...@@ -43,9 +46,10 @@ Runs test cases. ...@@ -43,9 +46,10 @@ Runs test cases.
**Example** **Example**
```js ```js
export default class UserTestRunner extends TestRunner { export default class UserTestRunner implements TestRunner {
onRun() { onPrepare() {
console.log("Trigger onRun") console.log("Trigger onRun")
} }
onRun(){}
}; };
``` ```
# WantAgent # WantAgent
The **WantAgent** module provides APIs for triggering, canceling, and comparing **WantAgent** objects. You can use the APIs to create a **WantAgent** object, and obtain the user ID, bundle name, and want information of the object.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
...@@ -418,6 +420,8 @@ Obtains the want in a **WantAgent** object. This API uses an asynchronous callba ...@@ -418,6 +420,8 @@ Obtains the want in a **WantAgent** object. This API uses an asynchronous callba
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name | Readable| Writable| Type | Mandatory| Description | | Name | Readable| Writable| Type | Mandatory| Description |
...@@ -490,6 +494,8 @@ Obtains the want in a **WantAgent** object. This API uses a promise to return th ...@@ -490,6 +494,8 @@ Obtains the want in a **WantAgent** object. This API uses a promise to return th
**System capability**: SystemCapability.Ability.AbilityRuntime.Core **System capability**: SystemCapability.Ability.AbilityRuntime.Core
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters** **Parameters**
| Name | Readable| Writable| Type | Mandatory| Description | | Name | Readable| Writable| Type | Mandatory| Description |
...@@ -704,7 +710,7 @@ Triggers a **WantAgent** object. This API uses an asynchronous callback to retur ...@@ -704,7 +710,7 @@ Triggers a **WantAgent** object. This API uses an asynchronous callback to retur
| Name | Readable| Writable| Type | Mandatory| Description | | Name | Readable| Writable| Type | Mandatory| Description |
| ----------- | --- | ---- | ----------------------------- | ---- | ------------------------------- | | ----------- | --- | ---- | ----------------------------- | ---- | ------------------------------- |
| agent | Yes | No | WantAgent | Yes | **WantAgent** object to trigger. | | agent | Yes | No | WantAgent | Yes | Target **WantAgent** object. |
| triggerInfo | Yes | No | TriggerInfo | Yes | **TriggerInfo** object. | | triggerInfo | Yes | No | TriggerInfo | Yes | **TriggerInfo** object. |
| callback | Yes | No | AsyncCallback\<CompleteData\> | Yes | Callback used to return the result.| | callback | Yes | No | AsyncCallback\<CompleteData\> | Yes | Callback used to return the result.|
...@@ -1052,7 +1058,7 @@ WantAgent.getOperationType(wantAgent).then((OperationType) => { ...@@ -1052,7 +1058,7 @@ WantAgent.getOperationType(wantAgent).then((OperationType) => {
| Name | Readable| Writable| Type | Mandatory| Description | | Name | Readable| Writable| Type | Mandatory| Description |
| -------------- | --- | ---- | ------------------------------- | ---- | ---------------------- | | -------------- | --- | ---- | ------------------------------- | ---- | ---------------------- |
| wants | Yes | Yes | Array\<Want\> | Yes | Array of all **Want** objects. | | wants | Yes | Yes | Array\<Want\> | Yes | Array of all **Want** objects. |
| operationType | Yes | Yes | wantAgent.OperationType | Yes | Action type. | | operationType | Yes | Yes | wantAgent.OperationType | Yes | Operation type. |
| requestCode | Yes | Yes | number | Yes | Request code defined by the user.| | requestCode | Yes | Yes | number | Yes | Request code defined by the user.|
| wantAgentFlags | Yes | Yes | Array<wantAgent.WantAgentFlags> | No | Array of flags for using the **WantAgent** object. | | wantAgentFlags | Yes | Yes | Array<wantAgent.WantAgentFlags> | No | Array of flags for using the **WantAgent** object. |
| extraInfo | Yes | Yes | {[key: string]: any} | No | Extra information. | | extraInfo | Yes | Yes | {[key: string]: any} | No | Extra information. |
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册