1# @ohos.promptAction (弹窗) 2 3创建并显示文本提示框、对话框和操作菜单。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 该模块不支持在[UIAbility](./js-apis-app-ability-uiAbility.md)的文件声明处使用，即不能在UIAbility的生命周期中调用，需要在创建组件实例后使用。 10> 11> 本模块功能依赖UI的执行上下文，不可在UI上下文不明确的地方使用，参见[UIContext](./js-apis-arkui-UIContext.md#uicontext)说明。 12> 13> 从API version 10开始，可以通过使用[UIContext](./js-apis-arkui-UIContext.md#uicontext)中的[getPromptAction](./js-apis-arkui-UIContext.md#getpromptaction)方法获取当前UI上下文关联的[PromptAction](./js-apis-arkui-UIContext.md#promptaction)对象。 14 15## 导入模块 16 17```ts 18import promptAction from '@ohos.promptAction'; 19``` 20 21## promptAction.showToast 22 23showToast(options: ShowToastOptions): void 24 25创建并显示文本提示框。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| ------- | ------------------------------------- | ---- | ------- | 33| options | [ShowToastOptions](#showtoastoptions) | 是 | 文本弹窗选项。 | 34 35**错误码：** 36 37以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](../errorcodes/errorcode-promptAction.md)错误码。 38 39| 错误码ID | 错误信息 | 40| --------- | ------- | 41| 100001 | if UI execution context not found. | 42 43**示例：** 44 45```ts 46import promptAction from '@ohos.promptAction' 47import { BusinessError } from '@ohos.base'; 48try { 49 promptAction.showToast({ 50 message: 'Message Info', 51 duration: 2000 52 }); 53} catch (error) { 54 let message = (error as BusinessError).message 55 let code = (error as BusinessError).code 56 console.error(`showToast args error code is ${code}, message is ${message}`); 57}; 58 59``` 60 61 62 63## ShowToastOptions 64 65文本提示框的选项。 66 67**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 68 69| 名称 | 类型 | 必填 | 说明 | 70| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 71| message | string\| [Resource](../arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 是 | 显示的文本信息。<br>**说明：** <br/>默认字体为'Harmony Sans'，不支持设置其他字体。 | 72| duration | number | 否 | 默认值1500ms，取值区间：1500ms-10000ms。若小于1500ms则取默认值，若大于10000ms则取上限值10000ms。 | 73| bottom | string\| number | 否 | 设置弹窗边框距离屏幕底部的位置。<br>默认值：80vp | 74 75## promptAction.showDialog 76 77showDialog(options: ShowDialogOptions): Promise<ShowDialogSuccessResponse> 78 79创建并显示对话框，对话框响应后异步返回结果。 80 81**系统能力：** SystemCapability.ArkUI.ArkUI.Full 82 83**参数：** 84 85| 参数名 | 类型 | 必填 | 说明 | 86| ------- | --------------------------------------- | ---- | ------ | 87| options | [ShowDialogOptions](#showdialogoptions) | 是 | 对话框选项。 | 88 89**返回值：** 90 91| 类型 | 说明 | 92| ---------------------------------------- | -------- | 93| Promise<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | 对话框响应结果。 | 94 95**错误码：** 96 97以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](../errorcodes/errorcode-promptAction.md)错误码。 98 99| 错误码ID | 错误信息 | 100| --------- | ------- | 101| 100001 | if UI execution context not found. | 102 103**示例：** 104 105```ts 106import promptAction from '@ohos.promptAction' 107import { BusinessError } from '@ohos.base'; 108try { 109 promptAction.showDialog({ 110 title: 'Title Info', 111 message: 'Message Info', 112 buttons: [ 113 { 114 text: 'button1', 115 color: '#000000' 116 }, 117 { 118 text: 'button2', 119 color: '#000000' 120 } 121 ], 122 }) 123 .then(data => { 124 console.info('showDialog success, click button: ' + data.index); 125 }) 126 .catch((err:Error) => { 127 console.info('showDialog error: ' + err); 128 }) 129} catch (error) { 130 let message = (error as BusinessError).message 131 let code = (error as BusinessError).code 132 console.error(`showDialog args error code is ${code}, message is ${message}`); 133}; 134``` 135 136 137 138## promptAction.showDialog 139 140showDialog(options: ShowDialogOptions, callback: AsyncCallback<ShowDialogSuccessResponse>):void 141 142创建并显示对话框，对话框响应结果异步返回。 143 144**系统能力：** SystemCapability.ArkUI.ArkUI.Full 145 146**参数：** 147 148| 参数名 | 类型 | 必填 | 说明 | 149| -------- | ---------------------------------------- | ---- | ------------ | 150| options | [ShowDialogOptions](#showdialogoptions) | 是 | 页面显示对话框信息描述。 | 151| callback | AsyncCallback<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | 是 | 对话框响应结果回调。 | 152 153**错误码：** 154 155以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](../errorcodes/errorcode-promptAction.md)错误码。 156 157| 错误码ID | 错误信息 | 158| --------- | ------- | 159| 100001 | if UI execution context not found. | 160 161**示例：** 162 163```ts 164import promptAction from '@ohos.promptAction'; 165import { BusinessError } from '@ohos.base'; 166try { 167 promptAction.showDialog({ 168 title: 'showDialog Title Info', 169 message: 'Message Info', 170 buttons: [ 171 { 172 text: 'button1', 173 color: '#000000' 174 }, 175 { 176 text: 'button2', 177 color: '#000000' 178 } 179 ] 180 }, (err, data) => { 181 if (err) { 182 console.info('showDialog err: ' + err); 183 return; 184 } 185 console.info('showDialog success callback, click button: ' + data.index); 186 }); 187} catch (error) { 188 let message = (error as BusinessError).message 189 let code = (error as BusinessError).code 190 console.error(`showDialog args error code is ${code}, message is ${message}`); 191}; 192``` 193 194 195 196## ShowDialogOptions 197 198对话框的选项。 199 200**系统能力：** SystemCapability.ArkUI.ArkUI.Full 201 202| 名称 | 类型 | 必填 | 说明 | 203| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 204| title | string\| [Resource](../arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 否 | 标题文本。 | 205| message | string\| [Resource](../arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 否 | 内容文本。 | 206| buttons | Array<[Button](#button)> | 否 | 对话框中按钮的数组，结构为：{text:'button', color: '\#666666'}，支持大于1个按钮。 207| alignment<sup>10+</sup> | [DialogAlignment](../arkui-ts/ts-methods-alert-dialog-box.md#dialogalignment枚举说明) | 否 | 弹窗在竖直方向上的对齐方式。<br>默认值：DialogAlignment.Default | 208| offset<sup>10+</sup> | [Offset](../arkui-ts/ts-types.md#offset) | 否 | 弹窗相对alignment所在位置的偏移量。<br/>默认值：{ dx: 0 , dy: 0 } | 209| maskRect<sup>10+</sup>| [Rectangle](../arkui-ts/ts-methods-alert-dialog-box.md#rectangle8类型说明) | 否 | 弹窗遮蔽层区域，在遮蔽层区域内的事件不透传，在遮蔽层区域外的事件透传。<br/>默认值：{ x: 0, y: 0, width: '100%', height: '100%' } | 210 211## ShowDialogSuccessResponse 212 213对话框的响应结果。 214 215**系统能力：** SystemCapability.ArkUI.ArkUI.Full 216 217| 名称 | 类型 | 必填 | 说明 | 218| ----- | ------ | ---- | ------------------------------- | 219| index | number | 否 | 选中按钮在buttons数组中的索引。 | 220 221## promptAction.showActionMenu 222 223showActionMenu(options: ActionMenuOptions, callback: AsyncCallback<ActionMenuSuccessResponse>):void 224 225创建并显示操作菜单，菜单响应结果异步返回。 226 227**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 228 229**参数：** 230 231| 参数名 | 类型 | 必填 | 说明 | 232| -------- | ---------------------------------------- | ---- | --------- | 233| options | [ActionMenuOptions](#actionmenuoptions) | 是 | 操作菜单选项。 | 234| callback | AsyncCallback<[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | 是 | 菜单响应结果回调。 | 235 236**错误码：** 237 238以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](../errorcodes/errorcode-promptAction.md)错误码。 239 240| 错误码ID | 错误信息 | 241| --------- | ------- | 242| 100001 | if UI execution context not found. | 243 244**示例：** 245 246```ts 247import promptAction from '@ohos.promptAction'; 248import { BusinessError } from '@ohos.base'; 249try { 250 promptAction.showActionMenu({ 251 title: 'Title Info', 252 buttons: [ 253 { 254 text: 'item1', 255 color: '#666666' 256 }, 257 { 258 text: 'item2', 259 color: '#000000' 260 }, 261 ] 262 }, (err, data) => { 263 if (err) { 264 console.info('showActionMenu err: ' + err); 265 return; 266 } 267 console.info('showActionMenu success callback, click button: ' + data.index); 268 }) 269} catch (error) { 270 let message = (error as BusinessError).message 271 let code = (error as BusinessError).code 272 console.error(`showActionMenu args error code is ${code}, message is ${message}`); 273}; 274``` 275 276 277 278## promptAction.showActionMenu 279 280showActionMenu(options: ActionMenuOptions): Promise<ActionMenuSuccessResponse> 281 282创建并显示操作菜单，菜单响应后异步返回结果。 283 284**系统能力：** SystemCapability.ArkUI.ArkUI.Full 285 286**参数：** 287 288| 参数名 | 类型 | 必填 | 说明 | 289| ------- | --------------------------------------- | ---- | ------- | 290| options | [ActionMenuOptions](#actionmenuoptions) | 是 | 操作菜单选项。 | 291 292**返回值：** 293 294| 类型 | 说明 | 295| ---------------------------------------- | ------- | 296| Promise<[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | 菜单响应结果。 | 297 298**错误码：** 299 300以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](../errorcodes/errorcode-promptAction.md)错误码。 301 302| 错误码ID | 错误信息 | 303| --------- | ------- | 304| 100001 | if UI execution context not found. | 305 306**示例：** 307 308```ts 309import promptAction from '@ohos.promptAction'; 310import { BusinessError } from '@ohos.base'; 311try { 312 promptAction.showActionMenu({ 313 title: 'showActionMenu Title Info', 314 buttons: [ 315 { 316 text: 'item1', 317 color: '#666666' 318 }, 319 { 320 text: 'item2', 321 color: '#000000' 322 }, 323 ] 324 }) 325 .then(data => { 326 console.info('showActionMenu success, click button: ' + data.index); 327 }) 328 .catch((err:Error) => { 329 console.info('showActionMenu error: ' + err); 330 }) 331} catch (error) { 332 let message = (error as BusinessError).message 333 let code = (error as BusinessError).code 334 console.error(`showActionMenu args error code is ${code}, message is ${message}`); 335}; 336``` 337 338 339 340## ActionMenuOptions 341 342操作菜单的选项。 343 344**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 345 346| 名称 | 类型 | 必填 | 说明 | 347| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 348| title | string\| [Resource](../arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 否 | 标题文本。 | 349| buttons | [[Button](#button),[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?] | 是 | 菜单中菜单项按钮的数组，结构为：{text:'button', color: '\#666666'}，支持1-6个按钮。按钮数量大于6个时，仅显示前6个按钮，之后的按钮不显示。 | 350 351## ActionMenuSuccessResponse 352 353操作菜单的响应结果。 354 355**系统能力：** SystemCapability.ArkUI.ArkUI.Full 356 357| 名称 | 类型 | 必填 | 说明 | 358| ----- | ------ | ---- | ------------------------ | 359| index | number | 否 | 选中按钮在buttons数组中的索引，从0开始。 | 360 361## Button 362 363菜单中的菜单项按钮。 364 365**系统能力：** SystemCapability.ArkUI.ArkUI.Full 366 367| 名称 | 类型 | 必填 | 说明 | 368| ----- | ---------------------------------------- | ---- | ------- | 369| text | string\| [Resource](../arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 是 | 按钮文本内容。 | 370| color | string\| [Resource](../arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 是 | 按钮文本颜色。 | 371
