!1253 提供服务组件新增/增强特性资料说明

Merge pull request !1253 from 刘宝/master

zh-cn/application-dev/reference/apis/js-apis-ability-context.md

+# AbilityContext
+
+- [属性](#属性)
+- [startAbility](#startAbility)
+- [startAbility](#startAbility)
+- [startAbilityForResult](#startAbilityForResult)
+- [startAbilityForResult](#startAbilityForResult)
+- [terminateSelf](#terminateSelf)
+- [terminateSelf](#terminateSelf)
+- [terminateSelfWithResult](#terminateSelfWithResult)
+- [terminateSelfWithResult](#terminateSelfWithResult)
+> ![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。通过Promise返回结果。
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 | 
+  | -------- | -------- | -------- | -------- |
+  | 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;
+
+停止Ability自身。
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 | 
+  | -------- | -------- | -------- | -------- |
+  | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 | 
+
+- 示例：
+  ```
+  this.context.terminateSelf((err) => {
+      console.log('terminateSelf result:' + JSON.stringfy(err);
+  }
+  ```
+
+
+## terminateSelf
+
+terminateSelf(): Promise<void>;
+
+停止Ability自身。通过Promise返回结果。
+
+- 返回值：
+  | 类型 | 说明 | 
+  | -------- | -------- |
+  | 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")
+  }
+  )
+  ```

zh-cn/application-dev/reference/apis/js-apis-extension-context.md

+# ExtensionContext
+
+- [属性](#属性)
+> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
+> 本模块首批接口从API 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+
+
+Extension的上下文环境，继承自Context。
+
+
+## 属性
+
+| 名称 | 参数类型 | 可读 | 可写 | 说明 | 
+| -------- | -------- | -------- | -------- | -------- |
+| currentHapModuleInfo | HapModuleInfo | 是 | 否 | 当前Hap包的信息。 | 

zh-cn/application-dev/reference/apis/js-apis-service-extension-context.md

+# ServiceExtensionContext
+
+- [startAbility](#startAbility)
+- [startAbility](#startAbility)
+- [terminateSelf](#terminateSelf)
+- [terminateSelf](#terminateSelf)
+- [connectAbility](#connectAbility)
+- [disconnectAbility](#disconnectAbility)
+- [disconnectAbility](#disconnectAbility)
+- [ConnectOptions](#ConnectOptions)
+> ![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。通过Promise返回结果。
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 | 
+  | -------- | -------- | -------- | -------- |
+  | 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;
+
+停止Ability自身。
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 | 
+  | -------- | -------- | -------- | -------- |
+  | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 | 
+
+- 示例：
+  ```
+  this.context.terminateSelf((err) => {
+      console.log('terminateSelf result:' + JSON.stringfy(err);
+  }
+  ```
+
+
+## terminateSelf
+
+terminateSelf(): Promise<void>;
+
+停止自身。通过Promise返回结果。
+
+- 返回值：
+  | 类型 | 说明 | 
+  | -------- | -------- |
+  | 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与服务类型的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与绑定的服务类型的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与绑定的服务类型的Ability解绑。通过Promise返回结果。
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 | 
+  | -------- | -------- | -------- | -------- |
+  | 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) | 连接失败时回调该接口。 | 

zh-cn/application-dev/reference/apis/js-apis-service-extension.md

+# ServiceExtension
+
+- [导入模块](#导入模块)
+- [权限](#权限)
+- [属性](#属性)
+- [onCreate](#onCreate)
+- [onDestroy](#onDestroy)
+- [onRequest](#onRequest)
+- [onConnect](#onConnect)
+- [onDisconnect](#onDisconnect)
+> ![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');
+      destory();
+  }
+  ```
+
+
+## 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);
+  }
+  ```