!18036 卡片请求用户自定义数据API

Merge pull request !18036 from wangkailong/fork

zh-cn/application-dev/reference/apis/js-apis-app-form-formExtensionAbility.md

@@ -308,4 +308,43 @@ export default class MyFormExtensionAbility extends FormExtensionAbility {
     return wantParams;
   }
 };
+```
+
+## onAcquireFormData<sup>10+</sup>
+
+onAcquireFormData?(formId: string): { [key: string]: Object }
+
+卡片提供方接收卡片请求自定义数据的通知接口。
+
+**系统接口**: 此接口为系统接口。
+
+**系统能力**：SystemCapability.Ability.Form
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| formId | string | 是   | 卡片标识。 |
+
+**返回值：**
+
+| 类型                                                         | 说明                                                        |
+| ------------------------------------------------------------ | ----------------------------------------------------------- |
+| {[key: string]: any} | 卡片的自定义数据，由开发者自行决定传入的键值对。 |
+
+**示例：**
+
+```ts
+import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+
+export default class MyFormExtensionAbility extends FormExtensionAbility {
+  onAcquireFormData(formId) {
+    console.log('FormExtensionAbility onAcquireFormData, formId: ${formId}');
+    let wantParams = {
+      'temperature': '20',
+      'time': '2022-8-8 09:59',
+    };
+    return wantParams;
+  }
+};
 ```
\ No newline at end of file

zh-cn/application-dev/reference/apis/js-apis-app-form-formHost.md

@@ -1865,3 +1865,95 @@ try {
 }
 ```
 
+## acquireFormData<sup>10+</sup>
+
+acquireFormData(formId: string, callback: AsyncCallback\<void>): void
+
+请求卡片提供方数据。使用callback异步回调。
+
+**需要权限**：ohos.permission.REQUIRE_FORM
+
+**系统能力**：SystemCapability.Ability.Form
+
+**参数：**
+
+| 参数名 | 类型    | 必填 | 说明    |
+| ------ | ------ | ---- | ------- |
+| formId | string | 是   | 卡片标识。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
+
+| 错误码ID | 错误信息 |
+| -------- | -------- |
+| 16500050 | An IPC connection error happened. |
+| 16500060 | A service connection error happened, please try again later. |
+| 16500100 | Failed to obtain the configuration information. |
+| 16501000 | An internal functional error occurred. |
+
+**示例：**
+
+```ts
+import formHost from '@ohos.app.form.formHost';
+
+let formId = '12400633174999288';
+try {
+  formHost.acquireFormData(formId, (error) => {
+    if (error) {
+      console.error(`error, code: ${error.code}, message: ${error.message}`);
+    }
+  });
+} catch(error) {
+  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
+}
+```
+
+## acquireFormData<sup>10+</sup>
+
+function acquireFormData(formId: string): Promise\<void\>;
+
+请求卡片提供方数据。使用Promise异步回调。
+
+**需要权限**：ohos.permission.REQUIRE_FORM
+
+**系统能力**：SystemCapability.Ability.Form
+
+**参数：**
+
+| 参数名      | 类型            | 必填 | 说明                             |
+| ----------- | --------------- | ---- | -------------------------------- |
+| formId | string | 是   | 卡片标识。 |
+
+**返回值：**
+
+| 类型                | 说明                      |
+| ------------------- | ------------------------- |
+| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
+
+| 错误码ID | 错误信息 |
+| -------- | -------- |
+| 16500050 | An IPC connection error happened. |
+| 16500060 | A service connection error happened, please try again later. |
+| 16500100 | Failed to obtain the configuration information. |
+| 16501000 | An internal functional error occurred. |
+
+```ts
+import formHost from '@ohos.app.form.formHost';
+
+let formId = '12400633174999288';
+try {
+  formHost.acquireFormData(formId).then(() => {
+    console.log('formHost acquireFormData success');
+  }).catch((error) => {
+    console.error(`error, code: ${error.code}, message: ${error.message}`);
+  });
+} catch(error) {
+  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
+}
+```
+

zh-cn/application-dev/reference/apis/js-apis-app-form-formInfo.md

@@ -102,6 +102,8 @@ import formInfo from '@ohos.app.form.formInfo';
 | ABILITY_NAME_KEY   | 'ohos.extra.param.key.ability_name'   | ability名称。  |
 | DEVICE_ID_KEY    | 'ohos.extra.param.key.device_id'   | 设备标识。   |
 | BUNDLE_NAME_KEY    | 'ohos.extra.param.key.bundle_name'   | 指示指定要获取的捆绑Bundle名称的键。 |
+| LAUNCH_REASON_KEY<sup>10+</sup>    | 'ohos.extra.param.key.form_launch_reason'   | 卡片创建原因。   |
+| PARAM_FORM_CUSTOMIZE_KEY<sup>10+</sup>    | 'ohos.extra.param.key.form_customize'   | 自定义数据。   |
 
 ##  FormDimension
 
@@ -137,4 +139,15 @@ import formInfo from '@ohos.app.form.formInfo';
 | 名称        |  值   | 说明         |
 | ----------- | ---- | ------------ |
 | FORM_VISIBLE | 1   | 表示卡片为可见。 |
-| FORM_INVISIBLE   | 2   | 表示卡片为不可见。 |
\ No newline at end of file
+| FORM_INVISIBLE   | 2   | 表示卡片为不可见。 |
+
+## LaunchReason<sup>10+</sup>
+
+卡片创建原因枚举。
+
+**系统能力**：SystemCapability.Ability.Form
+
+| 名称        |  值   | 说明         |
+| ----------- | ---- | ------------ |
+| FORM_DEFAULT | 1   | 表示卡片创建原因为默认创建。 |
+| FORM_SHARE   | 2   | 表示卡片创建原因为共享创建。 |
\ No newline at end of file