1# 绑定半模态页面（bindSheet）
2
3[半模态页面（bindSheet）](../reference/apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#bindsheet)默认是模态形式的非全屏弹窗式交互页面，允许部分底层父视图可见，帮助用户在与半模态交互时保留其父视图环境。
4
5半模态页面适用于展示简单的任务或信息面板，例如，个人信息、文本简介、分享面板、创建日程、添加内容等。若需展示可能影响父视图的半模态页面，半模态支持配置为非模态交互形式。
6
7半模态在不同宽度的设备上存在不同的形态能力，开发者对不同宽度的设备上有不同的形态诉求请参考([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-transition.md)。
8
9## 使用约束
10
11 - 半模态内嵌[UIExtension](../reference/apis-arkui/js-apis-arkui-uiExtension.md)时，不支持再在UIExtension内拉起半模态/弹窗。
12
13 - 若无二次确认或者自定义关闭行为的场景，不建议使用[shouldDismiss/onWilDismiss](../reference/apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#sheetoptions)接口。
14
15## 生命周期
16
17半模态页面提供了生命周期函数，用于通知用户该弹窗的生命周期状态。生命周期的触发顺序依次为：onWillAppear -> onAppear -> onWillDisappear -> onDisappear。
18
19| 名称            |类型| 说明                       |
20| ----------------- | ------ | ---------------------------- |
21| onWillAppear    | () => void | 半模态页面显示（动画开始前）回调函数。 |
22| onAppear    | () => void  | 半模态页面显示（动画结束后）回调函数。  |
23| onWillDisappear | () => void | 半模态页面回退（动画开始前）回调函数。 |
24| onDisappear |() => void  | 半模态页面回退（动画结束后）回调函数。     |
25
26## 使用嵌套滚动交互
27
28在半模态面板内容区域滑动时的操作优先级：
29
301. 内容处于最顶部（内容不可滚动时以此状态处理）
31
32   上滑时，优先向上扩展面板档位，如无档位可扩展，则滚动内容
33
34   下滑时，优先向下收缩面板档位，如无档位可收缩，则关闭面板
352. 内容处于中间位置（可上下滚动）
36
37   上/下滑时，优先滚动内容，直至页面内容到达底部/顶部
38
393. 内容处于底部位置（内容可滚动时）
40
41   上滑时，呈现内容区域回弹效果，不切换档位
42
43   下滑时，滚动内容直到到达顶部
44
45半模态上述交互默认的嵌套模式为：{Forward：PARENT\_FIRST，Backward：SELF\_FIRST}
46
47如果开发者希望在面板内容的builder中定义滚动容器，如List、Scroll，并结合半模态的上述交互能力，那么需要在垂直方向上为滚动容器设置嵌套滚动属性。
48
49```ts
50.nestedScroll({
51    // 可滚动组件往末尾端滚动时的嵌套滚动选项，手势向上
52    scrollForward: NestedScrollMode.PARENT_FIRST,
53    // 可滚动组件往起始端滚动时的嵌套滚动选项，手势向下
54    scrollBackward: NestedScrollMode.SELF_FIRST,
55})
56```
57
58完整示例代码如下：
59
60```ts
61@Entry
62@Component
63struct SheetDemo {
64  @State isShowSheet: boolean = false
65  private items : number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
66
67  @Builder
68  SheetBuilder() {
69    Column() {
70      // 第一步：自定义滚动容器
71      List({space:'10vp'}) {
72        ForEach(this.items,(item : number) => {
73          ListItem() {
74            Text(String(item)).fontSize(16).fontWeight(FontWeight.Bold)
75          }.width('90%').height('80vp').backgroundColor('#ff53ecd9').borderRadius(10)
76        })
77      }.alignListItem(ListItemAlign.Center).margin({top:'10vp'}).width('100%').height('900px')
78      // 第二步：设置滚动组件的嵌套滚动属性
79      .nestedScroll({
80        scrollForward: NestedScrollMode.PARENT_FIRST,
81        scrollBackward: NestedScrollMode.SELF_FIRST,
82      })
83
84      Text("非滚动区域").width('100%').backgroundColor(Color.Gray)
85        .layoutWeight(1)
86        .textAlign(TextAlign.Center)
87        .align(Alignment.Top)
88    }.width('100%').height('100%')
89  }
90  build() {
91    Column() {
92      Button('Open Sheet').width('90%').height('80vp')
93        .onClick(()=>{
94          this.isShowSheet = !this.isShowSheet
95        })
96        .bindSheet($$this.isShowSheet, this.SheetBuilder(), {
97          detents:[SheetSize.MEDIUM, SheetSize.LARGE, 600],
98          preferType: SheetType.BOTTOM,
99          title: {title: '嵌套滚动场景'},
100        })
101    }.width('100%').height('100%')
102    .justifyContent(FlexAlign.Center)
103  }
104}
105```
106
107## 二次确认能力
108
109推荐使用onWillDismiss接口，此接口支持在回调中处理二次确认，或自定义关闭行为。
110
111> **说明：**
112>
113> 声明onWillDismiss接口后，半模态页面的所有关闭操作，包括侧滑、点击关闭按钮、点击蒙层和下拉关闭，都需通过调用dismiss方法来实现。若未实现此逻辑，半模态页面将无法响应上述关闭操作。
114
115```ts
116// 第一步：声明onWillDismiss回调
117onWillDismiss: ((DismissSheetAction: DismissSheetAction) => {
118// 第二步：确认二次回调交互能力，此处用AlertDialog提示 "是否需要关闭半模态"
119  AlertDialog.show(
120    {
121      message: '是否选择关闭半模态',
122      autoCancel: true,
123      alignment: DialogAlignment.Bottom,
124      gridCount: 4,
125      offset: { dx: 0, dy: -20 },
126      primaryButton: {
127        value: 'cancel',
128        action: () => {
129          console.info('Callback when the cancel button is clicked')
130        }
131      },
132      secondaryButton: {
133        enabled: true,
134        defaultFocus: true,
135        style: DialogButtonStyle.HIGHLIGHT,
136        value: 'ok',
137        // 第三步：确认关闭半模态逻辑所在，此处为AlertDialog的Button回调
138        action: () => {
139          // 第四步：上述第三步逻辑触发的时候，调用dismiss()关闭半模态
140          DismissSheetAction.dismiss()
141          console.info('Callback when the ok button is clicked')
142        }
143      },
144      cancel: () => {
145        console.info('AlertDialog Closed callbacks')
146      }
147    }
148  )
149})
150```
151
152## 屏蔽部分关闭行为
153
154由于声明了onWillDismiss接口，半模态的关闭行为都需要dismiss处理。可以通过if等逻辑自定义处理关闭逻辑。
155下述示例显示半模态页面只在下滑的时候关闭。
156
157```ts
158onWillDismiss: ((DismissSheetAction: DismissSheetAction) => {
159  if (DismissSheetAction.reason == DismissReason.SLIDE_DOWN) {
160    DismissSheetAction.dismiss() //注册dismiss行为
161  }
162}),
163```
164
165同理可以结合`onWillSpringBackWhenDismiss`接口实现更好的下滑体验。
166类比`onWillDismiss`，在声明了`onWillSpringBackWhenDismiss`后，半模态下滑时的回弹操作需要使用 `SpringBackAction.springBack()`处理，无此逻辑则不会回弹。
167
168具体代码如下，在半模态下滑的时候无需回弹。
169
170```ts
171onWillDismiss: ((DismissSheetAction: DismissSheetAction) => {
172  if (DismissSheetAction.reason == DismissReason.SLIDE_DOWN) {
173    DismissSheetAction.dismiss() //注册dismiss行为
174  }
175}),
176
177onWillSpringBackWhenDismiss: ((SpringBackAction: SpringBackAction) => {
178 //没有注册springBack, 下拉半模态页面无回弹行为
179}),
180```
181
182
183