@ohos.app.form.formHost (formHost)(系统接口)

formHost模块提供了卡片使用方相关接口的能力，包括对使用方同一用户下安装的卡片进行删除、释放、请求更新、获取卡片信息、状态等操作。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 本模块接口均为系统接口。

导入模块

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

deleteForm

deleteForm(formId: string, callback: AsyncCallback<void>): void

删除指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务不再保留有关该卡片的信息。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.deleteForm(formId, (error: Base.BusinessError) => {
  if (error) {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  } else {
    console.log('formHost deleteForm success');
  }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

deleteForm

deleteForm(formId: string): Promise<void>

删除指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务不再保留有关该卡片的信息。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.deleteForm(formId).then(() => {
    console.log('formHost deleteForm success');
  }).catch((error: Base.BusinessError) => {
    console.error(`formHost deleteForm, error: ${JSON.stringify(error)}`);
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

releaseForm

releaseForm(formId: string, callback: AsyncCallback<void>): void

释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，但卡片管理器服务仍然保留有关该卡片的缓存信息和存储信息。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.releaseForm(formId, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

releaseForm

releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void

释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务保留有关该卡片的存储信息，可以选择是否保留缓存信息。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.releaseForm(formId, true, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

releaseForm

releaseForm(formId: string, isReleaseCache?: boolean): Promise<void>

释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务保留有关该卡片的存储信息，可以选择是否保留缓存信息。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.releaseForm(formId, true).then(() => {
    console.log('formHost releaseForm success');
  }).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}`);
}

requestForm

requestForm(formId: string, callback: AsyncCallback<void>): void

请求卡片更新。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.requestForm(formId, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

requestForm

requestForm(formId: string): Promise<void>

请求卡片更新。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.requestForm(formId).then(() => {
    console.log('formHost requestForm success');
  }).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}`);
}

castToNormalForm

castToNormalForm(formId: string, callback: AsyncCallback<void>): void

将指定的临时卡片转换为普通卡片。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.castToNormalForm(formId, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

castToNormalForm

castToNormalForm(formId: string): Promise<void>

将指定的临时卡片转换为普通卡片。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.castToNormalForm(formId).then(() => {
    console.log('formHost castTempForm success');
  }).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}`);
}

notifyVisibleForms

notifyVisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void

向卡片框架发送通知以使指定的卡片可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyVisibleForms(formId, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

notifyVisibleForms

notifyVisibleForms(formIds: Array<string>): Promise<void>

向卡片框架发送通知以使指定的卡片可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyVisibleForms(formId).then(() => {
    console.log('formHost notifyVisibleForms success');
  }).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}`);
}

notifyInvisibleForms

notifyInvisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void

向卡片框架发送通知以使指定的卡片不可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyInvisibleForms(formId, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

notifyInvisibleForms

notifyInvisibleForms(formIds: Array<string>): Promise<void>

向卡片框架发送通知以使指定的卡片不可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyInvisibleForms(formId).then(() => {
    console.log('formHost notifyInvisibleForms success');
  }).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}`);
}

enableFormsUpdate

enableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void

向卡片框架发送通知以使指定的卡片可以更新。该方法调用成功后，卡片刷新状态设置为使能，卡片可以接收来自卡片提供方的更新。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.enableFormsUpdate(formId, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

enableFormsUpdate

enableFormsUpdate(formIds: Array<string>): Promise<void>

向卡片框架发送通知以使指定的卡片可以更新。该方法调用成功后，卡片刷新状态设置为使能，卡片可以接收来自卡片提供方的更新。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.enableFormsUpdate(formId).then(() => {
    console.log('formHost enableFormsUpdate success');
  }).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}`);
}

disableFormsUpdate

disableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void

向卡片框架发送通知以使指定的卡片不可以更新。该方法调用成功后，卡片刷新状态设置为去使能，卡片不可以接收来自卡片提供方的更新。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.disableFormsUpdate(formId, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

disableFormsUpdate

disableFormsUpdate(formIds: Array<string>): Promise<void>

向卡片框架发送通知以使指定的卡片不可以更新。该方法调用成功后，卡片刷新状态设置为去使能，卡片不可以接收来自卡片提供方的更新。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.disableFormsUpdate(formId).then(() => {
    console.log('formHost disableFormsUpdate success');
  }).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}`);
}

isSystemReady

isSystemReady(callback: AsyncCallback<void>): void

检查系统是否准备好。使用callback异步回调。

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  formHost.isSystemReady((error: Base.BusinessError) => {
    if (error) {
      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}`);
}

isSystemReady

isSystemReady(): Promise<void>

检查系统是否准备好。使用Promise异步回调。

系统能力：SystemCapability.Ability.Form

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  formHost.isSystemReady().then(() => {
    console.log('formHost isSystemReady success');
  }).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}`);
}

getAllFormsInfo

getAllFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void

获取设备上所有应用提供的卡片信息。使用callback异步回调。

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  formHost.getAllFormsInfo((error: Base.BusinessError, data: formInfo.FormInfo[]) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log(`formHost getAllFormsInfo, data: ${JSON.stringify(data)}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

getAllFormsInfo

getAllFormsInfo(): Promise<Array<formInfo.FormInfo>>

获取设备上所有应用提供的卡片信息。使用Promise异步回调。

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  formHost.getAllFormsInfo().then((data: formInfo.FormInfo[]) => {
    console.log(`formHost getAllFormsInfo 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}`);
}

getFormsInfo

getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void

获取设备上指定应用程序提供的卡片信息。使用callback异步回调。

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

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

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

getFormsInfo

getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void

获取设备上指定应用程序提供的卡片信息。使用callback异步回调。

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

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

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

getFormsInfo

getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>>

获取设备上指定应用程序提供的卡片信息。使用Promise异步回调。

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data: formInfo.FormInfo[]) => {
    console.log(`formHost getFormsInfo, 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}`);
}

deleteInvalidForms

deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void

根据列表删除应用程序的无效卡片。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formIds: string[] = new Array('12400633174999288', '12400633174999289');
  formHost.deleteInvalidForms(formIds, (error: Base.BusinessError, data: number) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log(`formHost deleteInvalidForms, data: ${JSON.stringify(data)}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

deleteInvalidForms

deleteInvalidForms(formIds: Array<string>): Promise<number>

根据列表删除应用程序的无效卡片。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

try {
  let formIds: string[] = new Array('12400633174999288', '12400633174999289');
  formHost.deleteInvalidForms(formIds).then((data: number) => {
    console.log(`formHost deleteInvalidForms, 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}`);
}

acquireFormState

acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void

获取卡片状态。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

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

let want: Want = {
  'deviceId': '',
  'bundleName': 'ohos.samples.FormApplication',
  'abilityName': 'FormAbility',
  'parameters': {
    'ohos.extra.param.key.module_name': 'entry',
    'ohos.extra.param.key.form_name': 'widget',
    'ohos.extra.param.key.form_dimension': 2
  }
};
try {
  formHost.acquireFormState(want, (error:Base.BusinessError, data: formInfo.FormStateInfo) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log(`formHost acquireFormState, data: ${JSON.stringify(data)}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

acquireFormState

acquireFormState(want: Want): Promise<formInfo.FormStateInfo>

获取卡片状态。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

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

let want: Want = {
  'deviceId': '',
  'bundleName': 'ohos.samples.FormApplication',
  'abilityName': 'FormAbility',
  'parameters': {
    'ohos.extra.param.key.module_name': 'entry',
    'ohos.extra.param.key.form_name': 'widget',
    'ohos.extra.param.key.form_dimension': 2
  }
};
try {
  formHost.acquireFormState(want).then((data: formInfo.FormStateInfo) => {
    console.log(`formHost acquireFormState, 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}`);
}

on('formUninstall')

on(type: 'formUninstall', callback: Callback<string>): void

订阅卡片卸载事件。使用callback异步回调。

说明：

卡片卸载与卡片移除不同。当应用卸载时，对应的卡片会自动卸载。

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

formHost.on('formUninstall', (formId: string) => {
  console.log(`formHost on formUninstall, formId: ${formId}`);
});

off('formUninstall')

off(type: 'formUninstall', callback?: Callback<string>): void

取消订阅卡片卸载事件。使用callback异步回调。

说明：

卡片卸载与卡片移除不同。当应用卸载时，对应的卡片会自动卸载。

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

formHost.off('formUninstall', (formId: string) => {
  console.log(`formHost on formUninstall, formId: ${formId}`);
});

notifyFormsVisible

notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void

通知卡片是否可见。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsVisible(formIds, true, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

notifyFormsVisible

notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void>

通知卡片是否可见。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsVisible(formIds, true).then(() => {
    console.log('formHost notifyFormsVisible success');
  }).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}`);
}

notifyFormsEnableUpdate

notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void

通知卡片是否启用更新状态。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsEnableUpdate(formIds, true, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

notifyFormsEnableUpdate

notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void>

通知卡片是否启用更新状态。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsEnableUpdate(formIds, true).then(() => {
    console.log('formHost notifyFormsEnableUpdate success');
  }).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}`);
}

shareForm

shareForm(formId: string, deviceId: string, callback: AsyncCallback<void>): void

指定formId和远程设备Id进行卡片分享。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM 和 ohos.permission.DISTRIBUTED_DATASYNC

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

let formId: string = '12400633174999288';
let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2';
try {
  formHost.shareForm(formId, deviceId, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

shareForm

shareForm(formId: string, deviceId: string): Promise<void>

指定formId和远程设备Id进行卡片分享。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM 和 ohos.permission.DISTRIBUTED_DATASYNC

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

let formId: string = '12400633174999288';
let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2';
try {
  formHost.shareForm(formId, deviceId).then(() => {
    console.log('formHost shareForm success');
  }).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}`);
}

notifyFormsPrivacyProtected

notifyFormsPrivacyProtected(formIds: Array<string>, isProtected: boolean, callback: AsyncCallback<void>): void

通知指定卡片隐私保护状态改变。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsPrivacyProtected(formIds, true, (error: Base.BusinessError) => {
    if (error) {
      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}`);
}

notifyFormsPrivacyProtected

notifyFormsPrivacyProtected(formIds: Array<string>, isProtected: boolean): Promise<void>

通知指定卡片隐私保护状态改变。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

import Base from '@ohos.base';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsPrivacyProtected(formIds, true).then(() => {
    console.log('formHost notifyFormsPrivacyProtected success');
  }).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}`);
}

acquireFormData¹⁰⁺

acquireFormData(formId: string, callback: AsyncCallback<Record<string, Object>>): void

请求卡片提供方数据。使用callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import Base from '@ohos.base';

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

acquireFormData¹⁰⁺

acquireFormData(formId: string): Promise<Record<string, Object>>

请求卡片提供方数据。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

import Base from '@ohos.base';

let formId: string = '12400633174999288';
try {
  formHost.acquireFormData(formId).then((data) => {
    console.log('formHost acquireFormData success' + 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}`);
}

setRouterProxy¹¹⁺

setRouterProxy(formIds: Array<string>, proxy: Callback<Want>, callback: AsyncCallback<void>): void

设置卡片跳转代理。使用callback异步回调，返回卡片跳转所需要Want信息。

说明：

• 一般情况下，对于桌面添加的卡片，当卡片触发router跳转时，卡片框架会检测其跳转目的地是否合理，是否有跳转权限，然后进行应用跳转。如果卡片使用方添加了卡片，并设置了卡片跳转代理，那么卡片触发router跳转时，卡片框架不会再为其进行跳转操作，会把包含跳转目的地的want参数返回给卡片使用方。因此如果卡片使用方希望使用该want信息进行应用跳转，需要确保自身拥有应用跳转的权限，参考 UIAbilityContext.startAbility()接口。

• 一个formId最多只能设置一个跳转代理，多次设置后，最后设置的proxy生效。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import common from '@ohos.app.ability.common';
import formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';
import Want from '@ohos.app.ability.Want';

@Entry
@Component
struct CardExample {
  private context = getContext(this) as common.UIAbilityContext;
  @State formId:number = 0;
  @State fwidth:number = 420;
  @State fheight:number = 280;

  build() {
    Column() {
      FormComponent({
        id:this.formId,
        name:"widget",
        bundle:"com.example.cardprovider",
        ability:"EntryFormAbility",
        module:"entry",
        dimension:FormDimension.Dimension_2_2,
        temporary:false,
      })
        .allowUpdate(true)
        .size({width:this.fwidth,height:this.fheight})
        .visibility(Visibility.Visible)
        .onAcquired((form)=>{
          console.log(`testTag form info : ${JSON.stringify(form)}`);
          this.formId = form.id;
          try {
            let formIds: string[] = [ this.formId.toString() ];
            formHost.setRouterProxy(formIds, (want: Want) => {
              console.info(`formHost recv router event, want: ${JSON.stringify(want)}`);
              // 卡片使用方自己处理跳转
              this.context.startAbility(want, (err: Base.BusinessError) => {
                console.info(`formHost startAbility error, code: ${err.code}, message: ${err.message}`);
              });
            }, (err: Base.BusinessError) => {
              console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`);
            })
          } catch (e) {
            console.log('formHost setRouterProxy catch exception: ' + JSON.stringify(e));
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

setRouterProxy¹¹⁺

setRouterProxy(formIds: Array<string>, proxy: Callback<Want>): Promise<void>

设置卡片跳转代理。使用Promise异步回调，返回卡片跳转所需要Want信息。

说明：

• 一般情况下，对于桌面添加的卡片，当卡片触发router跳转时，卡片框架会检测其跳转目的地是否合理，是否有跳转权限，然后进行应用跳转。如果卡片使用方添加了卡片，并设置了卡片跳转代理，那么卡片触发router跳转时，卡片框架不会再为其进行跳转操作，会把包含跳转目的地的want参数返回给卡片使用方。因此如果卡片使用方希望使用该want信息进行应用跳转，需要确保自身拥有应用跳转的权限，参考UIAbilityContext.startAbility()接口。

• 一个formId最多只能设置一个跳转代理，多次设置后，最后设置的proxy生效。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import common from '@ohos.app.ability.common';
import formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';
import Want from '@ohos.app.ability.Want';

@Entry
@Component
struct CardExample {
  private context = getContext(this) as common.UIAbilityContext;
  @State formId:number = 0;
  @State fwidth:number = 420;
  @State fheight:number = 280;

  build() {
    Column() {
      FormComponent({
        id:this.formId,
        name:"widget",
        bundle:"com.example.cardprovider",
        ability:"EntryFormAbility",
        module:"entry",
        dimension:FormDimension.Dimension_2_2,
        temporary:false,
      })
        .allowUpdate(true)
        .size({width:this.fwidth,height:this.fheight})
        .visibility(Visibility.Visible)
        .onAcquired((form)=>{
          console.log(`testTag form info : ${JSON.stringify(form)}`);
          this.formId = form.id;
          try {
            let formIds: string[] = [ this.formId.toString() ];
            formHost.setRouterProxy(formIds, (want: Want) => {
              console.info(`formHost recv router event, want: ${JSON.stringify(want)}`);
              // 卡片使用方自己处理跳转
              this.context.startAbility(want, (err: Base.BusinessError) => {
                console.info(`formHost startAbility error, code: ${err.code}, message: ${err.message}`);
              });
            }).then(() => {
              console.info('formHost set router proxy success');
            }).catch((err: Base.BusinessError) => {
              console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`);
            })
          } catch (e) {
            console.log('formHost setRouterProxy catch exception: ' + JSON.stringify(e));
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

clearRouterProxy¹¹⁺

clearRouterProxy(formIds:Array<string>, callback: AsyncCallback<void>): void

清除卡片跳转代理。使用callback异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';
import Want from '@ohos.app.ability.Want';

try {
  let formIds: string[] = [ '12400633174999288' ];
  formHost.clearRouterProxy(formIds, (err: Base.BusinessError) => {
    if (err) {
        console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

clearRouterProxy¹¹⁺

clearRouterProxy(formIds:Array<string>): Promise<void>

清除卡片跳转代理。使用Promise异步回调。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';
import Want from '@ohos.app.ability.Want';

try {
  let formIds: string[] = [ '12400633174999288' ];
  formHost.clearRouterProxy(formIds).then(() => {
    console.log('formHost clear rourter proxy success');
  }).catch((err: Base.BusinessError) => {
    console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

setFormsRecyclable¹¹⁺

setFormsRecyclable(formIds:Array<string>, callback: AsyncCallback<void>): void

设置卡片可回收。使用callback异步回调。

模型约束: 此接口仅可在Stage模型下使用。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';
import Want from '@ohos.app.ability.Want';

try {
  let formIds: string[] = [ '12400633174999288' ];
  formHost.setFormsRecyclable(formIds, (err: Base.BusinessError) => {
    if (err) {
        console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

setFormsRecyclable¹¹⁺

setFormsRecyclable(formIds:Array<string>): Promise<void>

设置卡片可回收。使用Promise异步回调。

模型约束: 此接口仅可在Stage模型下使用。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';
import Want from '@ohos.app.ability.Want';

try {
  let formIds: string[] = [ '12400633174999288' ];
  formHost.setFormsRecyclable(formIds).then(() => {
    console.log('setFormsRecyclable success');
  }).catch((err: Base.BusinessError) => {
    console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

recoverForms¹¹⁺

recoverForms(formIds:Array<string>, callback: AsyncCallback<void>): void

恢复卡片。使用callback异步回调。

模型约束: 此接口仅可在Stage模型下使用。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';
import Want from '@ohos.app.ability.Want';

try {
  let formIds: string[] = [ '12400633174999288' ];
  formHost.recoverForms(formIds, (err: Base.BusinessError) => {
    if (err) {
        console.error(`recoverForms error, code: ${err.code}, message: ${err.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

recoverForms¹¹⁺

recoverForms(formIds: Array<string>): Promise<void>

恢复被回收的卡片，并将它的状态更新为不可回收，如果卡片未被回收则只更新状态为不可回收。使用Promise异步回调。

模型约束: 此接口仅可在Stage模型下使用。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

返回值：

错误码：

以上错误码的详细介绍请参见卡片错误码。

示例：

import formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';
import Want from '@ohos.app.ability.Want';

try {
  let formIds: string[] = [ '12400633174999288' ];
  formHost.recoverForms(formIds).then(() => {
    console.info('recover forms success');
  }).catch((err: Base.BusinessError) => {
    console.error(`formHost recover forms error, code: ${err.code}, message: ${err.message}`);
  });
} catch (e) {
  console.info(`catch error, code: ${e.code}, message: ${e.message}`);
}