Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
未验证 提交 18c1379e 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!21621 新增formObserver.d.ts对应文档 

Merge pull request !21621 from chenyuyan/0731
上级 42b769d1 6ecac6f0
隐藏空白更改
内联 并排
Showing with 699 addition and 568 deletion
zh-cn/application-dev/reference/apis/js-apis-app-form-formHost.md
浏览文件 @ 18c1379e
...@@ -1202,95 +1202,6 @@ try { ...@@ -1202,95 +1202,6 @@ try {
} }
``` ```
## getRunningFormInfos<sup>10+</sup>
getRunningFormInfos(callback: AsyncCallback&lt;Array&lt;formInfo.RunningFormInfo&gt;&gt;, hostBundleName?: string): void
获取设备上正在运行的所有非临时卡片信息。使用callback异步回调。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| callback | AsyncCallback&lt;Array&lt;formInfo.RunningFormInfo&gt;&gt; | 是 | 回调函数。获取设备上指定应用为卡片使用方的当前卡片信息成功，error为undefined，data为查询到的卡片信息。|
| hostBundleName | string | 否 | 指定要查询的卡片使用方名称，指定后会仅返回该卡片使用方下正在运行的非临时卡片信息。 <br> 缺省时，返回设备上所有正在运行的非临时卡片信息。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 16500050 | An IPC connection error happened. |
| 16500060 | A service connection error happened, please try again later. ||
**示例：**
```ts
import formHost from '@ohos.app.form.formHost';
try {
formHost.getRunningFormInfos((error, data) => {
if (error) {
console.error(`error, code: ${error.code}, message: ${error.message}`);
} else {
console.log('formHost getRunningFormInfos, data: ${JSON.stringify(data)}');
}
}, 'com.example.ohos.formjsdemo');
} catch(error) {
console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}
```
## getRunningFormInfos<sup>10+</sup>
getRunningFormInfos(hostBundleName?: string): Promise&lt;Array&lt;formInfo.RunningFormInfo&gt;&gt;
获取设备上正在运行的所有非临时卡片信息。使用Promise异步回调。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| hostBundleName | string | 否 | 指定要查询的卡片使用方名称，指定后会仅返回该卡片使用方下正在运行的非临时卡片信息。 <br> 缺省时，返回设备上所有正在运行的非临时卡片信息。 |
**返回值：**
| 类型 | 说明 |
| :----------------------------------------------------------- | :---------------------------------- |
| Promise&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | Promise对象，返回查询到的卡片信息。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 16500050 | An IPC connection error happened. |
| 16500060 | A service connection error happened, please try again later. ||
**示例：**
```ts
import formHost from '@ohos.app.form.formHost';
try {
formHost.getRunningFormInfos('com.example.ohos.formjsdemo').then((data) => {
console.log('formHost getRunningFormInfos, 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}`);
}
```
## deleteInvalidForms ## deleteInvalidForms
deleteInvalidForms(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;number&gt;): void deleteInvalidForms(formIds: Array&lt;string&gt;, callback: AsyncCallback&lt;number&gt;): void
...@@ -1583,138 +1494,6 @@ let callback = function(formId) { ...@@ -1583,138 +1494,6 @@ let callback = function(formId) {
formHost.off('formUninstall', callback); formHost.off('formUninstall', callback);
``` ```
## on('formAdd')<sup>10+</sup>
on(type: 'formAdd', observerCallback: Callback&lt;formInfo.RunningFormInfo&gt;, bundleName?: string): void
订阅卡片新增事件。使用callback异步回调，返回当前新增卡片的[RunningFormInfo](js-apis-app-form-formInfo.md)。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| type | string | 是 | 填写'formAdd'，表示卡片新增事件。 |
| callback | Callback&lt;formInfo.RunningFormInfo&gt; | 是 | 回调函数。返回新增卡片的RunningFormInfo。 |
| bundleName | string | 否 | 指定订阅卡片使用方包的bundleName。缺省则订阅所有卡片使用方的卡片新增事件。 |
**示例：**
```ts
import formHost from '@ohos.app.form.formHost';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('a new form added, data: ${JSON.stringify(data)');
}
formHost.on('formAdd', callback);
formHost.on('formAdd', callback, bundleName);
```
## off('formAdd')<sup>10+</sup>
off(type: "formAdd", observerCallback?: Callback&lt;formInfo.RunningFormInfo&gt;, bundleName?: string): void
取消订阅卡片新增事件。使用callback异步回调，返回当前新增卡片的[RunningFormInfo](js-apis-app-form-formInfo.md)。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| type | string | 是 | 填写'formAdd'，表示卡片新增事件。 |
| callback | Callback&lt;formInfo.RunningFormInfo&gt; | 否 | 回调函数。返回卡片RunningFormInfo。缺省时，表示注销对应已注册事件回调。<br> 需与对应on('formAdd')的callback一致。|
| bundleName | string | 否 | 指定订阅卡片使用方包的bundleName。<br> 填写该参数时，与注册时填写bundleName的on接口对应。<br> 缺省则订阅所有卡片使用方的卡片删除事件，与注册时未填写bundleName的on接口相对应。 |
**示例：**
```ts
import formHost from '@ohos.app.form.formHost';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('a new form added, data: ${JSON.stringify(data)');
}
formHost.off('formAdd', callback);
formHost.off('formAdd', callback, bundleName);
```
> **说明：**
> on('formAdd', callback)与off('formAdd', callback)相对应；
> on('formAdd', callback, bundleName)与off('formAdd', callback, bundleName)相对应；
> 订阅（on）只能由自己对应的取消订阅接口（off）取消。
## on('formRemove')<sup>10+</sup>
on(type: 'formRemove', observerCallback: Callback&lt;formInfo.RunningFormInfo&gt;, bundleName?: string): void
订阅卡片删除事件。使用callback异步回调，返回当前删除卡片的[RunningFormInfo](js-apis-app-form-formInfo.md)。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| type | string | 是 | 填写'formRemove'，表示卡片删除事件。 |
| callback | Callback&lt;formInfo.RunningFormInfo&gt; | 是 | 回调函数。返回删除卡片的RunningFormInfo。 |
| bundleName | string | 否 | 指定订阅卡片使用方包的bundleName。缺省则订阅所有卡片使用方的卡片删除事件。 |
**示例：**
```ts
import formHost from '@ohos.app.form.formHost';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('a new form added, data: ${JSON.stringify(data)');
}
formHost.on('formRemove', callback);
formHost.on('formRemove', callback, bundleName);
```
## off('formRemove')<sup>10+</sup>
off(type: "formRemove", observerCallback?: Callback&lt;formInfo.RunningFormInfo&gt;, bundleName?: string): void
取消订阅卡片删除事件。使用callback异步回调，返回当前删除卡片的[RunningFormInfo](js-apis-app-form-formInfo.md)。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| type | string | 是 | 填写'formRemove'，表示卡片删除事件。 |
| callback | Callback&lt;formInfo.RunningFormInfo&gt; | 否 | 回调函数。返回卡片RunningFormInfo。缺省时，表示注销对应已注册事件回调。<br> 需与对应on('formRemove')的callback一致。|
| bundleName | string | 否 | 指定订阅卡片使用方包的bundleName。<br> 填写该参数时，与注册时填写bundleName的on接口对应。<br> 缺省则订阅所有卡片使用方的卡片删除事件，与注册时未填写bundleName的on接口相对应。 |
**示例：**
```ts
import formHost from '@ohos.app.form.formHost';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('a new form added, data: ${JSON.stringify(data)');
}
formHost.off('formRemove', callback);
formHost.off('formRemove', callback, bundleName);
```
> **说明：**
> on('formRemove', callback)与off('formRemove', callback)相对应；
> on('formRemove', callback, bundleName)与off('formRemove', callback, bundleName)相对应；
> 订阅（on）只能由自己对应的取消订阅接口（off）取消。
## notifyFormsVisible ## notifyFormsVisible
notifyFormsVisible(formIds: Array&lt;string&gt;, isVisible: boolean, callback: AsyncCallback&lt;void&gt;): void notifyFormsVisible(formIds: Array&lt;string&gt;, isVisible: boolean, callback: AsyncCallback&lt;void&gt;): void
...@@ -2221,350 +2000,3 @@ try { ...@@ -2221,350 +2000,3 @@ try {
console.error(`catch error, code: ${error.code}, message: ${error.message}`); console.error(`catch error, code: ${error.code}, message: ${error.message}`);
} }
``` ```
## getRunningFormInfosByFilter<sup>10+</sup>
getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter): Promise&lt;Array&lt;formInfo.RunningFormInfo&gt;&gt;
根据提供方信息查询卡片已有的使用方列表信息。使用Promise异步回调。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | --------------- | ---- | -------------------------------- |
| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo.md#formProviderFilter) | 是 | 卡片提供方应用信息。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ------------------------- |
| Promise&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md#RunningFormInfo)&gt;&gt; | Promise对象，返回查询到的使用方列表信息。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
```ts
import formHost from '@ohos.app.form.formHost';
let formInstanceFilter = {
bundleName: "com.example.formprovide",
abilityName: "EntryFormAbility",
formName: "widget",
moduleName: "entry"
}
try {
formHost.getRunningFormInfosByFilter(formInstanceFilter).then(data1 => {
console.info('formHost getRunningFormInfosByFilter return err :');
}).catch((error) => {
console.error(`error, code: ${error.code}, message: ${error.message}`);
});
} catch(error) {
console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}
```
## getRunningFormInfosByFilter<sup>10+</sup>
getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter, callback: AsyncCallback&lt;Array&lt;formInfo.RunningFormInfo&gt;&gt;): void
根据提供方信息查询卡片已有的使用方列表信息。使用callback异步回调。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | --------------- | ---- | -------------------------------- |
| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo.md#formProviderFilter) | 是 | 卡片提供方应用信息。 |
| callback | AsyncCallback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 是 | 回调函数。返回查询到的使用方列表信息，error为undefined，data为查询到的使用方列表信息；否则为错误对象。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
```ts
import formHost from '@ohos.app.form.formHost';
let formInstanceFilter = {
bundleName: "com.example.formprovide",
abilityName: "EntryFormAbility",
formName: "widget",
moduleName: "entry"
}
try {
formHost.getRunningFormInfosByFilter(formInstanceFilter,(error, data) => {
if (error) {
console.error(`error, code: ${error.code}, message: ${error.message}`);
} else {
console.log('formHost getRunningFormInfosByFilter, data: ${JSON.stringify(data)}');
}
});
} catch(error) {
console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}
```
## getRunningFormInfoById<sup>10+</sup>
getRunningFormInfoById(formId: string): Promise&lt;formInfo.RunningFormInfo&gt;
根据formId查询卡片已有的使用方列表信息。使用Promise异步回调。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | --------------- | ---- | -------------------------------- |
| formId | string | 是 | 卡片标识。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ------------------------- |
| Promise&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt; | Promise对象，返回查询到的使用方列表信息。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
```ts
import formHost from '@ohos.app.form.formHost';
let formId = '12400633174999288';
try {
formHost.getRunningFormInfoById(formId).then(data1 => {
console.info('formHost getRunningFormInfoById return err :');
}).catch((error) => {
console.error(`error, code: ${error.code}, message: ${error.message}`);
});
} catch(error) {
console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}
```
## getRunningFormInfoById<sup>10+</sup>
getRunningFormInfoById(formId: string, callback: AsyncCallback&lt;formInfo.RunningFormInfo&gt;): void
根据提供方信息查询卡片已有的使用方列表信息。使用callback异步回调。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | --------------- | ---- | -------------------------------- |
| formId | string | 是 | 卡片标识。 |
| callback | AsyncCallback&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt; | 是 | 回调函数。返回查询到的使用方列表信息，error为undefined，data为查询到的使用方列表信息；否则为错误对象。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
```ts
import formHost from '@ohos.app.form.formHost';
let formId = '12400633174999288';
try {
formHost.getRunningFormInfoById(formId,(error, data) => {
if (error) {
console.error(`error, code: ${error.code}, message: ${error.message}`);
} else {
console.log('formHost getRunningFormInfoById, data: ${JSON.stringify(data)}');
}
});
} catch(error) {
console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}
```
## on('notifyVisible')<sup>10+</sup>
on(type: 'notifyVisible', observerCallback: Callback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt;, bundleName?: string): void
订阅通知卡片可见的事件。
​触发通知卡片可见场景为：调用notifyVisibleForms接口通知对应卡片可见性变更为可见状态
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 仅允许填写'notifyVisible'，表示订阅通知卡片可见的事件。 |
| callback | Callback &lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 是 | 回调函数。返回订阅通知卡片可见的RunningFormInfo。 |
| bundleName | string | 否 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。 |
**示例：**
```ts
import formHost from '@ohos.app.form.formHost';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('form change visibility, data: ${JSON.stringify(data)');
}
formHost.on('notifyVisible', callback);
formHost.on('notifyVisible', callback, bundleName);
```
## off('notifyVisible')<sup>10+</sup>
off(type: "notifyVisible", observerCallback?: Callback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt;, bundleName?: string): void
取消订阅通知卡片可见的事件。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 仅允许填写'notifyVisible'，表示取消订阅通知卡片为可见的事件。 |
| callback | Callback &lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 否 | 入参，注册时注册进去的callback。缺省时，表示注销对应已注册订阅的回调。<br> 需与对应on('notifyVisible')的callback一致。 |
| bundleName | string | 否 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。<br> 填写该参数时，与注册时填写bundleName的on接口对应。 |
**示例：**
```ts
import formHost from '@ohos.app.form.formHost';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('form change visibility, data: ${JSON.stringify(data)');
}
formHost.off('notifyVisible', callback);
formHost.off('notifyVisible', callback, bundleName);
```
> **说明：**
> on('notifyVisible', callback)与off('notifyVisible', callback)相对应；
> on('notifyVisible', callback, bundleName)与off('notifyVisible', callback, bundleName)相对应；
> 订阅（on）只能由自己对应的取消订阅接口（off）取消。
## on('notifyInvisible')<sup>10+</sup>
on(type: 'notifyInvisible', observerCallback: Callback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;>, bundleName?: string): void
订阅通知卡片不可见的事件。
​触发通知卡片不可见场景为：调用notifyInvisibleForms接口通知对应卡片可见性变更为不可见状态
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 仅允许填写'notifyInvisible'，表示订阅卡片不可见的事件。 |
| callback | Callback &lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 是 | 回调函数。返回订阅通知卡片不可见的RunningFormInfo。 |
| bundleName | string | 否 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。 |
**示例：**
```ts
import formHost from '@ohos.app.form.formHost';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('form change invisibility, data: ${JSON.stringify(data)');
}
formHost.on('notifyInvisible', callback);
formHost.on('notifyInvisible', callback, bundleName);
```
## off('notifyInvisible')<sup>10+</sup>
off(type: "notifyInvisible", observerCallback?: Callback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>&gt;, bundleName?: string): void
取消订阅通知卡片不可见事件。
**需要权限**：ohos.permission.REQUIRE_FORM
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 仅允许填写'notifyInvisible'，表示卡片可见性变更为不可见。 |
| callback | Callback &lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 否 | 入参，注册时注册进去的callback。缺省时，表示注销对应已注册事件回调。<br/> 需与对应on('notifyInvisible')的callback一致。 |
| bundleName | string | 否 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。<br> 填写该参数时，与注册时填写bundleName的on接口对应。<br> |
**示例：**
```ts
import formHost from '@ohos.app.form.formHost';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('form change invisibility, data: ${JSON.stringify(data)');
}
formHost.off('notifyInvisible', callback);
formHost.off('notifyInvisible', callback, bundleName);
```
> **说明：**
> on('notifyInvisible', callback)与off('notifyInvisible', callback)相对应；
> on('notifyInvisible', callback, bundleName)与off('notifyInvisible', callback, bundleName)相对应；
> 订阅（on）只能由自己对应的取消订阅接口（off）取消。
\ No newline at end of file
zh-cn/application-dev/reference/apis/js-apis-app-form-formObserver.md 0 → 100644
浏览文件 @ 18c1379e
# @ohos.app.form.formObserver (formObserver)
formObserver模块提供了卡片监听方相关接口的能力，包括对同一用户下安装的卡片新增、删除、可见性变化事件的订阅和取消订阅，获取正在运行的卡片信息等。
> **说明：**
>
> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> 本模块接口均为系统接口。
## 导入模块
```ts
import formObserver from '@ohos.app.form.formObserver';
```
## on('formAdd')
on(type: 'formAdd', observerCallback: Callback&lt;formInfo.RunningFormInfo&gt;): void
订阅卡片新增事件。使用callback异步回调，返回当前新增卡片的[RunningFormInfo](js-apis-app-form-formInfo.md)。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| type | string | 是 | 填写'formAdd'，表示卡片新增事件。 |
| callback | Callback&lt;formInfo.RunningFormInfo&gt; | 是 | 回调函数。返回新增卡片的RunningFormInfo。 |
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let callback = function(data) {
console.log('a new form added, data: ${JSON.stringify(data)');
}
formObserver.on('formAdd', callback);
```
## on('formAdd')
on(type: 'formAdd', bundleName: string, observerCallback: Callback&lt;formInfo.RunningFormInfo&gt;): void
订阅卡片新增事件。使用callback异步回调，返回指定卡片使用方应用新增卡片的[RunningFormInfo](js-apis-app-form-formInfo.md)。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| type | string | 是 | 填写'formAdd'，表示卡片新增事件。 |
| bundleName | string | 是 | 指定订阅卡片使用方包的bundleName。缺省则订阅所有卡片使用方的卡片新增事件。 |
| callback | Callback&lt;formInfo.RunningFormInfo&gt; | 是 | 回调函数。返回新增卡片的RunningFormInfo。 |
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('a new form added, data: ${JSON.stringify(data)');
}
formObserver.on('formAdd', bundleName, callback);
```
## off('formAdd')
off(type: "formAdd", bundleName?: string, observerCallback?: Callback&lt;formInfo.RunningFormInfo&gt;): void
取消订阅卡片新增事件。使用callback异步回调，返回当前新增卡片的[RunningFormInfo](js-apis-app-form-formInfo.md)。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| type | string | 是 | 填写'formAdd'，表示卡片新增事件。 |
| bundleName | string | 否 | 指定订阅卡片使用方包的bundleName。<br> 填写该参数时，与注册时填写bundleName的on接口对应。<br> 缺省则订阅所有卡片使用方的卡片删除事件，与注册时未填写bundleName的on接口相对应。 |
| callback | Callback&lt;formInfo.RunningFormInfo&gt; | 否 | 回调函数。返回卡片RunningFormInfo。缺省时，表示注销对应已注册事件回调。<br> 需与对应on('formAdd')的callback一致。|
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('a new form added, data: ${JSON.stringify(data)');
}
formObserver.off('formAdd', callback);
formObserver.off('formAdd', bundleName, callback);
```
> **说明：**
> on('formAdd', callback)与off('formAdd', callback)相对应；
> on('formAdd', bundleName, callback)与off('formAdd', bundleName, callback)相对应；
> 订阅（on）只能由自己对应的取消订阅接口（off）取消。
## on('formRemove')
on(type: 'formRemove', observerCallback: Callback&lt;formInfo.RunningFormInfo&gt;): void
订阅卡片删除事件。使用callback异步回调，返回当前删除卡片的[RunningFormInfo](js-apis-app-form-formInfo.md)。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| type | string | 是 | 填写'formRemove'，表示卡片删除事件。 |
| callback | Callback&lt;formInfo.RunningFormInfo&gt; | 是 | 回调函数。返回删除卡片的RunningFormInfo。 |
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let callback = function(data) {
console.log('form deleted, data: ${JSON.stringify(data)');
}
formObserver.on('formRemove', callback);
```
## on('formRemove')
on(type: 'formRemove', bundleName: string, observerCallback: Callback&lt;formInfo.RunningFormInfo&gt;): void
订阅卡片删除事件。使用callback异步回调，返回指定卡片使用方应用被删除卡片的[RunningFormInfo](js-apis-app-form-formInfo.md)。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| type | string | 是 | 填写'formRemove'，表示卡片删除事件。 |
| bundleName | string | 是 | 指定订阅卡片使用方包的bundleName。缺省则订阅所有卡片使用方的卡片删除事件。 |
| callback | Callback&lt;formInfo.RunningFormInfo&gt; | 是 | 回调函数。返回删除卡片的RunningFormInfo。 |
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('form deleted, data: ${JSON.stringify(data)');
}
formObserver.on('formRemove', bundleName, callback);
```
## off('formRemove')
off(type: "formRemove", bundleName?: string, observerCallback?: Callback&lt;formInfo.RunningFormInfo&gt;): void
取消订阅卡片删除事件。使用callback异步回调，返回当前删除卡片的[RunningFormInfo](js-apis-app-form-formInfo.md)。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| type | string | 是 | 填写'formRemove'，表示卡片删除事件。 |
| bundleName | string | 否 | 指定订阅卡片使用方包的bundleName。<br> 填写该参数时，与注册时填写bundleName的on接口对应。<br> 缺省则订阅所有卡片使用方的卡片删除事件，与注册时未填写bundleName的on接口相对应。 |
| callback | Callback&lt;formInfo.RunningFormInfo&gt; | 否 | 回调函数。返回卡片RunningFormInfo。缺省时，表示注销对应已注册事件回调。<br> 需与对应on('formRemove')的callback一致。|
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('a new form added, data: ${JSON.stringify(data)');
}
formObserver.off('formRemove', callback);
formObserver.off('formRemove', bundleName, callback);
```
> **说明：**
> on('formRemove', callback)与off('formRemove', callback)相对应；
> on('formRemove', bundleName, callback)与off('formRemove', bundleName, callback)相对应；
> 订阅（on）只能由自己对应的取消订阅接口（off）取消。
## on('notifyVisible')
on(type: 'notifyVisible', observerCallback: Callback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt;): void
订阅通知卡片可见的事件。
​触发通知卡片可见场景为：调用notifyVisibleForms接口通知对应卡片可见性变更为可见状态
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 仅允许填写'notifyVisible'，表示订阅通知卡片可见的事件。 |
| callback | Callback &lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 是 | 回调函数。返回订阅通知卡片可见的RunningFormInfo。 |
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let callback = function(data) {
console.log('form change visibility, data: ${JSON.stringify(data)');
}
formObserver.on('notifyVisible', callback);
```
## on('notifyVisible')
on(type: 'notifyVisible', bundleName: string, observerCallback: Callback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt;): void
订阅通知卡片可见的事件。
​触发通知卡片可见场景为：调用notifyVisibleForms接口通知对应卡片可见性变更为可见状态
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 仅允许填写'notifyVisible'，表示订阅通知卡片可见的事件。 |
| bundleName | string | 是 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。 |
| callback | Callback &lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 是 | 回调函数。返回订阅通知卡片可见的RunningFormInfo。 |
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('form change visibility, data: ${JSON.stringify(data)');
}
formObserver.on('notifyVisible', bundleName, callback);
```
## off('notifyVisible')
off(type: "notifyVisible", bundleName?: string, observerCallback?: Callback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt;): void
取消订阅通知卡片可见的事件。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 仅允许填写'notifyVisible'，表示取消订阅通知卡片为可见的事件。 |
| bundleName | string | 否 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。<br> 填写该参数时，与注册时填写bundleName的on接口对应。 |
| callback | Callback &lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 否 | 入参，注册时注册进去的callback。缺省时，表示注销对应已注册订阅的回调。<br> 需与对应on('notifyVisible')的callback一致。 |
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('form change visibility, data: ${JSON.stringify(data)');
}
formObserver.off('notifyVisible', callback);
formObserver.off('notifyVisible', bundleName, callback);
```
> **说明：**
> on('notifyVisible', callback)与off('notifyVisible', callback)相对应；
> on('notifyVisible', bundleName, callback)与off('notifyVisible', bundleName, callback)相对应；
> 订阅（on）只能由自己对应的取消订阅接口（off）取消。
## on('notifyInvisible')
on(type: 'notifyInvisible', observerCallback: Callback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;>): void
订阅通知卡片不可见的事件。
​触发通知卡片不可见场景为：调用notifyInvisibleForms接口通知对应卡片可见性变更为不可见状态
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 仅允许填写'notifyInvisible'，表示订阅卡片不可见的事件。 |
| callback | Callback &lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 是 | 回调函数。返回订阅通知卡片不可见的RunningFormInfo。 |
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let callback = function(data) {
console.log('form change invisibility, data: ${JSON.stringify(data)');
}
formObserver.on('notifyInvisible', callback);
```
## on('notifyInvisible')
on(type: 'notifyInvisible', bundleName: string, observerCallback: Callback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;>): void
订阅通知卡片不可见的事件。
​触发通知卡片不可见场景为：调用notifyInvisibleForms接口通知对应卡片可见性变更为不可见状态
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 仅允许填写'notifyInvisible'，表示订阅卡片不可见的事件。 |
| bundleName | string | 是 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。 |
| callback | Callback &lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 是 | 回调函数。返回订阅通知卡片不可见的RunningFormInfo。 |
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('form change invisibility, data: ${JSON.stringify(data)');
}
formObserver.on('notifyInvisible', bundleName, callback);
```
## off('notifyInvisible')
off(type: "notifyInvisible", bundleName?: string, observerCallback?: Callback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>&gt;): void
取消订阅通知卡片不可见事件。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 仅允许填写'notifyInvisible'，表示卡片可见性变更为不可见。 |
| bundleName | string | 否 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。<br> 填写该参数时，与注册时填写bundleName的on接口对应。<br> |
| callback | Callback &lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 否 | 入参，注册时注册进去的callback。缺省时，表示注销对应已注册事件回调。<br/> 需与对应on('notifyInvisible')的callback一致。 |
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
let bundleName = 'ohos.samples.FormApplication';
let callback = function(data) {
console.log('form change invisibility, data: ${JSON.stringify(data)');
}
formObserver.off('notifyInvisible', callback);
formObserver.off('notifyInvisible', bundleName, callback);
```
> **说明：**
> on('notifyInvisible', callback)与off('notifyInvisible', callback)相对应；
> on('notifyInvisible', bundleName, callback)与off('notifyInvisible', bundleName, callback)相对应；
> 订阅（on）只能由自己对应的取消订阅接口（off）取消。
## getRunningFormInfos
getRunningFormInfos(callback: AsyncCallback&lt;Array&lt;formInfo.RunningFormInfo&gt;&gt;, hostBundleName?: string): void
获取设备上正在运行的所有非临时卡片信息。使用callback异步回调。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| callback | AsyncCallback&lt;Array&lt;formInfo.RunningFormInfo&gt;&gt; | 是 | 回调函数。获取设备上指定应用为卡片使用方的当前卡片信息成功，error为undefined，data为查询到的卡片信息。|
| hostBundleName | string | 否 | 指定要查询的卡片使用方名称，指定后会仅返回该卡片使用方下正在运行的非临时卡片信息。 <br> 缺省时，返回设备上所有正在运行的非临时卡片信息。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 16500050 | An IPC connection error happened. |
| 16500060 | A service connection error happened, please try again later. ||
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
try {
formObserver.getRunningFormInfos((error, data) => {
if (error) {
console.error(`error, code: ${error.code}, message: ${error.message}`);
} else {
console.log('formObserver getRunningFormInfos, data: ${JSON.stringify(data)}');
}
}, 'com.example.ohos.formjsdemo');
} catch(error) {
console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}
```
## getRunningFormInfos
getRunningFormInfos(hostBundleName?: string): Promise&lt;Array&lt;formInfo.RunningFormInfo&gt;&gt;
获取设备上正在运行的所有非临时卡片信息。使用Promise异步回调。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| hostBundleName | string | 否 | 指定要查询的卡片使用方名称，指定后会仅返回该卡片使用方下正在运行的非临时卡片信息。 <br> 缺省时，返回设备上所有正在运行的非临时卡片信息。 |
**返回值：**
| 类型 | 说明 |
| :----------------------------------------------------------- | :---------------------------------- |
| Promise&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | Promise对象，返回查询到的卡片信息。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 16500050 | An IPC connection error happened. |
| 16500060 | A service connection error happened, please try again later. ||
**示例：**
```ts
import formObserver from '@ohos.app.form.formObserver';
try {
formObserver.getRunningFormInfos('com.example.ohos.formjsdemo').then((data) => {
console.log('formObserver getRunningFormInfos, 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}`);
}
```
## getRunningFormInfosByFilter
getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter): Promise&lt;Array&lt;formInfo.RunningFormInfo&gt;&gt;
根据提供方信息查询卡片已有的使用方列表信息。使用Promise异步回调。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | --------------- | ---- | -------------------------------- |
| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo.md#formProviderFilter) | 是 | 卡片提供方应用信息。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ------------------------- |
| Promise&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md#RunningFormInfo)&gt;&gt; | Promise对象，返回查询到的使用方列表信息。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
```ts
import formObserver from '@ohos.app.form.formObserver';
let formInstanceFilter = {
bundleName: "com.example.formprovide",
abilityName: "EntryFormAbility",
formName: "widget",
moduleName: "entry"
}
try {
formObserver.getRunningFormInfosByFilter(formInstanceFilter).then(data1 => {
console.info('formObserver getRunningFormInfosByFilter return err :');
}).catch((error) => {
console.error(`error, code: ${error.code}, message: ${error.message}`);
});
} catch(error) {
console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}
```
## getRunningFormInfosByFilter
getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter, callback: AsyncCallback&lt;Array&lt;formInfo.RunningFormInfo&gt;&gt;): void
根据提供方信息查询卡片已有的使用方列表信息。使用callback异步回调。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | --------------- | ---- | -------------------------------- |
| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo.md#formProviderFilter) | 是 | 卡片提供方应用信息。 |
| callback | AsyncCallback&lt;Array&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt;&gt; | 是 | 回调函数。返回查询到的使用方列表信息，error为undefined，data为查询到的使用方列表信息；否则为错误对象。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
```ts
import formObserver from '@ohos.app.form.formObserver';
let formInstanceFilter = {
bundleName: "com.example.formprovide",
abilityName: "EntryFormAbility",
formName: "widget",
moduleName: "entry"
}
try {
formObserver.getRunningFormInfosByFilter(formInstanceFilter,(error, data) => {
if (error) {
console.error(`error, code: ${error.code}, message: ${error.message}`);
} else {
console.log('formObserver getRunningFormInfosByFilter, data: ${JSON.stringify(data)}');
}
});
} catch(error) {
console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}
```
## getRunningFormInfoById
getRunningFormInfoById(formId: string): Promise&lt;formInfo.RunningFormInfo&gt;
根据formId查询卡片已有的使用方列表信息。使用Promise异步回调。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | --------------- | ---- | -------------------------------- |
| formId | string | 是 | 卡片标识。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ------------------------- |
| Promise&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt; | Promise对象，返回查询到的使用方列表信息。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
```ts
import formObserver from '@ohos.app.form.formObserver';
let formId = '12400633174999288';
try {
formObserver.getRunningFormInfoById(formId).then(data1 => {
console.info('formObserver getRunningFormInfoById return err :');
}).catch((error) => {
console.error(`error, code: ${error.code}, message: ${error.message}`);
});
} catch(error) {
console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}
```
## getRunningFormInfoById
getRunningFormInfoById(formId: string, callback: AsyncCallback&lt;formInfo.RunningFormInfo&gt;): void
根据提供方信息查询卡片已有的使用方列表信息。使用callback异步回调。
**需要权限**：ohos.permission.OBSERVE_FORM_RUNNING
**系统能力**：SystemCapability.Ability.Form
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | --------------- | ---- | -------------------------------- |
| formId | string | 是 | 卡片标识。 |
| callback | AsyncCallback&lt;[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)&gt; | 是 | 回调函数。返回查询到的使用方列表信息，error为undefined，data为查询到的使用方列表信息；否则为错误对象。 |
**错误码：**
以下错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
```ts
import formObserver from '@ohos.app.form.formObserver';
let formId = '12400633174999288';
try {
formObserver.getRunningFormInfoById(formId,(error, data) => {
if (error) {
console.error(`error, code: ${error.code}, message: ${error.message}`);
} else {
console.log('formObserver getRunningFormInfoById, data: ${JSON.stringify(data)}');
}
});
} catch(error) {
console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}
```
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或