1# Sheet Transition 2 3You can bind a sheet to a component through the **bindSheet** attribute. You can also set the sheet to the preset or custom height for when the component is inserted. 4 5> **NOTE** 6> 7> This feature is supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> Route hopping is not supported. 10 11## bindSheet 12 13bindSheet(isShow: Optional\<boolean\>, builder: CustomBuilder, options?: SheetOptions) 14 15Binds a sheet to the component, which is displayed when the component is touched. 16 17**Atomic service API**: This API can be used in atomic services since API version 11. 18 19**System capability**: SystemCapability.ArkUI.ArkUI.Full 20 21**Parameters** 22 23| Name | Type | Mandatory| Description | 24| ------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 25| isShow | Optional\<boolean\> | Yes | Whether to display the sheet.<br>Since API version 10, this parameter supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).<br>Since API version 18, this parameter supports two-way binding through [!!](../../../quick-start/arkts-new-binding.md#two-way-binding-between-built-in-component-parameters).| 26| builder | [CustomBuilder](ts-types.md#custombuilder8) | Yes | Content of the sheet. | 27| options | [SheetOptions](#sheetoptions) | No | Optional attributes of the sheet. | 28 29> **NOTE** 30> 31> 1. When no two-way binding is set up for the **isShow** parameter, closing the sheet by dragging does not change the parameter value. 32> 33> 2. To synchronize the value of the **isShow** parameter with the sheet UI state, set up a two-way binding for **isShow** through [$$](../../../quick-start/arkts-two-way-sync.md). Since API version 18, this parameter supports two-way binding through [!!](../../../quick-start/arkts-new-binding.md#two-way-binding-between-built-in-component-parameters). 34> 35> 3. In scenarios where a sheet with a single detent is dragged upwards or a sheet with multiple detents is shifted to another detent by swiping up, the display area is updated after the drag ends or the shift is completed. 36> 37> 4. A sheet is a popup that is strictly bound to its host node. To achieve an effect where the sheet appears the moment the page is displayed, ensure that the host node is mounted in the view hierarchy. If the host node is not yet mounted when **isShow** is set to **true**, the sheet will not be displayed. You are advised to use the [onAppear](ts-universal-events-show-hide.md#onappear) to ensure that the sheet is shown after the host node is mounted. 38> When [SheetMode](#sheetmode12) is set to **EMBEDDED**, in addition to the host node, also ensure that the corresponding page node is successfully mounted. 39> 40> 5. The exit animation of the sheet does not support interruption, and the sheet cannot respond to other gestures during the execution. The current exit animation uses a [spring curve](../../../ui/arkts-spring-curve.md), which has a subtle trailing effect that is not visually prominent. Therefore, when the sheet exits, although it may appear to have disappeared, the animation might not have fully finished, and attempting to initiate the sheet again by a touch will not work. You must wait for the animation to fully complete before you can initiate the sheet again. 41> 42## SheetOptions 43 44Inherits from [BindOptions](#bindoptions). 45 46| Name | Type | Mandatory | Description | 47| --------------- | ---------------------------------------- | ---- | --------------- | 48| height | [SheetSize](#sheetsize) \| [Length](ts-types.md#length) | No | Height of the sheet.<br>Default value: **LARGE**<br>**NOTE**<br>In versions earlier than API version 12, this attribute is ineffective for a bottom sheet in landscape mode; the height is fixed at 8 vp from the top of the screen.<br>Since API version 12, this attribute takes effect for a bottom sheet in landscape mode; the maximum height is 8 vp from the top of the screen.<br>Since API version 14, for a bottom sheet in landscape mode, the maximum height is 8 vp from the top of the screen if there is no status bar, and 8 vp from the status bar if there is one.<br>When a bottom sheet has **detents** set, this attribute is ineffective.<br>For a bottom sheet in portrait mode, the maximum height is 8 vp from the status bar.<br>For center and popup sheets set to **SheetSize.LARGE** or **SheetSize.MEDIUM**, this attribute is ineffective, with the default height being 560 vp. For center and popup sheets, the minimum height is 320 vp, and the maximum height is 90% of the shorter edge of the window. If the height specified by **Length** and the height adaptively set with **SheetSize.FIT_CONTENT** exceed the maximum height, the maximum height is used instead. If they are less than the minimum height, the minimum height is used instead.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 49| detents<sup>11+</sup> | [([SheetSize](#sheetsize) \| [Length](ts-types.md#length)), ( [SheetSize](#sheetsize) \| [Length](ts-types.md#length))?, ([SheetSize](#sheetsize) \| [Length](ts-types.md#length))?] | No| Array of heights where the sheet can rest.<br>**NOTE**<br>Since API version 12, this attribute takes effect for a bottom sheet in landscape mode.<br>In earlier versions, this attribute takes effect only for the bottom sheet in portrait mode. The first height in the tuple is the initial height.<br>The sheet can switch between heights by dragging. After the sheet is dragged and released, it switches to the target height or remains at the current height, depending on the velocity and distance.<br> If the velocity exceeds the threshold, the sheet switches to the target height in the same direction as the velocity. If the velocity is less than the threshold, the displacement distance is used for judgement. If the displacement distance is greater than 1/2 of the distance between the current and target positions, the sheet switches to the target height in the same direction as the velocity; otherwise, the sheet remains at the current height.<br> Velocity threshold: 1000; Distance threshold: 50%.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 50| preferType<sup>11+</sup> | [SheetType](#sheettype11)| No| Type of the sheet.<br>**NOTE**<br>The types supported by the sheet vary by window.<br>1. Width < 600 vp: bottom<br>2. 600 vp <= Width: bottom, center, and popup (default)<br>3. Width >= 840 vp: bottom, center, and popup (default)<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 51| showClose<sup>11+</sup> | boolean \| [Resource](ts-types.md#resource) | No| Whether to display the close icon. By default, the icon is displayed.<br> On 2-in-1 devices, the icon does not have a background by default.<br>**NOTE**<br>The value of **Resource** must be of the Boolean type.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 52| dragBar | boolean | No | Whether to display the drag bar.<br>**NOTE**<br>By default, the drag bar is displayed only when the sheet's **detents** attribute is set to multiple heights and the settings take effect. <br>**Atomic service API**: This API can be used in atomic services since API version 11.| 53| blurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| Background blur of the sheet. By default, there is no background blur.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 54| maskColor | [ResourceColor](ts-types.md#resourcecolor) | No| Mask color of the sheet.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 55| title<sup>11+</sup> | [SheetTitleOptions](#sheettitleoptions11) \| [CustomBuilder](ts-types.md#custombuilder8) | No| Title of the sheet.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 56| enableOutsideInteractive<sup>11+</sup> | boolean | No| Whether to allow users to interact with the page pertaining to the sheet.<br>**NOTE**<br>The value **true** means that interactions are allowed, in which case no mask is not displayed. The value **false** means that interactions are not allowed, in which case a mask is displayed. If this parameter is not set, interactions are allowed for the popup sheet, but not for bottom and center sheets. If this parameter is set to **true**, the setting of **maskColor** does not take effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 57| shouldDismiss<sup>11+</sup> | (sheetDismiss: [SheetDismiss](#sheetdismiss11)) => void | No| Callback invoked when the user performs an interactive dismiss operation: pulling down or clicking the back button, the mask, or the close icon.<br>**NOTE**<br>If this callback is registered, the sheet is not dismissed immediately when the user performs the above operations. To dismiss the sheet, you must call **shouldDismiss.dismiss()** in the callback.<br>If this callback is not registered, the sheet is dismissed immediately when the user performs the above operations, without any additional behavior.<br>It is recommended that this API be used in scenarios where a [secondary confirmation](../../../ui/arkts-sheet-page.md#secondary-confirmation-capability) is required<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 58| onWillDismiss<sup>12+</sup> | [DismissSheetAction](#dismisssheetaction12) | No | Callback invoked when the user performs an interactive dismiss operation: pulling down or clicking the back button, the mask, or the close icon, to obtain the type of dismiss operation and decide whether to dismiss the sheet.<br>**NOTE**<br>If this callback is registered, the sheet is not dismissed immediately when the user performs the above operations. Instead, you can use the [reason](../js-apis-promptAction.md#dismissreason12) parameter in the callback to determine the type of dismiss operation and decide whether to dismiss the sheet.<br>If this callback is not registered, the sheet is dismissed immediately when the user performs the above operations, without any additional behavior.<br>No further interception with **onWillDismiss** is allowed in an **onWillDismiss** callback.<br>It is recommended that this API be used in scenarios where a [secondary confirmation](../../../ui/arkts-sheet-page.md#secondary-confirmation-capability) is required<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 59| onWillSpringBackWhenDismiss<sup>12+</sup> | [SpringBackAction](#springbackaction12) | No | Callback invoked when the user performs a pull-down-to-dismiss gesture, to control the bounce effect.<br>**NOTE**<br>If this callback is registered along with **shouldDismiss** or **onWillDismiss**, you can control whether the sheet bounces back during the pull-down-to-dismiss operation by calling **springBack** in the callback.<br>If this callback is not registered but **shouldDismiss** or **onWillDismiss** is registered, the sheet will bounce back before remaining open or being dismissed based on the callback behavior.<br>If neither this callback nor **shouldDismiss** or **onWillDismiss** is registered, the sheet is dismissed by default during the pull-down-to-dismiss operation.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 60| onHeightDidChange<sup>12+</sup> | Callback<number> | No| Callback for changes in the height of the sheet.<br>**NOTE**<br>For a bottom sheet, the height of each frame is only returned when there are changes in detents or during drag actions. When the sheet is pulled up or making space for the soft keyboard, only the final height is returned. For other types of sheets, the final height is only returned when the sheet is pulled up.<br>The return value is in px.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 61| onDetentsDidChange<sup>12+</sup> | Callback<number> | No| Callback for changes in the detents of the sheet.<br>**NOTE**<br>For a bottom sheet, the final height is returned when there are changes in detents.<br>The return value is in px.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 62| onWidthDidChange<sup>12+</sup> | Callback<number> | No| Callback for changes in the width of the sheet.<br>**NOTE**<br>The final height is returned when there are changes in the width.<br>The return value is in px.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 63| onTypeDidChange<sup>12+</sup> | Callback<[SheetType](#sheettype11)>| No| Callback for changes in the type of the sheet.<br>**NOTE**<br>The final type is returned when there are changes in the type.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 64| borderWidth<sup>12+</sup> | [Dimension](ts-types.md#dimension10) \| [EdgeWidths](ts-types.md#edgewidths9) \| [LocalizedEdgeWidths](ts-types.md#localizededgewidths12)<sup>12+</sup> | No| Border width of the sheet.<br>You can set the width for all four sides or set separate widths for individual sides.<br>Default value: **0**<br> Percentage parameter method: Set the border width of the sheet as a percentage of the width of the parent element.<br>If the left and right border widths of the sheet are greater than the width of the sheet, and the top and bottom border widths are greater than the height of the sheet, the display may not appear as expected.<br>**NOTE**<br>For bottom sheets, the bottom border width setting is ineffective.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 65| borderColor<sup>12+</sup> | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](ts-types.md#edgecolors9) \| [LocalizedEdgeColors](ts-types.md#localizededgecolors12)<sup>12+</sup> | No| Border color of the sheet.<br>Default value: **Color.Black**<br> **borderColor** must be used with **borderWidth** in pairs.<br>**NOTE**<br>For bottom sheets, the bottom border color setting is ineffective.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 66| borderStyle<sup>12+</sup> | [BorderStyle](ts-appendix-enums.md#borderstyle) \| [EdgeStyles](ts-types.md#edgestyles9) | No| Border style of the sheet.<br>Default value: **BorderStyle.Solid**<br>**borderStyle** must be used with **borderWidth** in pairs.<br>**NOTE**<br>For bottom sheets, the bottom border style setting is ineffective.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 67| width<sup>12+</sup> | [Dimension](ts-types.md#dimension10) | No| Width of the sheet.<br> Percentage parameter method: Set the width of the sheet as a percentage of the width of the parent element. <br>**Atomic service API**: This API can be used in atomic services since API version 12.| 68| shadow<sup>12+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) | No| Shadow of the sheet.<br>Default value for 2-in-1 devices: **ShadowStyle.OUTER_FLOATING_SM**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 69| uiContext<sup>12+</sup> | [UIContext](../js-apis-arkui-UIContext.md#uicontext) | No| **UIContext** instance corresponding to the window where the sheet is displayed.<br>**NOTE**<br>The sheet launched with [openBindSheet](../js-apis-arkui-UIContext.md#openbindsheet12) does not support setting or updating this attribute.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 70| mode<sup>12+</sup> | [SheetMode](#sheetmode12) | No| Display mode of the sheet.<br>Default value: **SheetMode.OVERLAY**<br>**NOTE**<br> 1. During the display of the sheet, the **mode** attribute does not support dynamic changes. The display hierarchy of the two modes is entirely different, making it impossible to switch a sheet from one mode to another while it is being displayed. You are advised to clearly define and fix the **mode** value to ensure consistency in the display hierarchy.<br> 2. The **UIContext** attribute cannot be set when **SheetMode.EMBEDDED** is set, as their corresponding sheet display hierarchy effects are mutually conflicting.<br>3. For a sheet launched with [openBindSheet](../js-apis-arkui-UIContext.md#openbindsheet12), if a valid target ID is not provided, **SheetMode.EMBEDDED** cannot be set, and the default value **SheetMode.OVERLAY** is used.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 71| scrollSizeMode<sup>12+</sup> | [ScrollSizeMode](#scrollsizemode12) | No| Content update mode of the sheet when it is scrolled.<br>Default value: **ScrollSizeMode.FOLLOW_DETENT**| 72| keyboardAvoidMode<sup>13+</sup> | [SheetKeyboardAvoidMode](#sheetkeyboardavoidmode13) | No| How the sheet avoids the soft keyboard when it is brought up.<br> Default value: **TRANSLATE_AND_SCROLL**<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 73| enableHoverMode<sup>14+</sup> | boolean | No | Whether to enable the hover mode.<br>Default value: **false**, meaning not to enable the hover mode.<br>**NOTE**<br>The bottom and popup sheets do not respond in the hover mode.| 74| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](ts-appendix-enums.md#hovermodeareatype14) | No | Display area of the dialog box in hover mode.<br>Default value: **HoverModeAreaType.BOTTOM_SCREEN**| 75| radius<sup>15+</sup> | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) \| [BorderRadiuses](ts-types.md#borderradiuses9) \| [LocalizedBorderRadiuses](ts-types.md#LocalizedBorderRadiuses12) | No| Corner radius of the sheet.<br>To deliver the optimal experience, use the same radius for the four corners.<br>Default value: **32vp**<br>**NOTE**<br>1. The corner radius is displayed based on the set value. If it is not set, the default value is used. The bottom sheet does not display the bottom two corners, even if they are set.<br>2. If different corner radii are set for the four corners and one of the values is invalid, the corner pertaining to the invalid value is reset to the default value, while the other corners retain their set values. If a uniform corner radius is set for all four corners and the value is invalid, all four corners are reset to the default value.<br>3. When the corner radius is set as a percentage, the width of the sheet is used as the reference.<br>4. If the corner radius is greater than half the width of the sheet, it is set to half the width of the sheet.<br>5. If the height of the sheet is too small and the corner radius is set too large, it may cause display issues.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 76| detentSelection<sup>15+</sup> <br>| [SheetSize](#sheetsize) \| [Length](ts-types.md#length) | No | Initial detent (position) for non-gesture switching.<br>Default value: **detents[0]**<br>**NOTE**<br>1. The value must be within the range of the **detents** array. If the value is outside this range, this API has no effect.<br>2. When **SheetSize.FIT_CONTENT** is used, this API has no effect.<br>3. Avoid calling this API when gesture-based detent switching is used.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 77| placement<sup>18+</sup> | [Placement](ts-appendix-enums.md#placement8) | No| Display position of the sheet popup relative to the target.<br>Default value: **Placement.Bottom**<br>**NOTE**<br> 1. The system attempts to display the popup at the specified position if the popup fits within the window. If this is not feasible, it tries vertical flipping first, followed by a 90-degree horizontal rotation.<br>2. If the alignment causes the popup to exceed the window bounds, it will be adjusted horizontally or vertically until fully visible.<br>3. If none of the four directions can accommodate the popup, the behavior depends on the value of the **placementOnTarget** property:<br>(1) If the property value is **true**, the popup moves in the mirror direction of the specified placement until fully visible.<br>(2) If the property value is **false**, the system selects the direction that can fully display the popup width and has the most remaining height. It then adjusts the sheet height to fit this direction, ensuring that the popup is displayed while maintaining the alignment specified by the **placement** setting.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 78| placementOnTarget<sup>18+</sup> | Boolean | No| Whether the sheet popup can overlap the target if none of the four directions can accommodate the popup.<br> Default value: **true**<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 79| effectEdge<sup>18+</sup> | number | No| Edge effect used when the boundary of the scrolling area in reached in the sheet. Single-edge activation is supported.<br>Default value: [EffectEdge](ts-container-scrollable-common.md#effectedge18).START \| [EffectEdge](ts-container-scrollable-common.md#effectedge18).END (that is, value **3**)<br>**NOTE**<br>1. Only start edge: [EffectEdge](ts-container-scrollable-common.md#effectedge18).START<br>2. Only end edge: [EffectEdge](ts-container-scrollable-common.md#effectedge18).END<br>3. Both edges: [EffectEdge](ts-container-scrollable-common.md#effectedge18).START \| [EffectEdge](ts-container-scrollable-common.md#effectedge18).END (that is, value **3**)<br>4. Neither edge: [EffectEdge](ts-container-scrollable-common.md#effectedge18).START & [EffectEdge](ts-container-scrollable-common.md#effectedge18).END (that is, value **0**)<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 80| showInSubWindow<sup>18+</sup> | boolean | No | Whether to show the sheet in a subwindow.<br>Default value: **false**, meaning the sheet is displayed within the application, not in a separate subwindow<br>**NOTE**<br>1. A dialog box whose **showInSubWindow** attribute is **true** cannot trigger the display of another dialog box whose **showInSubWindow** attribute is also **true**.<br>2. Avoid using picker components (such as **CalendarPicker**, **CalendarPickerDialog**, **DatePickerDialog**, **TextPickerDialog**, and **TimePickerDialog**) in the dialog box where **showInSubWindow** is set to **true**, as the dialog box may affect the behavior of these components.<br>3. This property cannot be dynamically changed when the sheet is displayed.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 81 82## SheetSize 83 84Enumerates the sheet heights. 85 86| Name | Value | Description | 87| ------------------------- | ---- | -------------------------------- | 88| MEDIUM | 0 | The sheet height is half of the screen height.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 89| LARGE | 1 | The sheet height is almost the screen height.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 90| FIT_CONTENT<sup>11+</sup> | 2 | The sheet height automatically adapts to the content.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 91 92## BindOptions 93 94Defines the common configuration for sheets and modals. 95 96| Name | Type | Mandatory| Description | 97| --------------- | ------------------------------------------ | ---- | ------------------------ | 98| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the sheet.<br>Default value: **Color.White**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 99| onWillAppear<sup>12+</sup> | () => void | No | Callback for when the sheet is about to be displayed (before the animation starts). **Atomic service API**: This API can be used in atomic services since API version 12.| 100| onAppear | () => void | No | Callback for when the sheet is displayed (after the animation ends).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 101| onWillDisappear<sup>12+</sup> | () => void | No | Callback for when the sheet is about to disappear (before the animation starts).<br>**NOTE**<br>Modifying state variables within the **onWillDisappear** function is not allowed, as it may lead to unstable component behavior. **Atomic service API**: This API can be used in atomic services since API version 12.| 102| onDisappear | () => void | No | Callback for when the sheet disappears (after the animation ends).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 103 104## SheetType<sup>11+</sup> 105 106Enumerates the sheet styles. 107 108**Atomic service API**: This API can be used in atomic services since API version 12. 109 110| Name | Value | Description | 111| ------ | ---- | ------------------------------------------------------ | 112| BOTTOM | 0 | Bottom sheet. | 113| CENTER | 1 | Center sheet. | 114| POPUP | 2 | Popup sheet. The popup sheet cannot be dismissed with a pull-down gesture.| 115 116## SheetDismiss<sup>11+</sup> 117 118Controls the dismissal of a sheet. 119 120**Atomic service API**: This API can be used in atomic services since API version 12. 121 122| Name | Type | Mandatory| Description | 123| ------- | ---------- | ---- | ------------------------------------------------------------ | 124| dismiss | () => void | Yes | Callback for dismissing the sheet. Call this API only when you need the sheet to exit.| 125 126## SheetTitleOptions<sup>11+</sup> 127 128Provides the options for configuring the title of a sheet. 129 130**Atomic service API**: This API can be used in atomic services since API version 12. 131 132| Name | Type | Mandatory| Description | 133| -------- | -------------------------------------- | ---- | -------------------- | 134| title | [ResourceStr](ts-types.md#resourcestr) | Yes | Main title of the sheet.| 135| subtitle | [ResourceStr](ts-types.md#resourcestr) | No | Subtitle of the sheet.| 136 137## SheetMode<sup>12+</sup> 138 139Enumerates the display layer modes of a sheet. 140 141**Atomic service API**: This API can be used in atomic services since API version 12. 142 143| Name | Value | Description | 144| ------------------------- | ---- | -------------------------------- | 145| OVERLAY | 0 | The sheet is displayed at the top of the window corresponding to the current **UIContext** instance, above all pages. It is displayed at the same level as dialog boxes. | 146| EMBEDDED | 1 | The sheet is displayed at the top of the current page.<br>**NOTE**<br>Currently, the sheet can only be mounted on a **Page** or **NavDestination** node, with priority given to the **NavDestination** node if it is present. This means that, the sheet can only be displayed at the top of these two types of pages.<br> In this mode, new pages can overlay the sheet, and when the user returns to the previous page, the sheet remains present without losing its content.<br> In this mode, you must ensure that the target page node, such as the **Page** node, has been attached to the tree before bringing up the sheet; otherwise, the sheet will not be able to be attached to the corresponding page node.| 147 148## ScrollSizeMode<sup>12+</sup> 149 150Enumerates the content update modes of a sheet when it is scrolled vertically. 151 152| Name | Value | Description | 153| ------------------------- | ---- | -------------------------------- | 154| FOLLOW_DETENT | 0 | The sheet updates the content display area after a swipe ends. | 155| CONTINUOUS | 1 | The sheet continuously updates the content display area during the scroll process.| 156 157## DismissSheetAction<sup>12+</sup> 158 159Defines the callback triggered when a sheet is about to be dismissed. 160 161**Atomic service API**: This API can be used in atomic services since API version 12. 162 163| Name | Type | Mandatory | Description | 164| --------------- | ---------------------------------------- | ---- | ------------- | 165| dismiss | function | Yes | Callback for dismissing the sheet. Call this API when you need to exit the page.| 166| reason | [DismissReason](../js-apis-promptAction.md#dismissreason12) | Yes | Type of operation that causes the sheet to be dismissed. | 167 168## SpringBackAction<sup>12+</sup> 169 170Controls the interactive spring back of a sheet before it is dismissed. 171 172| Name | Type | Mandatory | Description | 173| --------------- | ---------------------------------------- | ---- | ------------- | 174| springBack | function | Yes | Callback to control the interactive spring back before the sheet is dismissed. | 175 176## SheetKeyboardAvoidMode<sup>13+</sup> 177 178| Name | Value | Description | 179| ------------------------- | ---- | -------------------------------- | 180| NONE | 0 | Disables keyboard avoidance for the sheet. | 181| TRANSLATE_AND_RESIZE | 1 | Lifts the sheet to avoid the keyboard;<br>if not enough, resizes the content.| 182| RESIZE_ONLY | 2 | Resizes the content to avoid the keyboard.| 183| TRANSLATE_AND_SCROLL | 3 | Lifts the sheet to avoid the keyboard;<br>if not enough, scrolls the content.| 184 185## Example 186### Example 1: Setting Sheets with Different Heights 187 188This example demonstrates how to set different heights for sheets using the **height** property. 189 190```ts 191// xxx.ets 192@Entry 193@Component 194struct SheetTransitionExample { 195 @State isShow: boolean = false 196 @State sheetHeight: number = 300; 197 198 @Builder 199 myBuilder() { 200 Column() { 201 Button("change height") 202 .margin(10) 203 .fontSize(20) 204 .onClick(() => { 205 this.sheetHeight = 500; 206 }) 207 208 Button("Set Illegal height") 209 .margin(10) 210 .fontSize(20) 211 .onClick(() => { 212 this.sheetHeight = -1; 213 }) 214 215 Button("close modal 1") 216 .margin(10) 217 .fontSize(20) 218 .onClick(() => { 219 this.isShow = false; 220 }) 221 } 222 .width('100%') 223 .height('100%') 224 } 225 226 build() { 227 Column() { 228 Button("transition modal 1") 229 .onClick(() => { 230 this.isShow = true 231 }) 232 .fontSize(20) 233 .margin(10) 234 .bindSheet($$this.isShow, this.myBuilder(), { 235 height: this.sheetHeight, 236 backgroundColor: Color.Green, 237 onWillAppear: () => { 238 console.log("BindSheet onWillAppear.") 239 }, 240 onAppear: () => { 241 console.log("BindSheet onAppear.") 242 }, 243 onWillDisappear: () => { 244 console.log("BindSheet onWillDisappear.") 245 }, 246 onDisappear: () => { 247 console.log("BindSheet onDisappear.") 248 } 249 }) 250 } 251 .justifyContent(FlexAlign.Center) 252 .width('100%') 253 .height('100%') 254 } 255} 256``` 257 258 259 260### Example 2: Setting Three Different Height Detents 261 262This example demonstrates how to use the **detents** property of **bindSheet** to set three different height detents for a sheet. 2631. The drag bar is only effective when there are multiple height detents. 2642. Unlike the **height** property, which can set different heights at different times, the **detents** property provides a gesture to switch between detent heights and is more suitable for fixed height intervals. 2653. If the height range is uncertain or there may be more than three different heights, avoid using the **detents** property. 266 267```ts 268// xxx.ets 269@Entry 270@Component 271struct SheetTransitionExample { 272 @State isShow: boolean = false 273 274 @Builder 275 myBuilder() { 276 Column() { 277 Button("content1") 278 .margin(10) 279 .fontSize(20) 280 281 Button("content2") 282 .margin(10) 283 .fontSize(20) 284 } 285 .width('100%') 286 } 287 288 build() { 289 Column() { 290 Button("transition modal 1") 291 .onClick(() => { 292 this.isShow = true 293 }) 294 .fontSize(20) 295 .margin(10) 296 .bindSheet($$this.isShow, this.myBuilder(), { 297 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 298 backgroundColor: Color.Gray, 299 blurStyle: BlurStyle.Thick, 300 showClose: true, 301 title: { title: "title", subtitle: "subtitle" }, 302 }) 303 } 304 .justifyContent(FlexAlign.Start) 305 .width('100%') 306 .height('100%') 307 } 308} 309``` 310 311 312 313### Example 3: Setting the Border Width and Color 314 315This example demonstrates how to use the **borderWidth** and **borderColor** properties with **LocalizedEdgeWidths** and **LocalizedEdgeColors** types in **bindSheet**. 316 317```ts 318// xxx.ets 319import { LengthMetrics } from '@kit.ArkUI' 320 321@Entry 322@Component 323struct SheetTransitionExample { 324 @State isShow: boolean = false 325 326 @Builder 327 myBuilder() { 328 Column() { 329 Button("content1") 330 .margin(10) 331 .fontSize(20) 332 333 Button("content2") 334 .margin(10) 335 .fontSize(20) 336 } 337 .width('100%') 338 } 339 340 build() { 341 Column() { 342 Button("transition modal 1") 343 .onClick(() => { 344 this.isShow = true 345 }) 346 .fontSize(20) 347 .margin(10) 348 .bindSheet($$this.isShow, this.myBuilder(), { 349 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 350 backgroundColor: Color.Gray, 351 blurStyle: BlurStyle.Thick, 352 showClose: true, 353 title: { title: "title", subtitle: "subtitle" }, 354 borderWidth: { top: LengthMetrics.vp(10), start: LengthMetrics.vp(10), end: LengthMetrics.vp(20) }, 355 borderColor: { top: Color.Pink, start: Color.Blue, end: Color.Yellow }, 356 }) 357 } 358 .justifyContent(FlexAlign.Start) 359 .width('100%') 360 .height('100%') 361 } 362} 363``` 364 365The following shows how the example is represented with left-to-right scripts. 366 367 368 369The following shows how the example is represented with right-to-left scripts. 370 371 372 373### Example 4: Using Dismiss Callbacks 374 375This example shows how to register **onWillDismiss** and **onWillSpringBackWhenDismiss** with **bindSheet**. 376 377```ts 378// xxx.ets 379@Entry 380@Component 381struct bindSheetExample { 382 @State isShow: Boolean = false; 383 384 @Builder 385 myBuilder() { 386 Column() { 387 Button() { 388 Text("CONTEXT") 389 }.height(50) 390 } 391 } 392 393 build() { 394 Column() { 395 Button("NoRegisterSpringback") 396 .onClick(() => { 397 this.isShow = true 398 }) 399 .fontSize(20) 400 .margin(10) 401 .bindSheet($$this.isShow, this.myBuilder(), { 402 height: SheetSize.MEDIUM, 403 blurStyle: BlurStyle.Thick, 404 showClose: true, 405 title: { title: "title", subtitle: "subtitle" }, 406 preferType: SheetType.CENTER, 407 408 409 onWillDismiss: ((DismissSheetAction: DismissSheetAction) => { 410 if (DismissSheetAction.reason == DismissReason.SLIDE_DOWN) { 411 DismissSheetAction.dismiss() // Register the dismiss behavior. 412 } 413 }), 414 415 onWillSpringBackWhenDismiss: ((SpringBackAction: SpringBackAction) => { 416 // If springBack is not registered, the sheet will not exhibit a spring back effect when pulled down. 417 //SpringBackAction.springBack() 418 }), 419 }) 420 } 421 } 422} 423``` 424 425 426### Example 5: Setting the Content Update Mode 427 428This example shows how to use **ScrollSizeMode.CONTINUOUS**, which continuously updates the content and is suitable for detents with multiple height settings. 429Whenever possible, minimize UI loading time within the builder, as real-time content refreshing during scrolling has higher performance requirements. 430 431```ts 432// xxx.ets 433@Entry 434@Component 435struct Index { 436 @State isShow: boolean = false; 437 438 @Builder 439 myBuilder() { 440 Column() { 441 Column() 442 .backgroundColor(Color.Blue) 443 .height(200) 444 .width('100%') 445 Column() 446 .backgroundColor(Color.Green) 447 .height(200) 448 .width('100%') 449 } 450 } 451 452 build() { 453 Column() { 454 Button('BindSheet') 455 .onClick(() => { 456 this.isShow = true; 457 }) 458 .bindSheet($$this.isShow, this.myBuilder(), { 459 detents: [300, 600, 900], 460 uiContext: this.getUIContext(), 461 mode: SheetMode.OVERLAY, 462 scrollSizeMode: ScrollSizeMode.CONTINUOUS, 463 backgroundColor: Color.Orange, 464 title: { title: 'Title', subtitle: 'Subtitle' } 465 }) 466 } 467 .justifyContent(FlexAlign.Center) 468 .width('100%') 469 .height('100%') 470 } 471} 472``` 473The sheet's content height is not updated until the user stops dragging and releases the sheet. 474 475 476 477The sheet's content height is updated in real time as the user drags the sheet. 478 479 480 481### Example 6: Configuring the Sheet to Resize to Avoid the Keyboard 482 483This example demonstrates how to adjust the scrollable content within a sheet when the keyboard height changes by setting **SheetKeyboardAvoidMode** to **RESIZE_ONLY**. 484 485```ts 486//xxx.ets 487import window from '@ohos.window'; 488import { BusinessError } from '@ohos.base'; 489 490@Entry 491@Component 492struct ListenKeyboardHeightChange { 493 @State isShow: boolean = false; 494 @State avoidMode: SheetKeyboardAvoidMode = SheetKeyboardAvoidMode.RESIZE_ONLY; 495 scroller = new Scroller(); 496 private arr: number[] = [0, 1, 2, 3, 4, 5, 6]; 497 windowClass: window.Window | undefined = undefined; 498 499 aboutToAppear(): void { 500 try { 501 window.getLastWindow(getContext(this), (err: BusinessError, data) => { 502 const errCode: number = err.code; 503 if (errCode) { 504 console.error(`Failed to obtain the top window, Cause code: ${err.code}, message: ${err.message}`); 505 return; 506 } 507 this.windowClass = data; 508 try { 509 if (this.windowClass !== undefined) { 510 console.log('success in listen height change'); 511 this.windowClass.on('keyboardHeightChange', this.callback); 512 } 513 } catch (exception) { 514 console.error(`Failed to enable the listener for keyboard height changes, Cause code: ${exception.code}, message: ${exception.message}`); 515 } 516 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 517 }); 518 } catch (exception) { 519 console.error(`Failed to obtain the top window, Cause code: ${exception.code}, message: ${exception.message}`); 520 } 521 } 522 523 callback = (height: number) => { 524 console.log('height change: ' + height); 525 if (height !== 0) { 526 this.scroller.scrollTo({ 527 xOffset: 0, yOffset: height + this.scroller.currentOffset().yOffset, 528 animation: { duration: 1000, curve: Curve.Ease, canOverScroll: false } 529 }); 530 } 531 } 532 533 @Builder 534 myBuilder() { 535 Scroll(this.scroller) { 536 Column() { 537 ForEach(this.arr, (item: number) => { 538 Row() { 539 Text(item.toString()) 540 .width('80%') 541 .height(60) 542 .backgroundColor('#3366CC') 543 .borderRadius(15) 544 .fontSize(16) 545 .textAlign(TextAlign.Center) 546 .margin({ top: 5 }) 547 } 548 }, (item: number) => item.toString()) 549 550 TextInput().height('100') 551 552 Flex({ alignItems: ItemAlign.End }) { 553 Row() { 554 Button("click") 555 .margin(10) 556 .fontSize(20) 557 .width('45%') 558 559 Button("cancel") 560 .margin(10) 561 .fontSize(20) 562 .width('45%') 563 }.width('100%') 564 }.height(100) 565 }.margin({ right: 15, bottom: 50 }) 566 } 567 .height('100%') 568 .scrollBar(BarState.On) 569 .scrollable(ScrollDirection.Vertical) 570 } 571 572 build() { 573 Column() { 574 Button("transition modal 1") 575 .onClick(() => { 576 this.isShow = true 577 }) 578 .fontSize(20) 579 .margin(10) 580 .bindSheet($$this.isShow, this.myBuilder(), { 581 height: 750, 582 backgroundColor: Color.Gray, 583 blurStyle: BlurStyle.Thick, 584 showClose: true, 585 title: { title: "title", subtitle: "subtitle" }, 586 keyboardAvoidMode: SheetKeyboardAvoidMode.RESIZE_ONLY, 587 }) 588 } 589 .justifyContent(FlexAlign.Start) 590 .width('100%') 591 .height('100%') 592 } 593} 594``` 595 596 597### Example 7: Setting the Corner Radius in a Mirrored Layout 598 599This example demonstrates how to set different corner radii for a sheet in a mirrored layout. Typically, to avoid a poor visual experience, do not set different values. 600 601In this example, the **radius** property of the sheet uses the LocalizedBorderRadiuses type. 602 603```ts 604import { LengthMetrics } from '@kit.ArkUI'; 605 606@Entry 607@Component 608struct SheetTransitionExample { 609 @State isShow: boolean = false 610 611 @Builder 612 myBuilder() { 613 Column() { 614 Button("content1") 615 .margin(10) 616 .fontSize(20) 617 618 Button("content2") 619 .margin(10) 620 .fontSize(20) 621 } 622 .width('100%') 623 } 624 625 build() { 626 Column() { 627 Button("transition modal 1") 628 .onClick(() => { 629 this.isShow = true 630 }) 631 .fontSize(20) 632 .margin(10) 633 .bindSheet($$this.isShow, this.myBuilder(), { 634 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 635 title: { title: "title", subtitle: "subtitle" }, 636 radius: { topStart: LengthMetrics.vp(50), topEnd: LengthMetrics.vp(10) }, 637 }) 638 } 639 .justifyContent(FlexAlign.Start) 640 .width('100%') 641 .height('100%') 642 } 643} 644``` 645 646The following shows how the example is represented with left-to-right scripts. 647 648 649 650The following shows how the example is represented with right-to-left scripts. 651 652 653<!--no_check-->
