1# @ohos.app.ability.dialogSession (dialogSession)(系统接口)
2
3dialogSession模块用于支持系统应用弹框功能。
4
5> **说明：**
6>
7> 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 本模块接口仅可在Stage模型下使用。
10>
11> 本模块为系统接口。
12
13## 导入模块
14
15```ts
16import { dialogSession } from '@kit.AbilityKit';
17```
18
19## DialogAbilityInfo
20
21提供会话组件信息，包括包名、模块名、组件名等信息。
22
23**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
24
25| 名称 | 类型 | 只读 | 必填 | 说明 |
26| -------- | -------- | -------- | -------- | -------- |
27| bundleName | string | 是 | 是 | 表示包名。 |
28| moduleName | string | 是 | 是 | 表示模块名。 |
29| abilityName | string | 是 | 是 | 表示组件名。 |
30| abilityIconId | number | 是 | 是 | 表示Ability图标ID。 |
31| abilityLabelId | number | 是 | 是 | 表示Ability标签ID。 |
32| bundleIconId | number | 是 | 是 | 表示Bundle图标ID。 |
33| bundleLabelId | number | 是 | 是 | 表示Bundle标签ID。 |
34| visible<sup>12+</sup> | boolean | 是 | 是 | 表示Ability是否可见。 |
35| appIndex<sup>12+</sup> | number | 是 | 是 | 表示应用的分身索引。 |
36| multiAppMode<sup>12+</sup> | [MultiAppMode](./js-apis-bundleManager-applicationInfo.md#multiappmode12) | 是 | 是 | 表示应用的多开模式。|
37
38## DialogSessionInfo
39
40提供会话信息，包括请求方信息、目标应用列表信息、其他参数。
41
42**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
43
44| 名称 | 类型 | 只读 | 必填 | 说明 |
45| -------- | -------- | -------- | -------- | -------- |
46| callerAbilityInfo | [DialogAbilityInfo](#dialogabilityinfo)| 是 | 是 | 表示请求方组件信息。 |
47| targetAbilityInfos | Array\<[DialogAbilityInfo](#dialogabilityinfo)\> | 是 | 是 | 表示目标应用列表信息。 |
48| parameters | Record<string, Object> | 是 | 否 | 表示其他参数。 |
49
50## getDialogSessionInfo
51
52getDialogSessionInfo(dialogSessionId: string): [DialogSessionInfo](#dialogsessioninfo)
53
54根据dialogSessionId获取会话信息。
55
56**系统接口**：此接口为系统接口。
57
58**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
59
60**参数：**
61
62  | 参数名 | 类型 | 必填 | 说明 |
63  | -------- | -------- | -------- | -------- |
64  | dialogSessionId | string | 是 | 用户请求会话ID。 |
65
66**返回值：**
67
68  | 类型 | 说明 |
69  | -------- | -------- |
70  | [DialogSessionInfo](#dialogsessioninfo) | 同步返回会话信息。 |
71
72**错误码**：
73
74以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
75
76| 错误码ID | 错误信息 |
77| ------- | -------- |
78| 202 | Not System App. Interface caller is not a system app. |
79| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. 3. Parameter verification failed. |
80| 16000005 | The specified process does not have the permission. |
81| 16000006  | Cross-user operations are not allowed. |
82| 16000050  | Internal error. |
83
84**示例：**
85
86```ts
87import { dialogSession, Want } from '@kit.AbilityKit';
88
89// want由系统内部指定，dialogSessionId为内置参数
90let dialogSessionId: string = want?.parameters?.dialogSessionId;
91
92// 查询DialogSessionInfo
93let dialogSessionInfo: dialogSession.DialogSessionInfo = dialogSession.getDialogSessionInfo(dialogSessionId);
94```
95
96## sendDialogResult
97
98sendDialogResult(dialogSessionId: string, targetWant: Want, isAllowed: boolean, callback: AsyncCallback\<void\>): void
99
100发送用户请求。使用callback异步回调。
101
102**系统接口**：此接口为系统接口。
103
104**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
105
106**参数：**
107
108  | 参数名 | 类型 | 必填 | 说明 |
109  | -------- | -------- | -------- | -------- |
110  | dialogSessionId | string | 是 | 用户请求会话ID。 |
111  | targetWant | Want | 是 | 用户请求目标。 |
112  | isAllowed | boolean | 是 | 用户请求结果。 |
113  | callback | AsyncCallback\<void\> | 是 | 回调函数。当发送用户请求成功，err为undefined，否则为错误对象。 |
114
115**错误码**：
116
117以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
118
119| 错误码ID | 错误信息 |
120| ------- | -------- |
121| 202 | Not System App. Interface caller is not a system app. |
122| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. 3. Parameter verification failed. |
123| 16000005 | The specified process does not have the permission. |
124| 16000006  | Cross-user operations are not allowed. |
125| 16000050  | Internal error. |
126
127**示例：**
128
129```ts
130import { dialogSession, Want } from '@kit.AbilityKit';
131import { BusinessError } from '@kit.BasicServicesKit';
132
133// want由系统内部指定，dialogSessionId为内置参数
134let dialogSessionId: string = want?.parameters?.dialogSessionId;
135
136// 查询DialogSessionInfo
137let dialogSessionInfo: dialogSession.DialogSessionInfo = dialogSession.getDialogSessionInfo(dialogSessionId);
138
139let isAllow: boolean = true;
140
141// isAllow为true时，用户请求结果targetWant为dialogSessionInfo.targetAbilityInfos之一
142let targetWant: Want = {
143  bundleName: 'com.example.myapplication',
144  abilityName: 'EntryAbility'
145};
146
147try {
148  dialogSession.sendDialogResult(dialogSessionId, targetWant, isAllow, (err, data) => {
149    if (err) {
150      console.error(`sendDialogResult error, errorCode: ${err.code}`);
151    } else {
152      console.log(`sendDialogResult success`);
153    }
154  });
155} catch (err) {
156  console.error(`sendDialogResult error, errorCode: ${(err as BusinessError).code}`);
157}
158```
159
160## sendDialogResult
161
162sendDialogResult(dialogSessionId: string, targetWant: Want, isAllowed: boolean): Promise\<void\>
163
164发送用户请求。使用Promise异步回调。
165
166**系统接口**：此接口为系统接口。
167
168**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
169
170**参数：**
171
172  | 参数名 | 类型 | 必填 | 说明 |
173  | -------- | -------- | -------- | -------- |
174  | dialogSessionId | string | 是 | 用户请求会话ID。 |
175  | targetWant | Want | 是 | 用户请求目标。 |
176  | isAllowed | boolean | 是 | 用户请求结果。 |
177
178**返回值：**
179
180| 类型 | 说明 |
181| -------- | -------- |
182| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
183
184**错误码**：
185
186以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
187
188| 错误码ID | 错误信息 |
189| ------- | -------- |
190| 202 | Not System App. Interface caller is not a system app. |
191| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. 3. Parameter verification failed. |
192| 16000005 | The specified process does not have the permission. |
193| 16000006  | Cross-user operations are not allowed. |
194| 16000050  | Internal error. |
195
196**示例：**
197
198```ts
199import { dialogSession, Want } from '@kit.AbilityKit';
200import { BusinessError } from '@kit.BasicServicesKit';
201
202// want由系统内部指定，dialogSessionId为内置参数
203let dialogSessionId: string = want?.parameters?.dialogSessionId;
204
205// 查询DialogSessionInfo
206let dialogSessionInfo: dialogSession.DialogSessionInfo = dialogSession.getDialogSessionInfo(dialogSessionId);
207
208let isAllow: boolean = true;
209
210// isAllow为true时，用户请求结果targetWant为dialogSessionInfo.targetAbilityInfos之一
211let targetWant: Want = {
212  bundleName: 'com.example.myapplication',
213  abilityName: 'EntryAbility'
214};
215
216try {
217  dialogSession.sendDialogResult(dialogSessionId, targetWant, isAllow)
218    .then((data) => {
219      console.log(`startChildProcess success, pid: ${data}`);
220    }, (err: BusinessError) => {
221      console.error(`startChildProcess error, errorCode: ${err.code}`);
222    })
223} catch (err) {
224  console.error(`sendDialogResult error, errorCode: ${(err as BusinessError).code}`);
225}
226```