From 078a106497227145a699bf6286218a07dcb477d4 Mon Sep 17 00:00:00 2001 From: wuliubao Date: Wed, 19 Jan 2022 17:31:03 +0800 Subject: [PATCH] =?UTF-8?q?IssueNo:#I4PCWF:=E3=80=90=E8=B5=84=E6=96=99?= =?UTF-8?q?=E3=80=91=E6=9C=8D=E5=8A=A1=E7=BB=84=E4=BB=B6=E8=AF=B4=E6=98=8E?= =?UTF-8?q?=20Description:=E6=8F=90=E4=BE=9B=E6=9C=8D=E5=8A=A1=E7=BB=84?= =?UTF-8?q?=E4=BB=B6=E6=96=B0=E5=A2=9E/=E5=A2=9E=E5=BC=BA=E7=89=B9?= =?UTF-8?q?=E6=80=A7=E8=B5=84=E6=96=99=E8=AF=B4=E6=98=8E=20Sig:SIG=5FAppli?= =?UTF-8?q?cationFramework=20Feature=20or=20Bugfix:Feature=20Binary=20Sour?= =?UTF-8?q?ce:No?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by:wuliubao --- .../reference/apis/js-apis-ability-context.md | 216 ++++++++++++++++++ .../apis/js-apis-extension-context.md | 11 + .../apis/js-apis-service-extension-context.md | 191 ++++++++++++++++ .../apis/js-apis-service-extension.md | 132 +++++++++++ 4 files changed, 550 insertions(+) create mode 100644 zh-cn/application-dev/reference/apis/js-apis-ability-context.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-extension-context.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-service-extension-context.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-service-extension.md diff --git a/zh-cn/application-dev/reference/apis/js-apis-ability-context.md b/zh-cn/application-dev/reference/apis/js-apis-ability-context.md new file mode 100644 index 0000000000..5392f5b038 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-ability-context.md @@ -0,0 +1,216 @@ +# AbilityContext + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +Ability的上下文环境，继承自Context。 + + +## 属性 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| abilityInfo | AbilityInfo | 是 | 否 | Abilityinfo相关信息 | +| currentHapModuleInfo | HapModuleInfo | 是 | 否 | 当前hap包的信息 | + + +## startAbility + +startAbility(want: Want, callback: AsyncCallback<void>): void + +启动Ability。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | 启动Ability的want信息。 | + | callback | AsyncCallback<void> | 是 | callback形式返回启动结果 | + +- 示例： + ``` + 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): Promise<void> + +启动Ability。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | 启动Ability的want信息。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | Promise形式返回启动结果。 | + +- 示例： + ``` + var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "com.extreme.test.MainAbility" + }; + this.context.startAbility(want) + .then((data) => { + console.log('Operation successful.') + }).catch((error) => { + console.log('Operation failed.'); + }) + ``` + + +## startAbilityForResult + +startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void + +启动Ability并在结束的时候返回执行结果。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | 启动Ability的want信息。 | + | callback | Callback<[AbilityResult](js-apis-featureAbility.md#AbilityResult类型说明)> | 是 | 执行结果回调函数。 | + +- 示例： + ``` + this.context.startAbilityForResult( + {bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo2"}, + (error, result) => { + console.log("startAbilityForResult AsyncCallback is called, error.code = " + error.code) + console.log("startAbilityForResult AsyncCallback is called, result.resultCode = " + result.resultCode) + } + ); + ``` + + +## startAbilityForResult + +startAbilityForResult(want: Want): Promise<AbilityResult> + +启动Ability并在结束的时候返回执行结果。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | 启动Ability的want信息。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | Promise<[AbilityResult](js-apis-featureAbility.md#AbilityResult类型说明)> | Promise形式返回执行结果。 | + +- 示例： + ``` + this.context.startAbilityForResult({bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo2"}).then((result) => { + console.log("startAbilityForResult Promise.resolve is called, result.resultCode = " + result.resultCode) + }, (error) => { + console.log("startAbilityForResult Promise.Reject is called, error.code = " + error.code) + }) + ``` + + +## terminateSelf + +terminateSelf(callback: AsyncCallback<void>): void + +停止自身。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 | + +- 示例： + ``` + this.context.terminateSelf((err) => { + console.log('terminateSelf result:' + JSON.stringfy(err); + } + ``` + + +## terminateSelf + +terminateSelf(): Promise<void> + +停止自身。 + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 返回一个Promise，包含接口的结果。 | + +- 示例： + ``` + this.context.terminateSelf(want).then((data) => { + console.log('success:' + JSON.stringfy(data)); + )).catch((error) => { + console.log('failed:' + JSON.stringfy(error)); + }); + ``` + + +## terminateSelfWithResult + +terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void + +停止Ability并返回给startAbilityForResult 调用方的信息。 + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | parameter | [AbilityResult](js-apis-featureAbility.md#AbilityResult类型说明) | 是 | 返回给startAbilityForResult 调用方的信息。 | + | callback | Callback<void> | 否 | callback形式返回停止结果 | + +- 示例： + ``` + this.context.terminateSelfWithResult( + { + want: {bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo"}, + resultCode: 100 + }, (error) => { + console.log("terminateSelfWithResult is called = " + error.code) + } + ); + ``` + + +## terminateSelfWithResult + +terminateSelfWithResult(parameter: AbilityResult): Promise<void> + +停止Ability并返回给startAbilityForResult 调用方的信息。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | parameter | [AbilityResult](js-apis-featureAbility.md#AbilityResult类型说明) | 是 | 返回给startAbilityForResult 调用方的信息。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | promise形式返回停止结果 | + +- 示例： + ``` + this.context.terminateSelfWithResult( + { + want: {bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo"}, + resultCode: 100 + }).then((result) => { + console.log("terminateSelfWithResult") + } + ) + ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-extension-context.md b/zh-cn/application-dev/reference/apis/js-apis-extension-context.md new file mode 100644 index 0000000000..49ab751724 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-extension-context.md @@ -0,0 +1,11 @@ +# ExtensionContext + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +Extension的上下文环境，继承自Context。 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| currentHapModuleInfo | HapModuleInfo | 是 | 否 | 当前Hap包的信息。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-service-extension-context.md b/zh-cn/application-dev/reference/apis/js-apis-service-extension-context.md new file mode 100644 index 0000000000..644ffc6219 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-service-extension-context.md @@ -0,0 +1,191 @@ +# ServiceExtensionContext + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +ServiceExtension的上下文环境，提供ServiceExtension具有的能力和接口，继承自ExtensionContext。 + +## startAbility + +startAbility(want: Want, callback: AsyncCallback<void>): void + + +启动Ability。 + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | Want类型参数，传入需要启动的ability的信息，如ability名称，包名等。 | + | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 | + +- 示例： + ``` + let want = { + "bundleName": "com.example.myapp", + "abilityName": "com.example.myapp.MyAbility" + }; + this.context.startAbility(want, (err) => { + console.log('startAbility result:' + JSON.stringfy(err); + } + ``` + + +## startAbility + +startAbility(want: Want): Promise<void> + +启动Ability。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | Want类型参数，传入需要启动的ability的信息，如ability名称，包名等。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 返回一个Promise，包含接口的结果。 | + +- 示例： + ``` + let want = { + "bundleName": "com.example.myapp", + "abilityName": "com.example.myapp.MyAbility" + }; + this.context.startAbility(want).then((data) => { + console.log('success:' + JSON.stringfy(data)); + )).catch((error) => { + console.log('failed:' + JSON.stringfy(error)); + }); + ``` + + +## terminateSelf + +terminateSelf(callback: AsyncCallback<void>): void + +停止自身。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 | + +- 示例： + ``` + this.context.terminateSelf((err) => { + console.log('terminateSelf result:' + JSON.stringfy(err); + } + ``` + + +## terminateSelf + +terminateSelf(): Promise<void> + +停止自身。 + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 返回一个Promise，包含接口的结果。 | + +- 示例： + ``` + 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 + +启动Ability。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | Want类型参数，传入需要启动的ability的信息，如ability名称，包名等。 | + | options | [ConnectOptions](#connectoptions) | 是 | ConnectOptions类型的回调函数，返回服务连接成功、断开或连接失败后的信息。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | number | 返回一个number，后续根据这个number去断开连接。 | + +- 示例： + ``` + let want = { + "bundleName": "com.example.myapp", + "abilityName": "com.example.myapp.MyAbility" + }; + let options = { + onConnect: function(elementName, proxy) {} + onDisConnect: function(elementName) {} + onFailed: function(code) {} + } + let connection = this.context.connectAbility(want,options); + ``` + + +## disconnectAbility + +disconnectAbility(connection: number, callback:AsyncCallback<void>): void + +启动Ability。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | connection | number | 是 | 在connectAbility中返回的number。 | + | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 | + +- 示例： + ``` + this.context.disconnectAbility(connection, (err) => { // connection为connectAbility中的返回值 + console.log('terminateSelf result:' + JSON.stringfy(err); + } + ``` + + +## disconnectAbility + +disconnectAbility(connection: number): Promise<void> + +启动Ability。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | connection | number | 是 | 在connectAbility中返回的number。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 返回一个Promise，包含接口的结果。 | + +- 示例： + ``` + this.context.disconnectAbility(connection).then((data) => { // connection为connectAbility中的返回值 + console.log('success:' + JSON.stringfy(data)); + )).catch((error) => { + console.log('failed:' + JSON.stringfy(error)); + }); + ``` + + +## ConnectOptions + +ConnectOptions数据结构。 + +| 名称 | 说明 | +| -------- | -------- | +| onConnect(elementName:ElementName, remote:IRemoteObject) | Ability成功连接一个服务类型Ability的回调接口。 | +| onDisconnect(elementName:ElementName) | 对端服务发生异常或者被杀死回调该接口。 | +| onFailed(code: number) | 连接失败时回调该接口。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-service-extension.md b/zh-cn/application-dev/reference/apis/js-apis-service-extension.md new file mode 100644 index 0000000000..79aa8f1779 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-service-extension.md @@ -0,0 +1,132 @@ +# ServiceExtension + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +提供ServiceExtension先关服务接口。 + + +## 导入模块 + +``` +import ServiceExtension from '@ohos.application.ServiceExtension'; +``` + + +## 权限 + +无 + + +## 属性 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| context | [ServiceExtensionContext](js-apis-service-extension-context.md) | 是 | 否 | ServiceExtension的上下文环境，继承自ExtensionContext。 | + + +## onCreate + +onCreate(want: Want): void + +Extension的生命周期，在创建时回调，可以做一些初始化操作。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 | + +- 示例： + ``` + onCreate(want) { + console.log('onCreate, want:' + want.abilityName); + } + ``` + + +## onDestroy + +onDestroy(): void + +Extension的生命周期，在销毁时回调，可以做资源清理等操作。 + +- 示例： + ``` + onDestroy() { + console.log('onDestroy'); + } + ``` + + +## onRequest + +onRequest(want: Want, startId: number): void + +Extension的生命周期，如果是startAbility拉起的服务，会在onCreate之后回调。每次拉起服务都会回调，startId会递增。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 | + | startId | number | 是 | 首次拉起值是1，多次拉起会递增。 | + +- 示例： + ``` + onRequest(want: Want, startId: number) { + console.log('onRequest, want:' + want.abilityName); + } + ``` + + +## onConnect + +onConnect(want: Want): rpc.RemoteObject + +Extension的生命周期，如果是connectAbility拉起的服务，会在onCreate之后回调。返回一个RemoteObject对象，用于和客户端进行通信。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | rpc.RemoteObject | 一个RemoteObject对象，用于和客户端进行通信。 | + +- 示例： + ``` + import rpc from '@ohos.rpc' + class StubTest extends rpc.RemoteObject{ + constructor(des) { + super(des); + } + onRemoteRequest(code, data, reply, option) { + } + } + ... + onConnect(want) { + console.log('onConnect , want:' + want.abilityName); + return new StubTest("test"); + } + ``` + + +## onDisconnect + +onDisconnect(want: Want): void + +Extension的生命周期，断开服务连接时回调。 + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 | + +- 示例： + ``` + onDisconnect(want) { + console.log('onDisconnect, want:' + want.abilityName); + } + ``` -- GitLab