全屏模态(bindContentCover)是介于"弹窗"与"页面跳转"之间的第三种形态:覆盖全屏但不进路由栈,关闭即回到原页面,状态原样保留。健康菜谱助手的图片查看器、全屏编辑器、引导页三个场景用它承接,前两个踩过状态同步和退出确认的坑,后一个验证了引导场景的适配。这篇复盘 bindContentCover 的完整接入:什么时候用它而不是 push 一个页面、modalTransition 的取值、全屏下的返回键与状态栏、以及一次重复打开的事故。

一、全屏模态的定位:与页面跳转的边界

全屏浮层和 push 页面都能"盖住当前内容",选择标准是"是否进入导航流"。图片查看器是标准例子:用户从菜谱图点开大图,左右滑看其他图,关闭回到原位置——查看器不改变导航位置,返回手势的语义是"关闭浮层"而不是"返回上一页",这是模态语义,用 bindContentCover;反之,菜谱详情页虽然也是"从列表盖住列表",但它是导航流中的一站(可以分享、可以深链直达、返回后退栈),必须走 Navigation push。判断口诀:会被分享、会被直达、会出现在返回路径上的,是页面;看完即走、随时丢弃、不产生导航历史的,是全屏模态。项目最初把图片查看器做成了 push 页面,用户按返回总回到列表页首,滚动位置全丢——改成全屏模态后,列表状态原样保留,这个体验差距立刻被用户感知到。

二、接口面:一个布尔状态驱动一切

bindContentCover 的用法是组件属性式:isShow 布尔状态 + builder 内容 + modalTransition 配置。开关全靠 isShow 置位,打开与关闭(含滑动手势关闭)都会回调 onDisappear,把 isShow 拉回 false——这个回调是状态一致性的关键,漏接它会导致"手势关了浮层,isShow 还是 true",再想打开就失灵。实现上把打开收拢成一个方法(openViewer(index)),关闭只依赖 onDisappear 统一收口,任何路径(按钮、手势、系统返回)关闭都汇到同一处。另一个参数 onWillDismiss 用来拦截关闭:编辑器有未保存内容时弹确认,确认后手动调 dismissAction.dismiss() 放行——和 Navigation 的 onWillPop 同一套拦截范式,学过一处另一处零成本。

@State isViewerShow: boolean = false @State viewerIndex: number = 0 Image(this.recipe.covers[this.viewerIndex]) .onClick(() => this.openViewer(this.viewerIndex)) private openViewer(index: number) { this.viewerIndex = index this.isViewerShow = true } Image(this.recipe.covers[this.viewerIndex]) .bindContentCover( $$this.isViewerShow, this.viewerBuilder(), { modalTransition: ModalTransition.DEFAULT, onDisappear: () => { this.isViewerShow = false } } )

三、图片查看器:双指缩放与翻页的组合

全屏查看器的核心交互:单指左右滑翻页、双指捏合缩放、双击放大。实现结构是 Swiper 包 Image,手势冲突的处理原则:缩放态(倍率大于1)时 Swiper 的滑动让位给图片平移,缩放态恢复 1 倍后翻页手势回归。踩的坑在双击:双击放大用了 ClickGesture 的 count=2,但它和 Swiper 的单击翻页区域重叠,双击第一下的位移会让 Swiper 翻半页——解决是把双击手势挂在外层容器,Swiper 设 disableSwipe 由缩放态控制,翻页只在倍率为 1 时启用。图片加载失败的场景也要接:查看器里大图加载失败的占位与重试按钮,比页面里更显眼,失败静默是查看器的重大体验事故。

Swiper() { ForEach(this.recipe.covers, (cover: string, idx: number) => { ZoomableImage({ src: cover }) }, (cover: string, idx: number) => cover + idx) } .index(this.viewerIndex) .disableSwipe(this.zoomScale > 1) // 缩放态禁翻页 .onChange((idx: number) => { this.viewerIndex = idx })

四、全屏编辑器:退出确认与状态保护

备注编辑器场景:列表项滑出"编辑备注",全屏模态展开编辑页,保存或放弃退出。两个工程要点。其一,退出确认:onWillDismiss 里检查脏标记(hasUnsaved),有未保存内容先弹系统 confirm,用户确认放弃才 dismiss——直接覆盖 onWillDismiss 后忘记放行是高频错误,拦截分支的每一条路径都要保证 dismissAction.dismiss() 被调用,不然浮层永远关不掉(和转场的 finishTransition 是同构的坑)。其二,状态隔离:编辑中的草稿文本存在编辑器自己的 @State,确认保存才写回列表数据源——直接双向绑定列表项会让"改一半"的内容实时污染列表,用户中途关闭后列表显示的就是半成品。状态隔离加上退出确认,编辑器的安全性就齐了。

.bindContentCover($$this.isEditorShow, this.editorBuilder(), { modalTransition: ModalTransition.DEFAULT, onWillDismiss: (action: DismissContentCoverAction) => { if (this.hasUnsaved) { promptAction.showDialog({ message: '放弃未保存的修改?' }) .then(() => action.dismiss()) } else { action.dismiss() } }, onDisappear: () => { this.isEditorShow = false } })

五、转场取值:三种 modalTransition 的实感差异

modalTransition 三档:DEFAULT(系统默认滑动)、SLIDE(底部滑入)、NONE(无动画自定义)。实感上 DEFAULT 是带系统阻尼的全屏推入,和 push 页面的转场观感几乎一致,90% 场景用它;SLIDE 从底部升起,适合"从底部延伸出来的内容"(菜单类全屏),用在查看器上反而怪(图片内容没有"从底部来"的隐喻);NONE 配合自定义转场动画,只有需要品牌化动画时才用。项目三个场景全用 DEFAULT——全屏模态的转场和页面转场长得一样是有意为之:用户分不清也不需要分清模态与页面,交互的一致性高于形态的区分度。强制区分(查看器用 NONE 配花哨动画)只会让用户困惑"刚才那是什么"。

六、返回键与手势:全屏下的退出路径

全屏模态的退出路径有三条:系统返回键/返回手势、内容里的关闭按钮、onWillDismiss 拦截后的主动关闭。返回手势在模态上的语义由系统接管(默认关闭模态),但有个细节:查看器在缩放态时返回手势应该先"恢复缩放"而不是直接关闭——两段式返回。实现是 onBackPress(API 12+ 的全屏模态回调)里判断缩放态,是则恢复缩放并 return true 吞掉事件。另外关闭按钮的可达性:全屏内容容易把关闭按钮放角落,大字号或横屏下容易点不到,顶部固定一条工具栏放关闭,比角落浮动按钮可靠。三条退出路径都要在回归清单里,漏一条就是"关不掉"的工单。

// 两段式返回:缩放态先恢复缩放 .onBackPress(() => { if (this.zoomScale > 1) { this.resetZoom() // 先回1倍 return true // 吞掉,不关闭 } return false // 正常关闭模态 })

七、状态栏与沉浸式:全屏下的系统栏处理

全屏模态默认继承宿主页面的沉浸式配置,但查看器场景要的是"状态栏隐藏、纯黑背景"的影院式体验。处理方式:模态打开时把状态栏设为隐藏(window.setWindowSystemBarEnable 传空数组),关闭时恢复——时机挂模态的 onAppear/onDisappear,保证成对执行。踩过一次坑:恢复时机写在了宿主页 onShow,模态快速开关时恢复晚于下一次打开,状态栏状态错乱——收敛到模态自己的回调里成对处理就稳了。深浅色的状态栏前景色也要对应:查看器纯黑背景下状态栏前景强制白色,与系统深浅色解耦,退出时恢复跟随系统。沉浸式处理的原则:谁打开谁恢复,成对出现,不依赖页面生命周期兜底。

// 模态打开隐藏状态栏,关闭恢复,成对执行 onAppear: () => { window.getLastWindow(getContext()).then(w => w.setWindowSystemBarEnable([])) }, onDisappear: () => { window.getLastWindow(getContext()).then(w => w.setWindowSystemBarEnable(['status'])) }

八、真实事故:重复打开的三个实例

上线后收到"查看器滑不动"的反馈,复现条件诡异:快速连点缩略图后偶发。排查发现全屏模态叠了三层——isShow 置 true 的 onClick 没做防抖,快速连点三次开了三个模态实例(浮层叠浮层,最上面那层没有图片数据,表现为黑屏滑不动)。修复两层:openViewer 里防重入(isShow 为 true 时直接 return);内容 builder 每次渲染校验 viewerIndex 合法性,越界渲染空态并自动关闭。这次事故的普适教训:模态的打开入口和页面的 push 入口一样需要防重入——用户的手速永远比开发者的想象快,任何"点一下开一个"的入口都要假设会被连点十次。防重入的一行 if,价值一张线上工单。

private openViewer(index: number) { if (this.isViewerShow) return // 防重入:开着就不再开 if (index < 0 || index >= this.recipe.covers.length) return this.viewerIndex = index this.isViewerShow = true }

九、生产验证:全屏模态的五项回归

全屏模态回归固定五项:一、三入口连点——防重入生效,只开一层;二、三路径退出——返回手势、关闭按钮、onWillDismiss 确认后关闭,逐条验证;三、两段式返回——缩放态按返回先回缩放,再按关闭;四、状态栏成对——开关十次状态栏状态无错乱;五、编辑器脏数据——改一半关闭弹确认,确认放弃后列表无半成品。五项覆盖了历史上的全部事故模式(重复打开、关不掉、状态栏错乱、半成品污染),清单来源就是事故,每一条都是学费。

十、总结:全屏模态的四条军规

收束成四条:一、定位守边界——不进导航流、无深链需求的盖屏场景才用模态,会被分享直达的走页面;二、状态收口——isShow 单一驱动,关闭统一 onDisappear 回调,打开入口必防重入;三、退出三路径全通——返回、按钮、拦截确认,onWillDismiss 每条分支必调 dismiss;四、沉浸成对——谁打开谁恢复,不靠页面生命周期兜底。全屏模态的 API 面很小,但它把"模态语义"带到了全屏尺度——语义守得住,它就是查看器与编辑器的最优解;守不住,它就是"关不掉的黑屏"的温床。

参考资料:

• 华为开发者:bindContentCover 全屏模态转场
• 华为开发者:DismissContentCoverAction 拦截
• 华为开发者:setWindowSystemBarEnable 沉浸式

#鸿蒙 #HarmonyOS 7(API 26)