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) to obtain the UI context. 12 13## ActionSheet.show 14 15static show(value: ActionSheetOptions) 16 17Shows an action sheet in the given settings. 18 19**Atomic service API**: This API can be used in atomic services since API version 11. 20 21**System capability**: SystemCapability.ArkUI.ArkUI.Full 22 23**Parameters** 24 25| Name| Type | Mandatory| Description. | 26| ------ | ------------------------------------------------- | ---- | ------------------------ | 27| value | [ActionSheetOptions](#actionsheetoptions) | Yes | Parameters of the action sheet.| 28 29## ActionSheetOptions 30 31| Name | Type | Mandatory | Description | 32| ---------- | -------------------------- | ------- | ----------------------------- | 33| title | [Resource](ts-types.md#resource) \| string | Yes | Title of the dialog box.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 34| 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.| 35| message | [Resource](ts-types.md#resource) \| string | Yes | Content of the dialog box.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 36| 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.| 37| confirm | {<br>enabled<sup>10+</sup>?: boolean,<br>defaultFocus<sup>10+</sup>?: boolean,<br>style<sup>10+</sup>?: [DialogButtonStyle](#dialogbuttonstyle10),<br>value: [Resource](ts-types.md#resource) \| string,<br>action: () => void<br>} | No | Information about the confirm button. When the dialog box has focus and the **Tab** key is not pressed for sequential focus navigation, the button responds to the **Enter** key by default.<br>**enabled**: whether the button responds to clicks. The value **true** means that the button responds to clicks, and **false** means the opposite.<br>Default value: **true**<br>**defaultFocus**: 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**<br>**style**: button style.<br>Default value: **DialogButtonStyle.DEFAULT**<br>**value**: button text.<br>**action**: callback upon button clicking.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 38| 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. | 39| 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**.| 40| offset | {<br>dx: number \| string \| [Resource](ts-types.md#resource),<br>dy: number \| string \| [Resource](ts-types.md#resource)<br>} | 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.| 41| 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.| 42| 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 12.| 43| 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.| 44| 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.| 45| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Background color of the dialog box.<br>Default value: **Color.Transparent**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 46| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-appendix-enums.md#blurstyle9) | No| Background blur style of the dialog box.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 47| onWillDismiss<sup>12+</sup> | Callback<[DismissDialogAction](ts-methods-alert-dialog-box.md#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.| 48| cornerRadius<sup>12+</sup> | [BorderRadiuses](ts-types.md#borderradiuses9) \| [Dimension](ts-types.md#dimension10) | No| Radius of the rounded corners of the background.<br>You can set separate radiuses for the four rounded corners.<br>Default value: **{ topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp' }**<br> The radius of the rounded corners is subject to the component size. Its maximum value is 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.| 49| borderWidth<sup>12+</sup> | [Dimension](ts-types.md#dimension10) \| [EdgeWidths](ts-types.md#edgewidths9) | 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.| 50| borderColor<sup>12+</sup> | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](ts-types.md#edgecolors9) | No| Border color of the dialog box.<br>Default value: **Color.Black**<br> **borderColor** must be used with **borderWidth** in pairs.| 51| 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.| 52| 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.| 53| 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.| 54| 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| 55| 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.| 56## SheetInfo 57 58**Atomic service API**: This API can be used in atomic services since API version 11. 59 60| Name| Type | Mandatory| Description | 61| ------ | ------------------------------------------------------------ | ---- | ----------------- | 62| title | string \| [Resource](ts-types.md#resource) | Yes | Sheet text. | 63| icon | string \| [Resource](ts-types.md#resource) | No | Sheet icon. By default, no icon is displayed. | 64| action | ()=>void | Yes | Callback when the sheet is selected.| 65 66## DialogButtonStyle<sup>10+</sup> 67 68**Atomic service API**: This API can be used in atomic services since API version 11. 69 70| Name | Description. | 71| --------- | --------------------------------- | 72| DEFAULT | Blue text on white background (black background under the dark theme).| 73| HIGHLIGHT | White text on blue background. | 74 75## Example 76 77### Example 1 78 79```ts 80@Entry 81@Component 82struct ActionSheetExample { 83 build() { 84 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 85 Button('Click to Show ActionSheet') 86 .onClick(() => { 87 ActionSheet.show({ 88 title: 'ActionSheet title', 89 subtitle: 'ActionSheet subtitle', 90 message: 'message', 91 autoCancel: true, 92 confirm: { 93 defaultFocus: true, 94 value: 'Confirm button', 95 action: () => { 96 console.log('Get Alert Dialog handled') 97 } 98 }, 99 cancel: () => { 100 console.log('actionSheet canceled') 101 }, 102 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 103 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 104 console.log("dialog onWillDismiss") 105 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 106 dismissDialogAction.dismiss() 107 } 108 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 109 dismissDialogAction.dismiss() 110 } 111 }, 112 alignment: DialogAlignment.Bottom, 113 offset: { dx: 0, dy: -10 }, 114 sheets: [ 115 { 116 title: 'apples', 117 action: () => { 118 console.log('apples') 119 } 120 }, 121 { 122 title: 'bananas', 123 action: () => { 124 console.log('bananas') 125 } 126 }, 127 { 128 title: 'pears', 129 action: () => { 130 console.log('pears') 131 } 132 } 133 ] 134 }) 135 }) 136 }.width('100%') 137 .height('100%') 138 } 139} 140``` 141 142 143 144### Example 2 145 146```ts 147@Entry 148@Component 149struct ActionSheetExample { 150 build() { 151 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 152 Button('Click to Show ActionSheet') 153 .onClick(() => { 154 ActionSheet.show({ 155 title: 'ActionSheet title', 156 subtitle: 'ActionSheet subtitle', 157 message: 'message', 158 autoCancel: true, 159 showInSubWindow: true, 160 isModal: true, 161 confirm: { 162 defaultFocus: true, 163 value: 'Confirm button', 164 action: () => { 165 console.log('Get Alert Dialog handled') 166 } 167 }, 168 cancel: () => { 169 console.log('actionSheet canceled') 170 }, 171 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 172 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 173 console.log("dialog onWillDismiss") 174 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 175 dismissDialogAction.dismiss() 176 } 177 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 178 dismissDialogAction.dismiss() 179 } 180 }, 181 alignment: DialogAlignment.Center, 182 offset: { dx: 0, dy: -10 }, 183 sheets: [ 184 { 185 title: 'apples', 186 action: () => { 187 console.log('apples') 188 } 189 }, 190 { 191 title: 'bananas', 192 action: () => { 193 console.log('bananas') 194 } 195 }, 196 { 197 title: 'pears', 198 action: () => { 199 console.log('pears') 200 } 201 } 202 ] 203 }) 204 }) 205 }.width('100%') 206 .height('100%') 207 } 208} 209``` 210 211 212 213### Example 3 214This example sets a 3s entrance animation and a 100 ms exit animation for the action sheet. 215```ts 216import router from '@ohos.router'; 217@Entry 218@Component 219struct ActionSheetExample { 220 build() { 221 Column({ space: 5 }) { 222 Button('ActionSheet Set Duration') 223 .onClick(() => { 224 ActionSheet.show({ 225 title: 'ActionSheet 1', 226 message: 'Set Animation Duration open 3 second, close 100 ms', 227 autoCancel: true, 228 alignment: DialogAlignment.Top, 229 transition:TransitionEffect.asymmetric(TransitionEffect.OPACITY 230 .animation({ duration: 3000, curve: Curve.Sharp }).combine(TransitionEffect.scale({x: 1.5, y: 1.5}).animation({duration: 3000, curve: Curve.Sharp})), 231 TransitionEffect.OPACITY.animation({ duration: 100, curve: Curve.Smooth }) 232 .combine(TransitionEffect.scale({x: 0.5, y: 0.5}).animation({duration: 100, curve: Curve.Smooth}))), 233 offset: { dx: 0, dy: -20 }, 234 confirm: { 235 value: 'button', 236 action: () => { 237 console.info('Button-clicking callback') 238 } 239 }, 240 cancel: () => { 241 console.info('Closed callbacks') 242 }, 243 sheets: [ 244 { 245 title: 'apples', 246 action: () => { 247 console.log('apples') 248 } 249 }, 250 { 251 title: 'bananas', 252 action: () => { 253 console.log('bananas') 254 } 255 }, 256 { 257 title: 'pears', 258 action: () => { 259 console.log('pears') 260 } 261 } 262 ] 263 }) 264 }).backgroundColor(0x317aff).height("88px") 265 }.width('100%').margin({ top: 5 }) 266 } 267} 268``` 269 270 271
