1# Action Sheet (ActionSheet) 2 3An action sheet is a dialog box that displays actions a user can take. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](../js-apis-arkui-UIContext.md#uicontext). 10> 11> Since API version 10, you can use the [showActionSheet](../js-apis-arkui-UIContext.md#showactionsheet) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext), which ensures that the action sheet is shown in the intended UI instance. 12 13## ActionSheet 14 15### show 16 17static show(value: ActionSheetOptions) 18 19Shows an action sheet in the given settings. 20 21**Atomic service API**: This API can be used in atomic services since API version 11. 22 23**System capability**: SystemCapability.ArkUI.ArkUI.Full 24 25**Parameters** 26 27| Name| Type | Mandatory| Description | 28| ------ | ------------------------------------------------- | ---- | ------------------------ | 29| value | [ActionSheetOptions](#actionsheetoptions) | Yes | Parameters of the action sheet.| 30 31## ActionSheetOptions 32 33**System capability**: SystemCapability.ArkUI.ArkUI.Full 34 35| Name | Type | Mandatory | Description | 36| ---------- | -------------------------- | ------- | ----------------------------- | 37| title | string \| [Resource](ts-types.md#resource) | Yes | Title of the dialog box.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 38| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Subtitle of the dialog box.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 39| message | string \| [Resource](ts-types.md#resource) | Yes | Content of the dialog box.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 40| autoCancel | boolean | No | Whether to close the dialog box when the overlay is clicked.<br>Default value: **true**<br>The value **true** means to close the dialog box when the overlay is clicked, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 41| confirm | [ActionSheetButtonOptions](#actionsheetbuttonoptions14) | No | Information about the confirm button. When the dialog box has focus and focus has not been shifted using the **Tab** key, the button responds to the **Enter** key by default, and multiple dialog boxes can gain focus consecutively to respond automatically. The default response to the **Enter** key does not work when **defaultFocus** is set to **true**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 42| cancel | () => void | No | Callback invoked when the dialog box is closed after the overlay is clicked.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 43| alignment | [DialogAlignment](ts-methods-alert-dialog-box.md#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Bottom**<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**NOTE**<br>If **showInSubWindow** is set to **true** in **UIExtension**, the dialog box is aligned with the host window based on **UIExtension**.| 44| offset | [ActionSheetOffset](#actionsheetoffset14) | No | Offset of the dialog box relative to the alignment position.<br>Default value:<br>1. When alignment is set to **Top**, **TopStart**, or **TopEnd**: {dx: 0,dy: "40vp"}<br>2. When **alignment** is set to any other value: {dx: 0,dy: "-40vp"}<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 45| sheets | Array<[SheetInfo](#sheetinfo)> | Yes | Options in the dialog box. Each option supports the image, text, and callback.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 46| maskRect<sup>10+</sup> | [Rectangle](ts-methods-alert-dialog-box.md#rectangle8) | No | Mask area of the dialog box. Events outside the mask area are transparently transmitted, and events within the mask area are not.<br>Default value: **{ x: 0, y: 0, width: '100%', height: '100%' }**<br>**NOTE**<br>**maskRect** does not take effect when **showInSubWindow** is set to **true**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 47| showInSubWindow<sup>11+</sup> | boolean | No| Whether to show the dialog box in a sub-window when the dialog box needs to be displayed outside the main window.<br>Default value: **false**<br>**NOTE**<br>A dialog box whose **showInSubWindow** attribute is **true** cannot trigger the display of another dialog box whose **showInSubWindow** attribute is also **true**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 48| isModal<sup>11+</sup> | boolean | No| Whether the dialog box is a modal. A modal dialog box has a mask applied, while a non-modal dialog box does not.<br>Default value: **true**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 49| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Background color of the dialog box.<br>Default value: **Color.Transparent**<br>**NOTE**<br>When **backgroundColor** is set to a non-transparent color, **backgroundBlurStyle** must be set to **BlurStyle.NONE**; otherwise, the color display may not meet the expected effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 50| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| Background blur style of the dialog box.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**NOTE**<br>Setting this parameter to **BlurStyle.NONE** disables the background blur. When **backgroundBlurStyle** is set to a value other than **NONE**, do not set **backgroundColor**. If you do, the color display may not produce the expected visual effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 51| onWillDismiss<sup>12+</sup> | Callback<[DismissDialogAction](#dismissdialogaction12)> | No| Callback for interactive closure of the dialog box.<br>**NOTE**<br>1. If this callback is registered, the dialog box will not be closed immediately after the user touches the mask or the Back button, presses the Esc key, or swipes left or right on the screen. The **reason** parameter in the callback is used to determine whether the dialog box can be closed. The reason returned by the component does not support the value **CLOSE_BUTTON**.<br>2. In the **onWillDismiss** callback, another **onWillDismiss** callback is not allowed.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 52| cornerRadius<sup>12+</sup> | [Dimension](ts-types.md#dimension10) \| [BorderRadiuses](ts-types.md#borderradiuses9) \| [LocalizedBorderRadiuses](ts-types.md#LocalizedBorderRadiuses12) | No| Corner radius of the background.<br>You can set the radius for each of the four corners individually.<br>Default value: **{ topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp' }**<br> The corner radius is subject to the component size, with the maximum value being half of the component width or height. If the value is negative, the default value is used.<br> When set to a percentage, the value defines the radius as a percentage of the parent component's width or height.<br>**NOTE**<br>When **cornerRadius** is of type LocalizedBorderRadiuses, the layout order can be dynamically adjusted based on the user's language settings.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 53| borderWidth<sup>12+</sup> | [Dimension](ts-types.md#dimension10) \| [EdgeWidths](ts-types.md#edgewidths9) \| [LocalizedEdgeWidths](ts-types.md#LocalizedEdgeWidths12) | No| Border width of the dialog box.<br>You can set the width for all four sides or set separate widths for individual sides.<br>Default value: **0**<br> When set to a percentage, the value defines the border width as a percentage of the parent dialog box's width.<br>If the left and right borders are greater than its width, or the top and bottom borders are greater than its height, the dialog box may not display as expected.<br>**NOTE**<br>When **borderWidth** is of type LocalizedEdgeWidths, the layout order can be dynamically adjusted based on the user's language settings.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 54| borderColor<sup>12+</sup> | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](ts-types.md#edgecolors9) \| [LocalizedEdgeColors](ts-types.md#LocalizedEdgeColors12) | No| Border color of the dialog box.<br>Default value: **Color.Black**<br> **borderColor** must be used with **borderWidth** in pairs.<br>**NOTE**<br>When **borderColor** is of type LocalizedEdgeColors, the layout order can be dynamically adjusted based on the user's language settings.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 55| borderStyle<sup>12+</sup> | [BorderStyle](ts-appendix-enums.md#borderstyle) \| [EdgeStyles](ts-types.md#edgestyles9) | No| Border style of the dialog box.<br>Default value: **BorderStyle.Solid**<br> **borderStyle** must be used with **borderWidth** in pairs.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 56| width<sup>12+</sup> | [Dimension](ts-types.md#dimension10) | No| Width of the dialog box.<br>**NOTE**<br>- Default maximum width of the dialog box: 400 vp<br>- When this parameter is set to a percentage, the reference width of the dialog box is the width of the window where the dialog box is located. You can decrease or increase the width as needed.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 57| height<sup>12+</sup> | [Dimension](ts-types.md#dimension10) | No| Height of the dialog box.<br>**NOTE**<br>- Default maximum height of the dialog box: 0.9 x (Window height – Safe area)<br>- When this parameter is set to a percentage, the reference height of the dialog box is the height of the window where the dialog box is located minus the safe area. You can decrease or increase the height as needed.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 58| shadow<sup>12+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) | No| Shadow of the dialog box.<br> Default value on 2-in-1 devices: **ShadowStyle.OUTER_FLOATING_MD** when the dialog box is focused and **ShadowStyle.OUTER_FLOATING_SM** otherwise<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 59| transition<sup>12+</sup> | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10) | No| Transition effect for the entrance and exit of the dialog box.<br>**NOTE**<br>1. If this parameter is not set, the default effect is used.<br>2. Touching the Back button during the entrance animation pauses the entrance animation and starts the exit animation. The final effect is one obtained after the curves of the entrance and exit animations are combined.<br>3. Touching the Back button during the exit animation does not affect the animation playback. Touching the Back button again closes the application.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 60| enableHoverMode<sup>13+</sup> | boolean | No | Whether to enable the hover mode.<br>Default value: **false**, meaning not to enable the hover mode.| 61| hoverModeArea<sup>13+</sup> | [HoverModeAreaType](ts-appendix-enums.md#hovermodeareatype13) | No | Display area of the dialog box in hover mode.<br>Default value: **HoverModeAreaType.BOTTOM_SCREEN**| 62 63## SheetInfo 64 65**Atomic service API**: This API can be used in atomic services since API version 11. 66 67**System capability**: SystemCapability.ArkUI.ArkUI.Full 68 69| Name| Type | Mandatory| Description | 70| ------ | ------------------------------------------------------------ | ---- | ----------------- | 71| title | string \| [Resource](ts-types.md#resource) | Yes | Sheet text. | 72| icon | string \| [Resource](ts-types.md#resource) | No | Sheet icon. By default, no icon is displayed. | 73| action | [VoidCallback](ts-types.md#voidcallback12) | Yes | Callback when the sheet is selected.| 74 75## DismissDialogAction<sup>12+</sup> 76 77Provides information about the action to dismiss the dialog box. 78 79**Atomic service API**: This API can be used in atomic services since API version 12. 80 81**System capability**: SystemCapability.ArkUI.ArkUI.Full 82 83### Properties 84 85| Name | Type | Readable| Writable| Description | 86| ------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 87| dismiss | Callback<void> | No | No | Callback for dismissing the dialog box. This API is called only when the dialog box needs to be exited.| 88| reason | [DismissReason](../js-apis-promptAction.md#dismissreason12) | No | No | Reason why the dialog box cannot be dismissed. You must specify whether to close the dialog box for each of the listed actions.| 89 90## ActionSheetButtonOptions<sup>14+</sup> 91 92**Atomic service API**: This API can be used in atomic services since API version 14. 93 94**System capability**: SystemCapability.ArkUI.ArkUI.Full 95 96| Name | Type | Mandatory| Description| 97| ------------ | ------- | ---- | ---- | 98| enabled | boolean | No | Whether to respond when the button is clicked. The value **true** means to respond when the button is clicked, and **false** means the opposite.<br>Default value: **true**| 99| defaultFocus | boolean | No | Whether the button is the default focus. The value **true** means that the button is the default focus, and **false** means the opposite.<br>Default value: **false**| 100| style | [DialogButtonStyle](ts-appendix-enums.md#dialogbuttonstyle10) | No | Button style.<br>Default value: **DialogButtonStyle.DEFAULT**| 101| value | string \| [Resource](ts-types.md#resource) | Yes | Button text.| 102| action | [VoidCallback](ts-types.md#voidcallback12) | Yes | Callback invoked when the button is selected.| 103 104## ActionSheetOffset<sup>14+</sup> 105 106**Atomic service API**: This API can be used in atomic services since API version 14. 107 108**System capability**: SystemCapability.ArkUI.ArkUI.Full 109 110| Name| Type | Mandatory| Description | 111| ---- | ------------------------------------------------------------ | ---- | ---------------------------------- | 112| dx | number \| string \| [Resource](ts-types.md#resource) | Yes | Offset of the action sheet along the x-axis relative to the alignment position.| 113| dy | number \| string \| [Resource](ts-types.md#resource) | Yes | Offset of the action sheet along the y-axis relative to the alignment position.| 114 115## Example 116 117> **NOTE** 118> 119> For clarity in UI execution context, use the [showActionSheet](../js-apis-arkui-UIContext.md#showactionsheet) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext). 120 121### Example 1: Displaying an Action Sheet 122 123This example demonstrates how to display an action sheet when a button is touched. 124 125```ts 126@Entry 127@Component 128struct ActionSheetExample { 129 build() { 130 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 131 Button('Click to Show ActionSheet') 132 .onClick(() => { 133 ActionSheet.show ({ // You are advised to use this.getUIContext().showActionSheet(). 134 title: 'ActionSheet title', 135 subtitle: 'ActionSheet subtitle', 136 message: 'message', 137 autoCancel: true, 138 confirm: { 139 defaultFocus: true, 140 value: 'Confirm button', 141 action: () => { 142 console.log('Get Alert Dialog handled') 143 } 144 }, 145 cancel: () => { 146 console.log('actionSheet canceled') 147 }, 148 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 149 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 150 console.log("dialog onWillDismiss") 151 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 152 dismissDialogAction.dismiss() 153 } 154 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 155 dismissDialogAction.dismiss() 156 } 157 }, 158 alignment: DialogAlignment.Bottom, 159 offset: { dx: 0, dy: -10 }, 160 sheets: [ 161 { 162 title: 'apples', 163 action: () => { 164 console.log('apples') 165 } 166 }, 167 { 168 title: 'bananas', 169 action: () => { 170 console.log('bananas') 171 } 172 }, 173 { 174 title: 'pears', 175 action: () => { 176 console.log('pears') 177 } 178 } 179 ] 180 }) 181 }) 182 }.width('100%') 183 .height('100%') 184 } 185} 186``` 187 188 189 190### Example 2: Opening an Action Sheet Outside the Main Window 191 192This example demonstrates how to configure an action sheet to display outside the main window by setting **showInSubWindow** to **true**. 193 194```ts 195@Entry 196@Component 197struct ActionSheetExample { 198 build() { 199 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 200 Button('Click to Show ActionSheet') 201 .onClick(() => { 202 ActionSheet.show({ 203 title: 'ActionSheet title', 204 subtitle: 'ActionSheet subtitle', 205 message: 'message', 206 autoCancel: true, 207 showInSubWindow: true, 208 isModal: true, 209 confirm: { 210 defaultFocus: true, 211 value: 'Confirm button', 212 action: () => { 213 console.log('Get Alert Dialog handled') 214 } 215 }, 216 cancel: () => { 217 console.log('actionSheet canceled') 218 }, 219 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 220 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 221 console.log("dialog onWillDismiss") 222 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 223 dismissDialogAction.dismiss() 224 } 225 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 226 dismissDialogAction.dismiss() 227 } 228 }, 229 alignment: DialogAlignment.Center, 230 offset: { dx: 0, dy: -10 }, 231 sheets: [ 232 { 233 title: 'apples', 234 action: () => { 235 console.log('apples') 236 } 237 }, 238 { 239 title: 'bananas', 240 action: () => { 241 console.log('bananas') 242 } 243 }, 244 { 245 title: 'pears', 246 action: () => { 247 console.log('pears') 248 } 249 } 250 ] 251 }) 252 }) 253 }.width('100%') 254 .height('100%') 255 } 256} 257``` 258 259 260 261### Example 3: Setting the Action Sheet Animation 262This example illustrates how to use the **transition** API to create custom animation effects for the dialog box's appearance and disappearance. 263 264```ts 265@Entry 266@Component 267struct ActionSheetExample { 268 build() { 269 Column({ space: 5 }) { 270 Button('ActionSheet Set Duration') 271 .onClick(() => { 272 ActionSheet.show({ 273 title: 'ActionSheet 1', 274 message: 'Set Animation Duration open 3 second, close 100 ms', 275 autoCancel: true, 276 alignment: DialogAlignment.Top, 277 transition:TransitionEffect.asymmetric(TransitionEffect.OPACITY 278 .animation({ duration: 3000, curve: Curve.Sharp }).combine(TransitionEffect.scale({x: 1.5, y: 1.5}).animation({duration: 3000, curve: Curve.Sharp})), 279 TransitionEffect.OPACITY.animation({ duration: 100, curve: Curve.Smooth }) 280 .combine(TransitionEffect.scale({x: 0.5, y: 0.5}).animation({duration: 100, curve: Curve.Smooth}))), 281 offset: { dx: 0, dy: -20 }, 282 confirm: { 283 value: 'button', 284 action: () => { 285 console.info('Button-clicking callback') 286 } 287 }, 288 cancel: () => { 289 console.info('Closed callbacks') 290 }, 291 sheets: [ 292 { 293 title: 'apples', 294 action: () => { 295 console.log('apples') 296 } 297 }, 298 { 299 title: 'bananas', 300 action: () => { 301 console.log('bananas') 302 } 303 }, 304 { 305 title: 'pears', 306 action: () => { 307 console.log('pears') 308 } 309 } 310 ] 311 }) 312 }).backgroundColor(0x317aff).height("88px") 313 }.width('100%').margin({ top: 5 }) 314 } 315} 316``` 317 318 319 320### Example 4: Setting the Action Sheet Style 321This example demonstrates how to set styles of an action sheet, including the width, height, background color, and shadow. 322```ts 323@Entry 324@Component 325struct ActionSheetExample { 326 build() { 327 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 328 Button('Click to Show ActionSheet') 329 .onClick(() => { 330 ActionSheet.show({ 331 title: 'ActionSheet title', 332 subtitle: 'ActionSheet subtitle', 333 message: 'message', 334 autoCancel: true, 335 width: 300, 336 height: 350, 337 cornerRadius: 20, 338 borderWidth: 1, 339 borderStyle: BorderStyle.Solid,// borderStyle must be used with borderWidth in pairs. 340 borderColor: Color.Blue,// borderColor must be used with borderWidth in pairs. 341 backgroundColor: Color.White, 342 shadow: ({ radius: 20, color: Color.Grey, offsetX: 50, offsetY: 0}), 343 confirm: { 344 defaultFocus: true, 345 value: 'Confirm button', 346 action: () => { 347 console.log('Get Alert Dialog handled') 348 } 349 }, 350 cancel: () => { 351 console.log('actionSheet canceled') 352 }, 353 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 354 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 355 console.log("dialog onWillDismiss") 356 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 357 dismissDialogAction.dismiss() 358 } 359 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 360 dismissDialogAction.dismiss() 361 } 362 }, 363 alignment: DialogAlignment.Bottom, 364 offset: { dx: 0, dy: -10 }, 365 sheets: [ 366 { 367 title: 'apples', 368 action: () => { 369 console.log('apples') 370 } 371 }, 372 { 373 title: 'bananas', 374 action: () => { 375 console.log('bananas') 376 } 377 }, 378 { 379 title: 'pears', 380 action: () => { 381 console.log('pears') 382 } 383 } 384 ] 385 }) 386 }) 387 }.width('100%') 388 .height('100%') 389 } 390} 391``` 392 393 394 395### Example 5: Configuring an Action Sheet in the Hover State 396 397This example demonstrates how to set the layout area of an action sheet in hover mode on a foldable device. 398 399```ts 400@Entry 401@Component 402struct ActionSheetExample { 403 build() { 404 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 405 Button('Click to Show ActionSheet') 406 .onClick(() => { 407 ActionSheet.show ({ // You are advised to use this.getUIContext().showActionSheet(). 408 title: 'ActionSheet title', 409 subtitle: 'ActionSheet subtitle', 410 message: 'message', 411 autoCancel: true, 412 confirm: { 413 defaultFocus: true, 414 value: 'Confirm button', 415 action: () => { 416 console.log('Get Alert Dialog handled') 417 } 418 }, 419 cancel: () => { 420 console.log('actionSheet canceled') 421 }, 422 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 423 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 424 console.log("dialog onWillDismiss") 425 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 426 dismissDialogAction.dismiss() 427 } 428 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 429 dismissDialogAction.dismiss() 430 } 431 }, 432 alignment: DialogAlignment.Bottom, 433 offset: { dx: 0, dy: -10 }, 434 enableHoverMode: true, 435 hoverModeArea: HoverModeAreaType.TOP_SCREEN, 436 sheets: [ 437 { 438 title: 'apples', 439 action: () => { 440 console.log('apples') 441 } 442 }, 443 { 444 title: 'bananas', 445 action: () => { 446 console.log('bananas') 447 } 448 }, 449 { 450 title: 'pears', 451 action: () => { 452 console.log('pears') 453 } 454 } 455 ] 456 }) 457 }) 458 }.width('100%') 459 .height('100%') 460 } 461} 462``` 463 464 465
