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