Action Sheet (ActionSheet)
An action sheet is a dialog box that displays actions a user can take.
NOTE
The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
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.
Since API version 10, you can use the showActionSheet API in UIContext, which ensures that the action sheet is shown in the intended UI instance.
ActionSheet
show
static show(value: ActionSheetOptions)
Shows an action sheet in the given settings.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | ActionSheetOptions | Yes | Parameters of the action sheet. |
ActionSheetOptions
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| title | string |Resource | Yes | Title of the dialog box. If the text is too long to display, it is truncated with an ellipsis (...). Atomic service API: This API can be used in atomic services since API version 11. |
| subtitle10+ | ResourceStr | No | Subtitle of the dialog box. If the text is too long to display, it is truncated with an ellipsis (...). Atomic service API: This API can be used in atomic services since API version 11. |
| message | string |Resource | Yes | Content of the dialog box. If the text is too long to display, a scrollbar is displayed. Atomic service API: This API can be used in atomic services since API version 11. |
| autoCancel | boolean | No | Whether to close the dialog box when the overlay is clicked. Default value: true The value true means to close the dialog box when the overlay is clicked, and false means the opposite. Atomic service API: This API can be used in atomic services since API version 11. |
| confirm | ActionSheetButtonOptions | 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. Atomic service API: This API can be used in atomic services since API version 11. |
| cancel | VoidCallback | No | Callback invoked when the dialog box is closed after the overlay is clicked. Atomic service API: This API can be used in atomic services since API version 11. |
| alignment | DialogAlignment | No | Alignment mode of the dialog box in the vertical direction. Default value: DialogAlignment.Bottom Atomic service API: This API can be used in atomic services since API version 11. NOTE If showInSubWindow is set to true in UIExtension, the dialog box is aligned with the host window based on UIExtension. |
| offset | ActionSheetOffset | No | Offset of the dialog box relative to the alignment position. Default value: 1. When alignment is set to Top, TopStart, or TopEnd: {dx: 0,dy: "40vp"} 2. When alignment is set to any other value: {dx: 0,dy: "-40vp"} Atomic service API: This API can be used in atomic services since API version 11. |
| sheets | Array<SheetInfo> | Yes | Options in the dialog box. Each option supports the image, text, and callback. Atomic service API: This API can be used in atomic services since API version 11. |
| maskRect10+ | Rectangle | No | Mask area of the dialog box. Events outside the mask area are transparently transmitted, and events within the mask area are not. Default value: { x: 0, y: 0, width: '100%', height: '100%' } NOTE maskRect does not take effect when showInSubWindow is set to true. Atomic service API: This API can be used in atomic services since API version 11. |
| showInSubWindow11+ | boolean | No | Whether to show the dialog box in a sub-window when the dialog box needs to be displayed outside the main window. Default value: false NOTE A dialog box whose showInSubWindow attribute is true cannot trigger the display of another dialog box whose showInSubWindow attribute is also true. Atomic service API: This API can be used in atomic services since API version 12. |
| isModal11+ | 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. Default value: true Atomic service API: This API can be used in atomic services since API version 12. |
| backgroundColor11+ | ResourceColor | No | Background color of the dialog box. Default value: Color.Transparent NOTE 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. Atomic service API: This API can be used in atomic services since API version 12. |
| backgroundBlurStyle11+ | BlurStyle | No | Background blur style of the dialog box. Default value: BlurStyle.COMPONENT_ULTRA_THICK NOTE 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. Atomic service API: This API can be used in atomic services since API version 12. |
| backgroundBlurStyleOptions18+ | BackgroundBlurStyleOptions | No | Options for customizing the background blur style. Atomic service API: This API can be used in atomic services since API version 18. |
| backgroundEffect18+ | BackgroundEffectOptions | No | Options for customizing the background effect. Atomic service API: This API can be used in atomic services since API version 18. |
| onWillDismiss12+ | Callback<DismissDialogAction> | No | Callback for interactive closure of the dialog box. NOTE 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. 2. In the onWillDismiss callback, another onWillDismiss callback is not allowed. Atomic service API: This API can be used in atomic services since API version 12. |
| cornerRadius12+ | Dimension |BorderRadiuses | LocalizedBorderRadiuses | No | Corner radius of the background. You can set the radius for each of the four corners individually. Default value: { topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp' } 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. When set to a percentage, the value defines the radius as a percentage of the parent component's width or height. NOTE When cornerRadius is of type LocalizedBorderRadiuses, the layout order can be dynamically adjusted based on the user's language settings. Atomic service API: This API can be used in atomic services since API version 12. |
| borderWidth12+ | Dimension |EdgeWidths |LocalizedEdgeWidths | No | Border width of the dialog box. You can set the width for all four sides or set separate widths for individual sides. Default value: 0 When set to a percentage, the value defines the border width as a percentage of the parent dialog box's width. 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. NOTE When borderWidth is of type LocalizedEdgeWidths, the layout order can be dynamically adjusted based on the user's language settings. Atomic service API: This API can be used in atomic services since API version 12. |
| borderColor12+ | ResourceColor |EdgeColors |LocalizedEdgeColors | No | Border color of the dialog box. Default value: Color.Black borderColor must be used with borderWidth in pairs. NOTE When borderColor is of type LocalizedEdgeColors, the layout order can be dynamically adjusted based on the user's language settings. Atomic service API: This API can be used in atomic services since API version 12. |
| borderStyle12+ | BorderStyle |EdgeStyles | No | Border style of the dialog box. Default value: BorderStyle.Solid borderStyle must be used with borderWidth in pairs. Atomic service API: This API can be used in atomic services since API version 12. |
| width12+ | Dimension | No | Width of the dialog box. NOTE - Default maximum width of the dialog box: 400 vp - 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. Atomic service API: This API can be used in atomic services since API version 12. |
| height12+ | Dimension | No | Height of the dialog box. NOTE - Default maximum height of the dialog box: 0.9 x (Window height – Safe area) - 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. Atomic service API: This API can be used in atomic services since API version 12. |
| shadow12+ | ShadowOptions |ShadowStyle | No | Shadow of the dialog box. Default value on 2-in-1 devices: ShadowStyle.OUTER_FLOATING_MD when the dialog box is focused and ShadowStyle.OUTER_FLOATING_SM otherwise Atomic service API: This API can be used in atomic services since API version 12. |
| transition12+ | TransitionEffect | No | Transition effect for the entrance and exit of the dialog box. NOTE 1. If this parameter is not set, the default effect is used. 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. 3. Touching the Back button during the exit animation does not affect the animation playback. Touching the Back button again closes the application. Atomic service API: This API can be used in atomic services since API version 12. |
| enableHoverMode14+ | boolean | No | Whether to enable the hover mode. Default value: false, meaning not to enable the hover mode. Atomic service API: This API can be used in atomic services since API version 14. |
| hoverModeArea14+ | HoverModeAreaType | No | Display area of the dialog box in hover mode. Default value: HoverModeAreaType.BOTTOM_SCREEN Atomic service API: This API can be used in atomic services since API version 14. |
| onWillAppear18+ | Callback<void> | No | Event callback when the dialog box is about to appear. NOTE 1. The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear. 2. You can set the callback event for changing the dialog box display effect in onWillAppear. The settings take effect next time the dialog box appears. Atomic service API: This API can be used in atomic services since API version 18. |
| onDidAppear18+ | Callback<void> | No | Event callback when the dialog box appears. NOTE 1. The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear. 2. You can set the callback event for changing the dialog box display effect in onDidAppear. The settings take effect next time the dialog box appears. 3. If the dialog is dismissed before its entrance animation is finished, the animation will be interrupted, and onDidAppear will not be triggered. Atomic service API: This API can be used in atomic services since API version 18. |
| onWillDisappear18+ | Callback<void> | No | Event callback when the dialog box is about to disappear. NOTE 1. The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear. Atomic service API: This API can be used in atomic services since API version 18. |
| onDidDisappear18+ | Callback<void> | No | Event callback when the dialog box disappears. NOTE 1. The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear. Atomic service API: This API can be used in atomic services since API version 18. |
| levelMode15+ | LevelMode | No | Display level of the dialog box. NOTE - Default value: LevelMode.OVERLAY. - This parameter takes effect only when showInSubWindow is set to false. Atomic service API: This API can be used in atomic services since API version 15. |
| levelUniqueId15+ | number | No | Unique ID of the node under the display level for the page-level dialog box. NOTE - This parameter takes effect only when levelMode is set to LevelMode.EMBEDDED. Atomic service API: This API can be used in atomic services since API version 15. |
| immersiveMode15+ | ImmersiveMode | No | Overlay effect for the page-level dialog box. NOTE - Default value: ImmersiveMode.DEFAULT - This parameter takes effect only when levelMode is set to LevelMode.EMBEDDED. Atomic service API: This API can be used in atomic services since API version 15. |
| levelOrder18+ | LevelOrder | No | Display order of the dialog box. NOTE - Default value: LevelOrder.clamp(0) - Dynamic updating is not supported. Atomic service API: This API can be used in atomic services since API version 18. |
SheetInfo
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| title | string |Resource | Yes | Sheet text. If the text is too long to display, a scrollbar is displayed. |
| icon | string |Resource | No | Sheet icon. By default, no icon is displayed. The string type can be used to load local images and, more frequently, online images. The value can be a relative path to a local image, for example, Image("common/test.jpg"). |
| action | VoidCallback | Yes | Callback when the sheet is selected. |
LevelMode15+
type LevelMode = LevelMode
Defines the display level for the dialog box.
Atomic service API: This API can be used in atomic services since API version 15.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Type | Description |
|---|---|
| LevelMode | Display level of the dialog box. |
ImmersiveMode15+
type ImmersiveMode = ImmersiveMode
Defines the overlay effect for the dialog box.
Atomic service API: This API can be used in atomic services since API version 15.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Type | Description |
|---|---|
| ImmersiveMode | Overlay effect for the page-level dialog box. |
DismissDialogAction12+
Provides information about the action to dismiss the dialog box.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Properties
| Name | Type | Readable | Writable | Description |
|---|---|---|---|---|
| dismiss | Callback<void> | No | No | Callback for dismissing the dialog box. This API is called only when the dialog box needs to be exited. |
| reason | DismissReason | 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. |
ActionSheetButtonOptions18+
Atomic service API: This API can be used in atomic services since API version 18.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| enabled10+ | 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. Default value: true Atomic service API: This API can be used in atomic services since API version 11. |
| defaultFocus10+ | 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. Default value: false Atomic service API: This API can be used in atomic services since API version 11. |
| style10+ | DialogButtonStyle | No | Button style. Default value: DialogButtonStyle.DEFAULT Atomic service API: This API can be used in atomic services since API version 11. |
| value8+ | string |Resource | Yes | Button text. If the text is too long to display, it is truncated with an ellipsis (...). Atomic service API: This API can be used in atomic services since API version 11. |
| action8+ | VoidCallback | Yes | Callback invoked when the button is selected. Atomic service API: This API can be used in atomic services since API version 11. |
ActionSheetOffset18+
Atomic service API: This API can be used in atomic services since API version 18.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| dx | number |string |Resource | Yes | Offset of the action sheet along the x-axis relative to the alignment position. String type. Specify the length unit explicitly, for example, '10px', or provide the length in percentage, for example, '100%'. NOTE If the unit is not specified, the default unit vp is used, in which case '10' is equivalent to 10 vp. |
| dy | number |string |Resource | Yes | Offset of the action sheet along the y-axis relative to the alignment position. String type. Specify the length unit explicitly, for example, '10px', or provide the length in percentage, for example, '100%'. NOTE If the unit is not specified, the default unit vp is used, in which case '10' is equivalent to 10 vp. |
Example
NOTE
For clarity in UI execution context, use the showActionSheet API in UIContext.
Example 1: Displaying an Action Sheet
This example demonstrates how to display an action sheet when a button is touched.
@Entry
@Component
struct ActionSheetExample {
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Button('Click to Show ActionSheet')
.onClick(() => {
ActionSheet.show ({ // You are advised to use this.getUIContext().showActionSheet().
title: 'ActionSheet title',
subtitle: 'ActionSheet subtitle',
message: 'message',
autoCancel: true,
confirm: {
defaultFocus: true,
value: 'Confirm button',
action: () => {
console.log('Get Alert Dialog handled')
}
},
cancel: () => {
console.log('actionSheet canceled')
},
onWillDismiss:(dismissDialogAction: DismissDialogAction)=> {
console.info("reason=" + JSON.stringify(dismissDialogAction.reason))
console.log("dialog onWillDismiss")
if (dismissDialogAction.reason == DismissReason.PRESS_BACK) {
dismissDialogAction.dismiss()
}
if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) {
dismissDialogAction.dismiss()
}
},
alignment: DialogAlignment.Bottom,
offset: { dx: 0, dy: -10 },
sheets: [
{
title: 'apples',
action: () => {
console.log('apples')
}
},
{
title: 'bananas',
action: () => {
console.log('bananas')
}
},
{
title: 'pears',
action: () => {
console.log('pears')
}
}
]
})
})
}.width('100%')
.height('100%')
}
}
Example 2: Opening an Action Sheet Outside the Main Window
This example demonstrates how to configure an action sheet to display outside the main window on a 2-in-1 device by setting showInSubWindow to true.
@Entry
@Component
struct ActionSheetExample {
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Button('Click to Show ActionSheet')
.onClick(() => {
ActionSheet.show({
title: 'ActionSheet title',
subtitle: 'ActionSheet subtitle',
message: 'message',
autoCancel: true,
showInSubWindow: true,
isModal: true,
confirm: {
defaultFocus: true,
value: 'Confirm button',
action: () => {
console.log('Get Alert Dialog handled')
}
},
cancel: () => {
console.log('actionSheet canceled')
},
onWillDismiss:(dismissDialogAction: DismissDialogAction)=> {
console.info("reason=" + JSON.stringify(dismissDialogAction.reason))
console.log("dialog onWillDismiss")
if (dismissDialogAction.reason == DismissReason.PRESS_BACK) {
dismissDialogAction.dismiss()
}
if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) {
dismissDialogAction.dismiss()
}
},
alignment: DialogAlignment.Center,
offset: { dx: 0, dy: -10 },
sheets: [
{
title: 'apples',
action: () => {
console.log('apples')
}
},
{
title: 'bananas',
action: () => {
console.log('bananas')
}
},
{
title: 'pears',
action: () => {
console.log('pears')
}
}
]
})
})
}.width('100%')
.height('100%')
}
}
Example 3: Setting the Action Sheet Animation
This example illustrates how to use the transition API to create custom animation effects for the dialog box's appearance and disappearance.
@Entry
@Component
struct ActionSheetExample {
build() {
Column({ space: 5 }) {
Button('ActionSheet Set Duration')
.onClick(() => {
ActionSheet.show({
title: 'ActionSheet 1',
message: 'Set Animation Duration open 3 second, close 100 ms',
autoCancel: true,
alignment: DialogAlignment.Top,
transition:TransitionEffect.asymmetric(TransitionEffect.OPACITY
.animation({ duration: 3000, curve: Curve.Sharp }).combine(TransitionEffect.scale({x: 1.5, y: 1.5}).animation({duration: 3000, curve: Curve.Sharp})),
TransitionEffect.OPACITY.animation({ duration: 100, curve: Curve.Smooth })
.combine(TransitionEffect.scale({x: 0.5, y: 0.5}).animation({duration: 100, curve: Curve.Smooth}))),
offset: { dx: 0, dy: -20 },
confirm: {
value: 'button',
action: () => {
console.info('Button-clicking callback')
}
},
cancel: () => {
console.info('Closed callbacks')
},
sheets: [
{
title: 'apples',
action: () => {
console.log('apples')
}
},
{
title: 'bananas',
action: () => {
console.log('bananas')
}
},
{
title: 'pears',
action: () => {
console.log('pears')
}
}
]
})
}).backgroundColor(0x317aff).height("88px")
}.width('100%').margin({ top: 5 })
}
}
Example 4: Setting the Action Sheet Style
This example demonstrates how to set styles of an action sheet, including the width, height, background color, and shadow.
@Entry
@Component
struct ActionSheetExample {
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center }) {
Button('Click to Show ActionSheet')
.onClick(() => {
ActionSheet.show({
title: 'ActionSheet title',
subtitle: 'ActionSheet subtitle',
message: 'message',
autoCancel: true,
width: 300,
height: 350,
cornerRadius: 20,
borderWidth: 1,
borderStyle: BorderStyle.Solid,// borderStyle must be used with borderWidth in pairs.
borderColor: Color.Blue,// borderColor must be used with borderWidth in pairs.
backgroundColor: Color.White,
shadow: ({ radius: 20, color: Color.Grey, offsetX: 50, offsetY: 0}),
confirm: {
defaultFocus: true,
value: 'Confirm button',
action: () => {
console.log('Get Alert Dialog handled')
}
},
cancel: () => {
console.log('actionSheet canceled')
},
onWillDismiss:(dismissDialogAction: DismissDialogAction)=> {
console.info("reason=" + JSON.stringify(dismissDialogAction.reason))
console.log("dialog onWillDismiss")
if (dismissDialogAction.reason == DismissReason.PRESS_BACK) {
dismissDialogAction.dismiss()
}
if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) {
dismissDialogAction.dismiss()
}
},
alignment: DialogAlignment.Bottom,
offset: { dx: 0, dy: -10 },
sheets: [
{
title: 'apples',
action: () => {
console.log('apples')
}
},
{
title: 'bananas',
action: () => {
console.log('bananas')
}
},
{
title: 'pears',
action: () => {
console.log('pears')
}
}
]
})
})
}.width('100%')
}
}
Example 5: Configuring an Action Sheet in the Hover State
This example demonstrates how to set the layout area of an action sheet in hover mode on a foldable device.
@Entry
@Component
struct ActionSheetExample {
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Button('Click to Show ActionSheet')
.onClick(() => {
ActionSheet.show ({ // You are advised to use this.getUIContext().showActionSheet().
title: 'ActionSheet title',
subtitle: 'ActionSheet subtitle',
message: 'message',
autoCancel: true,
confirm: {
defaultFocus: true,
value: 'Confirm button',
action: () => {
console.log('Get Alert Dialog handled')
}
},
cancel: () => {
console.log('actionSheet canceled')
},
onWillDismiss:(dismissDialogAction: DismissDialogAction)=> {
console.info("reason=" + JSON.stringify(dismissDialogAction.reason))
console.log("dialog onWillDismiss")
if (dismissDialogAction.reason == DismissReason.PRESS_BACK) {
dismissDialogAction.dismiss()
}
if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) {
dismissDialogAction.dismiss()
}
},
alignment: DialogAlignment.Bottom,
offset: { dx: 0, dy: -10 },
enableHoverMode: true,
hoverModeArea: HoverModeAreaType.TOP_SCREEN,
sheets: [
{
title: 'apples',
action: () => {
console.log('apples')
}
},
{
title: 'bananas',
action: () => {
console.log('bananas')
}
},
{
title: 'pears',
action: () => {
console.log('pears')
}
}
]
})
})
}.width('100%')
.height('100%')
}
}
