# 绑定半模态页面（bindSheet） [半模态页面（bindSheet）](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-sheet-transition#bindsheet)默认是模态形式的非全屏弹窗式交互页面，允许部分底层父视图可见，帮助用户在与半模态交互时保留其父视图环境。 半模态页面适用于展示简单的任务或信息面板，例如，个人信息、文本简介、分享面板、创建日程、添加内容等。若需展示可能影响父视图的半模态页面，半模态支持配置为非模态交互形式。 半模态在不同宽度的设备上存在不同的形态能力，开发者对不同宽度的设备上有不同的形态诉求请参考([preferType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-sheet-transition#sheetoptions))属性。可以使用bindSheet构建半模态转场效果，详见[模态转场](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-modal-transition#使用bindsheet构建半模态转场效果)。对于复杂或者冗长的用户流程，建议考虑其他的转场方式替代半模态。如[全模态转场](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-contentcover-page)和[Navigation转场](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-navigation-animation)。 ## 使用约束 * 半模态内嵌[UIExtension](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-uiextension)时，不支持再在UIExtension内拉起半模态/弹窗。 * 若无二次确认或者自定义关闭行为的场景，不建议使用[shouldDismiss](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-sheet-transition#sheetoptions)/[onWillDismiss](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-sheet-transition#sheetoptions)接口。 ## 生命周期 半模态页面提供了生命周期函数，用于通知用户该弹窗的生命周期状态。生命周期的触发顺序依次为：onWillAppear -> onAppear -> onWillDisappear -> onDisappear。 |名称|类型|说明| |:--------------|:---------|:------------------| |onWillAppear|() => void|半模态页面显示（动画开始前）回调函数。| |onAppear|() => void|半模态页面显示（动画结束后）回调函数。| |onWillDisappear|() => void|半模态页面回退（动画开始前）回调函数。| |onDisappear|() => void|半模态页面回退（动画结束后）回调函数。| ## 使用嵌套滚动交互 在半模态面板内容区域滑动时的操作优先级： 1. 内容处于最顶部（内容不可滚动时以此状态处理） 上滑时，优先向上扩展面板挡位，如无挡位可扩展，则滚动内容 下滑时，优先向下收缩面板挡位，如无挡位可收缩，则关闭面板 2. 内容处于中间位置（可上下滚动） 上/下滑时，优先滚动内容，直至页面内容到达底部/顶部 3. 内容处于底部位置（内容可滚动时） 上滑时，呈现内容区域回弹效果，不切换挡位 下滑时，滚动内容直到到达顶部 半模态上述交互默认的嵌套模式为：{Forward：PARENT_FIRST，Backward：SELF_FIRST} 如果开发者希望在面板内容的builder中定义滚动容器，如List、Scroll，并结合半模态的上述交互能力，那么需要在垂直方向上为滚动容器设置嵌套滚动属性。 ```ts .nestedScroll({ // 可滚动组件往末尾端滚动时的嵌套滚动选项，手势向上 scrollForward: NestedScrollMode.PARENT_FIRST, // 可滚动组件往起始端滚动时的嵌套滚动选项，手势向下 scrollBackward: NestedScrollMode.SELF_FIRST, }) ``` 完整示例代码如下： ```TypeScript @Entry @Component struct SheetDemo { @State isShowSheet: boolean = false; private items: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; @Builder SheetBuilder() { Column() { // 第一步：自定义滚动容器 List({ space: '10vp' }) { ForEach(this.items, (item: number) => { ListItem() { Text(String(item)).fontSize(16).fontWeight(FontWeight.Bold) }.width('90%').height('80vp').backgroundColor('#ff53ecd9').borderRadius(10) }) } .alignListItem(ListItemAlign.Center) .margin({ top: '10vp' }) .width('100%') .height('900px') // 第二步：设置滚动组件的嵌套滚动属性 .nestedScroll({ scrollForward: NestedScrollMode.PARENT_FIRST, scrollBackward: NestedScrollMode.SELF_FIRST, }) // 请将$r('app.string.tSheetBuilder_text1')替换为实际资源文件，在本示例中该资源文件的value值为"非滚动区域" Text($r('app.string.tSheetBuilder_text1')) .width('100%') .backgroundColor(Color.Gray) .layoutWeight(1) .textAlign(TextAlign.Center) .align(Alignment.Top) }.width('100%').height('100%') } build() { Column() { Button('Open Sheet').width('90%').height('80vp') .onClick(() => { this.isShowSheet = !this.isShowSheet; }) .bindSheet($$this.isShowSheet, this.SheetBuilder(), { detents: [SheetSize.MEDIUM, SheetSize.LARGE, 600], preferType: SheetType.BOTTOM, // 请将$r('app.string.tSheetBuilder_text2')替换为实际资源文件，在本示例中该资源文件的value值为"嵌套滚动场景" title: { title: $r('app.string.tSheetBuilder_text2') }, }) }.width('100%').height('100%') .justifyContent(FlexAlign.Center) } } ``` ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/48/v3/xJU4YDqhQ4yod03OYlwAjA/zh-cn_image_0000002784582267.png?HW-CC-KV=V1&HW-CC-Date=20261009T092718Z&HW-CC-Expire=31536000000&HW-CC-Sign=1E43184F9D71383B8920BBF18E961A3AC9350275533A3C58F2FBFD6DE9F5D5A8) ## 二次确认能力 推荐使用onWillDismiss接口，此接口支持在回调中处理二次确认，或自定义关闭行为。 > 说明 > > 声明onWillDismiss接口后，半模态页面的所有关闭操作，包括侧滑、点击关闭按钮、点击蒙层和下拉关闭，都需通过调用dismiss方法来实现。若未实现此逻辑，半模态页面将无法响应上述关闭操作。 ```TypeScript import { hilog } from '@kit.PerformanceAnalysisKit'; const TAG = '[Sample_SupportingAgingFriendly]'; const DOMAIN = 0xF811; const BUNDLE = 'SupportingAgingFriendly_'; @Entry @Component struct OnWillDismiss_Dismiss { @State isShow: boolean = false; @Builder myBuilder() { Column() { Button('Button') } } build() { Button('OpenBindSheet') .onClick(() => { this.isShow = true }) .margin(120) // 第一步：创建半模态页面 .bindSheet($$this.isShow, this.myBuilder(), { height: SheetSize.MEDIUM, blurStyle: BlurStyle.Thick, dragBar: true, detents: [SheetSize.MEDIUM, SheetSize.LARGE], title: { title: 'title', subtitle: 'subtitle' }, enableOutsideInteractive: false, onWillDismiss: ((dismissSheetAction: DismissSheetAction) => { // 第二步：确认二次回调交互能力，此处用AlertDialog提示 "是否选择关闭半模态" this.getUIContext().showAlertDialog( { // 请将$r('app.string.bindSheetCmd_label12')替换为实际资源文件，在本示例中该资源文件的value值为"是否选择关闭半模态" message: $r('app.string.bindSheetCmd_label12'), autoCancel: true, alignment: DialogAlignment.Bottom, gridCount: 4, offset: { dx: 0, dy: -20 }, primaryButton: { value: 'cancel', action: () => { hilog.info(DOMAIN, TAG, 'Callback when the cancel button is clicked'); } }, secondaryButton: { enabled: true, defaultFocus: true, style: DialogButtonStyle.HIGHLIGHT, value: 'ok', // 第三步：确认关闭半模态逻辑所在，此处为AlertDialog的Button回调 action: () => { // 第四步：上述第三步逻辑触发的时候，调用dismiss()关闭半模态 dismissSheetAction.dismiss(); hilog.info(DOMAIN, TAG, 'Callback when the ok button is clicked'); } }, cancel: () => { hilog.info(DOMAIN, TAG, BUNDLE + 'onWillDismiss_Dismiss:' + 'AlertDialog Closed callbacks'); } } ) }) }) } } ``` ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1c/v3/J7lzjsJ6Qxy9vsS9Zi3UPA/zh-cn_image_0000002784662447.png?HW-CC-KV=V1&HW-CC-Date=20261009T092718Z&HW-CC-Expire=31536000000&HW-CC-Sign=3B866FE13A7B534C63A62A640CAD2267A08D89B16AB2DB1F10EF784B60ADFD44) ## 屏蔽部分关闭行为 由于声明了onWillDismiss接口，半模态的关闭行为都需要dismiss处理。可以通过if等逻辑自定义处理关闭逻辑。 下述示例显示半模态页面只在下滑的时候关闭。 ```ts onWillDismiss: ((DismissSheetAction: DismissSheetAction) => { if (DismissSheetAction.reason === DismissReason.SLIDE_DOWN) { DismissSheetAction.dismiss();// 注册dismiss行为 } }), ``` 同理可以结合onWillSpringBackWhenDismiss接口实现更好的下滑体验。 类比onWillDismiss，在声明了onWillSpringBackWhenDismiss后，半模态下滑时的回弹操作需要使用 SpringBackAction.springBack()处理，无此逻辑则不会回弹。 具体代码如下，在半模态下滑的时候无需回弹。 ```ts onWillDismiss: ((DismissSheetAction: DismissSheetAction) => { if (DismissSheetAction.reason === DismissReason.SLIDE_DOWN) { DismissSheetAction.dismiss();// 注册dismiss行为 } }), onWillSpringBackWhenDismiss: ((SpringBackAction: SpringBackAction) => { // 没有注册springBack，下拉半模态页面无回弹行为 }), ``` ## 半模态支持避让中轴 半模态从API version 14开始支持中轴避让，当前在2in1设备默认开启（仅窗口处于瀑布模式时产生避让）中轴避让能力，且在2in1设备默认避让区域为上半屏。开发者可以通过[SheetOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-sheet-transition#sheetoptions)的enableHoverMode主动设置是否避让中轴，及[SheetOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-sheet-transition#sheetoptions)的hoverModeArea设置避让中轴后显示区域。 * 半模态中轴避让不支持控件子窗能力，[SheetOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-sheet-transition#sheetoptions)中的showInSubWindow为true的场景。 * 2in1设备上需同时满足窗口处于瀑布模式才会产生避让。 完整示例代码如下： ```TypeScript @Entry @Component struct SheetTransitionExample { @State isShow: boolean = false; @State enableHoverMode: boolean = true; @State hoverModeArea: HoverModeAreaType = HoverModeAreaType.TOP_SCREEN; @Builder myBuilder() { Column() { // 请将$r('app.string.bindSheetCmd_label10')替换为实际资源文件，在本示例中该资源文件的value值为"enableHoverMode切换" Button($r('app.string.bindSheetCmd_label10')) .margin(10) .fontSize(20) .onClick(() => { this.enableHoverMode = !this.enableHoverMode; }) // 请将$r('app.string.bindSheetCmd_label11')替换为实际资源文件，在本示例中该资源文件的value值为"hoverModeArea切换" Button($r('app.string.bindSheetCmd_label11')) .margin(10) .fontSize(20) .onClick(() => { this.hoverModeArea = this.hoverModeArea === HoverModeAreaType.TOP_SCREEN ? HoverModeAreaType.BOTTOM_SCREEN : HoverModeAreaType.TOP_SCREEN; }) Button('close modal') .margin(10) .fontSize(20) .onClick(() => { this.isShow = false; }) } .width('100%') .height('100%') } build() { Column() { // 请将$r('app.string.bindSheetCmd_label9')替换为实际资源文件，在本示例中该资源文件的value值为"拉起半模态" Button($r('app.string.bindSheetCmd_label9')) .onClick(() => { this.isShow = true; }) .fontSize(20) .margin(10) .bindSheet($$this.isShow, this.myBuilder(), { height: 300, backgroundColor: Color.Green, preferType: SheetType.CENTER, enableHoverMode: this.enableHoverMode, hoverModeArea: this.hoverModeArea }) } .justifyContent(FlexAlign.Center) .width('100%') .height('100%') } } ``` ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/5e/v3/aGlRS_5RTJmOuF4Pf9HCkA/zh-cn_image_0000002755023514.png?HW-CC-KV=V1&HW-CC-Date=20261009T092718Z&HW-CC-Expire=31536000000&HW-CC-Sign=2D8FDD60C2FC9420411263A64CAED8D117334BE4D8B09757865DEAA392766D63)