@ohos.app.form.formObserver (formObserver)

The formObserver module provides APIs related to widget listeners. You can use the APIs to subscribe to and unsubscribe from widget addition, removal, and visibility change events, and obtain information about running widgets.

NOTE

The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. The APIs provided by this module are system APIs.

Modules to Import

import formObserver from '@ohos.app.form.formObserver';

on('formAdd')

on(type: 'formAdd', observerCallback: Callback<formInfo.RunningFormInfo>): void

Subscribes to widget addition events. This API uses an asynchronous callback to return the information about the new widget.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let callback = (data: formInfo.RunningFormInfo) => {
  console.log(`a new form added, data: ${JSON.stringify(data)}`);
}

formObserver.on('formAdd', callback);

on('formAdd')

on(type: 'formAdd', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void

Subscribes to widget addition events for a given bundle that functions as the widget host. This API uses an asynchronous callback to return the information about the new widget.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let bundleName: string = 'ohos.samples.FormApplication';

let callback = (data: formInfo.RunningFormInfo) => {
  console.log(`a new form added, data: ${JSON.stringify(data)}`);
}

formObserver.on('formAdd', bundleName, callback);

off('formAdd')

off(type: "formAdd", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void

Unsubscribes from widget addition events. This API uses an asynchronous callback to return the information about the new widget.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let bundleName: string = 'ohos.samples.FormApplication';

let callback = (data: formInfo.RunningFormInfo) => {
  console.log(`a new form added, data: ${JSON.stringify(data)}`);
}

formObserver.off('formAdd', bundleName, callback);

NOTE on('formAdd', callback) and off('formAdd', callback) must be used in pairs. on('formAdd', bundleName, callback) and off('formAdd', bundleName, callback) must be used in pairs. To cancel the subscription with a given callback or for a given bundle name, the callback or bundleName parameter in off() must be set to the same value as that in on().

on('formRemove')

on(type: 'formRemove', observerCallback: Callback<formInfo.RunningFormInfo>): void

Subscribes to widget removal events. This API uses an asynchronous callback to return the information about the widget removed.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let callback = (data: formInfo.RunningFormInfo) => {
  console.log(`form deleted, data: ${JSON.stringify(data)}`);
}

formObserver.on('formRemove', callback);

on('formRemove')

on(type: 'formRemove', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void

Subscribes to widget removal events for a given bundle, which functions as the widget host. This API uses an asynchronous callback to return the information about the widget removed.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let bundleName: string = 'ohos.samples.FormApplication';

let callback = (data: formInfo.RunningFormInfo) => {
  console.log(`form deleted, data: ${JSON.stringify(data)}`);
}

formObserver.on('formRemove', bundleName, callback);

off('formRemove')

off(type: "formRemove", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void

Unsubscribes from widget removal events. This API uses an asynchronous callback to return the information about the widget removed.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let bundleName: string = 'ohos.samples.FormApplication';

let callback = (data: formInfo.RunningFormInfo) => {
  console.log(`a new form added, data: ${JSON.stringify(data)}`);
}

formObserver.off('formRemove', bundleName, callback);

NOTE on('formRemove', callback) and off('formRemove', callback) must be used in pairs. on('formRemove', bundleName, callback) and off('formRemove', bundleName, callback) must be used in pairs. To cancel the subscription with a given callback or for a given bundle name, the callback or bundleName parameter in off() must be set to the same value as that in on().

on('notifyVisible')

on(type: 'notifyVisible', observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void

Subscribes to events indicating that a widget becomes visible. This API uses an asynchronous callback to return the result.

​The event is triggered when notifyVisibleForms is called to notify that the widget becomes visible.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let callback = (data: formInfo.RunningFormInfo[]) => {
  console.log(`form change visibility, data: ${JSON.stringify(data)}`);
}

formObserver.on('notifyVisible', callback);

on('notifyVisible')

on(type: 'notifyVisible', hostBundleName: string, observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void

Subscribes to events indicating that a widget becomes visible for a given bundle, which functions as the widget host. This API uses an asynchronous callback to return the result.

​The event is triggered when notifyVisibleForms is called to notify that the widget becomes visible.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let bundleName: string = 'ohos.samples.FormApplication';

let callback = (data: formInfo.RunningFormInfo[]) => {
  console.log(`form change visibility, data: ${JSON.stringify(data)}`);
}

formObserver.on('notifyVisible', bundleName, callback);

off('notifyVisible')

off(type: "notifyVisible", hostBundleName?: string, observerCallback?: Callback<Array<formInfo.RunningFormInfo>>): void

Unsubscribes from events indicating that a widget becomes visible. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let bundleName: string = 'ohos.samples.FormApplication';

let callback = (data: formInfo.RunningFormInfo[]) => {
  console.log(`form change visibility, data: ${JSON.stringify(data)}`);
}

formObserver.off('notifyVisible', bundleName, callback);

NOTE on('notifyVisible', callback) and off('notifyVisible', callback) must be used in pairs. on('notifyVisible', bundleName, callback) and off('notifyVisible', bundleName, callback) must be used in pairs. To cancel the subscription with a given callback or for a given bundle name, the callback or bundleName parameter in off() must be set to the same value as that in on().

on('notifyInvisible')

on(type: 'notifyInvisible', observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void

Subscribes to events indicating that a widget becomes invisible. This API uses an asynchronous callback to return the result.

​The event is triggered when notifyInvisibleForms is called to notify that the widget becomes invisible.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let callback = (data: formInfo.RunningFormInfo[]) => {
  console.log(`form change invisibility, data: ${JSON.stringify(data)}`);
}

formObserver.on('notifyInvisible', callback);

on('notifyInvisible')

on(type: 'notifyInvisible', hostBundleName: string, observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void

Subscribes to events indicating that a widget becomes invisible for a given bundle, which functions as the widget host. This API uses an asynchronous callback to return the result.

​The event is triggered when notifyInvisibleForms is called to notify that the widget becomes invisible.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let bundleName: string = 'ohos.samples.FormApplication';

let callback = (data: formInfo.RunningFormInfo[]) => {
  console.log(`form change invisibility, data: ${JSON.stringify(data)}`);
}

formObserver.on('notifyInvisible', bundleName, callback);

off('notifyInvisible')

off(type: "notifyInvisible", hostBundleName?: string, observerCallback?: Callback<Array<formInfo.RunningFormInfo>>): void

Unsubscribes from events indicating that a widget becomes invisible. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';

let bundleName: string = 'ohos.samples.FormApplication';

let callback = (data: formInfo.RunningFormInfo[]) => {
  console.log(`form change invisibility, data: ${JSON.stringify(data)}`);
}

formObserver.off('notifyInvisible', bundleName, callback);

NOTE on('notifyInvisible', callback) and off('notifyInvisible', callback) must be used in pairs. on('notifyInvisible', bundleName, callback) and off('notifyInvisible', bundleName, callback) must be used in pairs. To cancel the subscription with a given callback or for a given bundle name, the callback or bundleName parameter in off() must be set to the same value as that in on().

getRunningFormInfos

getRunningFormInfos(callback: AsyncCallback<Array<formInfo.RunningFormInfo>>, hostBundleName?: string): void

Obtains the information about all non-temporary widgets running on the device. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Error codes For details about the error codes, see Form Error Codes.

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';
import Base from '@ohos.base';

try {
  formObserver.getRunningFormInfos((error: Base.BusinessError, data: formInfo.RunningFormInfo[]) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log(`formObserver getRunningFormInfos, data: ${JSON.stringify(data)}`);
    }
  }, 'com.example.ohos.formjsdemo');
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

getRunningFormInfos

getRunningFormInfos(hostBundleName?: string): Promise<Array<formInfo.RunningFormInfo>>

Obtains the information about all non-temporary widgets running on the device. This API uses a promise to return the result.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Return value

Error codes For details about the error codes, see Form Error Codes.

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';
import Base from '@ohos.base';

try {
  formObserver.getRunningFormInfos('com.example.ohos.formjsdemo').then((data: formInfo.RunningFormInfo[]) => {
    console.log(`formObserver getRunningFormInfos, data: ${JSON.stringify(data)}`);
  }).catch((error: Base.BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

getRunningFormInfosByFilter

getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter): Promise<Array<formInfo.RunningFormInfo>>

Obtains the information about widgets based on the widget provider. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Return value

Error codes

For details about the error codes, see Form Error Codes.

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';
import Base from '@ohos.base';

let formInstanceFilter: formInfo.FormProviderFilter = {
  bundleName: "com.example.formprovide",
  abilityName: "EntryFormAbility",
  formName: "widget",
  moduleName: "entry"
}
try {
  formObserver.getRunningFormInfosByFilter(formInstanceFilter).then((data: formInfo.RunningFormInfo[]) => {
    console.info('formObserver getRunningFormInfosByFilter success, data:' + JSON.stringify(data));
  }).catch((error: Base.BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

getRunningFormInfosByFilter

getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter, callback: AsyncCallback<Array<formInfo.RunningFormInfo>>): void

Obtains the information about widgets based on the widget provider. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Error codes

For details about the error codes, see Form Error Codes.

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';
import Base from '@ohos.base';

let formInstanceFilter: formInfo.FormProviderFilter = {
  bundleName: "com.example.formprovide",
  abilityName: "EntryFormAbility",
  formName: "widget",
  moduleName: "entry"
}
try {
  formObserver.getRunningFormInfosByFilter(formInstanceFilter,(error: Base.BusinessError, data: formInfo.RunningFormInfo[]) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log(`formObserver getRunningFormInfosByFilter, data: ${JSON.stringify(data)}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

getRunningFormInfoById

getRunningFormInfoById(formId: string): Promise<formInfo.RunningFormInfo>

Obtains the information about the widget based on the widget ID. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Return value

Error codes

For details about the error codes, see Form Error Codes.

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';
import Base from '@ohos.base';

let formId: string = '12400633174999288';
try {
  formObserver.getRunningFormInfoById(formId).then((data: formInfo.RunningFormInfo) => {
    console.info('formObserver getRunningFormInfoById success, data:' + JSON.stringify(data));
  }).catch((error: Base.BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

getRunningFormInfoById

getRunningFormInfoById(formId: string, callback: AsyncCallback<formInfo.RunningFormInfo>): void

Obtains the information about the widget based on the widget ID. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.OBSERVE_FORM_RUNNING

System capability: SystemCapability.Ability.Form

Parameters

Error codes

For details about the error codes, see Form Error Codes.

Example

import formObserver from '@ohos.app.form.formObserver';
import formInfo from '@ohos.app.form.formInfo';
import Base from '@ohos.base';

let formId: string = '12400633174999288';
try {
  formObserver.getRunningFormInfoById(formId,(error: Base.BusinessError, data: formInfo.RunningFormInfo) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log(`formObserver getRunningFormInfoById, data: ${JSON.stringify(data)}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}