diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index d17726d0077e2506ca4337342d84f07c00233274..f7c9b469e10d06763183f9f488aefa0ca39d5775 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -43,6 +43,10 @@ - application/[ProcessRunningInfo](js-apis-processrunninginfo.md) - application/[ServiceExtensionContext](js-apis-service-extension-context.md) - application/[shellCmdResult](js-apis-application-shellCmdResult.md) + - application/[AbilityManager (AbilityManager)](js-apis-abilityManager.md) + - application/[ExtensionAbilityContext (ExtensionAbilityContext)](js-apis-extension-ability-context.md) + - application/[ExtensionAbilityInfo (ExtensionAbilityInfo)](js-apis-extensionAbilityInfo.md) + - application/[ServiceExtAbilityContext (ServiceExtAbilityContext)](js-apis-serviceExtAbilityContext.md) - Common Event and Notification - [@ohos.commonEvent](js-apis-commonEvent.md) diff --git a/en/application-dev/reference/apis/js-apis-abilityManager.md b/en/application-dev/reference/apis/js-apis-abilityManager.md new file mode 100644 index 0000000000000000000000000000000000000000..ccd0cd96c51f747588cb30bd7a3144fd34534c9c --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-abilityManager.md @@ -0,0 +1,204 @@ +# AbilityManager + +> **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. +> +> API version 9 is a canary version for trial use. The APIs of this version may be unstable. + +# Modules to Import + +```js +import AbilityManager from '@ohos.application.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. | + + +## updateConfiguration + +updateConfiguration(config: Configuration, callback: AsyncCallback\): void + +Updates the configuration. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------------- | +| config | Configuration | Yes | New configuration.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Example** + +```js +import abilitymanager from '@ohos.application.abilityManager'; + +var config = { + language: 'chinese' +} + +abilitymanager.updateConfiguration(config, () => { + console.log('------------ updateConfiguration -----------'); +}) +``` + +## updateConfiguration + +updateConfiguration(config: Configuration): Promise\ + +Updates the configuration. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------------- | +| config | Configuration | Yes | New configuration.| + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------- | +| Promise\ | Promised used to return the result.| + +**Example** + +```js +import abilitymanager from '@ohos.application.abilityManager'; + +var config = { + language: 'chinese' +} + +abilitymanager.updateConfiguration(config).then(() => { + console.log('updateConfiguration success'); +}).catch((err) => { + console.log('updateConfiguration fail'); +}) +``` + +## getAbilityRunningInfos + +getAbilityRunningInfos(callback: AsyncCallback\>): void + +Obtains the ability running information. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------------- | +| callback | AsyncCallback\> | Yes | Callback used to return the result. | + +**Example** + +```js +import abilitymanager from '@ohos.application.abilityManager'; + +abilitymanager.getAbilityRunningInfos((err,data) => { + console.log("getAbilityRunningInfos err: " + err + " data: " + JSON.stringify(data)); +}); +``` + +## getAbilityRunningInfos + +getAbilityRunningInfos(): Promise\> + +Obtains the ability running information. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------- | +| Promise\> | Promised used to return the result.| + +**Example** + +```js +import abilitymanager from '@ohos.application.abilityManager'; + +abilitymanager.getAbilityRunningInfos().then((data) => { + console.log("getAbilityRunningInfos data: " + JSON.stringify(data)) +}).catch((err) => { + console.log("getAbilityRunningInfos err: " + err) +}); +``` + +## getExtensionRunningInfos9+ + +getExtensionRunningInfos(upperLimit: number, callback: AsyncCallback\>): void + +Obtains the extension running information. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------------- | +| upperLimit | number | Yes| Maximum number of messages that can be obtained.| +| callback | AsyncCallback\> | Yes | Callback used to return the result. | + +**Example** + +```js +import abilitymanager from '@ohos.application.abilityManager'; + +var upperLimit = 0; + +abilitymanager.getExtensionRunningInfos(upperLimit, (err,data) => { + console.log("getExtensionRunningInfos err: " + err + " data: " + JSON.stringify(data)); +}); +``` + +## getExtensionRunningInfos9+ + +getExtensionRunningInfos(upperLimit: number): Promise\> + +Obtains the extension running information. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------------- | +| upperLimit | number | Yes| Maximum number of messages that can be obtained.| + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------- | +| Promise\> | Promised used to return the result.| + +**Example** + +```js +import abilitymanager from '@ohos.application.abilityManager'; + +var upperLimit = 0; + +abilitymanager.getExtensionRunningInfos(upperLimit).then((data) => { + console.log("getAbilityRunningInfos data: " + JSON.stringify(data)); +}).catch((err) => { + console.log("getAbilityRunningInfos err: " + err); +}) +``` diff --git a/en/application-dev/reference/apis/js-apis-extension-ability-context.md b/en/application-dev/reference/apis/js-apis-extension-ability-context.md new file mode 100644 index 0000000000000000000000000000000000000000..62064b2b315190772607710faaf150db36d65491 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-extension-ability-context.md @@ -0,0 +1,17 @@ +# ExtensionAbilityContext + +> **NOTE**
+> +> The initial APIs of this module are supported since API version 9. API version 9 is a canary version for trial use. The APIs of this version may be unstable. + + +Implements the Extension ability context. This module is inherited from **Context**. + + +## Attributes + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| currentHapModuleInfo | HapModuleInfo | Yes| No| Information about the current HAP file. | diff --git a/en/application-dev/reference/apis/js-apis-extensionAbilityInfo.md b/en/application-dev/reference/apis/js-apis-extensionAbilityInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..abee12afeee1aebc4fc898217719b50924a29fb4 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-extensionAbilityInfo.md @@ -0,0 +1,28 @@ +# ExtensionAbilityInfo + +> **NOTE**
+> +> The initial APIs of this module are supported since API version 9. API version 9 is a canary version for trial use. The APIs of this version may be unstable. + +## AbilityInfo + +Provides the ability information. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Readable | Writable | Description | +| --------------------- | --------------------- | ---- | ---- | ------------------------ | +| bundleName | string | Yes | No | Bundle name of the application. | +| moduleName | string | Yes | No | Name of the HAP file to which the ability belongs. | +| name | string | Yes | No | Ability name. | +| labelId | number | Yes | No | Ability label ID. | +| descriptionId | number | Yes | No | Ability description ID. | +| iconId | number | Yes | No | Ability icon ID. | +| isVisible | boolean | Yes | No | Whether the ability can be called by other applications. | +| extensionAbilityType | bundle.ExtensionAbilityType | Yes | No | Type of the Extension ability. | +| permissions | Array\ | Yes | No | Permissions required for other applications to call the ability.| +| applicationInfo | ApplicationInfo | Yes | No | Application configuration information. | +| metaData | Array\ | Yes | No | Metadata of the ability. | +| enabled | boolean | Yes | No | Whether the ability is enabled. | +| readPermission | string | Yes | No | Permission required for reading the ability data. | +| writePermission | string | Yes | No | Permission required for writing data to the ability. | diff --git a/en/application-dev/reference/apis/js-apis-serviceExtAbilityContext.md b/en/application-dev/reference/apis/js-apis-serviceExtAbilityContext.md new file mode 100644 index 0000000000000000000000000000000000000000..2647c44803988d63acf8d9f80d9f402033e60207 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-serviceExtAbilityContext.md @@ -0,0 +1,414 @@ +# ServiceExtAbilityContext + + +> **NOTE**
+> +> The initial APIs of this module are supported since API version 9. API version 9 is a canary version for trial use. The APIs of this version may be unstable. + + +## Attributes + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| extensionAbilityInfo | ExtensionAbilityInfo | Yes| No| Extension ability information. | + + +## startAbility + +startAbility(want: Want, callback: AsyncCallback<void>): void + +Starts an ability. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-featureAbility.md#want)| 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": "com.extreme.test.MainAbility" +}; +this.context.startAbility(want, (error) => { + console.log("error.code = " + error.code) +}) +``` + +## startAbility + +startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void + +Starts an ability with **options** specified. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-featureAbility.md#want) | Yes| Information about the **Want** used for starting an ability.| +| options | StartOptions | 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": "com.extreme.test.MainAbility" +}; +var options = { + windowMode: 0, +}; +this.context.startAbility(want, options, (error) => { + console.log("error.code = " + error.code) +}) +``` + + +## startAbility + +startAbility(want: Want, options: StartOptions): Promise<void> + +Starts an ability with **options** specified. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-featureAbility.md#want)| Yes| Information about the **Want** used for starting an ability.| +| options | StartOptions | Yes| Parameters used for starting the ability.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the result.| + +**Example** +```js +var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "com.extreme.test.MainAbility" +}; +var options = { + windowMode: 0, +}; +this.context.startAbility(want, options) +.then((data) => { + console.log('Operation successful.') +}).catch((error) => { + console.log('Operation failed.'); +}) +``` + +## startAbilityWithAccount + +startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\): void + +Starts an ability based on an account. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-featureAbility.md#want)| Yes| Information about the **Want** used for starting an ability.| +| accountId | number | Yes| Account ID. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + +```js +var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "com.extreme.test.MainAbility" +}; +var accountId = 11; +this.context.startAbility(want, accountId, (error) => { + console.log("error.code = " + error.code) +}) +``` + +## startAbilityWithAccount + +startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\): void + +Starts an ability based on an account and **options**. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-featureAbility.md#want) | Yes| Information about the **Want** used for starting an ability.| +| accountId | number | Yes| Account ID. | +| options | StartOptions | 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": "com.extreme.test.MainAbility" +}; +var options = { + windowMode: 0, +}; +var accountId = 11; +this.context.startAbility(want, accountId, options, (error) => { + console.log("error.code = " + error.code) +}) +``` + + +## startAbilityWithAccount + +startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\ + +Starts an ability based on an account and **options**. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-featureAbility.md#want)| Yes| Information about the **Want** used for starting an ability.| +| accountId | number | Yes| Account ID. | +| options | StartOptions | No| Parameters used for starting the ability.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the result.| + +**Example** +```js +var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "com.extreme.test.MainAbility" +}; +var options = { + windowMode: 0, +}; +var accountId = 11; +this.context.startAbility(want, accountId, options) +.then((data) => { + console.log('Operation successful.') +}).catch((error) => { + console.log('Operation failed.'); +}) +``` + +## terminateSelf + +terminateSelf(callback: AsyncCallback<void>): void + +Terminates 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<void> | Yes| Callback used to return the result.| + +**Example** + +```js +this.context.terminateSelf((err) => { + console.log('terminateSelf result:' + JSON.stringfy(err)); +}); +``` + +## terminateSelf + +terminateSelf(): Promise<void> + +Terminates this ability. 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 +this.context.terminateSelf(want).then((data) => { + console.log('success:' + JSON.stringfy(data)); +}).catch((error) => { + console.log('failed:' + JSON.stringfy(error)); +}); +``` + + +## 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 + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-featureAbility.md#want)| Yes| Information about the **Want** used for starting an ability.| +| options | ConnectOptions | Yes| Connection channel.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| number | ID of the connection between the two abilities.| + +**Example** +```js +var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "com.extreme.test.MainAbility" +} +var options = { + onConnect: (elementName, remote) => { + console.log('connectAbility onConnect, elementName: ' + elementName + ', remote: ' remote) + }, + onDisconnect: (elementName) => { + console.log('connectAbility onDisconnect, elementName: ' + elementName) + }, + onFailed: (code) => { + console.log('connectAbility onFailed, code: ' + code) + } +} +this.context.connectAbility(want, options) { + console.log('code: ' + code) +} +``` + +## connectAbilityWithAccount + +connectAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number + +Uses the **AbilityInfo.AbilityType.SERVICE** template to connect this ability to another ability based on an account. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-featureAbility.md#want)| Yes| Information about the **Want** used for starting an ability.| +| accountId | number | Yes| Account ID.| +| options | ConnectOptions | Yes| Connection channel.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| number | ID of the connection between the two abilities.| + +**Example** +```js +var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "com.extreme.test.MainAbility" +} +var accountId = 111; +var options = { + onConnect: (elementName, remote) => { + console.log('connectAbility onConnect, elementName: ' + elementName + ', remote: ' remote) + }, + onDisconnect: (elementName) => { + console.log('connectAbility onDisconnect, elementName: ' + elementName) + }, + onFailed: (code) => { + console.log('connectAbility onFailed, code: ' + code) + } +} +this.context.connectAbility(want, accountId, options) { + console.log('code: ' + code) +} +``` + +## disconnectAbility + +disconnectAbility(connection: number, callback:AsyncCallback): void + +Disconnects this ability from another ability. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| connection | number | Yes| ID of the connection to be disconnected.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + +```js +var connection = 111; +this.context.disconnectAbility(connection, () => { + console.log('disconnection') +}) +``` + +## disconnectAbility + +disconnectAbility(connection: number): Promise + +Disconnects this ability from another ability. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| connection | number | Yes| ID of the connection to be disconnected.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +var connection = 111; +this.context.disconnectAbility(connection).then(() => { + console.log('disconnected successfully') +}).catch((err) => { + console.log('disconnected failed') +}) +```