!12925 卡片API参考文档优化

Merge pull request !12925 from yangzk/master

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

@@ -48,20 +48,17 @@ createFormBindingData(obj?: Object | string): FormBindingData
 **示例：**
 
 ```ts
-import featureAbility from '@ohos.ability.featureAbility';
-import fileio from '@ohos.fileio';
-let context=featureAbility.getContext();
-context.getOrCreateLocalDir((err,data)=>{
-  let path=data+"/xxx.jpg";
-  let fd = fileio.openSync(path);
+import fs from '@ohos.file.fs';
+import formBindingData from '@ohos.app.form.formBindingData';
+
+try {
+  let fd = fs.openSync('/path/to/form.png')
   let obj = {
     "temperature": "21°",
-    "formImages": {"image": fd}
+    "formImages": { "image": fd }
   };
-  try {
-    formBindingData.createFormBindingData(obj);
-  } catch (error) {
-    console.log(`catch err->${JSON.stringify(err)}`);
-  }
-})
+  formBindingData.createFormBindingData(obj);
+} catch (error) {
+  console.log(`catch error, code: ${error.code}, message: ${error.message})`);
+}
 ```
\ No newline at end of file

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

@@ -33,7 +33,7 @@ onAddForm(want: Want): formBindingData.FormBindingData
 
 | 参数名 | 类型                                   | 必填 | 说明                                                         |
 | ------ | -------------------------------------- | ---- | ------------------------------------------------------------ |
-| want   | [Want](js-apis-application-want.md) | 是   | 当前ExtensionAbility相关的Want类型信息，包括卡片ID、卡片名称、卡片样式等。这些卡片信息必须作为持久数据进行管理，以便后续更新和删除卡片。 |
+| want   | [Want](js-apis-application-want.md) | 是   | 当前卡片相关的Want类型信息，包括卡片ID、卡片名称、卡片样式等。这些卡片信息必须作为持久数据进行管理，以便后续更新和删除卡片。 |
 
 **返回值：**
 
@@ -45,17 +45,19 @@ onAddForm(want: Want): formBindingData.FormBindingData
 
 ```ts
 import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+import formBindingData from '@ohos.app.form.formBindingData';
+
 export default class MyFormExtensionAbility extends FormExtensionAbility {
   onAddForm(want) {
     console.log('FormExtensionAbility onAddForm, want:' + want.abilityName);
     let dataObj1 = {
-      temperature:"11c",
-      "time":"11:00"
+      temperature: "11c",
+      "time": "11:00"
     };
     let obj1 = formBindingData.createFormBindingData(dataObj1);
     return obj1;
   }
-}
+};
 ```
 
 ## onCastToNormalForm
@@ -75,11 +77,13 @@ onCastToNormalForm(formId: string): void
 **示例：**
 
 ```ts
+import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+
 export default class MyFormExtensionAbility extends FormExtensionAbility {
   onCastToNormalForm(formId) {
     console.log('FormExtensionAbility onCastToNormalForm, formId:' + formId);
   }
-}
+};
 ```
 
 ## onUpdateForm
@@ -99,17 +103,24 @@ onUpdateForm(formId: string): void
 **示例：**
 
 ```ts
-import formBindingData from '@ohos.app.form.formBindingData'
+import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+import formBindingData from '@ohos.app.form.formBindingData';
+import formProvider from '@ohos.app.form.formProvider';
+
 export default class MyFormExtensionAbility extends FormExtensionAbility {
   onUpdateForm(formId) {
     console.log('FormExtensionAbility onUpdateForm, formId:' + formId);
-    let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"});
-    this.context.updateForm(formId, obj2).then((data)=>{
+    let obj2 = formBindingData.createFormBindingData({
+      temperature: "22c",
+      time: "22:00"
+    });
+    formProvider.updateForm(formId, obj2).then((data) => {
       console.log('FormExtensionAbility context updateForm, data:' + data);
     }).catch((error) => {
-      console.error('Operation updateForm failed. Cause: ' + error);});
-    }
-}
+      console.error('Operation updateForm failed. Cause: ' + error);
+    });
+  }
+};
 ```
 
 ## onChangeFormVisibility
@@ -129,21 +140,28 @@ onChangeFormVisibility(newStatus: { [key: string]: number }): void
 **示例：**
 
 ```ts
+import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
 import formBindingData from '@ohos.app.form.formBindingData'
+import formProvider from '@ohos.app.form.formProvider';
+
 export default class MyFormExtensionAbility extends FormExtensionAbility {
   onChangeFormVisibility(newStatus) {
-  console.log('FormExtensionAbility onChangeFormVisibility, newStatus:' + newStatus);
-  let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"});
-
-  for (let key in newStatus) {
-    console.log('FormExtensionAbility onChangeFormVisibility, key:' + key + ", value=" + newStatus[key]);
-    this.context.updateForm(key, obj2).then((data)=>{
+    console.log('FormExtensionAbility onChangeFormVisibility, newStatus:' + newStatus);
+    let obj2 = formBindingData.createFormBindingData({
+      temperature: "22c",
+      time: "22:00"
+    });
+
+    for (let key in newStatus) {
+      console.log('FormExtensionAbility onChangeFormVisibility, key:' + key + ", value=" + newStatus[key]);
+      formProvider.updateForm(key, obj2).then((data) => {
         console.log('FormExtensionAbility context updateForm, data:' + data);
-    }).catch((error) => {
-        console.error('Operation updateForm failed. Cause: ' + error);});
+      }).catch((error) => {
+        console.error('Operation updateForm failed. Cause: ' + error);
+      });
     }
   }
-}
+};
 ```
 
 ## onFormEvent
@@ -164,11 +182,13 @@ onFormEvent(formId: string, message: string): void
 **示例：**
 
 ```ts
-export default class MyFormExtension extends FormExtensionAbility {
+import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+
+export default class MyFormExtensionAbility extends FormExtensionAbility {
   onFormEvent(formId, message) {
     console.log('FormExtensionAbility onFormEvent, formId:' + formId + ", message:" + message);
   }
-}
+};
 ```
 
 ## onRemoveForm
@@ -188,11 +208,13 @@ onRemoveForm(formId: string): void
 **示例：**
 
 ```ts
+import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+
 export default class MyFormExtensionAbility extends FormExtensionAbility {
   onRemoveForm(formId) {
     console.log('FormExtensionAbility onRemoveForm, formId:' + formId);
   }
-}
+};
 ```
 
 ## onConfigurationUpdate
@@ -212,11 +234,13 @@ onConfigurationUpdate(newConfig: Configuration): void;
 **示例：**
 
 ```ts
-class MyFormExtensionAbility extends FormExtensionAbility {
+import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+
+export default class MyFormExtensionAbility extends FormExtensionAbility {
   onConfigurationUpdate(config) {
     console.log('onConfigurationUpdate, config:' + JSON.stringify(config));
   }
-}
+};
 ```
 
 ## onAcquireFormState
@@ -236,13 +260,15 @@ onAcquireFormState?(want: Want): formInfo.FormState;
 **示例：**
 
 ```ts
+import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
 import formInfo from '@ohos.app.form.formInfo';
-class MyFormExtensionAbility extends FormExtensionAbility {
+
+export default class MyFormExtensionAbility extends FormExtensionAbility {
   onAcquireFormState(want) {
     console.log('FormExtensionAbility onAcquireFormState, want:' + want);
     return formInfo.FormState.UNKNOWN;
   }
-}
+};
 ```
 
 ## onShareForm
@@ -270,14 +296,16 @@ onShareForm?(formId: string): { [key: string]: any }
 **示例：**
 
 ```ts
-class MyFormExtensionAbility extends FormExtensionAbility {
+import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+
+export default class MyFormExtensionAbility extends FormExtensionAbility {
   onShareForm(formId) {
     console.log('FormExtensionAbility onShareForm, formId:' + formId);
     let wantParams = {
-      "temperature":"20",
-      "time":"2022-8-8 09:59",
+      "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-formInfo.md

-# @ohos.app.form.formInfo (FormInfo)
+# @ohos.app.form.formInfo (formInfo)
 
-FormInfo模块提供对卡片的相关卡片信息和状态进行设置和查询的能力。
+formInfo模块提供了卡片信息和状态等相关类型和枚举。
 
 > **说明：**
 >
@@ -30,11 +30,11 @@ import formInfo from '@ohos.app.form.formInfo';
 | colorMode  | [ColorMode](#colormode) | 是    | 否     | 卡片颜色模式。                                       |
 | isDefault    | boolean      | 是    | 否     | 卡片是否是默认卡片。                              |
 | updateEnabled  | boolean               | 是    | 否     | 卡片是否使能更新。                    |
-| formVisibleNotify  | string               | 是    | 否     | 卡片是否使能可见通知。            |
+| formVisibleNotify  | boolean        | 是    | 否     | 卡片是否使能可见通知。            |
 | relatedBundleName | string               | 是    | 否     | 卡片所属的相关联Bundle名称。           |
 | scheduledUpdateTime        | string               | 是    | 否     | 卡片更新时间。     |
 | formConfigAbility | string               | 是    | 否     | 卡片配置ability。指定长按卡片弹出的选择框内，编辑选项所对应的ability。   |
-| updateDuration        | string             | 是    | 否     | 卡片更新周期。 |
+| updateDuration        | number       | 是    | 否     | 卡片更新周期。 |
 | defaultDimension  | number | 是    | 否     | 表示卡片规格                                       |
 | supportDimensions    | Array<number>      | 是    | 否     | 卡片支持的规格。具体可选规格参考[FormDimension](#formdimension)   |
 | customizeData    | {[key: string]: [value: string]}      | 是    | 否     | 卡片用户数据。         |
@@ -100,8 +100,8 @@ import formInfo from '@ohos.app.form.formInfo';
 | WIDTH_KEY        | "ohos.extra.param.key.form_width"   | 卡片宽度。   |
 | HEIGHT_KEY         | "ohos.extra.param.key.form_height"   | 卡片高度。   |
 | TEMPORARY_KEY          | "ohos.extra.param.key.form_temporary"   | 临时卡片。   |
-| ABILITY_NAME_KEY   | "ohos.extra.param.key.ability_name"   | ability名称   |
-| DEVICE_ID_KEY    | "ohos.extra.param.key.device_id"   | 设备标识。<br/>**系统接口**: 此接口为系统接口。   |
+| 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名称的键。 |
 
 ##  FormDimension
@@ -127,7 +127,7 @@ import formInfo from '@ohos.app.form.formInfo';
 
 | 名称        | 说明         |
 | ----------- | ------------ |
-| moduleName   | 仅保留moduleName与提供值相符的卡片信息。 |
+| moduleName   | 选填。仅保留moduleName与提供值相符的卡片信息。未填写时则不通过moduleName进行过滤。 |
 
 ## VisibilityType
 

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

 # FormExtensionContext
 
-FormExtensionContext模块是FormExtension的上下文环境，继承自ExtensionContext。
+FormExtensionContext模块是FormExtensionAbility的上下文环境，继承自ExtensionContext。
 
-FormExtensionContext模块提供FormExtension具有的接口和能力。
+FormExtensionContext模块提供FormExtensionAbility具有的接口和能力。
 
 > **说明：**
 >
@@ -11,23 +11,24 @@ FormExtensionContext模块提供FormExtension具有的接口和能力。
 
 ## 使用说明
 
-在使用FormExtensionContext的功能前，需要通过FormExtension获取。
+在使用FormExtensionContext的功能前，需要通过FormExtensionAbility获取。
 
 ```ts
 import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
 import formBindingData from '@ohos.app.form.formBindingData';
+
 export default class MyFormExtensionAbility extends FormExtensionAbility {
-    onAddForm() {
-        let formContext = this.context; // 获取FormExtensionContext
-        // ...
-        let dataObj1 = {
-            temperature:"11c",
-            "time":"11:00"
-        };
-        let obj1 = formBindingData.createFormBindingData(dataObj1);
-        return obj1;
-    }
-}
+  onAddForm(want) {
+    let formContext = this.context; // 获取FormExtensionContext
+    // ...
+    let dataObj1 = {
+      temperature: "11c",
+      "time": "11:00"
+    };
+    let obj1 = formBindingData.createFormBindingData(dataObj1);
+    return obj1;
+  }
+};
 ```
 
 ## startAbility
@@ -50,23 +51,29 @@ startAbility(want: Want, callback: AsyncCallback<void>): void
 **示例：**
 
 ```ts
-var want = {
-    deviceId: "",
-    bundleName: "com.example.formstartability",
-    abilityName: "MainAbility",
-    action: "action1",
-    entities: ["entity1"],
-    type: "MIMETYPE",
-    uri: "key={true,true,false}",
-    parameters: {}
-}
-this.context.startAbility(want, (error, data) => {
-    if (error) {
-      console.log('FormExtensionContext startAbility, error:' + JSON.stringify(error));
-    } else {
-      console.log(`FormExtensionContext startAbility success`);
-    }
-})
+import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+
+export default class MyFormExtensionAbility extends FormExtensionAbility {
+  onFormEvent(formId, message) {
+    // 当触发卡片message事件时，执行startAbility
+    console.log('FormExtensionAbility onFormEvent, formId:' + formId + ", message:" + message);
+    let want = {
+      deviceId: "",
+      bundleName: "com.example.formstartability",
+      abilityName: "MainAbility",
+      parameters: {
+        "message": message
+      }
+    };
+    this.context.startAbility(want, (error, data) => {
+      if (error) {
+        console.log('FormExtensionContext startAbility, error:' + JSON.stringify(error));
+      } else {
+        console.log('FormExtensionContext startAbility success');
+      }
+    });
+  }
+};
 ```
 
 ## startAbility
@@ -89,24 +96,30 @@ startAbility(want: Want): Promise<void>
 
 | 类型          | 说明                                |
 | ------------ | ---------------------------------- |
-| Promise<void< | 无返回结果的Promise对象。 |
+| Promise<void> | 无返回结果的Promise对象。 |
 
 **示例：**
 
 ```ts
-var want = {
-    deviceId: "",
-    bundleName: "com.example.formstartability",
-    abilityName: "MainAbility",
-    action: "action1",
-    entities: ["entity1"],
-    type: "MIMETYPE",
-    uri: "key={true,true,false}",
-    parameters: {}
-}
-this.context.startAbility(want).then(() => {
-    console.info("StartAbility Success");
-}).catch((error) => {
-    console.info("StartAbility failed");
-});
+import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+
+export default class MyFormExtensionAbility extends FormExtensionAbility {
+  onFormEvent(formId, message) {
+    // 当触发卡片message事件时，执行startAbility
+    console.log('FormExtensionAbility onFormEvent, formId:' + formId + ", message:" + message);
+    let want = {
+      deviceId: "",
+      bundleName: "com.example.formstartability",
+      abilityName: "MainAbility",
+      parameters: {
+        "message": message
+      }
+    };
+    this.context.startAbility(want).then(() => {
+      console.info("StartAbility Success");
+    }).catch((error) => {
+      console.info("StartAbility failed");
+    });
+  }
+};
 ```
\ No newline at end of file