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).| 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). 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> | [SheetSize](#sheetsize) \| [Length](ts-types.md#length) | No | Initial detent (position) for non-gesture switching.<br>Default value: **detents[0]**<br>**NOTE**<br>This API has no effect when **SheetSize.FIT_CONTENT** is used.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 77 78## SheetSize 79 80Enumerates the sheet heights. 81 82| Name | Value | Description | 83| ------------------------- | ---- | -------------------------------- | 84| 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. | 85| 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. | 86| 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.| 87 88## BindOptions 89 90Defines the common configuration for sheets and modals. 91 92| Name | Type | Mandatory| Description | 93| --------------- | ------------------------------------------ | ---- | ------------------------ | 94| 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.| 95| 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.| 96| 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.| 97| 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.| 98| 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.| 99 100## SheetType<sup>11+</sup> 101 102Enumerates the sheet styles. 103 104**Atomic service API**: This API can be used in atomic services since API version 12. 105 106| Name | Value | Description | 107| ------ | ---- | ------------------------------------------------------ | 108| BOTTOM | 0 | Bottom sheet. | 109| CENTER | 1 | Center sheet. | 110| POPUP | 2 | Popup sheet. The popup sheet cannot be dismissed with a pull-down gesture.| 111 112## SheetDismiss<sup>11+</sup> 113 114Controls the dismissal of a sheet. 115 116**Atomic service API**: This API can be used in atomic services since API version 12. 117 118| Name | Type | Mandatory| Description | 119| ------- | ---------- | ---- | ------------------------------------------------------------ | 120| dismiss | () => void | Yes | Callback for dismissing the sheet. Call this API only when you need the sheet to exit.| 121 122## SheetTitleOptions<sup>11+</sup> 123 124Provides the options for configuring the title of a sheet. 125 126**Atomic service API**: This API can be used in atomic services since API version 12. 127 128| Name | Type | Mandatory| Description | 129| -------- | -------------------------------------- | ---- | -------------------- | 130| title | [ResourceStr](ts-types.md#resourcestr) | Yes | Main title of the sheet.| 131| subtitle | [ResourceStr](ts-types.md#resourcestr) | No | Subtitle of the sheet.| 132 133## SheetMode<sup>12+</sup> 134 135Enumerates the display layer modes of a sheet. 136 137**Atomic service API**: This API can be used in atomic services since API version 12. 138 139| Name | Value | Description | 140| ------------------------- | ---- | -------------------------------- | 141| 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. | 142| 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.| 143 144## ScrollSizeMode<sup>12+</sup> 145 146Enumerates the content update modes of a sheet when it is scrolled vertically. 147 148| Name | Value | Description | 149| ------------------------- | ---- | -------------------------------- | 150| FOLLOW_DETENT | 0 | The sheet updates the content display area after a swipe ends. | 151| CONTINUOUS | 1 | The sheet continuously updates the content display area during the scroll process.| 152 153## DismissSheetAction<sup>12+</sup> 154 155Defines the callback triggered when a sheet is about to be dismissed. 156 157**Atomic service API**: This API can be used in atomic services since API version 12. 158 159| Name | Type | Mandatory | Description | 160| --------------- | ---------------------------------------- | ---- | ------------- | 161| dismiss | function | Yes | Callback for dismissing the sheet. Call this API when you need to exit the page.| 162| reason | [DismissReason](../js-apis-promptAction.md#dismissreason12) | Yes | Type of operation that causes the sheet to be dismissed. | 163 164## SpringBackAction<sup>12+</sup> 165 166Controls the interactive spring back of a sheet before it is dismissed. 167 168| Name | Type | Mandatory | Description | 169| --------------- | ---------------------------------------- | ---- | ------------- | 170| springBack | function | Yes | Callback to control the interactive spring back before the sheet is dismissed. | 171 172## SheetKeyboardAvoidMode<sup>13+</sup> 173 174| Name | Value | Description | 175| ------------------------- | ---- | -------------------------------- | 176| NONE | 0 | Disables keyboard avoidance for the sheet. | 177| TRANSLATE_AND_RESIZE | 1 | Lifts the sheet to avoid the keyboard;<br>if not enough, resizes the content.| 178| RESIZE_ONLY | 2 | Resizes the content to avoid the keyboard.| 179| TRANSLATE_AND_SCROLL | 3 | Lifts the sheet to avoid the keyboard;<br>if not enough, scrolls the content.| 180 181## Example 182### Example 1: Setting Sheets with Different Heights 183 184This example demonstrates how to set different heights for sheets using the **height** property. 185 186```ts 187// xxx.ets 188@Entry 189@Component 190struct SheetTransitionExample { 191 @State isShow: boolean = false 192 @State sheetHeight: number = 300; 193 194 @Builder 195 myBuilder() { 196 Column() { 197 Button("change height") 198 .margin(10) 199 .fontSize(20) 200 .onClick(() => { 201 this.sheetHeight = 500; 202 }) 203 204 Button("Set Illegal height") 205 .margin(10) 206 .fontSize(20) 207 .onClick(() => { 208 this.sheetHeight = -1; 209 }) 210 211 Button("close modal 1") 212 .margin(10) 213 .fontSize(20) 214 .onClick(() => { 215 this.isShow = false; 216 }) 217 } 218 .width('100%') 219 .height('100%') 220 } 221 222 build() { 223 Column() { 224 Button("transition modal 1") 225 .onClick(() => { 226 this.isShow = true 227 }) 228 .fontSize(20) 229 .margin(10) 230 .bindSheet($$this.isShow, this.myBuilder(), { 231 height: this.sheetHeight, 232 backgroundColor: Color.Green, 233 onWillAppear: () => { 234 console.log("BindSheet onWillAppear.") 235 }, 236 onAppear: () => { 237 console.log("BindSheet onAppear.") 238 }, 239 onWillDisappear: () => { 240 console.log("BindSheet onWillDisappear.") 241 }, 242 onDisappear: () => { 243 console.log("BindSheet onDisappear.") 244 } 245 }) 246 } 247 .justifyContent(FlexAlign.Center) 248 .width('100%') 249 .height('100%') 250 } 251} 252``` 253 254 255 256### Example 2: Setting Three Different Height Detents 257 258This example demonstrates how to use the **detents** property of **bindSheet** to set three different height detents for a sheet. 2591. The drag bar is only effective when there are multiple height detents. 2602. 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. 2613. If the height range is uncertain or there may be more than three different heights, avoid using the **detents** property. 262 263```ts 264// xxx.ets 265@Entry 266@Component 267struct SheetTransitionExample { 268 @State isShow: boolean = false 269 270 @Builder 271 myBuilder() { 272 Column() { 273 Button("content1") 274 .margin(10) 275 .fontSize(20) 276 277 Button("content2") 278 .margin(10) 279 .fontSize(20) 280 } 281 .width('100%') 282 } 283 284 build() { 285 Column() { 286 Button("transition modal 1") 287 .onClick(() => { 288 this.isShow = true 289 }) 290 .fontSize(20) 291 .margin(10) 292 .bindSheet($$this.isShow, this.myBuilder(), { 293 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 294 backgroundColor: Color.Gray, 295 blurStyle: BlurStyle.Thick, 296 showClose: true, 297 title: { title: "title", subtitle: "subtitle" }, 298 }) 299 } 300 .justifyContent(FlexAlign.Start) 301 .width('100%') 302 .height('100%') 303 } 304} 305``` 306 307 308 309### Example 3: Setting the Border Width and Color 310 311This example demonstrates how to use the **borderWidth** and **borderColor** properties with **LocalizedEdgeWidths** and **LocalizedEdgeColors** types in **bindSheet**. 312 313```ts 314// xxx.ets 315import { LengthMetrics } from '@kit.ArkUI' 316 317@Entry 318@Component 319struct SheetTransitionExample { 320 @State isShow: boolean = false 321 322 @Builder 323 myBuilder() { 324 Column() { 325 Button("content1") 326 .margin(10) 327 .fontSize(20) 328 329 Button("content2") 330 .margin(10) 331 .fontSize(20) 332 } 333 .width('100%') 334 } 335 336 build() { 337 Column() { 338 Button("transition modal 1") 339 .onClick(() => { 340 this.isShow = true 341 }) 342 .fontSize(20) 343 .margin(10) 344 .bindSheet($$this.isShow, this.myBuilder(), { 345 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 346 backgroundColor: Color.Gray, 347 blurStyle: BlurStyle.Thick, 348 showClose: true, 349 title: { title: "title", subtitle: "subtitle" }, 350 borderWidth: { top: LengthMetrics.vp(10), start: LengthMetrics.vp(10), end: LengthMetrics.vp(20) }, 351 borderColor: { top: Color.Pink, start: Color.Blue, end: Color.Yellow }, 352 }) 353 } 354 .justifyContent(FlexAlign.Start) 355 .width('100%') 356 .height('100%') 357 } 358} 359``` 360 361The following shows how the example is represented with left-to-right scripts. 362 363 364 365The following shows how the example is represented with right-to-left scripts. 366 367 368 369### Example 4: Using Dismiss Callbacks 370 371This example shows how to register **onWillDismiss** and **onWillSpringBackWhenDismiss** with **bindSheet**. 372 373```ts 374// xxx.ets 375@Entry 376@Component 377struct bindSheetExample { 378 @State isShow: Boolean = false; 379 380 @Builder 381 myBuilder() { 382 Column() { 383 Button() { 384 Text("CONTEXT") 385 }.height(50) 386 } 387 } 388 389 build() { 390 Column() { 391 Button("NoRegisterSpringback") 392 .onClick(() => { 393 this.isShow = true 394 }) 395 .fontSize(20) 396 .margin(10) 397 .bindSheet($$this.isShow, this.myBuilder(), { 398 height: SheetSize.MEDIUM, 399 blurStyle: BlurStyle.Thick, 400 showClose: true, 401 title: { title: "title", subtitle: "subtitle" }, 402 preferType: SheetType.CENTER, 403 404 405 onWillDismiss: ((DismissSheetAction: DismissSheetAction) => { 406 if (DismissSheetAction.reason == DismissReason.SLIDE_DOWN) { 407 DismissSheetAction.dismiss() // Register the dismiss behavior. 408 } 409 }), 410 411 onWillSpringBackWhenDismiss: ((SpringBackAction: SpringBackAction) => { 412 // If springBack is not registered, the sheet will not exhibit a spring back effect when pulled down. 413 //SpringBackAction.springBack() 414 }), 415 }) 416 } 417 } 418} 419``` 420 421 422### Example 5: Setting the Content Update Mode 423 424This example shows how to use **ScrollSizeMode.CONTINUOUS**, which continuously updates the content and is suitable for detents with multiple height settings. 425Whenever possible, minimize UI loading time within the builder, as real-time content refreshing during scrolling has higher performance requirements. 426 427```ts 428// xxx.ets 429@Entry 430@Component 431struct Index { 432 @State isShow: boolean = false; 433 434 @Builder 435 myBuilder() { 436 Column() { 437 Column() 438 .backgroundColor(Color.Blue) 439 .height(200) 440 .width('100%') 441 Column() 442 .backgroundColor(Color.Green) 443 .height(200) 444 .width('100%') 445 } 446 } 447 448 build() { 449 Column() { 450 Button('BindSheet') 451 .onClick(() => { 452 this.isShow = true; 453 }) 454 .bindSheet($$this.isShow, this.myBuilder(), { 455 detents: [300, 600, 900], 456 uiContext: this.getUIContext(), 457 mode: SheetMode.OVERLAY, 458 scrollSizeMode: ScrollSizeMode.CONTINUOUS, 459 backgroundColor: Color.Orange, 460 title: { title: 'Title', subtitle: 'Subtitle' } 461 }) 462 } 463 .justifyContent(FlexAlign.Center) 464 .width('100%') 465 .height('100%') 466 } 467} 468``` 469The sheet's content height is not updated until the user stops dragging and releases the sheet. 470 471 472 473The sheet's content height is updated in real time as the user drags the sheet. 474 475 476 477### Example 6: Configuring the Sheet to Resize to Avoid the Keyboard 478 479This example demonstrates how to adjust the scrollable content within a sheet when the keyboard height changes by setting **SheetKeyboardAvoidMode** to **RESIZE_ONLY**. 480 481```ts 482//xxx.ets 483import window from '@ohos.window'; 484import { BusinessError } from '@ohos.base'; 485 486@Entry 487@Component 488struct ListenKeyboardHeightChange { 489 @State isShow: boolean = false; 490 @State avoidMode: SheetKeyboardAvoidMode = SheetKeyboardAvoidMode.RESIZE_ONLY; 491 scroller = new Scroller(); 492 private arr: number[] = [0, 1, 2, 3, 4, 5, 6]; 493 windowClass: window.Window | undefined = undefined; 494 495 aboutToAppear(): void { 496 try { 497 window.getLastWindow(getContext(this), (err: BusinessError, data) => { 498 const errCode: number = err.code; 499 if (errCode) { 500 console.error(`Failed to obtain the top window, Cause code: ${err.code}, message: ${err.message}`); 501 return; 502 } 503 this.windowClass = data; 504 try { 505 if (this.windowClass !== undefined) { 506 console.log('success in listen height change'); 507 this.windowClass.on('keyboardHeightChange', this.callback); 508 } 509 } catch (exception) { 510 console.error(`Failed to enable the listener for keyboard height changes, Cause code: ${exception.code}, message: ${exception.message}`); 511 } 512 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 513 }); 514 } catch (exception) { 515 console.error(`Failed to obtain the top window, Cause code: ${exception.code}, message: ${exception.message}`); 516 } 517 } 518 519 callback = (height: number) => { 520 console.log('height change: ' + height); 521 if (height !== 0) { 522 this.scroller.scrollTo({ 523 xOffset: 0, yOffset: height + this.scroller.currentOffset().yOffset, 524 animation: { duration: 1000, curve: Curve.Ease, canOverScroll: false } 525 }); 526 } 527 } 528 529 @Builder 530 myBuilder() { 531 Scroll(this.scroller) { 532 Column() { 533 ForEach(this.arr, (item: number) => { 534 Row() { 535 Text(item.toString()) 536 .width('80%') 537 .height(60) 538 .backgroundColor('#3366CC') 539 .borderRadius(15) 540 .fontSize(16) 541 .textAlign(TextAlign.Center) 542 .margin({ top: 5 }) 543 } 544 }, (item: number) => item.toString()) 545 546 TextInput().height('100') 547 548 Flex({ alignItems: ItemAlign.End }) { 549 Row() { 550 Button("click") 551 .margin(10) 552 .fontSize(20) 553 .width('45%') 554 555 Button("cancel") 556 .margin(10) 557 .fontSize(20) 558 .width('45%') 559 }.width('100%') 560 }.height(100) 561 }.margin({ right: 15, bottom: 50 }) 562 } 563 .height('100%') 564 .scrollBar(BarState.On) 565 .scrollable(ScrollDirection.Vertical) 566 } 567 568 build() { 569 Column() { 570 Button("transition modal 1") 571 .onClick(() => { 572 this.isShow = true 573 }) 574 .fontSize(20) 575 .margin(10) 576 .bindSheet($$this.isShow, this.myBuilder(), { 577 height: 750, 578 backgroundColor: Color.Gray, 579 blurStyle: BlurStyle.Thick, 580 showClose: true, 581 title: { title: "title", subtitle: "subtitle" }, 582 keyboardAvoidMode: SheetKeyboardAvoidMode.RESIZE_ONLY, 583 }) 584 } 585 .justifyContent(FlexAlign.Start) 586 .width('100%') 587 .height('100%') 588 } 589} 590``` 591 592 593### Example 7: Setting the Corner Radius in a Mirrored Layout 594 595This 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. 596 597In this example, the **radius** property of the sheet uses the LocalizedBorderRadiuses type. 598 599```ts 600import { LengthMetrics } from '@kit.ArkUI'; 601 602@Entry 603@Component 604struct SheetTransitionExample { 605 @State isShow: boolean = false 606 607 @Builder 608 myBuilder() { 609 Column() { 610 Button("content1") 611 .margin(10) 612 .fontSize(20) 613 614 Button("content2") 615 .margin(10) 616 .fontSize(20) 617 } 618 .width('100%') 619 } 620 621 build() { 622 Column() { 623 Button("transition modal 1") 624 .onClick(() => { 625 this.isShow = true 626 }) 627 .fontSize(20) 628 .margin(10) 629 .bindSheet($$this.isShow, this.myBuilder(), { 630 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 631 title: { title: "title", subtitle: "subtitle" }, 632 radius: { topStart: LengthMetrics.vp(50), topEnd: LengthMetrics.vp(10) }, 633 }) 634 } 635 .justifyContent(FlexAlign.Start) 636 .width('100%') 637 .height('100%') 638 } 639} 640``` 641 642The following shows how the example is represented with left-to-right scripts. 643 644 645 646The following shows how the example is represented with right-to-left scripts. 647 648 649
