• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 场景动效类型互动卡片开发指导（系统应用）
2
3场景动效类型互动卡片基础开发指导，可以参考文档[场景动效类型互动卡片开发指导](arkts-ui-liveform-sceneanimation-development.md)。针对系统应用，场景动效类型互动卡片提供了**手势禁用配置**和**卡片长时间保持激活态**两个扩展能力。
4
5## 接口说明
6
7场景动效类型互动卡片开发关键接口如下表所示。
8
9**表1** 主要接口
10
11| 接口名                                                                                                                                                                       | 描述                                                                                                                  |
12|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
13| [formProvider.activateSceneAnimation(formId: string): Promise<void>](../reference/apis-form-kit/js-apis-app-form-formProvider-sys.md#activatesceneanimation20)     | 互动卡片请求状态切换到激活态。 |
14| [formProvider.deactivateSceneAnimation(formId: string): Promise<void>](../reference/apis-form-kit/js-apis-app-form-formProvider-sys.md#deactivatesceneanimation20) | 互动卡片请求切换到非激活态。 |
15
16
17## 手势禁用配置
18针对[场景动效类型互动卡片](arkts-ui-liveform-sceneanimation-overview.md)，若用户在桌面的长按、拖拽等操作会打断当前动效，卡片重新变成非激活态。系统应用可通过form_config.json中[disabledDesktopBehaviors](arkts-ui-widget-configuration.md#sceneanimationparams标签)字段进行配置取消该限制，确保用户在激活态卡片交互热区内操作时，不打断当前卡片动效。
19不配置时，默认不拦截桌面的任何有效手势操作。手势操作被拦截后，对应的手势事件由LiveFormExtensionAbility响应。
20
21```ts
22// entry/src/main/resources/base/profile/form_config.json
23{
24  "forms": [
25    {
26      // ...
27      "sceneAnimationParams": {
28        "abilityName": "MySystemLiveFormExtensionAbility",
29        "disabledDesktopBehaviors": [
30          "SWIPE_DESKTOP",
31          "PULL_DOWN_SEARCH",
32          "LONG_CLICK",
33          "DRAG"
34        ]
35      }
36    }
37  ]
38}
39```
40
41## 卡片长时间保持激活态
42
43系统应用支持通过接口控制卡片状态切换，卡片可长时间保持激活态。卡片状态切换由[formProvider.activateSceneAnimation](../reference/apis-form-kit/js-apis-app-form-formProvider-sys.md#activatesceneanimation20)和[formProvider.deactivateSceneAnimation](../reference/apis-form-kit/js-apis-app-form-formProvider-sys.md#deactivatesceneanimation20)接口控制。
44此外，卡片通过formProvider.activateSceneAnimation切换到激活态后，卡片动效渲染区域和卡片自身渲染区域等大，此时调用[formProvider.requestOverflow](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderrequestoverflow20)接口请求溢出动效不生效。
45
46### 开发流程
471. 导入模块
48
49```ts
50import { formProvider } from '@kit.FormKit';
51import { BusinessError } from '@kit.BasicServicesKit';
52```
53
542. 触发卡片长时激活
55
56```ts
57let formId: string = '12400633174999288';
58
59try {
60  formProvider.activateSceneAnimation(formId).then(() => {
61    console.info('activateSceneAnimation succeed.');
62  }).catch((error: BusinessError) => {
63    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
64  });
65} catch (error) {
66  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
67}
68```
69
703. 卡片退出激活态
71
72```ts
73let formId: string = '12400633174999288';
74
75try {
76  formProvider.deactivateSceneAnimation(formId).then(() => {
77    console.info('deactivateSceneAnimation succeed.');
78  }).catch((error: BusinessError) => {
79    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
80  });
81} catch (error) {
82  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
83}
84```
85
864. LiveFormExtensionAbility适配
87
88激活态加载复杂页面UI时（例如复杂物理仿真动效等），耗时较长容易造成页面切换不流畅。因此提供基于[UIExtensionContentSession](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionContentSession.md)消息通知机制，当激活态页面加载完成，卡片提供方需通过UIExtensionContentSession发送信息通知卡片使用方，卡片使用方收到信息后再切换卡片激活态界面。
89
90```ts
91// entry/src/main/ets/mysystemliveformextensionability/MySystemLiveFormExtensionAbility.ets
92import { formInfo, LiveFormInfo, LiveFormExtensionAbility } from '@kit.FormKit';
93import { UIExtensionContentSession } from '@kit.AbilityKit';
94
95export default class MySystemLiveFormExtensionAbility extends LiveFormExtensionAbility {
96  onLiveFormCreate(liveFormInfo: LiveFormInfo, session: UIExtensionContentSession) {
97    let storage: LocalStorage = new LocalStorage();
98    storage.setOrCreate('session', session);
99
100    // 获取参卡片信息
101    let formId: string = liveFormInfo.formId as string;
102    storage.setOrCreate('formId', formId);
103    let formRect: formInfo.Rect = liveFormInfo.rect;
104    storage.setOrCreate('formRect', formRect);
105    let borderRadius: number = liveFormInfo.borderRadius;
106    storage.setOrCreate('borderRadius', borderRadius);
107    console.log(`MySystemLiveFormExtensionAbility onSessionCreate formId: ${formId}, borderRadius: ${borderRadius}` +
108      `, formRect: ${JSON.stringify(formRect)}`);
109
110    // 加载提供方页面
111    session.loadContent('mysystemliveformextensionability/pages/MySystemLiveFormPage', storage);
112
113    // 通过UIExtensionContentSession发送信息告知卡片使用方，告知确认激活态页面加载完成
114    session.sendData({['isFormReady']: true});
115  }
116
117  onLiveFormDestroy(liveFormInfo: LiveFormInfo) {
118    console.log(`MySystemLiveFormExtensionAbility onDestroy`);
119  }
120}
121```
122