半模态转场
通过bindSheet属性为组件绑定半模态页面,在组件插入时可通过设置自定义或默认的内置高度确定半模态大小。
说明:
从API Version 10开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
不支持路由跳转。
bindSheet
bindSheet(isShow: boolean, builder: CustomBuilder, options?: SheetOptions)
给组件绑定半模态页面,点击后显示模态页面。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
isShow | boolean | 是 | 是否显示半模态页面。 从API version 10开始,该参数支持$$双向绑定变量。 |
builder | CustomBuilder | 是 | 配置半模态页面内容。 |
options | SheetOptions | 否 | 配置半模态页面的可选属性。 |
说明:
在非双向绑定情况下,以拖拽方式关闭半模态页面不会改变isShow参数的值。
为了使isShow参数值与半模态界面的状态同步,建议使用$$双向绑定isShow参数。
在半模态单挡位向上拖拽或是多挡位上滑换挡请况下,内容在拖拽结束或换挡结束后更新显示区域。
SheetOptions
继承自BindOptions。
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
height | SheetSize | Length | 否 | 半模态高度,默认是LARGE。 说明: 底部弹窗时,当设置detents时,该属性设置无效。 底部弹窗竖屏时,最大高度为距离信号栏8vp。 底部弹窗横屏时,该属性设置无效,高度为距离屏幕顶部8vp。 居中弹窗和跟手弹窗设置类型为SheetSize.LARGE和SheetSize.MEDIUM无效,显示默认高度560vp。居中弹窗和跟手弹窗最小高度为320vp,最大高度为窗口短边的90%。当使用Length设置的高度和使用SheetSize.FIT_CONTENT自适应的高度大于最大高度,则显示最大高度,小于最小高度,则显示最小高度。 原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。 |
detents11+ | [(SheetSize | Length), ( SheetSize | Length)?, (SheetSize | Length)?] | 否 | 半模态页面的切换高度档位。 说明: 底部弹窗竖屏生效,元组中第一个高度为初始高度。 面板可跟手滑动切换档位,松手后是否滑动至目标档位有两个判断条件:速度和距离。速度超过阈值,则执行滑动至与手速方向一致的目标档位;速度小于阈值,则引入距离判断条件,当位移距离>当前位置与目标位置的1/2,滑动至与手速方向一致的目标档位,位移距离当前位置与目标位置的1/2,返回至当前档位。速度阈值:1000,距离阈值:50%。 原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。 |
preferType11+ | SheetType | 否 | 半模态页面的样式。 原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。 |
showClose11+ | boolean | Resource | 否 | 是否显示关闭图标,默认显示。 说明: Resource需要为boolean类型。 原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。 |
dragBar | boolean | 否 | 是否显示控制条。 说明: 半模态面板的dentents属性设置多个不同高度并且设置生效时,默认显示控制条。否则不显示控制条。 原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。 |
blurStyle11+ | BlurStyle | 否 | 半模态面板的模糊背景。默认无模糊背景。 原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。 |
maskColor | ResourceColor | 否 | 半模态页面的背景蒙层颜色。 原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。 |
title11+ | SheetTitleOptions | CustomBuilder | 否 | 半模态面板的标题。 原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。 |
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<number> | 否 | 半模态页面高度变化回调函数。 说明: 底部弹窗时,只有档位变化和拖拽跟手才返回每一帧高度,拉起半模态和避让软键盘只返回最后的高度,其他弹窗只在半模态拉起返回最后高度。 返回值为px。 |
onDetentsDidChange12+ | Callback<number> | 否 | 半模态页面档位变化回调函数。 说明: 底部弹窗时,档位变化返回最后的高度。 返回值为px。 |
onWidthDidChange12+ | Callback<number> | 否 | 半模态页面宽度变化回调函数。 说明: 宽度变化时返回最后的宽度。 返回值为px。 |
onTypeDidChange12+ | Callback<SheetType> | 否 | 半模态页面形态变化回调函数。 说明: 形态变化时返回最后的形态。 |
borderWidth12+ | Dimension | EdgeWidths | LocalizedEdgeWidths12+ | 否 | 设置半模态页面的边框宽度。 可分别设置4个边框宽度。 默认值:0。 百分比参数方式:以父元素半模态页面宽的百分比来设置半模态页面的边框宽度。 当半模态页面左边框和右边框大于半模态页面宽度,半模态页面上边框和下边框大于半模态页面高度,显示可能不符合预期。 说明: 底部弹窗时,底部边框宽度设置无效。 |
borderColor12+ | ResourceColor | EdgeColors | LocalizedEdgeColors12+ | 否 | 设置半模态页面的边框颜色。 默认值:Color.Black。 如果使用borderColor属性,需要和borderWidth属性一起使用。 说明: 底部弹窗时,底部边框颜色设置无效。 |
borderStyle12+ | BorderStyle | EdgeStyles | 否 | 设置半模态页面的边框样式。 默认值:BorderStyle.Solid。 如果使用borderStyle属性,需要和borderWidth属性一起使用。 说明: 底部弹窗时,底部边框样式设置无效。 |
width12+ | Dimension | 否 | 设置半模态页面的宽度。 百分比参数方式:以父元素宽的百分比来设置半模态页面的宽度。 |
shadow12+ | ShadowOptions | ShadowStyle | 否 | 设置半模态页面的阴影。 |
uiContext12+ | UIContext | 否 | 在UIContext实例对应的窗口中显示半模态。 |
mode12+ | SheetMode | 否 | 设置半模态页面的显示层级。 默认值:SheetMode.OVERLAY。 |
scrollSizeMode12+ | ScrollSizeMode | 否 | 设置半模态面板滑动时,内容区域刷新时机。 默认值:ScrollSizeMode.FOLLOW_DETENT 。 |
SheetSize枚举说明
名称 | 值 | 参数描述 |
---|---|---|
MEDIUM | 0 | 指定半模态高度为屏幕高度一半。 原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。 |
LARGE | 1 | 指定半模态高度几乎为屏幕高度。 原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。 |
FIT_CONTENT11+ | 2 | 指定半模态高度为适应内容的高度。 原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。 |
BindOptions
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
backgroundColor | ResourceColor | 否 | 半模态页面的背板颜色,默认为白色。 原子化服务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开始,该接口支持在原子化服务中使用。
名称 | 值 | 参数描述 |
---|---|---|
BOTTOM | 0 | 底部弹窗。 |
CENTER | 1 | 居中弹窗。 |
POPUP | 2 | 跟手弹窗。跟手弹窗面板不支持跟手滑动,下滑面板不关闭。 |
SheetDismiss11+
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
dismiss | () => void | 是 | 半模态面板关闭回调函数。开发者需要退出时调用,不需要退出时无需调用。 |
SheetTitleOptions11+
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
title | ResourceStr | 是 | 半模态面板的主标题。 |
subtitle | ResourceStr | 否 | 半模态面板的副标题。 |
SheetMode12+
名称 | 值 | 参数描述 |
---|---|---|
OVERLAY | 0 | 设置半模态面板在当前UIContext内顶层显示,在所有页面之上。和弹窗类组件显示在一个层级。 |
EMBEDDED | 1 | 设置半模态面板在当前页面内的顶层显示。 说明: 目前只支持挂载在Page节点上,只支持在Page页面内顶层显示。 该模式下新起的页面可以覆盖在半模态弹窗上,页面返回后该半模态依旧存在,半模态面板内容不丢失。 该模式下需确保页面节点如Page节点已挂树,再拉起半模态,否则半模态无法挂载到对应的页面节点内。 |
ScrollSizeMode12+
名称 | 值 | 参数描述 |
---|---|---|
FOLLOW_DETENT | 0 | 设置半模态面板跟手滑动结束后更新内容显示区域。 |
CONTINUOUS | 1 | 设置半模态面板在滑动过程中持续更新内容显示区域。 |
DismissSheetAction12+
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
dismiss | function | 是 | 半模态页面关闭回调函数。开发者需要退出页面时调用。 |
reason | DismissReason | 是 | 返回本次半模态页面退出的操作类型。 |
SpringBackAction12+
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
springBack | function | 是 | 半模态页面关闭前控制回弹函数,开发者需要半模态回弹时调用。 |
示例
示例1
// xxx.ets
@Entry
@Component
struct SheetTransitionExample {
@State isShow:boolean = false
@State isShow2:boolean = false
@State sheetHeight:number = 300;
@Builder myBuilder() {
Column() {
Button("change height")
.margin(10)
.fontSize(20)
.onClick(()=>{
this.sheetHeight = 500;
})
Button("Set Illegal height")
.margin(10)
.fontSize(20)
.onClick(()=>{
this.sheetHeight = -1;
})
Button("close modal 1")
.margin(10)
.fontSize(20)
.onClick(()=>{
this.isShow = false;
})
}
.width('100%')
.height('100%')
}
build() {
Column() {
Button("transition modal 1")
.onClick(() => {
this.isShow = true
})
.fontSize(20)
.margin(10)
.bindSheet($$this.isShow, this.myBuilder(), {
height: this.sheetHeight,
backgroundColor: Color.Green,
onWillAppear: () => {console.log("BindSheet onWillAppear.")},
onAppear: () => {console.log("BindSheet onAppear.")},
onWillDisappear: () => {console.log("BindSheet onWillDisappear.")},
onDisappear: () => {console.log("BindSheet onDisappear.")}
})
}
.justifyContent(FlexAlign.Center)
.width('100%')
.height('100%')
}
}
ts
示例2
// xxx.ets
@Entry
@Component
struct SheetTransitionExample {
@State isShow:boolean = false
@Builder myBuilder() {
Column() {
Button("content1")
.margin(10)
.fontSize(20)
Button("content2")
.margin(10)
.fontSize(20)
}
.width('100%')
}
build() {
Column() {
Button("transition modal 1")
.onClick(() => {
this.isShow = true
})
.fontSize(20)
.margin(10)
.bindSheet($$this.isShow, this.myBuilder(),{
detents:[SheetSize.MEDIUM,SheetSize.LARGE,200],
backgroundColor:Color.Gray,
blurStyle:BlurStyle.Thick,
showClose:true,
title:{title:"title", subtitle:"subtitle"},
preferType: SheetType.CENTER,
shouldDismiss:((sheetDismiss: SheetDismiss)=> {
console.log("bind sheet shouldDismiss")
sheetDismiss.dismiss()
})
})
}
.justifyContent(FlexAlign.Start)
.width('100%')
.height('100%')
}
}
ts
示例3
// xxx.ets
// bindSheet属性的borderWidth、borderColor属性值使用LocalizedEdgeWidths类型和LocalizedEdgeColors类型
import { LengthMetrics } from '@ohos.arkui.node'
@Entry
@Component
struct SheetTransitionExample {
@State isShow: boolean = false
@Builder
myBuilder() {
Column() {
Button("content1")
.margin(10)
.fontSize(20)
Button("content2")
.margin(10)
.fontSize(20)
}
.width('100%')
}
build() {
Column() {
Button("transition modal 1")
.onClick(() => {
this.isShow = true
})
.fontSize(20)
.margin(10)
.bindSheet($$this.isShow, this.myBuilder(), {
detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200],
backgroundColor: Color.Gray,
blurStyle: BlurStyle.Thick,
showClose: true,
title: { title: "title", subtitle: "subtitle" },
preferType: SheetType.CENTER,
borderWidth: { top: LengthMetrics.vp(10), start: LengthMetrics.vp(10), end: LengthMetrics.vp(20) },
borderColor: { top: Color.Pink, start: Color.Blue, end: Color.Yellow },
shouldDismiss: ((sheetDismiss: SheetDismiss) => {
console.log("bind sheet shouldDismiss")
sheetDismiss.dismiss()
})
})
}
.justifyContent(FlexAlign.Start)
.width('100%')
.height('100%')
}
}
ts
从左至右显示语言模式示例图
从右至左显示语言模式示例图
示例4
// xxx.ets
// bindSheet注册onWillDismiss与onWillSpringBackWhenDismiss
@Entry
@Component
struct index {
@State isShow: Boolean = false;
@Builder
myBuilder() {
Column() {
Button() {
Text("CONTEXT")
}.height(50)
}
}
build() {
Column() {
Button("NoRegisterSpringback")
.onClick(() => {
this.isShow = true
})
.fontSize(20)
.margin(10)
.bindSheet($$this.isShow, this.myBuilder(), {
height: SheetSize.MEDIUM,
blurStyle: BlurStyle.Thick,
showClose: true,
title: { title: "title", subtitle: "subtitle" },
preferType: SheetType.CENTER,
onWillDismiss: ((DismissSheetAction: DismissSheetAction) => {
if (DismissSheetAction.reason == DismissReason.SLIDE_DOWN) {
DismissSheetAction.dismiss() //注册dismiss行为
}
}),
onWillSpringBackWhenDismiss: ((SpringBackAction: SpringBackAction) => {
//没有注册springBack, 下拉半模态页面无回弹行为
//SpringBackAction.springBack()
}),
})
}
}
}
ts
最后
有很多小伙伴不知道学习哪些鸿蒙开发技术?不知道需要重点掌握哪些鸿蒙应用开发知识点?而且学习时频繁踩坑,最终浪费大量时间。所以有一份实用的鸿蒙(HarmonyOS NEXT)资料用来跟着学习是非常有必要的。
这份鸿蒙(HarmonyOS NEXT)资料包含了鸿蒙开发必掌握的核心知识要点,内容包含了(ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、OpenHarmony南向开发、鸿蒙项目实战等等)鸿蒙(HarmonyOS NEXT)技术知识点。
希望这一份鸿蒙学习资料能够给大家带来帮助,有需要的小伙伴自行领取,限时开源,先到先得~无套路领取!!
获取这份完整版高清学习路线,请点击→纯血版全套鸿蒙HarmonyOS NEXT学习资料
鸿蒙(HarmonyOS NEXT)最新学习路线
-
HarmonOS基础技能
- HarmonOS就业必备技能
- HarmonOS多媒体技术
- 鸿蒙NaPi组件进阶
- HarmonOS高级技能
- 初识HarmonOS内核
- 实战就业级设备开发
有了路线图,怎么能没有学习资料呢,小编也准备了一份联合鸿蒙官方发布笔记整理收纳的一套系统性的鸿蒙(OpenHarmony )学习手册(共计1236页)与鸿蒙(OpenHarmony )开发入门教学视频,内容包含:ArkTS、ArkUI、Web开发、应用模型、资源分类…等知识点。
获取以上完整版高清学习路线,请点击→纯血版全套鸿蒙HarmonyOS NEXT学习资料
《鸿蒙 (OpenHarmony)开发入门教学视频》
《鸿蒙生态应用开发V2.0白皮书》
《鸿蒙 (OpenHarmony)开发基础到实战手册》
OpenHarmony北向、南向开发环境搭建
《鸿蒙开发基础》
- ArkTS语言
- 安装DevEco Studio
- 运用你的第一个ArkTS应用
- ArkUI声明式UI开发
- .……
《鸿蒙开发进阶》
- Stage模型入门
- 网络管理
- 数据管理
- 电话服务
- 分布式应用开发
- 通知与窗口管理
- 多媒体技术
- 安全技能
- 任务管理
- WebGL
- 国际化开发
- 应用测试
- DFX面向未来设计
- 鸿蒙系统移植和裁剪定制
- ……
《鸿蒙进阶实战》
- ArkTS实践
- UIAbility应用
- 网络案例
- ……
获取以上完整鸿蒙HarmonyOS学习资料,请点击→纯血版全套鸿蒙HarmonyOS NEXT学习资料
总结
总的来说,华为鸿蒙不再兼容安卓,对中年程序员来说是一个挑战,也是一个机会。只有积极应对变化,不断学习和提升自己,他们才能在这个变革的时代中立于不败之地。