1# 绑定半模态页面（bindSheet） 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @CCFFWW--> 5<!--Designer: @yangfan229--> 6<!--Tester: @lxl007--> 7<!--Adviser: @HelloCrease--> 8 9[半模态页面（bindSheet）](../reference/apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#bindsheet)默认是模态形式的非全屏弹窗式交互页面，允许部分底层父视图可见，帮助用户在与半模态交互时保留其父视图环境。 10 11半模态页面适用于展示简单的任务或信息面板，例如，个人信息、文本简介、分享面板、创建日程、添加内容等。若需展示可能影响父视图的半模态页面，半模态支持配置为非模态交互形式。 12 13半模态在不同宽度的设备上存在不同的形态能力，开发者对不同宽度的设备上有不同的形态诉求请参考([preferType](../reference/apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#sheetoptions))属性。可以使用bindSheet构建半模态转场效果，详见[模态转场](arkts-modal-transition.md#使用bindsheet构建半模态转场效果)。对于复杂或者冗长的用户流程，建议考虑其他的转场方式替代半模态。如[全模态转场](arkts-contentcover-page.md)和[Navigation转场](arkts-navigation-navigation.md)。 14 15## 使用约束 16 17 - 半模态内嵌[UIExtension](../reference/apis-arkui/js-apis-arkui-uiExtension.md)时，不支持再在UIExtension内拉起半模态/弹窗。 18 19 - 若无二次确认或者自定义关闭行为的场景，不建议使用[shouldDismiss/onWillDismiss](../reference/apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#sheetoptions)接口。 20 21## 生命周期 22 23半模态页面提供了生命周期函数，用于通知用户该弹窗的生命周期状态。生命周期的触发顺序依次为：onWillAppear -> onAppear -> onWillDisappear -> onDisappear。 24 25| 名称 |类型| 说明 | 26| ----------------- | ------ | ---------------------------- | 27| onWillAppear | () => void | 半模态页面显示（动画开始前）回调函数。 | 28| onAppear | () => void | 半模态页面显示（动画结束后）回调函数。 | 29| onWillDisappear | () => void | 半模态页面回退（动画开始前）回调函数。 | 30| onDisappear |() => void | 半模态页面回退（动画结束后）回调函数。 | 31 32## 使用嵌套滚动交互 33 34在半模态面板内容区域滑动时的操作优先级： 35 361. 内容处于最顶部（内容不可滚动时以此状态处理） 37 38 上滑时，优先向上扩展面板档位，如无档位可扩展，则滚动内容 39 40 下滑时，优先向下收缩面板档位，如无档位可收缩，则关闭面板 412. 内容处于中间位置（可上下滚动） 42 43 上/下滑时，优先滚动内容，直至页面内容到达底部/顶部 44 453. 内容处于底部位置（内容可滚动时） 46 47 上滑时，呈现内容区域回弹效果，不切换档位 48 49 下滑时，滚动内容直到到达顶部 50 51半模态上述交互默认的嵌套模式为：{Forward：PARENT\_FIRST，Backward：SELF\_FIRST} 52 53如果开发者希望在面板内容的builder中定义滚动容器，如List、Scroll，并结合半模态的上述交互能力，那么需要在垂直方向上为滚动容器设置嵌套滚动属性。 54 55```ts 56.nestedScroll({ 57 // 可滚动组件往末尾端滚动时的嵌套滚动选项，手势向上 58 scrollForward: NestedScrollMode.PARENT_FIRST, 59 // 可滚动组件往起始端滚动时的嵌套滚动选项，手势向下 60 scrollBackward: NestedScrollMode.SELF_FIRST, 61}) 62``` 63 64完整示例代码如下： 65 66```ts 67@Entry 68@Component 69struct SheetDemo { 70 @State isShowSheet: boolean = false; 71 private items: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; 72 73 @Builder 74 SheetBuilder() { 75 Column() { 76 // 第一步：自定义滚动容器 77 List({ space: '10vp' }) { 78 ForEach(this.items, (item: number) => { 79 ListItem() { 80 Text(String(item)).fontSize(16).fontWeight(FontWeight.Bold) 81 }.width('90%').height('80vp').backgroundColor('#ff53ecd9').borderRadius(10) 82 }) 83 } 84 .alignListItem(ListItemAlign.Center) 85 .margin({ top: '10vp' }) 86 .width('100%') 87 .height('900px') 88 // 第二步：设置滚动组件的嵌套滚动属性 89 .nestedScroll({ 90 scrollForward: NestedScrollMode.PARENT_FIRST, 91 scrollBackward: NestedScrollMode.SELF_FIRST, 92 }) 93 94 Text("非滚动区域") 95 .width('100%') 96 .backgroundColor(Color.Gray) 97 .layoutWeight(1) 98 .textAlign(TextAlign.Center) 99 .align(Alignment.Top) 100 }.width('100%').height('100%') 101 } 102 103 build() { 104 Column() { 105 Button('Open Sheet').width('90%').height('80vp') 106 .onClick(() => { 107 this.isShowSheet = !this.isShowSheet; 108 }) 109 .bindSheet($$this.isShowSheet, this.SheetBuilder(), { 110 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 600], 111 preferType: SheetType.BOTTOM, 112 title: { title: '嵌套滚动场景' }, 113 }) 114 }.width('100%').height('100%') 115 .justifyContent(FlexAlign.Center) 116 } 117} 118``` 119 120 121 122## 二次确认能力 123 124推荐使用onWillDismiss接口，此接口支持在回调中处理二次确认，或自定义关闭行为。 125 126> **说明：** 127> 128> 声明onWillDismiss接口后，半模态页面的所有关闭操作，包括侧滑、点击关闭按钮、点击蒙层和下拉关闭，都需通过调用dismiss方法来实现。若未实现此逻辑，半模态页面将无法响应上述关闭操作。 129 130```ts 131@Entry 132@Component 133struct onWillDismiss_Dismiss { 134 @State isShow: Boolean = false; 135 136 @Builder 137 myBuilder() { 138 Column() { 139 Button('Button') 140 } 141 } 142 143 build() { 144 Button("OpenBindSheet") 145 .onClick(() => { 146 this.isShow = true 147 }) 148 .margin(120) 149 .bindSheet($$this.isShow, this.myBuilder(), { 150 height: SheetSize.MEDIUM, 151 blurStyle: BlurStyle.Thick, 152 dragBar: true, 153 detents: [SheetSize.MEDIUM, SheetSize.LARGE], 154 title: { title: "title", subtitle: "subtitle" }, 155 enableOutsideInteractive: false, 156 onWillDismiss: ((DismissSheetAction: DismissSheetAction) => { 157 // 第二步：确认二次回调交互能力，此处用AlertDialog提示 "是否需要关闭半模态" 158 this.getUIContext().showAlertDialog( 159 { 160 message: '是否选择关闭半模态', 161 autoCancel: true, 162 alignment: DialogAlignment.Bottom, 163 gridCount: 4, 164 offset: { dx: 0, dy: -20 }, 165 primaryButton: { 166 value: 'cancel', 167 action: () => { 168 console.info('Callback when the cancel button is clicked'); 169 } 170 }, 171 secondaryButton: { 172 enabled: true, 173 defaultFocus: true, 174 style: DialogButtonStyle.HIGHLIGHT, 175 value: 'ok', 176 // 第三步：确认关闭半模态逻辑所在，此处为AlertDialog的Button回调 177 action: () => { 178 // 第四步：上述第三步逻辑触发的时候，调用dismiss()关闭半模态 179 DismissSheetAction.dismiss(); 180 console.info('Callback when the ok button is clicked'); 181 } 182 }, 183 cancel: () => { 184 console.info('AlertDialog Closed callbacks'); 185 } 186 } 187 ) 188 }) 189 }) 190 } 191} 192``` 193 194 195## 屏蔽部分关闭行为 196 197由于声明了onWillDismiss接口，半模态的关闭行为都需要dismiss处理。可以通过if等逻辑自定义处理关闭逻辑。 198下述示例显示半模态页面只在下滑的时候关闭。 199 200```ts 201onWillDismiss: ((DismissSheetAction: DismissSheetAction) => { 202 if (DismissSheetAction.reason === DismissReason.SLIDE_DOWN) { 203 DismissSheetAction.dismiss(); //注册dismiss行为 204 } 205}), 206``` 207 208同理可以结合`onWillSpringBackWhenDismiss`接口实现更好的下滑体验。 209类比`onWillDismiss`，在声明了`onWillSpringBackWhenDismiss`后，半模态下滑时的回弹操作需要使用 `SpringBackAction.springBack()`处理，无此逻辑则不会回弹。 210 211具体代码如下，在半模态下滑的时候无需回弹。 212 213```ts 214onWillDismiss: ((DismissSheetAction: DismissSheetAction) => { 215 if (DismissSheetAction.reason === DismissReason.SLIDE_DOWN) { 216 DismissSheetAction.dismiss(); //注册dismiss行为 217 } 218}), 219 220onWillSpringBackWhenDismiss: ((SpringBackAction: SpringBackAction) => { 221 //没有注册springBack，下拉半模态页面无回弹行为 222}), 223``` 224 225## 半模态支持避让中轴 226 227半模态从API version 14开始支持中轴避让，当前在2in1设备默认开启（仅窗口处于瀑布模式时产生避让）中轴避让能力，且在2in1设备默认避让区域为上半屏。开发者可以通过[SheetOptions](../reference/apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#sheetoptions)的enableHoverMode主动设置是否避让中轴，及[SheetOptions](../reference/apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#sheetoptions)的hoverModeArea设置避让中轴后显示区域。 228 229- 半模态中轴避让不支持控件子窗能力，[SheetOptions](../reference/apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#sheetoptions)中的showInSubWindow为true的场景。 230- 2in1设备上需同时满足窗口处于瀑布模式才会产生避让。 231 232完整示例代码如下： 233 234```ts 235@Entry 236@Component 237struct SheetTransitionExample { 238 @State isShow: boolean = false; 239 @State enableHoverMode: boolean = true; 240 @State hoverModeArea: HoverModeAreaType = HoverModeAreaType.TOP_SCREEN; 241 242 @Builder 243 myBuilder() { 244 Column() { 245 Button("enableHoverMode切换") 246 .margin(10) 247 .fontSize(20) 248 .onClick(() => { 249 this.enableHoverMode = !this.enableHoverMode; 250 }) 251 252 Button("hoverModeArea切换") 253 .margin(10) 254 .fontSize(20) 255 .onClick(() => { 256 this.hoverModeArea = this.hoverModeArea === HoverModeAreaType.TOP_SCREEN ? 257 HoverModeAreaType.BOTTOM_SCREEN : HoverModeAreaType.TOP_SCREEN; 258 }) 259 260 Button("close modal") 261 .margin(10) 262 .fontSize(20) 263 .onClick(() => { 264 this.isShow = false; 265 }) 266 } 267 .width('100%') 268 .height('100%') 269 } 270 271 build() { 272 Column() { 273 Button("拉起半模态") 274 .onClick(() => { 275 this.isShow = true; 276 }) 277 .fontSize(20) 278 .margin(10) 279 .bindSheet($$this.isShow, this.myBuilder(), { 280 height: 300, 281 backgroundColor: Color.Green, 282 preferType: SheetType.CENTER, 283 enableHoverMode: this.enableHoverMode, 284 hoverModeArea: this.hoverModeArea 285 }) 286 } 287 .justifyContent(FlexAlign.Center) 288 .width('100%') 289 .height('100%') 290 } 291} 292``` 293 294 295
