!20892 FormExtensionContext新增connect/disconnect接口

Merge pull request !20892 from HuangXW/ETSForm

zh-cn/application-dev/reference/apis/js-apis-inner-application-formExtensionContext.md

@@ -15,7 +15,7 @@ FormExtensionContext模块提供FormExtensionAbility具有的接口和能力。
 import common from '@ohos.app.ability.common';
 ```
 
-## startAbility
+## FormExtensionContext.startAbility
 
 startAbility(want: Want, callback: AsyncCallback<void>): void
 
@@ -73,7 +73,7 @@ export default class MyFormExtensionAbility extends FormExtensionAbility {
 };
 ```
 
-## startAbility
+## FormExtensionContext.startAbility
 
 startAbility(want: Want): Promise<void>
 
@@ -132,4 +132,205 @@ export default class MyFormExtensionAbility extends FormExtensionAbility {
     });
   }
 };
-```
\ No newline at end of file
+```
+
+## FormExtensionContext.connectServiceExtensionAbility<sup>10+</sup>
+
+connectServiceExtensionAbility(want: Want, options: ConnectOptions): number;
+
+将一个Ability与服务类型的Ability绑定。
+
+**系统能力**：SystemCapability.Ability.Form
+
+**系统API**: 此接口为系统接口，三方应用不支持调用。
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| want | [Want](js-apis-application-want.md)  | 是 | Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。 |
+| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | ConnectOptions类型的回调函数，返回服务连接成功、断开或连接失败后的信息。 |
+
+**返回值：**
+
+| 类型 | 说明 |
+| -------- | -------- |
+| number | 返回一个connectId，后续根据此connectId断开连接。 |
+
+**错误码：**
+
+| 错误码ID | 错误信息 |
+| ------- | -------------------------------- |
+| 16000001 | The specified ability does not exist. |
+| 16000002 | Incorrect ability type. |
+| 16000004 | Can not start invisible component. |
+| 16000006 | Cross-user operations are not allowed. |
+| 16000008 | The crowdtesting application expires. |
+| 16000053 | The ability is not on the top of the UI. |
+| 16000055 | Installation-free timed out. |
+| 16000011 | The context does not exist.        |
+| 16000050 | Internal error. |
+
+以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。
+
+**示例：**
+
+  ```ts
+  import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+
+  let commRemote = null;
+  export default class MyFormExtensionAbility extends FormExtensionAbility {
+    onFormEvent(formId, message) {
+      // 当触发卡片message事件时，执行connectServiceExtensionAbility
+      console.log(`FormExtensionAbility onFormEvent, formId:${formId}, message:${message}`);
+      let want = {
+        deviceId: '',
+        bundleName: 'com.example.formstartability',
+        abilityName: 'EntryAbility',
+        parameters: {
+          'message': message
+        }
+      };
+      let options = {
+        onConnect(elementName, remote) { 
+          commRemote = remote; // remote 用于与ServiceExtensionAbility进行通信
+          console.log('----------- onConnect -----------'); 
+        },
+        onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
+        onFailed(code) { console.error('----------- onFailed -----------') }
+      };
+
+      let connection = null;
+      try {
+        connection = this.context.connectServiceExtensionAbility(want, options);
+      } catch (paramError) {
+        // 处理入参错误异常
+        console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`);
+      }
+    }
+  };
+  ```
+
+## FormExtensionContext.disconnectServiceExtensionAbility<sup>10+</sup>
+
+disconnectServiceExtensionAbility(connection: number, callback:AsyncCallback&lt;void&gt;): void;
+
+将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空。
+
+**系统能力**：SystemCapability.Ability.Form
+
+**系统API**: 此接口为系统接口，三方应用不支持调用。
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| connection | number | 是 | 在connectServiceExtensionAbility中返回的number。 |
+| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数，返回接口调用是否成功的结果。 |
+
+**错误码：**
+
+| 错误码ID | 错误信息 |
+| ------- | -------------------------------- |
+| 16000011 | The context does not exist.        |
+| 16000050 | Internal error. |
+
+以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。
+
+**示例：**
+
+  ```ts
+  import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+
+  // commRemote为onConnect回调内返回的remote对象，此处定义为null无任何实际意义，仅作示例
+  let commRemote = null;
+  export default class MyFormExtensionAbility extends FormExtensionAbility {
+    onFormEvent(formId, message) {
+      // 实际使用时，connection为connectServiceExtensionAbility中的返回值，此处定义为1无任何实际意义，仅作示例
+      let connection = 1;
+
+      try {
+        this.context.disconnectServiceExtensionAbility(connection, (error) => {
+          commRemote = null;
+          if (error.code) {
+            // 处理业务逻辑错误
+            console.error(
+              `disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
+            return;
+          }
+          // 执行正常业务
+          console.log('disconnectServiceExtensionAbility succeed');
+        });
+      } catch (paramError) {
+        commRemote = null;
+        // 处理入参错误异常
+        console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`);
+      }
+    }
+  };
+  ```
+
+## FormExtensionContext.disconnectServiceExtensionAbility<sup>10+</sup>
+
+disconnectServiceExtensionAbility(connection: number): Promise&lt;void&gt;;
+
+将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空(Promise形式返回结果)。
+
+**系统能力**：SystemCapability.Ability.Form
+
+**系统API**: 此接口为系统接口，三方应用不支持调用。
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| connection | number | 是 | 在connectServiceExtensionAbility中返回的number。 |
+
+**返回值：**
+
+| 类型 | 说明 |
+| -------- | -------- |
+| Promise&lt;void&gt; | 返回一个Promise，包含接口的结果。 |
+
+**错误码：**
+
+| 错误码ID | 错误信息 |
+| ------- | -------------------------------- |
+| 16000011 | The context does not exist.        |
+| 16000050 | Internal error. |
+
+以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。
+
+**示例：**
+
+  ```ts
+  import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+
+  // commRemote为onConnect回调内返回的remote对象，此处定义为null无任何实际意义，仅作示例
+  let commRemote = null;
+  export default class MyFormExtensionAbility extends FormExtensionAbility {
+    onFormEvent(formId, message) {
+      // 实际使用时，connection为connectServiceExtensionAbility中的返回值，此处定义为1无任何实际意义，仅作示例
+      let connection = 1;
+
+      try {
+        this.context.disconnectServiceExtensionAbility(connection)
+          .then((data) => {
+            commRemote = null;
+            // 执行正常业务
+            console.log('disconnectServiceExtensionAbility succeed');
+          })
+          .catch((error) => {
+            commRemote = null;
+            // 处理业务逻辑错误
+            console.error(
+              `disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
+          });
+      } catch (paramError) {
+        commRemote = null;
+        // 处理入参错误异常
+        console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`);
+      }
+    }
+  };
+  ```

zh-cn/application-dev/reference/apis/js-apis-inner-application-serviceExtensionContext.md

@@ -1418,7 +1418,7 @@ startAbilityByCall(want: Want): Promise<Caller>;
     console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
   }
   ```
-## UIAbilityContext.startRecentAbility
+## ServiceExtensionContext.startRecentAbility
 
 startRecentAbility(want: Want, callback: AsyncCallback\<void>): void;
 
@@ -1483,7 +1483,7 @@ try {
   console.error(`startRecentAbility failed failed, code is ${err.code}, message is ${err.message}`);
 }
   ```
-## UIAbilityContext.startRecentAbility
+## ServiceExtensionContext.startRecentAbility
 
 startRecentAbility(want: Want, options: StartOptions, callback: AsyncCallback\<void>): void;
 
@@ -1554,7 +1554,7 @@ try {
   console.error(`startRecentAbility failed failed, code is ${err.code}, message is ${err.message}`);
 }
   ```
-## UIAbilityContext.startRecentAbility
+## ServiceExtensionContext.startRecentAbility
 
 startRecentAbility(want: Want, options?: StartOptions): Promise\<void>;