1# formfwk Subsystem Changelog
2
3## cl.formfwk.1 Some APIs Moved from @ohos.app.form.formHost.d.ts and Their Permission Changed
4
51. APIs used for listening for and obtaining dynamic widget information are moved from **@ohos.app.form.formHost.d.ts** to **@ohos.app.form.formObserver.d.ts**.
62. The permission for these APIs is changed from **ohos.permission.REQUIRE_FORM** to **ohos.permission.OBSERVE_FORM_RUNNING**.
7
8**Change Impact**
9
10Applications that use the involved ArkTS APIs may have compatibility issues.
11
12**Key API/Component Changes**
13
14|     API     | Home .d.ts File Before Modification| Home .d.ts File After Modification| Permission Required Before Modification| Permission Required After Modification|
15|   --------    |   --------    |   --------    | --------      | --------  |
16| on('formAdd') | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM|ohos.permission.OBSERVE_FORM_RUNNING|
17| off('formAdd')| @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM|ohos.permission.OBSERVE_FORM_RUNNING | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING |
18| on('formRemove') | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING |
19| off('formRemove') | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING |
20| on('notifyVisible') | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING |
21| off('notifyVisible') | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING |
22| on('notifyInvisible') | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING |
23| off('notifyInvisible') | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING |
24| getRunningFormInfos | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING |
25| getRunningFormInfosByFilter | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING |
26| getRunningFormInfoById | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING | @ohos.app.form.formHost.d.ts | @ohos.app.form.formObserver.d.ts | ohos.permission.REQUIRE_FORM | ohos.permission.OBSERVE_FORM_RUNNING |
27
28
29**Adaptation Guide**
30
31Adapt your application code accordingly. To use these APIs in OpenHarmony 4.0.9.5 and later versions, import **@ohos.app.form.formObserver.d.ts** and request the **ohos.permission.OBSERVE_FORM_RUNNING** permission.
32
33**Example**
34```ts
35import formObserver from '@ohos.app.form.formObserver';
36import formInfo from '@ohos.app.form.formInfo';
37import Base from '@ohos.base';
38
39try {
40  formObserver.getRunningFormInfos((error: Base.BusinessError, data: formInfo.RunningFormInfo[]) => {
41    if (error) {
42      console.error(`error, code: ${error.code}, message: ${error.message}`);
43    } else {
44      console.log('formHost getRunningFormInfos, data: ${JSON.stringify(data)}');
45    }
46  }, 'com.example.ohos.formjsdemo');
47} catch(error) {
48  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
49}
50```
51
52## cl.formfwk.2 Adjusted the Parameter Sequence of Event Subscription and Unsubscription APIs (on/off)
53
54The **callback** parameter is moved as the last parameter in the event subscription and unsubscription APIs (**on**/**off**).
55
56**Change Impact**
57
58Applications that use the involved ArkTS APIs may have compatibility issues.
59
60**Key API/Component Changes**
61
62Before change:
63
64```ts
65function on(type: 'formAdd', observerCallback: Callback<formInfo.RunningFormInfo>, bundleName?: string): void;
66function off(type: 'formAdd', observerCallback?: Callback<formInfo.RunningFormInfo>, bundleName?: string): void;
67
68function on(type: 'formRemove', observerCallback: Callback<formInfo.RunningFormInfo>, bundleName?: string): void;
69function off(type: 'formRemove', observerCallback?: Callback<formInfo.RunningFormInfo>, bundleName?: string): void;
70
71function on(
72    type: 'notifyVisible',
73    observerCallback: Callback<Array<formInfo.RunningFormInfo>>,
74    hostBundleName?: string
75  ): void;
76function off(
77    type: 'notifyVisible',
78    observerCallback?: Callback<Array<formInfo.RunningFormInfo>>,
79    hostBundleName?: string
80  ): void;
81
82function on(
83    type: 'notifyInvisible',
84    observerCallback: Callback<Array<formInfo.RunningFormInfo>>,
85    hostBundleName?: string
86  ): void;
87function off(
88    type: 'notifyInvisible',
89    observerCallback?: Callback<Array<formInfo.RunningFormInfo>>,
90    hostBundleName?: string
91  ): void;
92```
93
94After change:
95
96```ts
97function on(type: 'formAdd', observerCallback: Callback<formInfo.RunningFormInfo>): void;
98function on(type: 'formAdd', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void;
99function off(type: 'formAdd', hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void;
100
101function on(type: 'formRemove', observerCallback: Callback<formInfo.RunningFormInfo>): void;
102function on(type: 'formRemove', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void;
103function off(type: 'formRemove', hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void;
104
105function on(type: 'notifyVisible', observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void;
106function on(
107    type: 'notifyVisible',
108    hostBundleName: string,
109    observerCallback: Callback<Array<formInfo.RunningFormInfo>>
110  ): void;
111function off(
112    type: 'notifyVisible',
113    hostBundleName?: string,
114    observerCallback?: Callback<Array<formInfo.RunningFormInfo>>
115  ): void;
116
117function on(type: 'notifyInvisible', observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void;
118function on(
119    type: 'notifyInvisible',
120    hostBundleName: string,
121    observerCallback: Callback<Array<formInfo.RunningFormInfo>>,
122  ): void;
123function off(
124    type: 'notifyInvisible',
125    hostBundleName?: string,
126    observerCallback?: Callback<Array<formInfo.RunningFormInfo>>
127  ): void;
128```
129
130
131**Adaptation Guide**
132
133Adapt your application code accordingly. In OpenHarmony 4.0.9.5 and later versions, pass in **callback** as the last parameter when calling these APIs.
134
135**Example**
136```ts
137import formObserver from '@ohos.app.form.formObserver';
138
139let bundleName = 'ohos.samples.FormApplication';
140let callback = function(data) {
141  console.log('a new form added, data: ${JSON.stringify(data)');
142}
143
144formHost.on('formAdd', callback);
145formHost.on('formAdd', bundleName, callback);
146```
147