1# 半模态转场 2 3通过bindSheet属性为组件绑定半模态页面，在组件插入时可通过设置自定义或默认的内置高度确定半模态大小。 4 5> **说明：** 6> 7> 从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> 不支持路由跳转。 10 11## bindSheet 12 13bindSheet(isShow: boolean, builder: CustomBuilder, options?: SheetOptions) 14 15给组件绑定半模态页面，点击后显示模态页面。 16 17**系统能力：** SystemCapability.ArkUI.ArkUI.Full 18 19**参数：** 20 21| 参数名 | 类型 | 必填 | 说明 | 22| ------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 23| isShow | boolean | 是 | 是否显示半模态页面。<br/>从API version 10开始，该参数支持[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定变量。 | 24| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 配置半模态页面内容。 | 25| options | [SheetOptions](#sheetoptions) | 否 | 配置半模态页面的可选属性。 | 26 27> **说明：** 28> 29> 在非双向绑定情况下，以拖拽方式关闭半模态页面不会改变isShow参数的值。 30> 31> 为了使isShow参数值与半模态界面的状态同步，建议使用[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定isShow参数。 32## SheetOptions 33 34继承自[BindOptions](#bindoptions)。 35 36| 名称 | 类型 | 必填 | 描述 | 37| --------------- | ---------------------------------------- | ---- | --------------- | 38| height | [SheetSize](#sheetsize枚举说明) \| [Length](ts-types.md#length) | 否 | 半模态高度，默认是LARGE。<br/>**说明：**<br/>底部弹窗竖屏时，当设置detents时，该属性设置无效。<br/>底部弹窗竖屏时，最大高度为距离信号栏8vp。<br />底部弹窗横屏时，该属性设置无效，高度为距离屏幕顶部8vp。<br/>居中弹窗和跟手弹窗设置类型为SheetSize.LARGE和SheetSize.MUDIUM无效，显示默认高度560vp。居中弹窗和跟手弹窗最小高度为320vp，最大高度为窗口短边的90%。当使用Length设置的高度和使用SheetSize.FIT_CONTENT自适应的高度大于最大高度，则显示最大高度，小于最小高度，则显示最小高度。 | 39| 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))?] | 否 | 半模态页面的切换高度档位。<br/>**说明：**<br/>底部弹窗竖屏生效，元组中第一个高度为初始高度。<br />面板可跟手滑动切换档位，松手后是否滑动至目标档位有两个判断条件：速度和距离。速度超过阈值，则执行滑动至与手速方向一致的目标档位；速度小于阈值，则引入距离判断条件，当位移距离>当前位置与目标位置的1/2，滑动至与手速方向一致的目标档位，位移距离当前位置与目标位置的1/2，返回至当前档位。速度阈值：1000，距离阈值：50%。 | 40| preferType<sup>11+</sup> | [SheetType.CENTER](#sheettype11枚举说明) \| [SheetType.POPUP](#sheettype11枚举说明) | 否 | 半模态页面的样式。<br/>**说明：**<br/>preferType不可设置为SheetType.BOTTOM。 | 41| showClose<sup>11+</sup> | boolean \| [Resource](ts-types.md#resource) | 否 | 是否显示关闭图标，默认显示。<br/>**说明：**<br/>Resource需要为boolean类型。 | 42| dragBar | boolean | 否 | 是否显示控制条。<br/>**说明：**<br/>半模态面板的dentents属性设置多个不同高度并且设置生效时，默认显示控制条。否则不显示控制条。 | 43| blurStyle<sup>11+</sup> | [BlurStyle](ts-appendix-enums.md#blurstyle9) | 否 | 半模态面板的模糊背景。默认无模糊背景。 | 44| maskColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 半模态页面的背景蒙层颜色。 | 45| title<sup>11+</sup> | [SheetTitleOptions](#sheettitleoptions11) \| [CustomBuilder](ts-types.md#custombuilder8) | 否 | 半模态面板的标题。 | 46| enableOutsideInteractive<sup>11+</sup> | boolean | 否 | 半模态所在页面是否允许交互。<br/>**说明：**<br/>设置为true时允许交互，不显示蒙层；设置为false时不允许交互，显示蒙层；若不进行设置，默认底部弹窗与居中弹窗不允许交互，跟手弹窗允许交互。当设置为true时，maskColor设置无效。 | 47| shouldDismiss<sup>11+</sup> | (sheetDismiss: [SheetDismiss](#sheetdismiss11)) => void | 否 | 半模态页面交互式关闭回调函数。<br/>**说明：**<br/>当用户执行下拉关闭/back事件/点击蒙层关闭/关闭按钮关闭交互操作时，如果注册该回调函数，则不会立刻关闭。 | 48 49## SheetSize枚举说明 50 51| 名称 | 参数描述 | 52| ------------------------- | -------------------------------- | 53| MEDIUM | 指定半模态高度为屏幕高度一半。 | 54| LARGE | 指定半模态高度几乎为屏幕高度。 | 55| FIT_CONTENT<sup>11+</sup> | 指定半模态高度为适应内容的高度。 | 56 57## BindOptions 58 59| 名称 | 类型 | 必填 | 说明 | 60| --------------- | ------------------------------------------ | ---- | ------------------------ | 61| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 半模态页面的背板颜色。 | 62| onAppear | () => void | 否 | 半模态页面显示回调函数。 | 63| onDisappear | () => void | 否 | 半模态页面回退回调函数。 | 64 65## SheetType<sup>11+</sup>枚举说明 66 67| 名称 | 参数描述 | 68| ------ | ------------------------------------------------------ | 69| BOTTOM | 底部弹窗。 | 70| CENTER | 居中弹窗。 | 71| POPUP | 跟手弹窗。跟手弹窗面板不支持跟手滑动，下滑面板不关闭。 | 72 73## SheetDismiss<sup>11+</sup> 74 75| 名称 | 类型 | 必填 | 描述 | 76| ------- | ---------- | ---- | ------------------------------------------------------------ | 77| dismiss | () => void | 是 | 半模态面板关闭回调函数。开发者需要退出时调用，不需要退出时无需调用。 | 78 79## SheetTitleOptions<sup>11+</sup> 80 81| 名称 | 类型 | 必填 | 描述 | 82| -------- | -------------------------------------- | ---- | -------------------- | 83| title | [ResourceStr](ts-types.md#resourcestr) | 是 | 半模态面板的主标题。 | 84| subtitle | [ResourceStr](ts-types.md#resourcestr) | 否 | 半模态面板的副标题。 | 85 86## 示例1 87 88```ts 89// xxx.ets 90@Entry 91@Component 92struct SheetTransitionExample { 93 @State isShow:boolean = false 94 @State isShow2:boolean = false 95 @State sheetHeight:number = 300; 96 @State showDragBar:boolean = true; 97 98 @Builder myBuilder() { 99 Column() { 100 Button("change height") 101 .margin(10) 102 .fontSize(20) 103 .onClick(()=>{ 104 this.sheetHeight = 500; 105 }) 106 107 Button("Set Illegal height") 108 .margin(10) 109 .fontSize(20) 110 .onClick(()=>{ 111 this.sheetHeight = -1; 112 }) 113 114 Button("close dragBar") 115 .margin(10) 116 .fontSize(20) 117 .onClick(()=>{ 118 this.showDragBar = false; 119 }) 120 121 Button("close modal 1") 122 .margin(10) 123 .fontSize(20) 124 .onClick(()=>{ 125 this.isShow = false; 126 }) 127 } 128 .width('100%') 129 .height('100%') 130 } 131 132 build() { 133 Column() { 134 Button("transition modal 1") 135 .onClick(() => { 136 this.isShow = true 137 }) 138 .fontSize(20) 139 .margin(10) 140 .bindSheet($$this.isShow, this.myBuilder(), {height: this.sheetHeight, dragBar: this.showDragBar, backgroundColor: Color.Green, onAppear: () => {console.log("BindSheet onAppear.")}, onDisappear: () => {console.log("BindSheet onDisappear.")}}) 141 } 142 .justifyContent(FlexAlign.Center) 143 .width('100%') 144 .height('100%') 145 } 146} 147``` 148 149 150 151## 示例2 152 153```ts 154// xxx.ets 155@Entry 156@Component 157struct SheetTransitionExample { 158 @State isShow:boolean = false 159 @Builder myBuilder() { 160 Column() { 161 Button("content1") 162 .margin(10) 163 .fontSize(20) 164 165 Button("content2") 166 .margin(10) 167 .fontSize(20) 168 } 169 .width('100%') 170 } 171 172 build() { 173 Column() { 174 Button("transition modal 1") 175 .onClick(() => { 176 this.isShow = true 177 }) 178 .fontSize(20) 179 .margin(10) 180 .bindSheet($$this.isShow, this.myBuilder(),{ 181 detents:[SheetSize.MEDIUM,SheetSize.LARGE,200], 182 backgroundColor:Color.Gray, 183 blurStyle:BlurStyle.Thick, 184 showClose:true, 185 title:{title:"title", subtitle:"subtitle"}, 186 preferType: SheetType.CENTER, 187 shouldDismiss:((sheetDismiss: SheetDismiss)=> { 188 console.log("bind sheet shouldDismiss") 189 sheetDismiss.dismiss() 190 }) 191 }) 192 } 193 .justifyContent(FlexAlign.Start) 194 .width('100%') 195 .height('100%') 196 } 197} 198``` 199 200
