@ohos.app.form.formHost (formHost)


@ohos.app.form.formHost (formHost)

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

说明:

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

导入模块

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

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