From 09504057ecab3bd307655f6bfca22d45a34be4fd Mon Sep 17 00:00:00 2001 From: yangzk Date: Fri, 28 Jan 2022 11:41:39 +0800 Subject: [PATCH 1/2] IssueNo:#I4PCGJ:add docs for form extension Description:add docs for form extension Sig:SIG_ApplicationFramework Feature or Bugfix:Feature Binary Source:No Signed-off-by: yangzk Change-Id: I5c786330e633f845d6c87789d86e9dfe6cba1cf3 --- .../reference/apis/js-apis-formbindingdata.md | 51 ++++++ .../reference/apis/js-apis-formextension.md | 165 ++++++++++++++++++ .../apis/js-apis-formextensioncontext.md | 59 +++++++ 3 files changed, 275 insertions(+) create mode 100644 zh-cn/application-dev/reference/apis/js-apis-formbindingdata.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-formextension.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md diff --git a/zh-cn/application-dev/reference/apis/js-apis-formbindingdata.md b/zh-cn/application-dev/reference/apis/js-apis-formbindingdata.md new file mode 100644 index 00000000000..db6c4676f2a --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-formbindingdata.md @@ -0,0 +1,51 @@ +# 卡片数据绑定类 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 导入模块 + +``` +import formBindingData from '@ohos.application.formBindingData'; +``` + +## 权限 + +无 + +## formBindingData.createFormBindingData + +createFormBindingData(obj?: Object | string): FormBindingData + +创建一个FormBindingData对象。 + +- 参数： + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------------- | ---- | -------------------- | + | obj | Object或string | 否 | js卡片要展示的数据。 | + + + +- 返回值： + + | 类型 | 说明 | + | ----------------------------------- | --------------------------------------- | + | [FormBindingData](#formbindingdata) | 根据传入数据创建的FormBindingData对象。 | + + + +- 示例： + + ``` + let obj = {"temperature": "21°"}; + let formBindingDataObj = formBindingData.createFormBindingData(obj); + ``` + +## FormBindingData + +FormBindingData相关描述。 + +| 名称 | 类型 | 说明 | +| ---- | -------------- | -------------------- | +| obj | Object或string | js卡片要展示的数据。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-formextension.md b/zh-cn/application-dev/reference/apis/js-apis-formextension.md new file mode 100644 index 00000000000..1c87d59e0e1 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-formextension.md @@ -0,0 +1,165 @@ +# FormExtension + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +提供FormExtension卡片扩展相关接口。 + +## 导入模块 + +``` +import FormExtension from '@ohos.application.FormExtension'; +``` + +## 权限 + +无 + +## 属性 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ------- | ------------------------------------------------------- | ---- | ---- | --------------------------------------------------- | +| context | [FormExtensionContext](js-apis-formextensioncontext.md) | 是 | 否 | FormExtension的上下文环境，继承自ExtensionContext。 | + +## onCreate + +onCreate(want: Want): formBindingData.FormBindingData + +卡片提供方接收创建卡片的通知接口。 + +- 参数： + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | + | want | [Want](js-apis-featureAbility.md#want) | 是 | 当前Extension相关的Want类型信息，包括卡片ID、卡片名称、卡片样式等。 | + +- 返回值： + + | 类型 | 说明 | + | ------------------------------------------------------------ | ----------------------------------------------------------- | + | [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | 一个formBindingData.FormBindingData对象，卡片要显示的数据。 | + +- 示例： + + ``` + onCreate(want) { + console.log('FormExtension onCreate, want:' + want.abilityName); + let dataObj1 = { + temperature:"11c", + "time":"11:00" + }; + let obj1 = formBindingData.createFormBindingData(dataObj1); + return obj1; + } + ``` + +## onCastToNormal + +onCastToNormal(formId: string): void + +卡片提供方接收临时卡片转常态卡片的通知接口。 + +- 参数： + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------ | + | formId | string | 是 | 请求转换为常态的卡片ID。 | + +- 示例： + + ``` + onCastToNormal(formId) { + console.log('FormExtension onCastToNormal, formId:' + formId); + } + ``` + +## onUpdate + +onUpdate(formId: string): void + +卡片提供方接收更新卡片的通知接口。 + +- 参数： + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------ | + | formId | string | 是 | 请求更新的卡片ID。 | + +- 示例： + + ``` + onUpdate(formId) { + console.log('FormExtension onUpdate, formId:' + formId); + } + ``` + +## onVisibilityChange + +onVisibilityChange(newStatus: { [key: string]: number }): void + +卡片提供方接收修改可见性的通知接口。 + +- 参数： + + | 参数名 | 类型 | 必填 | 说明 | + | --------- | ------------------------- | ---- | ---------------------------- | + | newStatus | { [key: string]: number } | 是 | 请求修改的卡片ID和可见状态。 | + +- 示例： + + ``` + onVisibilityChange(newStatus) { + console.log('FormExtension onVisibilityChange, newStatus:' + newStatus); + let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + + for (let key in newStatus) { + console.log('FormExtension onVisibilityChange, key:' + key + ", value=" + newStatus[key]); + this.context.updateForm(key, obj2) + .then((data)=>{ + console.log('FormExtension context updateForm, data:' + data); + }).catch((error) => { + console.error('Operation updateForm failed. Cause: ' + error);}); + } + } + ``` + +## onEvent + +onEvent(formId: string, message: string): void + +卡片提供方接收处理卡片事件的通知接口。 + +- 参数： + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------ | ---- | ---------------------- | + | formId | string | 是 | 请求触发事件的卡片ID。 | + | message | string | 是 | 事件消息。 | + +- 示例： + + ``` + onEvent(formId, message) { + console.log('FormExtension onEvent, formId:' + formId + ", message:" + message); + } + ``` + +## onDestroy + +onDestroy(formId: string): void + +卡片提供方接收销毁卡片的通知接口。 + +- 参数： + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------ | + | formId | string | 是 | 请求销毁的卡片ID。 | + +- 示例： + + ``` + onDestroy(formId) { + console.log('FormExtension onDestroy, formId:' + formId); + } + ``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md b/zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md new file mode 100644 index 00000000000..16c4de97a27 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md @@ -0,0 +1,59 @@ +# FormExtensionContext + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +FormExtension的上下文环境，提供FormExtension具有的能力和接口，继承自ExtensionContext。 + +## updateForm + +updateForm(formId: string, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\): void + +更新卡片。 + +- 参数： + + | 参数名 | 类型 | 必填 | 说明 | + | --------------- | ------------------------------------------------------------ | ---- | -------------------------------------- | + | formId | string | 是 | 请求更新的卡片ID。 | + | formBindingData | [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | 是 | 卡片新的数据。 | + | callback | AsyncCallback\ | 是 | 回调函数，返回接口调用是否成功的结果。 | + +- 示例： + + ``` + let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + this.context.updateForm(formId, obj2, (data)=>{ + console.log('FormExtension context updateForm, data:' + data); + }); + ``` + +## updateForm + +updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise\ + +更新卡片。 + +- 参数： + + | 参数名 | 类型 | 必填 | 说明 | + | --------------- | ------------------------------------------------------------ | ---- | ------------------ | + | formId | string | 是 | 请求更新的卡片ID。 | + | formBindingData | [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | 是 | 卡片新的数据。 | + +- 返回值： + + | 类型 | 说明 | + | -------------- | --------------------------------- | + | Promise\ | 返回一个Promise，包含接口的结果。 | + +- 示例： + + ``` + let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + this.context.updateForm(formId, obj2) + .then((data)=>{ + console.log('FormExtension context updateForm, data:' + data); + }).catch((error) => { + console.error('Operation updateForm failed. Cause: ' + error);}); + ``` \ No newline at end of file -- Gitee From d15dd3cde2c9280d60cde1627b48dd710fd745f8 Mon Sep 17 00:00:00 2001 From: yangzk Date: Tue, 8 Feb 2022 10:38:17 +0800 Subject: [PATCH 2/2] IssueNo:#I4PCGJ:add docs for form extension Description:add docs for form extension Sig:SIG_ApplicationFramework Feature or Bugfix:Feature Binary Source:No Signed-off-by: yangzk Change-Id: Ifbf4866e484fa8398f999bbe259beaa328cc20d8 --- .../reference/apis/js-apis-formbindingdata.md | 12 ++++++------ .../reference/apis/js-apis-formextension.md | 10 ++++++++-- .../reference/apis/js-apis-formextensioncontext.md | 2 +- 3 files changed, 15 insertions(+), 9 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-formbindingdata.md b/zh-cn/application-dev/reference/apis/js-apis-formbindingdata.md index db6c4676f2a..97263eedf6c 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-formbindingdata.md +++ b/zh-cn/application-dev/reference/apis/js-apis-formbindingdata.md @@ -21,9 +21,9 @@ createFormBindingData(obj?: Object | string): FormBindingData - 参数： - | 参数名 | 类型 | 必填 | 说明 | - | ------ | -------------- | ---- | -------------------- | - | obj | Object或string | 否 | js卡片要展示的数据。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------------- | ---- | ------------------------------------------------------------ | + | obj | Object或string | 否 | js卡片要展示的数据。可以是包含若干键值对的Object或者 json 格式的字符串。 | @@ -46,6 +46,6 @@ createFormBindingData(obj?: Object | string): FormBindingData FormBindingData相关描述。 -| 名称 | 类型 | 说明 | -| ---- | -------------- | -------------------- | -| obj | Object或string | js卡片要展示的数据。 | \ No newline at end of file +| 名称 | 类型 | 说明 | +| ---- | -------------- | ------------------------------------------------------------ | +| obj | Object或string | js卡片要展示的数据。可以是包含若干键值对的Object或者 json 格式的字符串。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-formextension.md b/zh-cn/application-dev/reference/apis/js-apis-formextension.md index 1c87d59e0e1..83e27c049ba 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-formextension.md +++ b/zh-cn/application-dev/reference/apis/js-apis-formextension.md @@ -31,7 +31,7 @@ onCreate(want: Want): formBindingData.FormBindingData | 参数名 | 类型 | 必填 | 说明 | | ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | - | want | [Want](js-apis-featureAbility.md#want) | 是 | 当前Extension相关的Want类型信息，包括卡片ID、卡片名称、卡片样式等。 | + | want | [Want](js-apis-featureAbility.md#want) | 是 | 当前Extension相关的Want类型信息，包括卡片ID、卡片名称、卡片样式等。这些卡片信息必须作为持久数据进行管理，以便后续更新和删除卡片。 | - 返回值： @@ -77,7 +77,7 @@ onCastToNormal(formId: string): void onUpdate(formId: string): void -卡片提供方接收更新卡片的通知接口。 +卡片提供方接收更新卡片的通知接口。获取最新数据后调用[FormExtensionContext](js-apis-formextensioncontext.md)的updateForm接口刷新卡片数据。 - 参数： @@ -90,6 +90,12 @@ onUpdate(formId: string): void ``` onUpdate(formId) { console.log('FormExtension onUpdate, formId:' + formId); + let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + this.context.updateForm(formId, obj2) + .then((data)=>{ + console.log('FormExtension context updateForm, data:' + data); + }).catch((error) => { + console.error('Operation updateForm failed. Cause: ' + error);}); } ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md b/zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md index 16c4de97a27..1a7cb0401ca 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md +++ b/zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md @@ -9,7 +9,7 @@ FormExtension的上下文环境，提供FormExtension具有的能力和接口， updateForm(formId: string, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\): void -更新卡片。 +主动更新卡片。 - 参数： -- Gitee