1# Developing a Scene-based Widget (for System Applications) 2 3For details about the development guidelines of scene-based widgets, see [Developing a Scene-based Widget](arkts-ui-liveform-sceneanimation-development.md). For system applications, scene-based widgets provide two extended capabilities: gesture suspension configuration and long-term widget activation. 4 5## Available APIs 6 7The following table lists the key APIs for a scene-based widget. 8 9**Table 1** Main APIs 10 11| API | Description | 12|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| 13| [formProvider.activateSceneAnimation(formId: string): Promise<void>](../reference/apis-form-kit/js-apis-app-form-formProvider-sys.md#activatesceneanimation20) | Called to switch the interactive widget state to active.| 14| [formProvider.deactivateSceneAnimation(formId: string): Promise<void>](../reference/apis-form-kit/js-apis-app-form-formProvider-sys.md#deactivatesceneanimation20) | Called to switch the interactive widget state to inactive.| 15 16 17## Gesture Suspension Configuration 18For [scene-based widgets](arkts-ui-liveform-sceneanimation-overview.md), operations such as long-pressing and dragging on the home screen will interrupt the current animation, causing the widget to revert to the inactive state. However, system applications can cancel this limitation by configuring [disabledDesktopBehaviors](arkts-ui-widget-configuration.md#sceneanimationparams-field) in the **form_config.json** file, ensuring smooth animations within the interactive target of the activated widget. 19If no configuration is performed, the system does not intercept any valid gesture operations on the home screen by default. Once gestures are intercepted, the corresponding gesture events are handled by the 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## Long-term Widget Activation 42 43System applications can control widget state switching via APIs, enabling widgets to remain active for a long time. Widget state transitions are managed through [formProvider.activateSceneAnimation](../reference/apis-form-kit/js-apis-app-form-formProvider-sys.md#activatesceneanimation20) and [formProvider.deactivateSceneAnimation](../reference/apis-form-kit/js-apis-app-form-formProvider-sys.md#deactivatesceneanimation20). 44After the widget is activated by calling **formProvider.activateSceneAnimation**, the rendering area of the widget animation is the same as that of the widget itself. In this case, the overflow animation requested by calling the [formProvider.requestOverflow](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderrequestoverflow20) API does not take effect. 45 46### How to Develop 471. Import modules. 48 49```ts 50import { formProvider } from '@kit.FormKit'; 51import { BusinessError } from '@kit.BasicServicesKit'; 52``` 53 542. Trigger long-time widget activation. 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. Deactivate the widget. 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. Adapt LiveFormExtensionAbility. 87 88Loading complex UIs (for example, complex physical simulation animations) in the active state is time-consuming and often results in choppy page transitions. To address this, the [UIExtensionContentSession](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionContentSession.md) message notification mechanism is provided. Once the active page finishes loading, the widget provider must send a notification to the widget host via **UIExtensionContentSession**. Upon receiving the notification, the widget host then switches to the active state. 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 // Obtain the widget information. 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 // Load the provider page. 111 session.loadContent('mysystemliveformextensionability/pages/MySystemLiveFormPage', storage); 112 113 // Once the active page finishes loading, the widget provider must send a notification to the widget host via UIExtensionContentSession. 114 session.sendData({['isFormReady']: true}); 115 } 116 117 onLiveFormDestroy(liveFormInfo: LiveFormInfo) { 118 console.log(`MySystemLiveFormExtensionAbility onDestroy`); 119 } 120} 121``` 122