diff --git a/en/release-notes/changelogs/OpenHarmony_4.0.9.5/changelogs-formfwk.md b/en/release-notes/changelogs/OpenHarmony_4.0.9.5/changelogs-formfwk.md new file mode 100644 index 0000000000000000000000000000000000000000..e5ed4eecd2e0d4e6c1f176d6bfa808c136a3889b --- /dev/null +++ b/en/release-notes/changelogs/OpenHarmony_4.0.9.5/changelogs-formfwk.md @@ -0,0 +1,146 @@ +# formfwk Subsystem Changelog + +## cl.formfwk.1 Some APIs Moved from @ohos.app.form.formHost.d.ts and Their Permission Changed + +1. 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**. + +2. The permission for these APIs is changed from **ohos.permission.REQUIRE_FORM** to **ohos.permission.OBSERVE_FORM_RUNNING**. + +**Change Impact** + +Applications that use the involved APIs may have compatibility issues. + +**Key API/Component Changes** + +| API | Home .d.ts File Before Modification| Home .d.ts File After Modification| Permission Required Before Modification| Permission Required After Modification| +| -------- | -------- | -------- | -------- | -------- | +| 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| +| 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 | +| 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 | +| 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 | +| 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 | +| 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 | +| 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 | +| 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 | +| 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 | +| 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 | +| 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 | + +**Adaptation Guide** + +Adapt 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. + +**Example** + +```js +import formObserver from @ohos.app.form.formObserver.d.ts; + +try { + formObserver.getRunningFormInfos((error, data) => { + if (error) { + console.error(`error, code: ${error.code}, message: ${error.message}`); + } else { + console.log('formHost getRunningFormInfos, data: ${JSON.stringify(data)}'); + } + }, 'com.example.ohos.formjsdemo'); +} catch(error) { + console.error(`catch error, code: ${error.code}, message: ${error.message}`); +} +``` + + +## cl.formfwk.2 Adjusted the Parameter Sequence of Event Subscription and Unsubscription APIs (on/off) + +The **callback** parameter is moved as the last parameter in the event subscription and unsubscription APIs (**on**/**off**). + +**Change Impact** + +Applications that use the involved APIs may have compatibility issues. + +**Key API/Component Changes** + +Before change: + +```js +function on(type: 'formAdd', observerCallback: Callback, bundleName?: string): void; +function off(type: 'formAdd', observerCallback?: Callback, bundleName?: string): void; + +function on(type: 'formRemove', observerCallback: Callback, bundleName?: string): void; +function off(type: 'formRemove', observerCallback?: Callback, bundleName?: string): void; + +function on( + type: 'notifyVisible', + observerCallback: Callback>, + hostBundleName?: string + ): void; +function off( + type: 'notifyVisible', + observerCallback?: Callback>, + hostBundleName?: string + ): void; + +function on( + type: 'notifyInvisible', + observerCallback: Callback>, + hostBundleName?: string + ): void; +function off( + type: 'notifyInvisible', + observerCallback?: Callback>, + hostBundleName?: string + ): void; +``` + +After change: + +```js +function on(type: 'formAdd', observerCallback: Callback): void; +function on(type: 'formAdd', hostBundleName: string, observerCallback: Callback): void; +function off(type: 'formAdd', hostBundleName?: string, observerCallback?: Callback): void; + +function on(type: 'formRemove', observerCallback: Callback): void; +function on(type: 'formRemove', hostBundleName: string, observerCallback: Callback): void; +function off(type: 'formRemove', hostBundleName?: string, observerCallback?: Callback): void; + +function on(type: 'notifyVisible', observerCallback: Callback>): void; +function on( + type: 'notifyVisible', + hostBundleName: string, + observerCallback: Callback> + ): void; +function off( + type: 'notifyVisible', + hostBundleName?: string, + observerCallback?: Callback> + ): void; + +function on(type: 'notifyInvisible', observerCallback: Callback>): void; +function on( + type: 'notifyInvisible', + hostBundleName: string, + observerCallback: Callback>, + ): void; +function off( + type: 'notifyInvisible', + hostBundleName?: string, + observerCallback?: Callback> + ): void; +``` + +**Adaptation Guide** + +Adapt your application code accordingly. In OpenHarmony 4.0.9.5 and later versions, pass in **callback** as the last parameter when calling these APIs. + +**Example** + +```js +import formObserver from @ohos.app.form.formObserver.d.ts; + +let bundleName = 'ohos.samples.FormApplication'; +let callback = function(data) { + console.log('a new form added, data: ${JSON.stringify(data)'); +} + +formHost.on('formAdd', callback); +formHost.on('formAdd', bundleName, callback); +```