@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

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
callback	AsyncCallback<void>	是	回调函数。当删除指定的卡片成功，error为undefined，否则为错误对象

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = '12400633174999288';
  formHost.deleteForm(formId, (error) => {
  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.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

deleteForm

deleteForm(formId: string): Promise<void>

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

参数：

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

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

1
2
3
4
5
6
7
8
9
10
11
12

releaseForm

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
callback	AsyncCallback<void>	是	回调函数。当释放指定的卡片成功，error为undefined；否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = '12400633174999288';
  formHost.releaseForm(formId, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

releaseForm

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
isReleaseCache	boolean	是	是否释放缓存。
callback	AsyncCallback<void>	是	回调函数。当释放指定的卡片成功，error为undefined；否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = '12400633174999288';
  formHost.releaseForm(formId, true, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

releaseForm

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
isReleaseCache	boolean	否	是否释放缓存。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = '12400633174999288';
  formHost.releaseForm(formId, true).then(() => {
    console.log('formHost releaseForm success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

requestForm

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
callback	AsyncCallback<void>	是	回调函数。当请求卡片更新成功，error为undefined；否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = '12400633174999288';
  formHost.requestForm(formId, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

requestForm

requestForm(formId: string): Promise<void>

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = '12400633174999288';
  formHost.requestForm(formId).then(() => {
    console.log('formHost requestForm success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12
13

castToNormalForm

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
callback	AsyncCallback<void>	是	回调函数。当将指定的临时卡片转换为普通卡片成功，error为undefined，否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = '12400633174999288';
  formHost.castToNormalForm(formId, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

castToNormalForm

castToNormalForm(formId: string): Promise<void>

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = '12400633174999288';
  formHost.castToNormalForm(formId).then(() => {
    console.log('formHost castTempForm success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

notifyVisibleForms

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
callback	AsyncCallback<void>	是	回调函数。当向卡片框架发送通知以使指定的卡片可见成功，error为undefined，否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = ['12400633174999288'];
  formHost.notifyVisibleForms(formId, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

notifyVisibleForms

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = ['12400633174999288'];
  formHost.notifyVisibleForms(formId).then(() => {
    console.log('formHost notifyVisibleForms success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

notifyInvisibleForms

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
callback	AsyncCallback<void>	是	回调函数。当向卡片框架发送通知以使指定的卡片不可见成功，error为undefined，否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = ['12400633174999288'];
  formHost.notifyInvisibleForms(formId, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

notifyInvisibleForms

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = ['12400633174999288'];
  formHost.notifyInvisibleForms(formId).then(() => {
    console.log('formHost notifyInvisibleForms success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

enableFormsUpdate

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
callback	AsyncCallback<void>	是	回调函数。当向卡片框架发送通知以使指定的卡片可以更新成功，error为undefined，否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = ['12400633174999288'];
  formHost.enableFormsUpdate(formId, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

enableFormsUpdate

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = ['12400633174999288'];
  formHost.enableFormsUpdate(formId).then(() => {
    console.log('formHost enableFormsUpdate success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

disableFormsUpdate

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
callback	AsyncCallback<void>	是	回调函数。当向卡片框架发送通知以使指定的卡片不可以更新成功，error为undefined，否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = ['12400633174999288'];
  formHost.disableFormsUpdate(formId, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

disableFormsUpdate

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  let formId = ['12400633174999288'];
  formHost.disableFormsUpdate(formId).then(() => {
    console.log('formHost disableFormsUpdate success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

isSystemReady

isSystemReady(callback: AsyncCallback<void>): void

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

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调函数。当检查系统是否准备好成功，error为undefined，否则为错误对象。

示例：

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

try {
  formHost.isSystemReady((error, data) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11

isSystemReady

isSystemReady(): Promise<void>

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

系统能力：SystemCapability.Ability.Form

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

示例：

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

try {
  formHost.isSystemReady().then(() => {
    console.log('formHost isSystemReady success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11

getAllFormsInfo

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

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

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Array<formInfo.FormInfo>>	是	回调函数。当获取设备上所有应用提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。

示例：

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

try {
  formHost.getAllFormsInfo((error, data) => {
    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.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12
13

getAllFormsInfo

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

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

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

返回值：

类型	说明
Promise<Array<formInfo.FormInfo>>	Promise对象，返回查询到的卡片信息。

示例：

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

try {
  formHost.getAllFormsInfo().then((data) => {
    console.log('formHost getAllFormsInfo data: ${JSON.stringify(data)}');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11

getFormsInfo

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

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

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
bundleName	string	是	要查询的应用Bundle名称。
callback	AsyncCallback<Array<formInfo.FormInfo>>	是	回调函数。当获取设备上指定应用程序提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', (error, data) => {
    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.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12
13

getFormsInfo

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

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

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
bundleName	string	是	要查询的应用Bundle名称。
moduleName	string	是	要查询的模块名称。
callback	AsyncCallback<Array<formInfo.FormInfo>>	是	回调函数。当获取设备上指定应用程序提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry', (error, data) => {
    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.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12
13

getFormsInfo

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

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

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
bundleName	string	是	要查询的应用Bundle名称。
moduleName	string	否	要查询的模块名称。

返回值：

类型	说明
Promise<Array<formInfo.FormInfo>>	Promise对象，返回查询到的卡片信息。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data) => {
    console.log('formHost getFormsInfo, data: ${JSON.stringify(data)}');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11

deleteInvalidForms

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	有效卡片标识列表。
callback	AsyncCallback<number>	是	回调函数。当根据列表删除应用程序的无效卡片成功，error为undefined，data为删除的卡片个数；否则为错误对象。

示例：

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

try {
  let formIds = new Array('12400633174999288', '12400633174999289');
  formHost.deleteInvalidForms(formIds, (error, data) => {
    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.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

deleteInvalidForms

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	有效卡片标识列表。

返回值：

类型	说明
Promise<number>	Promise对象，返回删除的卡片个数。

示例：

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

try {
  let formIds = new Array('12400633174999288', '12400633174999289');
  formHost.deleteInvalidForms(formIds).then((data) => {
    console.log('formHost deleteInvalidForms, data: ${JSON.stringify(data)}');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

acquireFormState

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

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

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

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
want	Want	是	查询卡片状态时携带的want信息。需要包含bundle名、ability名、module名、卡片名、卡片规格等。
callback	AsyncCallback<formInfo.FormStateInfo>	是	回调函数。当获取卡片状态成功，error为undefined，data为获取到的卡片状态；否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

let 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, data) => {
    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.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

acquireFormState

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

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

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

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
want	Want	是	查询卡片状态时携带的want信息。需要包含bundle名、ability名、module名、卡片名、卡片规格等。

返回值：

类型	说明
Promise<formInfo.FormStateInfo>	Promise对象，返回卡片状态。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

let 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) => {
    console.log('formHost acquireFormState, data: ${JSON.stringify(data)}');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

on('formUninstall')

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

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

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
type	string	是	填写'formUninstall'，表示卡片卸载事件。
callback	Callback<string>	是	回调函数。返回卡片标识。

示例：

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

let callback = function(formId) {
  console.log('formHost on formUninstall, formId: ${formId}');
}
formHost.on('formUninstall', callback);

1
2
3
4
5
6

off('formUninstall')

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

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

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
type	string	是	填写'formUninstall'，表示卡片卸载事件。
callback	Callback<string>	否	回调函数。返回卡片标识。缺省时，表示注销所有已注册事件回调。需与对应on('formUninstall')的callback一致。

示例：

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

let callback = function(formId) {
  console.log('formHost on formUninstall, formId: ${formId}');
}
formHost.off('formUninstall', callback);

1
2
3
4
5
6

notifyFormsVisible

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
isVisible	boolean	是	是否可见。
callback	AsyncCallback<void>	是	回调函数。当通知卡片是否可见成功，error为undefined，否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

let formIds = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsVisible(formIds, true, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

notifyFormsVisible

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
isVisible	boolean	是	是否可见。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

let formIds = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsVisible(formIds, true).then(() => {
    console.log('formHost notifyFormsVisible success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

notifyFormsEnableUpdate

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
isEnableUpdate	boolean	是	是否使能更新。
callback	AsyncCallback<void>	是	回调函数。当通知卡片是否启用更新状态成功，error为undefined，否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

let formIds = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsEnableUpdate(formIds, true, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

notifyFormsEnableUpdate

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
isEnableUpdate	boolean	是	是否使能更新。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

let formIds = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsEnableUpdate(formIds, true).then(() => {
    console.log('formHost notifyFormsEnableUpdate success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

shareForm

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

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

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

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
deviceId	string	是	远程设备标识。
callback	AsyncCallback<void>	是	回调函数。当指定formId和远程设备Id进行卡片分享成功，error为undefined，否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

let formId = '12400633174999288';
let deviceId = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2';
try {
  formHost.shareForm(formId, deviceId, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12
13

shareForm

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

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

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

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
deviceId	string	是	远程设备标识。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

let formId = '12400633174999288';
let deviceId = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2';
try {
  formHost.shareForm(formId, deviceId).then(() => {
    console.log('formHost shareForm success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12
13

notifyFormsPrivacyProtected

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	需要修改隐私保护的卡片标识列表。
isProtected	boolean	是	是否进行隐私保护。
callback	AsyncCallback<void>	是	回调函数。当指定卡片设置隐私保护属性成功，error为undefined，否则为错误对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

示例：

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

let formIds = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsPrivacyProtected(formIds, true, (error) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

notifyFormsPrivacyProtected

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

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

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	需要修改隐私保护的卡片标识列表。
isProtected	boolean	是	是否进行隐私保护。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
401	调用接口入参错误。
以上错误码的详细介绍请参见卡片错误码。

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

let formIds = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsPrivacyProtected(formIds, true).then(() => {
    console.log('formHost notifyFormsPrivacyProtected success');
  }).catch((error) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

1
2
3
4
5
6
7
8
9
10
11
12

@ohos.app.form.formHost (formHost)

@ohos.app.form.formHost (formHost)

导入模块

deleteForm

deleteForm

releaseForm

releaseForm

releaseForm

requestForm

requestForm

castToNormalForm

castToNormalForm

notifyVisibleForms

notifyVisibleForms

notifyInvisibleForms

notifyInvisibleForms

enableFormsUpdate

enableFormsUpdate

disableFormsUpdate

disableFormsUpdate

isSystemReady

isSystemReady

getAllFormsInfo

getAllFormsInfo

getFormsInfo

getFormsInfo

getFormsInfo

deleteInvalidForms

deleteInvalidForms

acquireFormState

acquireFormState

on('formUninstall')

off('formUninstall')

notifyFormsVisible

notifyFormsVisible

notifyFormsEnableUpdate

notifyFormsEnableUpdate

shareForm

shareForm

notifyFormsPrivacyProtected

notifyFormsPrivacyProtected

Description