1# 列表选择弹窗 (ActionSheet) 2 3列表弹窗。 4 5> **说明：** 6> 7> 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> 本模块功能依赖UI的执行上下文，不可在UI上下文不明确的地方使用，参见[UIContext](../js-apis-arkui-UIContext.md#uicontext)说明。 10> 11> 从API version 10开始，可以通过使用[UIContext](../js-apis-arkui-UIContext.md#uicontext)中的[showActionSheet](../js-apis-arkui-UIContext.md#showactionsheet)来明确UI的执行上下文。 12 13## ActionSheet 14 15### show 16 17static show(value: ActionSheetOptions) 18 19定义列表弹窗并弹出。 20 21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------ | ------------------------------------------------- | ---- | ------------------------ | 29| value | [ActionSheetOptions](#actionsheetoptions对象说明) | 是 | 配置列表选择弹窗的参数。 | 30 31## ActionSheetOptions对象说明 32 33**系统能力：** SystemCapability.ArkUI.ArkUI.Full 34 35| 名称 | 类型 | 必填 | 说明 | 36| ---------- | -------------------------- | ------- | ----------------------------- | 37| title | string \| [Resource](ts-types.md#resource) | 是 | 弹窗标题。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 38| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 弹窗副标题。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 39| message | string \| [Resource](ts-types.md#resource) | 是 | 弹窗内容。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 40| autoCancel | boolean | 否 | 点击遮障层时，是否关闭弹窗。<br>默认值：true<br>值为true时，点击遮障层关闭弹窗，值为false时，点击遮障层不关闭弹窗。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 41| confirm | {<br/>enabled<sup>10+</sup>?: boolean,<br/>defaultFocus<sup>10+</sup>?: boolean,<br />style<sup>10+</sup>?: [DialogButtonStyle](ts-appendix-enums.md#dialogbuttonstyle10),<br />value: string \| [Resource](ts-types.md#resource),<br/>action: () => void<br/>} | 否 | 确认Button的使能状态、默认焦点、按钮风格、文本内容和点击回调。在弹窗获焦且未进行tab键走焦时，该按钮默认响应Enter键，且多重弹窗可自动获焦连续响应。默认响应Enter键能力在defaultFocus为true时不生效。<br>enabled：点击Button是否响应，true表示Button可以响应，false表示Button不可以响应。<br />默认值：true<br />defaultFocus：设置Button是否是默认焦点，true表示Button是默认焦点，false表示Button不是默认焦点。<br />默认值：false<br />style：设置Button的风格样式。<br />默认值：DialogButtonStyle.DEFAULT<br/>value：Button文本内容。<br/>action: Button选中时的回调。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 42| cancel | () => void | 否 | 点击遮障层关闭dialog时的回调。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 43| alignment | [DialogAlignment](ts-methods-alert-dialog-box.md#dialogalignment枚举说明) | 否 | 弹窗在竖直方向上的对齐方式。<br>默认值：DialogAlignment.Bottom <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**说明**：<br/>若在UIExtension中设置showInSubWindow为true, 弹窗将基于UIExtension的宿主窗口对齐。| 44| offset | {<br/>dx: number \| string \| [Resource](ts-types.md#resource),<br/>dy: number \| string \| [Resource](ts-types.md#resource)<br/>} | 否 | 弹窗相对alignment所在位置的偏移量。<br/>默认值：<br/>1.alignment设置为Top、TopStart、TopEnd时默认值为{dx: 0,dy: "40vp"} <br/>2.alignment设置为其他时默认值为{dx: 0,dy: "-40vp"} <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 45| sheets | Array<[SheetInfo](#sheetinfo对象说明)> | 是 | 设置选项内容，每个选择项支持设置图片、文本和选中的回调。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 46| maskRect<sup>10+</sup> | [Rectangle](ts-methods-alert-dialog-box.md#rectangle8类型说明) | 否 | 弹窗遮蔽层区域，在遮蔽层区域内的事件不透传，在遮蔽层区域外的事件透传。<br/>默认值：{ x: 0, y: 0, width: '100%', height: '100%' } <br/>**说明：**<br/>showInSubWindow为true时，maskRect不生效。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 47| showInSubWindow<sup>11+</sup> | boolean | 否 | 某弹框需要显示在主窗口之外时，是否在子窗口显示此弹窗。<br/>默认值：false，弹窗显示在应用内，而非独立子窗口。<br/>**说明**：showInSubWindow为true的弹窗无法触发显示另一个showInSubWindow为true的弹窗。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 48| isModal<sup>11+</sup> | boolean | 否 | 弹窗是否为模态窗口，模态窗口有蒙层，非模态窗口无蒙层。<br/>默认值：true，此时弹窗有蒙层。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 49| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 弹窗背板颜色。<br/>默认值：Color.Transparent<br/>**说明：** <br/>当设置了backgroundColor为非透明色时，backgroundBlurStyle需要设置为BlurStyle.NONE，否则颜色显示将不符合预期效果。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 50| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | 否 | 弹窗背板模糊材质。<br/>默认值：BlurStyle.COMPONENT_ULTRA_THICK<br/>**说明：** <br/>设置为BlurStyle.NONE即可关闭背景虚化。当设置了backgroundBlurStyle为非NONE值时，则不要设置backgroundColor，否则颜色显示将不符合预期效果。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 51| onWillDismiss<sup>12+</sup> | Callback<[DismissDialogAction](#dismissdialogaction12)> | 否 | 交互式关闭回调函数。<br/>**说明：**<br/>1.当用户执行点击遮障层关闭、左滑/右滑、三键back、键盘ESC关闭交互操作时，如果注册该回调函数，则不会立刻关闭弹窗。在回调函数中可以通过reason得到阻拦关闭弹窗的操作类型，从而根据原因选择是否能关闭弹窗。当前组件返回的reason中，暂不支持CLOSE_BUTTON的枚举值。<br/>2.在onWillDismiss回调中，不能再做onWillDismiss拦截。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 52| cornerRadius<sup>12+</sup> | [Dimension](ts-types.md#dimension10) \| [BorderRadiuses](ts-types.md#borderradiuses9) \| [LocalizedBorderRadiuses](ts-types.md#LocalizedBorderRadiuses12) | 否 | 设置背板的圆角半径。<br />可分别设置4个圆角的半径。<br />默认值：{ topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp' }<br /> 圆角大小受组件尺寸限制，最大值为组件宽或高的一半，若值为负，则按照默认值处理。 <br /> 百分比参数方式：以父元素弹窗宽和高的百分比来设置弹窗的圆角。<br/>**说明：**<br/>当cornerRadius属性类型为LocalizedBorderRadiuses时，支持随语言习惯改变布局顺序。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 53| borderWidth<sup>12+</sup> | [Dimension](ts-types.md#dimension10) \| [EdgeWidths](ts-types.md#edgewidths9) \| [LocalizedEdgeWidths](ts-types.md#LocalizedEdgeWidths12) | 否 | 设置弹窗背板的边框宽度。<br />可分别设置4个边框宽度。<br />默认值：0<br /> 百分比参数方式：以父元素弹窗宽的百分比来设置弹窗的边框宽度。<br />当弹窗左边框和右边框大于弹窗宽度，弹窗上边框和下边框大于弹窗高度，显示可能不符合预期。<br/>**说明：**<br/>当borderWidth属性类型为LocalizedEdgeWidths时，支持随语言习惯改变布局顺序。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 54| borderColor<sup>12+</sup> | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](ts-types.md#edgecolors9) \| [LocalizedEdgeColors](ts-types.md#LocalizedEdgeColors12) | 否 | 设置弹窗背板的边框颜色。<br/>默认值：Color.Black<br/> 如果使用borderColor属性，需要和borderWidth属性一起使用。<br/>**说明：**<br/>当borderColor属性类型为LocalizedEdgeColors时，支持随语言习惯改变布局顺序。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 55| borderStyle<sup>12+</sup> | [BorderStyle](ts-appendix-enums.md#borderstyle) \| [EdgeStyles](ts-types.md#edgestyles9) | 否 | 设置弹窗背板的边框样式。<br/>默认值：BorderStyle.Solid。<br/> 如果使用borderStyle属性，需要和borderWidth属性一起使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 56| width<sup>12+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 设置弹窗背板的宽度。<br />**说明：**<br>- 弹窗宽度默认最大值：400vp。<br />- 百分比参数方式：弹窗参考宽度为所在窗口的宽度，在此基础上调小或调大。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 57| height<sup>12+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 设置弹窗背板的高度。<br />**说明：**<br />- 弹窗高度默认最大值：0.9 *（窗口高度 - 安全区域）。<br />- 百分比参数方式：弹窗参考高度为（窗口高度 - 安全区域），在此基础上调小或调大。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 58| shadow<sup>12+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否 | 设置弹窗背板的阴影。 <br /> 当设备为2in1时，默认场景下获焦阴影值为ShadowStyle.OUTER_FLOATING_MD，失焦为ShadowStyle.OUTER_FLOATING_SM<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 59| transition<sup>12+</sup> | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10) | 否 | 设置弹窗显示和退出的过渡效果。<br/>**说明：**<br/>1.如果不设置，则使用默认的显示/退出动效。<br/>2.显示动效中按back键，打断显示动效，执行退出动效，动画效果为显示动效与退出动效的曲线叠加后的效果。<br/>3.退出动效中按back键，不会打断退出动效，退出动效继续执行，继续按back键退出应用。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 60| enableHoverMode<sup>14+</sup> | boolean | 否 | 是否响应悬停态。<br />默认值：false，默认不响应。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。| 61| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](ts-appendix-enums.md#hovermodeareatype14) | 否 | 悬停态下弹窗默认展示区域。<br />默认值：HoverModeAreaType.BOTTOM_SCREEN。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。| 62 63## SheetInfo对象说明 64 65**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 66 67**系统能力：** SystemCapability.ArkUI.ArkUI.Full 68 69| 名称 | 类型 | 必填 | 说明 | 70| ------ | ------------------------------------------------------------ | ---- | ----------------- | 71| title | string \| [Resource](ts-types.md#resource) | 是 | 选项的文本内容。 | 72| icon | string \| [Resource](ts-types.md#resource) | 否 | 选项的图标，默认无图标显示。 | 73| action | ()=>void | 是 | 选项选中的回调。 | 74 75## DismissDialogAction<sup>12+</sup> 76 77Dialog关闭的信息。 78 79**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 80 81**系统能力：** SystemCapability.ArkUI.ArkUI.Full 82 83### 属性 84 85| 名称 | 类型 | 可读 | 可写 | 说明 | 86| ------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 87| dismiss | Callback<void> | 否 | 否 | Dialog关闭回调函数。开发者需要退出时调用，不需要退出时无需调用。 | 88| reason | [DismissReason](../js-apis-promptAction.md#dismissreason12枚举说明) | 否 | 否 | Dialog无法关闭原因。根据开发者需要选择不同操作下，Dialog是否需要关闭。 | 89 90## 示例 91 92> **说明：** 93> 94> 推荐通过使用[UIContext](../js-apis-arkui-UIContext.md#uicontext)中的[showActionSheet](../js-apis-arkui-UIContext.md#showactionsheet)来明确UI的执行上下文。 95 96### 示例1（弹出列表选择弹窗） 97 98该示例通过点击按钮弹窗列表选择弹窗。 99 100```ts 101@Entry 102@Component 103struct ActionSheetExample { 104 build() { 105 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 106 Button('Click to Show ActionSheet') 107 .onClick(() => { 108 ActionSheet.show({ // 建议使用 this.getUIContext().showActionSheet()接口 109 title: 'ActionSheet title', 110 subtitle: 'ActionSheet subtitle', 111 message: 'message', 112 autoCancel: true, 113 confirm: { 114 defaultFocus: true, 115 value: 'Confirm button', 116 action: () => { 117 console.log('Get Alert Dialog handled') 118 } 119 }, 120 cancel: () => { 121 console.log('actionSheet canceled') 122 }, 123 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 124 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 125 console.log("dialog onWillDismiss") 126 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 127 dismissDialogAction.dismiss() 128 } 129 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 130 dismissDialogAction.dismiss() 131 } 132 }, 133 alignment: DialogAlignment.Bottom, 134 offset: { dx: 0, dy: -10 }, 135 sheets: [ 136 { 137 title: 'apples', 138 action: () => { 139 console.log('apples') 140 } 141 }, 142 { 143 title: 'bananas', 144 action: () => { 145 console.log('bananas') 146 } 147 }, 148 { 149 title: 'pears', 150 action: () => { 151 console.log('pears') 152 } 153 } 154 ] 155 }) 156 }) 157 }.width('100%') 158 .height('100%') 159 } 160} 161``` 162 163 164 165### 示例2（可在主窗外弹出的弹窗） 166 167该示例通过配置showInSubWindow为true弹出可以在主窗外显示的弹窗。 168 169```ts 170@Entry 171@Component 172struct ActionSheetExample { 173 build() { 174 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 175 Button('Click to Show ActionSheet') 176 .onClick(() => { 177 ActionSheet.show({ 178 title: 'ActionSheet title', 179 subtitle: 'ActionSheet subtitle', 180 message: 'message', 181 autoCancel: true, 182 showInSubWindow: true, 183 isModal: true, 184 confirm: { 185 defaultFocus: true, 186 value: 'Confirm button', 187 action: () => { 188 console.log('Get Alert Dialog handled') 189 } 190 }, 191 cancel: () => { 192 console.log('actionSheet canceled') 193 }, 194 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 195 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 196 console.log("dialog onWillDismiss") 197 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 198 dismissDialogAction.dismiss() 199 } 200 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 201 dismissDialogAction.dismiss() 202 } 203 }, 204 alignment: DialogAlignment.Center, 205 offset: { dx: 0, dy: -10 }, 206 sheets: [ 207 { 208 title: 'apples', 209 action: () => { 210 console.log('apples') 211 } 212 }, 213 { 214 title: 'bananas', 215 action: () => { 216 console.log('bananas') 217 } 218 }, 219 { 220 title: 'pears', 221 action: () => { 222 console.log('pears') 223 } 224 } 225 ] 226 }) 227 }) 228 }.width('100%') 229 .height('100%') 230 } 231} 232``` 233 234 235 236### 示例3（设置弹窗的动画） 237该示例通过配置transition实现弹窗的显示和消失动画。 238 239```ts 240@Entry 241@Component 242struct ActionSheetExample { 243 build() { 244 Column({ space: 5 }) { 245 Button('ActionSheet Set Duration') 246 .onClick(() => { 247 ActionSheet.show({ 248 title: 'ActionSheet 1', 249 message: 'Set Animation Duration open 3 second, close 100 ms', 250 autoCancel: true, 251 alignment: DialogAlignment.Top, 252 transition:TransitionEffect.asymmetric(TransitionEffect.OPACITY 253 .animation({ duration: 3000, curve: Curve.Sharp }).combine(TransitionEffect.scale({x: 1.5, y: 1.5}).animation({duration: 3000, curve: Curve.Sharp})), 254 TransitionEffect.OPACITY.animation({ duration: 100, curve: Curve.Smooth }) 255 .combine(TransitionEffect.scale({x: 0.5, y: 0.5}).animation({duration: 100, curve: Curve.Smooth}))), 256 offset: { dx: 0, dy: -20 }, 257 confirm: { 258 value: 'button', 259 action: () => { 260 console.info('Button-clicking callback') 261 } 262 }, 263 cancel: () => { 264 console.info('Closed callbacks') 265 }, 266 sheets: [ 267 { 268 title: 'apples', 269 action: () => { 270 console.log('apples') 271 } 272 }, 273 { 274 title: 'bananas', 275 action: () => { 276 console.log('bananas') 277 } 278 }, 279 { 280 title: 'pears', 281 action: () => { 282 console.log('pears') 283 } 284 } 285 ] 286 }) 287 }).backgroundColor(0x317aff).height("88px") 288 }.width('100%').margin({ top: 5 }) 289 } 290} 291``` 292 293 294 295### 示例4（设置弹窗的样式） 296该示例定义了ActionSheet的样式，如宽度、高度、背景色、阴影等等。 297```ts 298@Entry 299@Component 300struct ActionSheetExample { 301 build() { 302 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 303 Button('Click to Show ActionSheet') 304 .onClick(() => { 305 ActionSheet.show({ 306 title: 'ActionSheet title', 307 subtitle: 'ActionSheet subtitle', 308 message: 'message', 309 autoCancel: true, 310 width: 300, 311 height: 350, 312 cornerRadius: 20, 313 borderWidth: 1, 314 borderStyle: BorderStyle.Solid,//使用borderStyle属性，需要和borderWidth属性一起使用 315 borderColor: Color.Blue,//使用borderColor属性，需要和borderWidth属性一起使用 316 backgroundColor: Color.White, 317 shadow: ({ radius: 20, color: Color.Grey, offsetX: 50, offsetY: 0}), 318 confirm: { 319 defaultFocus: true, 320 value: 'Confirm button', 321 action: () => { 322 console.log('Get Alert Dialog handled') 323 } 324 }, 325 cancel: () => { 326 console.log('actionSheet canceled') 327 }, 328 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 329 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 330 console.log("dialog onWillDismiss") 331 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 332 dismissDialogAction.dismiss() 333 } 334 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 335 dismissDialogAction.dismiss() 336 } 337 }, 338 alignment: DialogAlignment.Bottom, 339 offset: { dx: 0, dy: -10 }, 340 sheets: [ 341 { 342 title: 'apples', 343 action: () => { 344 console.log('apples') 345 } 346 }, 347 { 348 title: 'bananas', 349 action: () => { 350 console.log('bananas') 351 } 352 }, 353 { 354 title: 'pears', 355 action: () => { 356 console.log('pears') 357 } 358 } 359 ] 360 }) 361 }) 362 }.width('100%') 363 .height('100%') 364 } 365} 366``` 367 368 369 370### 示例5（悬停态弹窗） 371 372该示例展示了在折叠屏悬停态下设置dialog布局区域的效果。 373 374```ts 375@Entry 376@Component 377struct ActionSheetExample { 378 build() { 379 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 380 Button('Click to Show ActionSheet') 381 .onClick(() => { 382 ActionSheet.show({ // 建议使用 this.getUIContext().showActionSheet()接口 383 title: 'ActionSheet title', 384 subtitle: 'ActionSheet subtitle', 385 message: 'message', 386 autoCancel: true, 387 confirm: { 388 defaultFocus: true, 389 value: 'Confirm button', 390 action: () => { 391 console.log('Get Alert Dialog handled') 392 } 393 }, 394 cancel: () => { 395 console.log('actionSheet canceled') 396 }, 397 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 398 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 399 console.log("dialog onWillDismiss") 400 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 401 dismissDialogAction.dismiss() 402 } 403 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 404 dismissDialogAction.dismiss() 405 } 406 }, 407 alignment: DialogAlignment.Bottom, 408 offset: { dx: 0, dy: -10 }, 409 enableHoverMode: true, 410 hoverModeArea: HoverModeAreaType.TOP_SCREEN, 411 sheets: [ 412 { 413 title: 'apples', 414 action: () => { 415 console.log('apples') 416 } 417 }, 418 { 419 title: 'bananas', 420 action: () => { 421 console.log('bananas') 422 } 423 }, 424 { 425 title: 'pears', 426 action: () => { 427 console.log('pears') 428 } 429 } 430 ] 431 }) 432 }) 433 }.width('100%') 434 .height('100%') 435 } 436} 437``` 438 439 440
