diff --git a/zh-cn/application-dev/reference/apis-form-kit/Readme-CN.md b/zh-cn/application-dev/reference/apis-form-kit/Readme-CN.md index f93da79c18a4dac71518f060e30685ed5780d60f..a5e93605774b6b3837f99c439cb02f2b9ac7f8ad 100644 --- a/zh-cn/application-dev/reference/apis-form-kit/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis-form-kit/Readme-CN.md @@ -6,6 +6,7 @@ - [@ohos.app.form.formInfo (FormInfo)](js-apis-app-form-formInfo.md) - [@ohos.app.form.formProvider (FormProvider)](js-apis-app-form-formProvider.md) - [@ohos.app.form.FormEditExtensionAbility (FormEditExtensionAbility)](js-apis-app-form-formEditExtensionAbility.md) + - [@ohos.app.form.LiveFormExtensionAbility (LiveFormExtensionAbility)](js-apis-app-form-LiveFormExtensionAbility.md) - [@ohos.app.form.formAgent (FormAgent)(系统接口)](js-apis-app-form-formAgent-sys.md) - [@ohos.app.form.FormExtensionAbility (FormExtensionAbility)(系统接口)](js-apis-app-form-formExtensionAbility-sys.md) @@ -17,6 +18,7 @@ - application - [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) - [FormEditExtensionContext](js-apis-inner-application-formEditExtensionContext.md) + - [LiveFormExtensionContext](js-apis-application-LiveFormExtensionContext.md) - [FormExtensionContext(系统接口)](js-apis-inner-application-formExtensionContext-sys.md) diff --git a/zh-cn/application-dev/reference/apis-form-kit/errorcode-form.md b/zh-cn/application-dev/reference/apis-form-kit/errorcode-form.md index b89552a48560644fbbe0f40b7b85bdbd68ed7770..1bc4543b7d97fbf63e3f8bcc32b62eea49794ff6 100644 --- a/zh-cn/application-dev/reference/apis-form-kit/errorcode-form.md +++ b/zh-cn/application-dev/reference/apis-form-kit/errorcode-form.md @@ -187,6 +187,24 @@ Waiting for the form addition to the desktop timed out. 服务繁忙，请稍后重试。 +## 16501010 设置互动卡片背景图失败 + +**错误信息** + +Failed to set the live form background image. + +**错误描述** + +设置互动卡片背景图时，传入背景图资源无效，系统会报此错误码。 + +**可能原因** + +背景图资源无效。 + +**处理步骤** + +检查传入的背景图资源是否有效。 + ## 16501011 当前卡片不支持互动卡片能力 **错误信息** @@ -321,4 +339,4 @@ Get system manager service failed. **处理步骤** 1. 重启系统后重试。 -2. 重启后仍旧失败，请提[在线工单](http://developer.huawei.com/consumer/cn/support/feedback/#)获取帮助。 \ No newline at end of file +2. 重启后仍旧失败，请提[在线工单](http://developer.huawei.com/consumer/cn/support/feedback/#)获取帮助。 diff --git a/zh-cn/application-dev/reference/apis-form-kit/js-apis-app-form-LiveFormExtensionAbility.md b/zh-cn/application-dev/reference/apis-form-kit/js-apis-app-form-LiveFormExtensionAbility.md new file mode 100644 index 0000000000000000000000000000000000000000..cb5868d93b8b14ce077cc3d5a3973a5d9bdb2dca --- /dev/null +++ b/zh-cn/application-dev/reference/apis-form-kit/js-apis-app-form-LiveFormExtensionAbility.md @@ -0,0 +1,108 @@ +# @ohos.app.form.LiveFormExtensionAbility (LiveFormExtensionAbility) + +LiveFormExtensionAbility模块提供互动卡片功能，包括创建、销毁互动卡片等，继承自[ExtensionAbility](../apis-ability-kit/js-apis-app-ability-extensionAbility.md)。 + +> **说明：** +> +> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> +> 本模块接口仅可在Stage模型下使用。 + +## 导入模块 + +```ts +import { LiveFormExtensionAbility } from '@kit.FormKit'; +``` +## LiveFormExtensionAbility +互动卡片扩展类。包含互动卡片提供方接收创建和销毁互动卡片的通知接口。 + +### 属性 + +**模型约束：** 此接口仅可在Stage模型下使用。 + +**系统能力：** SystemCapability.Ability.Form + | 名称 | 类型 | 只读 | 可选 |说明| + | ------ | ------ | ---- | ---- | ---- | + | context | [LiveFormExtensionContext](./js-apis-application-LiveFormExtensionContext.md) | 否 | 否 |LiveFormExtensionAbility的上下文环境，继承自[ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md)。| + +### onLiveFormCreate + +onLiveFormCreate(liveFormInfo: LiveFormInfo, session: UIExtensionContentSession): void + +LiveFormExtensionAbility界面内容对象创建后调用。 + +**模型约束：** 此接口仅可在Stage模型下使用。 + +**系统能力**：SystemCapability.Ability.Form + +**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| liveFormInfo | [LiveFormInfo](#liveforminfo) | 是 | 互动卡片信息，包括卡片id等信息。| +| session | [UIExtensionContentSession](../apis-ability-kit/js-apis-app-ability-uiExtensionContentSession.md) | 是 | LiveFormExtensionAbility界面内容相关信息。 | + +**示例：** + +```ts +import { UIExtensionContentSession } from '@kit.AbilityKit'; +import { LiveFormExtensionAbility } from '@kit.FormKit'; +import { LiveFormInfo } from '@ohos.app.form.LiveFormExtensionAbility'; + +const TAG: string = '[testTag] LiveFormExtAbility'; + +export default class LiveFormExtAbility extends LiveFormExtensionAbility { + onLiveFormCreate(liveFormInfo: LiveFormInfo, session: UIExtensionContentSession) { + console.info(TAG, `onLiveFormCreate, liveFormInfo: ${JSON.stringify(liveFormInfo)}`); + } +} +``` + +### onLiveFormDestroy + +onLiveFormDestroy(liveFormInfo: LiveFormInfo): void + +LiveFormExtensionAbility生命周期回调，在销毁时回调，执行资源清理等操作。 + +**模型约束：** 此接口仅可在Stage模型下使用。 + +**系统能力**：SystemCapability.Ability.Form + +**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| liveFormInfo | [LiveFormInfo](#liveforminfo) | 是 | 互动卡片信息，包括卡片id等信息。| + +**示例：** + +```ts +import { LiveFormExtensionAbility } from '@kit.FormKit'; +import { LiveFormInfo } from '@ohos.app.form.LiveFormExtensionAbility'; + +const TAG: string = '[testTag] LiveFormExtAbility'; + +export default class LiveFormExtAbility extends LiveFormExtensionAbility { + onLiveFormDestroy(liveFormInfo: LiveFormInfo) { + console.info(TAG, `onLiveFormDestroy, liveFormInfo: ${JSON.stringify(liveFormInfo)}`); + } +} +``` +### LiveFormInfo + +互动卡片信息。 + +**模型约束：** 此接口仅可在Stage模型下使用。 + +**系统能力：** SystemCapability.Ability.Form + +**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| ------ | ------ | ---- | ---- | -------- | +| formId | string | 否 | 否 | 卡片id。 | +| rect | [formInfo.Rect](js-apis-app-form-formInfo.md#rect20) | 否 | 否 | 卡片位置和大小信息。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis-form-kit/js-apis-application-LiveFormExtensionContext.md b/zh-cn/application-dev/reference/apis-form-kit/js-apis-application-LiveFormExtensionContext.md new file mode 100644 index 0000000000000000000000000000000000000000..b359bfd2f054462794333fb58355b2cf23d842d5 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-form-kit/js-apis-application-LiveFormExtensionContext.md @@ -0,0 +1,79 @@ +# LiveFormExtensionContext + +LiveFormExtensionContext是[LiveFormExtensionAbility](./js-apis-app-form-LiveFormExtensionAbility.md)的上下文，继承自[ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md)。 + +LiveFormExtensionContext提供允许访问特定于LiveFormExtensionAbility资源的能力。 + +> **说明：** +> +> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> +> 本模块接口仅可在Stage模型下使用。 + +## 导入模块 +```ts +import { LiveFormExtensionAbility } from '@kit.FormKit'; +``` +### LiveFormExtensionContext.setBackgroundImage + +setBackgroundImage(res: Resource): Promise<void> + +设置互动卡片的背景图。使用Promise异步回调。 + +**模型约束：** 此接口仅可在Stage模型下使用。 + +**系统能力：** SystemCapability.Ability.Form + +**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------------------- | + | res | [Resource](../apis-localization-kit/js-apis-resource.md) | 是 | 需要设置的互动卡片背景图对应的资源信息，包括资源id、资源类型等。| + +**返回值：** + +| 类型 | 说明 | +| ------------ | ---------------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)和[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | +| 16501010 | Failed to set the live form background image. | + +**示例：** + +```ts +import { UIExtensionContentSession } from '@kit.AbilityKit'; +import { BusinessError } from '@kit.BasicServicesKit'; +import { LiveFormExtensionAbility } from '@kit.FormKit'; +import { LiveFormInfo } from '@ohos.app.form.LiveFormExtensionAbility'; + +const TAG: string = '[testTag]LiveFormExtAbility'; + +export default class LiveFormExtAbility extends LiveFormExtensionAbility { + onLiveFormCreate(liveFormInfo: LiveFormInfo, session: UIExtensionContentSession): void { + try { + //请开发者自行在scr/main/resources/base/media路径下添加backgroundImage图片，否则运行时会因资源缺失而报错 + this.context.setBackgroundImage($r('app.media.backgroundImage')) + .then(() => { + // 执行正常业务 + console.info(TAG, 'setBackgroundImage succeed'); + }) + .catch((err: BusinessError) => { + // 处理业务逻辑错误 + console.error(TAG, `setBackgroundImage failed, code is ${err?.code}, message is ${err?.message}`); + }); + } catch (err) { + // 处理入参错误 + console.error(TAG, `setBackgroundImage failed, code is ${err?.code}, message is ${err?.message}`); + } + } +}; +``` \ No newline at end of file