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>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>**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>**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 attempts to dismiss the sheet.<br>**NOTE**<br>When the user attempts to dismiss the sheet by a pull-down gesture or clicking the back button, the mask, or the close icon, the sheet is not dismissed; instead, the callback is executed.<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 attempts to dismiss the sheet.<br>**NOTE**<br>If this callback is registered, when the user attempts to dismiss the sheet, the sheet is not dismissed immediately; instead, this callback is executed, and you can control whether to dismiss the sheet based on [reason](ts-appendix-enums.md#dismissreason12) in the callback. No further interception with **onWillDismiss** is allowed in an **onWillDismiss** callback. **Atomic service API**: This API can be used in atomic services since API version 12.| 59| onWillSpringBackWhenDismiss<sup>12+</sup> | [SpringBackAction](#springbackaction12) | No | Callback to control the interactive spring back before the sheet is dismissed.<br>**NOTE**<br>When a user performs a pull-down-to-dismiss gesture and either **shouldDismiss** or **onWillDismiss** is registered, the sheet will not spring back automatically if this callback is registered. You can then control whether the sheet should spring back through **springBack** in the callback. **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>**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 | Timing for updating the content display area of the sheet when it is scrolled.<br>Default value: **ScrollSizeMode.FOLLOW_DETENT**| 72 73## SheetSize 74 75| Name | Value | Description | 76| ------------------------- | ---- | -------------------------------- | 77| 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. | 78| 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. | 79| 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. | 80 81## BindOptions 82 83| Name | Type | Mandatory | Description | 84| --------------- | ------------------------------------------ | ---- | ------------------------ | 85| 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. | 86| 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. | 87| 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. | 88| 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. | 89| 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. | 90 91## SheetType<sup>11+</sup> 92 93**Atomic service API**: This API can be used in atomic services since API version 12. 94 95| Name | Value | Description | 96| ------ | ---- | ------------------------------------------------------ | 97| BOTTOM | 0 | Bottom sheet. | 98| CENTER | 1 | Center sheet. | 99| POPUP | 2 | Popup sheet. The popup sheet cannot be dismissed with a pull-down gesture. | 100 101## SheetDismiss<sup>11+</sup> 102 103**Atomic service API**: This API can be used in atomic services since API version 12. 104 105| Name | Type | Mandatory | Description | 106| ------- | ---------- | ---- | ------------------------------------------------------------ | 107| dismiss | () => void | Yes | Callback for dismissing the sheet. Call this API only when you need the sheet to exit. | 108 109## SheetTitleOptions<sup>11+</sup> 110 111**Atomic service API**: This API can be used in atomic services since API version 12. 112 113| Name | Type | Mandatory | Description | 114| -------- | -------------------------------------- | ---- | -------------------- | 115| title | [ResourceStr](ts-types.md#resourcestr) | Yes | Main title of the sheet. | 116| subtitle | [ResourceStr](ts-types.md#resourcestr) | No | Subtitle of the sheet. | 117 118## SheetMode<sup>12+</sup> 119 120**Atomic service API**: This API can be used in atomic services since API version 12. 121 122| Name | Value | Description | 123| ------------------------- | ---- | -------------------------------- | 124| 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. | 125| 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 mounted to the tree before bringing up the sheet; otherwise, the sheet will not be able to be attached to the corresponding page node.| 126 127## ScrollSizeMode<sup>12+</sup> 128| Name | Value | Description | 129| ------------------------- | ---- | -------------------------------- | 130| FOLLOW_DETENT | 0 | The sheet updates the content display area after a swipe ends. | 131| CONTINUOUS | 1 | The sheet continuously updates the content display area during the scroll process.| 132 133## DismissSheetAction<sup>12+</sup> 134 135**Atomic service API**: This API can be used in atomic services since API version 12. 136 137| Name | Type | Mandatory | Description | 138| --------------- | ---------------------------------------- | ---- | ------------- | 139| dismiss | function | Yes | Callback for dismissing the sheet. Call this API when you need to exit the page. | 140| reason | [DismissReason](ts-appendix-enums.md#dismissreason12) | Yes | Type of operation that causes the sheet to be dismissed. | 141 142## SpringBackAction<sup>12+</sup> 143 144| Name | Type | Mandatory | Description | 145| --------------- | ---------------------------------------- | ---- | ------------- | 146| springBack | function | Yes | Callback to control the interactive spring back before the sheet is dismissed. | 147 148## Example 149### Example 1 150 151```ts 152// xxx.ets 153@Entry 154@Component 155struct SheetTransitionExample { 156 @State isShow:boolean = false 157 @State isShow2:boolean = false 158 @State sheetHeight:number = 300; 159 160 @Builder myBuilder() { 161 Column() { 162 Button("change height") 163 .margin(10) 164 .fontSize(20) 165 .onClick(()=>{ 166 this.sheetHeight = 500; 167 }) 168 169 Button("Set Illegal height") 170 .margin(10) 171 .fontSize(20) 172 .onClick(()=>{ 173 this.sheetHeight = -1; 174 }) 175 176 Button("close modal 1") 177 .margin(10) 178 .fontSize(20) 179 .onClick(()=>{ 180 this.isShow = false; 181 }) 182 } 183 .width('100%') 184 .height('100%') 185 } 186 187 build() { 188 Column() { 189 Button("transition modal 1") 190 .onClick(() => { 191 this.isShow = true 192 }) 193 .fontSize(20) 194 .margin(10) 195 .bindSheet($$this.isShow, this.myBuilder(), { 196 height: this.sheetHeight, 197 backgroundColor: Color.Green, 198 onWillAppear: () => {console.log("BindSheet onWillAppear.")}, 199 onAppear: () => {console.log("BindSheet onAppear.")}, 200 onWillDisappear: () => {console.log("BindSheet onWillDisappear.")}, 201 onDisappear: () => {console.log("BindSheet onDisappear.")} 202 }) 203 } 204 .justifyContent(FlexAlign.Center) 205 .width('100%') 206 .height('100%') 207 } 208} 209``` 210 211 212 213### Example 2 214 215```ts 216// xxx.ets 217@Entry 218@Component 219struct SheetTransitionExample { 220 @State isShow:boolean = false 221 @Builder myBuilder() { 222 Column() { 223 Button("content1") 224 .margin(10) 225 .fontSize(20) 226 227 Button("content2") 228 .margin(10) 229 .fontSize(20) 230 } 231 .width('100%') 232 } 233 234 build() { 235 Column() { 236 Button("transition modal 1") 237 .onClick(() => { 238 this.isShow = true 239 }) 240 .fontSize(20) 241 .margin(10) 242 .bindSheet($$this.isShow, this.myBuilder(),{ 243 detents:[SheetSize.MEDIUM,SheetSize.LARGE,200], 244 backgroundColor:Color.Gray, 245 blurStyle:BlurStyle.Thick, 246 showClose:true, 247 title:{title:"title", subtitle:"subtitle"}, 248 preferType: SheetType.CENTER, 249 shouldDismiss:((sheetDismiss: SheetDismiss)=> { 250 console.log("bind sheet shouldDismiss") 251 sheetDismiss.dismiss() 252 }) 253 }) 254 } 255 .justifyContent(FlexAlign.Start) 256 .width('100%') 257 .height('100%') 258 } 259} 260``` 261 262 263 264### Example 3 265 266```ts 267// xxx.ets 268// The borderWidth and borderColor attributes of bindSheet use the LocalizedEdgeWidths type and LocalizedEdgeColors type, respectively. 269 270import { LengthMetrics } from '@kit.ArkUI' 271 272@Entry 273@Component 274struct SheetTransitionExample { 275 @State isShow: boolean = false 276 277 @Builder 278 myBuilder() { 279 Column() { 280 Button("content1") 281 .margin(10) 282 .fontSize(20) 283 284 Button("content2") 285 .margin(10) 286 .fontSize(20) 287 } 288 .width('100%') 289 } 290 291 build() { 292 Column() { 293 Button("transition modal 1") 294 .onClick(() => { 295 this.isShow = true 296 }) 297 .fontSize(20) 298 .margin(10) 299 .bindSheet($$this.isShow, this.myBuilder(), { 300 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 301 backgroundColor: Color.Gray, 302 blurStyle: BlurStyle.Thick, 303 showClose: true, 304 title: { title: "title", subtitle: "subtitle" }, 305 preferType: SheetType.CENTER, 306 borderWidth: { top: LengthMetrics.vp(10), start: LengthMetrics.vp(10), end: LengthMetrics.vp(20) }, 307 borderColor: { top: Color.Pink, start: Color.Blue, end: Color.Yellow }, 308 shouldDismiss: ((sheetDismiss: SheetDismiss) => { 309 console.log("bind sheet shouldDismiss") 310 sheetDismiss.dismiss() 311 }) 312 }) 313 } 314 .justifyContent(FlexAlign.Start) 315 .width('100%') 316 .height('100%') 317 } 318} 319``` 320 321The following shows how the example is represented with left-to-right scripts. 322 323 324 325The following shows how the example is represented with right-to-left scripts. 326 327 328 329### Example 4 330 331```ts 332// xxx.ets 333// Registers onWillDismiss and onWillSpringBackWhenDismiss for bindSheet. 334 335@Entry 336@Component 337struct bindSheetExample { 338 @State isShow: Boolean = false; 339 340 @Builder 341 myBuilder() { 342 Column() { 343 Button() { 344 Text("CONTEXT") 345 }.height(50) 346 } 347 } 348 349 build() { 350 Column() { 351 Button("NoRegisterSpringback") 352 .onClick(() => { 353 this.isShow = true 354 }) 355 .fontSize(20) 356 .margin(10) 357 .bindSheet($$this.isShow, this.myBuilder(), { 358 height: SheetSize.MEDIUM, 359 blurStyle: BlurStyle.Thick, 360 showClose: true, 361 title: { title: "title", subtitle: "subtitle" }, 362 preferType: SheetType.CENTER, 363 364 365 onWillDismiss: ((DismissSheetAction: DismissSheetAction) => { 366 if (DismissSheetAction.reason == DismissReason.SLIDE_DOWN) { 367 DismissSheetAction.dismiss() // Register the dismiss behavior. 368 } 369 }), 370 371 onWillSpringBackWhenDismiss: ((SpringBackAction: SpringBackAction) => { 372 // If springBack is not registered, the sheet will not exhibit a spring back effect when pulled down. 373 //SpringBackAction.springBack() 374 }), 375 }) 376 } 377 } 378} 379``` 380 381
