鸿蒙OpenHarmony【模态转场设置之半模态转场】ArkTS组件通用属性 ...

通过bindSheet属性为组件绑定半模态页面，在组件插入时可通过设置自定义或默认的内置高度确定半模态巨细。
说明
从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
不支持路由跳转。
bindSheet

bindSheet(isShow: Optional, builder: CustomBuilder, options?: SheetOptions)
给组件绑定半模态页面，点击后显示模态页面。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明isShowOptional是是否显示半模态页面。从API version 10开始，该参数支持[$$]双向绑定变量。builder[CustomBuilder]是配置半模态页面内容。options[SheetOptions]否配置半模态页面的可选属性。 说明

• 在非双向绑定情况下，以拖拽方式关闭半模态页面不会改变isShow参数的值。
  
• 为了使isShow参数值与半模态界面的状态同步，建议使用[$$]双向绑定isShow参数。
  
• 在半模态单挡位向上拖拽或是多挡位上滑换挡情况下，内容在拖拽竣事或换挡竣事后更新显示区域。
  
• 半模态是一个严格和宿主节点绑定在一起的弹窗。若是想实现类似“页面显示的瞬间就弹出半模态”的效果，请确认宿主节点是否已挂载上树。若宿主节点还没上树就将isShow置为true，半模态将不收效。建议使用[onAppear]函数，确保在宿主节点挂载后再显示半模态。
  尤其是 [SheetMode] = EMBEDDED 时，除宿主节点外，还需确保对应的页面节点成功挂载。
  
• 半模态页面的离场动效不支持打断，动效实行期间无法响应其他手势动作。目前离场动效使用[弹簧曲线]，该动画曲线存在视觉上并不显着的拖尾动画。因此，在半模态退出时，视觉上半模态页面已经消散，但此时动效可能还未竣事，若想再次点击拉起半模态页面则不会响应。必要等动效完全竣事后，才可以再次拉起。
  

SheetOptions

继承自[BindOptions]。
名称类型必填形貌height[SheetSize][Length]否detents11+[([SheetSize][Length]), ( [SheetSize][Length])?, ([SheetSize]preferType11+[SheetType]否半模态页面的样式。**说明：**半模态在不同屏幕宽度所支持的显示类型：1. 宽度 < 600vp：底部。2. 600vp <= 宽度 < 840vp：底部、居中。3. 宽度 >= 840vp：底部、居中、跟手。元服务API： 从API version 12开始，该接口支持在元服务中使用。showClose11+boolean[Resource]否dragBarboolean否是否显示控制条。**说明：**半模态面板的detents属性设置多个不同高度而且设置收效时，默认显示控制条。否则不显示控制条。元服务API： 从API version 11开始，该接口支持在元服务中使用。blurStyle11+[BlurStyle]否半模态面板的含糊背景。默认无含糊背景。元服务API： 从API version 12开始，该接口支持在元服务中使用。maskColor[ResourceColor]否半模态页面的背景蒙层颜色。元服务API： 从API version 11开始，该接口支持在元服务中使用。title11+[SheetTitleOptions][CustomBuilder]否enableOutsideInteractive11+boolean否半模态所在页面是否允许交互。**说明：**设置为true时允许交互，不显示蒙层；设置为false时不允许交互，显示蒙层；若不举行设置，默认底部弹窗与居中弹窗不允许交互，跟手弹窗允许交互。当设置为true时，maskColor设置无效。元服务API： 从API version 12开始，该接口支持在元服务中使用。shouldDismiss11+(sheetDismiss: [SheetDismiss]) => void否半模态页面交互式关闭回调函数。**说明：**当用户实行下拉关闭/back事件/点击蒙层关闭/关闭按钮关闭交互操纵时，如果注册该回调函数，则不会立即关闭。元服务API： 从API version 12开始，该接口支持在元服务中使用。onWillDismiss12+[DismissSheetAction]否半模态页面交互式关闭回调函数。**说明：**当用户实行关闭操纵时，如果注册该回调函数，不会立即关闭, 由开辟者控制是否关闭。在回调函数中可以通过[reason]得到关闭页面的操纵类型，从而根据原因选择是否关闭半模态页面。在onWillDismiss回调中，不能再做onWillDismiss拦截。元服务API： 从API version 12开始，该接口支持在元服务中使用。onWillSpringBackWhenDismiss12+[SpringBackAction]否半模态页面交互式关闭前控制回弹函数。**说明：**当用户实行下拉关闭操纵并注册shouldDimiss或onWillDismiss时，如果注册该回调函数，则不会回弹，由开辟者控制下滑关闭时是否回弹。在回调函数中可以通过调用springBack来实现回弹效果。元服务API： 从API version 12开始，该接口支持在元服务中使用。onHeightDidChange12+Callback否半模态页面高度变化回调函数。**说明：**底部弹窗时，只有档位变化和拖拽跟手才返回每一帧高度，拉起半模态和避让软键盘只返回末了的高度，其他弹窗只在半模态拉起返回末了高度。返回值为px。元服务API： 从API version 12开始，该接口支持在元服务中使用。onDetentsDidChange12+Callback否半模态页面档位变化回调函数。**说明：**底部弹窗时，档位变化返回末了的高度。返回值为px。元服务API： 从API version 12开始，该接口支持在元服务中使用。onWidthDidChange12+Callback否半模态页面宽度变化回调函数。**说明：**宽度变化时返回末了的宽度。返回值为px。元服务API： 从API version 12开始，该接口支持在元服务中使用。onTypeDidChange12+Callback<[SheetType]>否半模态页面形态变化回调函数。**说明：**形态变化时返回末了的形态。元服务API： 从API version 12开始，该接口支持在元服务中使用。borderWidth12+[Dimension][EdgeWidths][LocalizedEdgeWidths]12+borderColor12+[ResourceColor][EdgeColors][LocalizedEdgeColors]12+borderStyle12+[BorderStyle][EdgeStyles]否width12+[Dimension]否设置半模态页面的宽度。百分比参数方式：以父元素宽的百分比来设置半模态页面的宽度。元服务API： 从API version 12开始，该接口支持在元服务中使用。shadow12+[ShadowOptions][ShadowStyle]否uiContext12+[UIContext]否在UIContext实例对应的窗口中显示半模态。**说明：**使用[openBindSheet]启动的半模态页面，不支持设置、更新该属性。元服务API： 从API version 12开始，该接口支持在元服务中使用。mode12+[SheetMode]否设置半模态页面的显示层级。默认值：SheetMode.OVERLAY。**说明：**1. 半模态显示期间mode属性不支持动态切换，两种模式的显示层级完全不同，无法做到显示期间同一个半模态从一个层级变换到另一个层级。建议在使用时明确诉求固定mode值。2. 设置SheetMode.EMBEDDED时不支持设置UIContext属性，两者对应的半模态显示层级效果互相冲突。3. 使用[openBindSheet]启动半模态页面，若未传入有效的targetId，则不支持设置为SheetMode.EMBEDDED，默以为SheetMode.OVERLAY。元服务API： 从API version 12开始，该接口支持在元服务中使用。scrollSizeMode12+[ScrollSizeMode]否设置半模态面板滑动时，内容区域革新时机。默认值：ScrollSizeMode.FOLLOW_DETENT 。 SheetSize枚举说明

名称值参数形貌MEDIUM0指定半模态高度为屏幕高度一半。元服务API： 从API version 11开始，该接口支持在元服务中使用。LARGE1指定半模态高度几乎为屏幕高度。元服务API： 从API version 11开始，该接口支持在元服务中使用。FIT_CONTENT11+2指定半模态高度为适应内容的高度。元服务API： 从API version 12开始，该接口支持在元服务中使用。 BindOptions

名称类型必填说明backgroundColor[ResourceColor]否半模态页面的背板颜色。默认值：Color.White。元服务API： 从API version 11开始，该接口支持在元服务中使用。onWillAppear12+() => void否半模态页面显示（动画开始前）回调函数。元服务API： 从API version 12开始，该接口支持在元服务中使用。onAppear() => void否半模态页面显示（动画竣事后）回调函数。元服务API： 从API version 11开始，该接口支持在元服务中使用。onWillDisappear12+() => void否半模态页面回退（动画开始前）回调函数。**说明：**不允许在onWillDisappear函数中修改状态变量，可能会导致组件行为不稳固。元服务API： 从API version 12开始，该接口支持在元服务中使用。onDisappear() => void否半模态页面回退（动画竣事后）回调函数。元服务API： 从API version 11开始，该接口支持在元服务中使用。 SheetType11+枚举说明

元服务API： 从API version 12开始，该接口支持在元服务中使用。
名称值参数形貌BOTTOM0底部弹窗。CENTER1居中弹窗。POPUP2跟手弹窗。跟手弹窗面板不支持跟手滑动，下滑面板不关闭。 SheetDismiss11+

元服务API： 从API version 12开始，该接口支持在元服务中使用。
名称类型必填形貌dismiss() => void是半模态面板关闭回调函数。开辟者必要退出时调用，不必要退出时无需调用。 SheetTitleOptions11+

元服务API： 从API version 12开始，该接口支持在元服务中使用。
名称类型必填形貌title[ResourceStr]是半模态面板的主标题。subtitle[ResourceStr]否半模态面板的副标题。 SheetMode12+

元服务API： 从API version 12开始，该接口支持在元服务中使用。
名称值参数形貌OVERLAY0设置半模态面板在当前UIContext内顶层显示，在所有页面之上。和弹窗类组件显示在一个层级。EMBEDDED1设置半模态面板在当前页面内的顶层显示。**说明：**目前只支持挂载在Page大概NavDestination节点上，如有NavDestination优先挂载在NavDestination上。只支持在这两种页面内顶层显示。该模式下新起的页面可以覆盖在半模态弹窗上，页面返回后该半模态依旧存在，半模态面板内容不丢失。该模式下需确保目标页面节点如Page节点已挂载上树，再拉起半模态，否则半模态将无法挂载到对应的页面节点内。 ScrollSizeMode12+

名称值参数形貌FOLLOW_DETENT0设置半模态面板跟手滑动竣事后更新内容显示区域。CONTINUOUS1设置半模态面板在滑动过程中持续更新内容显示区域。 DismissSheetAction12+

元服务API： 从API version 12开始，该接口支持在元服务中使用。
名称类型必填形貌dismissfunction是半模态页面关闭回调函数。开辟者必要退出页面时调用。reason[DismissReason]是返回本次半模态页面退出的操纵类型。 SpringBackAction12+

名称类型必填形貌springBackfunction是半模态页面关闭前控制回弹函数，开辟者必要半模态回弹时调用。 示例

示例1

1. // xxx.ets
2. @Entry
3. @Component
4. struct SheetTransitionExample {
5.   @State isShow:boolean = false
6.   @State isShow2:boolean = false
7.   @State sheetHeight:number = 300;
9.   @Builder myBuilder() {
10.     Column() {
11.       Button("change height")
12.         .margin(10)
13.         .fontSize(20)
14.         .onClick(()=>{
15.           this.sheetHeight = 500;
16.         })
18.       Button("Set Illegal height")
19.         .margin(10)
20.         .fontSize(20)
21.         .onClick(()=>{
22.           this.sheetHeight = -1;
23.         })
25.       Button("close modal 1")
26.         .margin(10)
27.         .fontSize(20)
28.         .onClick(()=>{
29.           this.isShow = false;
30.         })
31.     }
32.     .width('100%')
33.     .height('100%')
34.   }
36.   build() {
37.     Column() {
38.       Button("transition modal 1")
39.         .onClick(() => {
40.           this.isShow = true
41.         })
42.         .fontSize(20)
43.         .margin(10)
44.         .bindSheet($$this.isShow, this.myBuilder(), {
45.           height: this.sheetHeight,
46.           backgroundColor: Color.Green,
47.           onWillAppear: () => {console.log("BindSheet onWillAppear.")},
48.           onAppear: () => {console.log("BindSheet onAppear.")},
49.           onWillDisappear: () => {console.log("BindSheet onWillDisappear.")},
50.           onDisappear: () => {console.log("BindSheet onDisappear.")}
51.         })
52.     }
53.     .justifyContent(FlexAlign.Center)
54.     .width('100%')
55.     .height('100%')
56.   }
57. }

复制代码

示例2

使用bindSheet的detents属性设置三个不同高度的档位

1. // xxx.ets
2. @Entry
3. @Component
4. struct SheetTransitionExample {
5.   @State isShow:boolean = false
6.   @Builder myBuilder() {
7.     Column() {
8.       Button("content1")
9.         .margin(10)
10.         .fontSize(20)
12.       Button("content2")
13.         .margin(10)
14.         .fontSize(20)
15.     }
16.     .width('100%')
17.   }
19.   build() {
20.     Column() {
21.       Button("transition modal 1")
22.         .onClick(() => {
23.           this.isShow = true
24.         })
25.         .fontSize(20)
26.         .margin(10)
27.         .bindSheet($$this.isShow, this.myBuilder(),{
28.           detents:[SheetSize.MEDIUM,SheetSize.LARGE,200],
29.           backgroundColor:Color.Gray,
30.           blurStyle:BlurStyle.Thick,
31.           showClose:true,
32.           title:{title:"title", subtitle:"subtitle"},
33.         })
34.     }
35.     .justifyContent(FlexAlign.Start)
36.     .width('100%')
37.     .height('100%')
38.   }
39. }

复制代码

示例3

bindSheet属性的borderWidth、borderColor属性值使用LocalizedEdgeWidths类型和LocalizedEdgeColors类型

1. // xxx.ets
3. import { LengthMetrics } from '@kit.ArkUI'
5. @Entry
6. @Component
7. struct SheetTransitionExample {
8.   @State isShow: boolean = false
10.   @Builder
11.   myBuilder() {
12.     Column() {
13.       Button("content1")
14.         .margin(10)
15.         .fontSize(20)
17.       Button("content2")
18.         .margin(10)
19.         .fontSize(20)
20.     }
21.     .width('100%')
22.   }
24.   build() {
25.     Column() {
26.       Button("transition modal 1")
27.         .onClick(() => {
28.           this.isShow = true
29.         })
30.         .fontSize(20)
31.         .margin(10)
32.         .bindSheet($$this.isShow, this.myBuilder(), {
33.           detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200],
34.           backgroundColor: Color.Gray,
35.           blurStyle: BlurStyle.Thick,
36.           showClose: true,
37.           title: { title: "title", subtitle: "subtitle" },
38.           borderWidth: { top: LengthMetrics.vp(10), start: LengthMetrics.vp(10), end: LengthMetrics.vp(20) },
39.           borderColor: { top: Color.Pink, start: Color.Blue, end: Color.Yellow },
40.         })
41.     }
42.     .justifyContent(FlexAlign.Start)
43.     .width('100%')
44.     .height('100%')
45.   }
46. }

复制代码

从左至右显示语言模式示例图

从右至左显示语言模式示例图

示例4

bindSheet注册onWillDismiss与onWillSpringBackWhenDismiss

1. // xxx.ets
3. @Entry
4. @Component
5. struct bindSheetExample {
6.   @State isShow: Boolean = false;
8.   @Builder
9.   myBuilder() {
10.     Column() {
11.       Button() {
12.         Text("CONTEXT")
13.       }.height(50)
14.     }
15.   }
17.   build() {
18.     Column() {
19.       Button("NoRegisterSpringback")
20.         .onClick(() => {
21.           this.isShow = true
22.         })
23.         .fontSize(20)
24.         .margin(10)
25.         .bindSheet($$this.isShow, this.myBuilder(), {
26.           height: SheetSize.MEDIUM,
27.           blurStyle: BlurStyle.Thick,
28.           showClose: true,
29.           title: { title: "title", subtitle: "subtitle" },
30.           preferType: SheetType.CENTER,
34.           onWillDismiss: ((DismissSheetAction: DismissSheetAction) => {
35.             if (DismissSheetAction.reason == DismissReason.SLIDE_DOWN) {
36.               DismissSheetAction.dismiss() //注册dismiss行为
37.             }
38.           }),
40.           onWillSpringBackWhenDismiss: ((SpringBackAction: SpringBackAction) => {
41.             //没有注册springBack, 下拉半模态页面无回弹行为
42.             //SpringBackAction.springBack()
43.           }),
44.         })
45.     }
46.   }
47. }

复制代码

示例5

1. // xxx.ets
2. // bindSheet设置scrollSizeMode
4. @Entry
5. @Component
6. struct Index {
7.   @State isShow: boolean = false;
11.   @Builder
12.   myBuilder() {
13.     Column() {
14.       Column()
15.         .backgroundColor(Color.Blue)
16.         .height(200)
17.         .width('100%')
18.       Column()
19.         .backgroundColor(Color.Green)
20.         .height(200)
21.         .width('100%')
22.     }
23.   }
25.   build() {
26.     Column() {
27.         Button('BindSheet')
28.           .onClick(()=>{
29.             this.isShow = true;
30.           })
31.           .bindSheet($$this.isShow, this.myBuilder(), {
32.             detents: [300, 600, 900],
33.             uiContext: this.getUIContext(),
34.             mode: SheetMode.OVERLAY,
35.             scrollSizeMode: ScrollSizeMode.CONTINUOUS,
36.             backgroundColor: Color.Orange,
37.             title: {title: 'Title', subtitle: 'Subtitle'}
38.           })
39.     }
40.     .justifyContent(FlexAlign.Center)
41.     .width('100%')
42.     .height('100%')
43.   }
44. }

复制代码

跟手触发档位切换时，放手才触发面板内容高度革新

跟手触发档位切换时，跟手时期就会触发面板内容高度革新

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。