董云舟这个月在做商城详情页时，产品提了个需求：长按商品卡要弹出一个规格浮层，左边放主图、右边放可滚动规格项，底下还要跟一个备注输入框。我习惯性地想去翻系统弹窗，试了一圈发现内置AlertDialog只能承载标题、文本和按钮，做完的感觉就是“能用，但很委屈”。后来我把目光转向了鸿蒙自定义弹窗——基于CustomDialogController的完整弹窗方案，不仅长相全由自己控制，布局、动效、数据回传也能按业务来设计。这篇文章就是这段时间项目的实操总结。
我会从系统弹窗的边界、弹窗背后的UI机制、三种高频弹窗形态的实现，到项目里反复踩到的状态同步和重复打开崩溃问题，完整讲清楚。读者对象是正在学习HarmonyOS NEXT或ArkUI的开发者，尤其适合那些已经开始写业务页面、对“如何优雅地做弹窗”有真实需求的同学。
1. 先看清边界：系统弹窗搞不定的场景，才是自定义弹窗的战场
1.1 系统内置弹窗究竟能做什么
先说结论，系统自带的那几个弹窗接口不是没用，而是适用面非常固定。它们适合的是“打断式确认”和“简单提示”。
- 退出登录时的二次确认
- 删除数据前的风险提醒
- 展示接口返回的错误文案
- 升级提示、公告通知这类纯文本场景
这种弹窗有一个共同特点：内容静态、结构简单、不需要承载太多用户操作。你只需要告诉用户“发生了什么，你要选哪个”，系统弹窗就能胜任。它们可以提供标题、正文、一到三个按钮，开发者能做的基本只是改文案和按钮点击回调。
如果业务刚好在这些场景里，我不建议你强行上自定义弹窗。原因很简单：系统弹窗实现成本几乎为零，代码也短，而且它内部处理了遮罩、点击外部关闭、返回键逻辑和基础转场动画。自己写一套反而要操心用户体验的一致性，并不划算。
1.2 哪三类需求会让系统弹窗“漏底”
当业务需求开始进入下面三类，系统弹窗就不够用了。
第一类是内容复杂度超过“文本+按钮”的弹窗。比如商品规格选择，弹窗内需要图片、价格、库存标签、Radio选项、上下滚动区域，还可能有多级联动。你可以试着用系统弹窗的customBuilder去塞自定义内容，但你会发现样式约束、尺寸适配都会很别扭，内容一多，屏幕适配和滚动点击问题就全冒出来了。
第二类是需要在弹窗内完成完整交互流程的需求。例如订单备注填写弹窗，用户要输入文字、选择快捷短语、勾选隐私授权，再点提交。系统弹窗的输入体验很弱，回调语义也不够丰富。你要拿它做表单，开发者需要绕很多路。
第三类是用弹窗承载“页面级功能”的需求。最典型的是付款前安全验证、地址选择器、时间范围筛选这类。它们虽然形态上是个浮层，但实际上是一次独立操作流程，有完整的UI布局、数据加载、状态校验和结果回传。这种弹窗用系统接口实现，会把你逼进死角。
1.3 业务侧的一个典型失败案例
我最初接到的规格浮层需求，第一版就用AlertDialog.show的思路做的。具体来说，是把一个自绘的Column强行塞进系统弹窗的content扩展区。
第一轮跑通看起来没什么大碍，但到了真机测试问题就来了：弹窗内规格超过8个以后内容会顶出屏幕边界，而且自己加的Scroll在弹窗环境里的滚动判定很怪。更要命的是弹窗内部状态一变，整个浮层会跟着父页面一起重绘，导致滚动位置丢、选中态闪烁。这些问题合在一起，倒逼我回到自定义弹窗方案。
所以我的真实体会是：如果预判弹窗内容会超过“100个字加两个按钮”，不如一开始就考虑自定义弹窗，别到联调阶段再推倒返工。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 自定义弹窗不是“另一个页面”，而是一棵独立UI子树
2.1 CustomDialogController背后的执行逻辑
很多首次接触鸿蒙自定义弹窗的开发者，容易把它想象成“打开了一个新窗口”或“往页面上盖了一层自己做的透明遮罩”。这两种理解都不完全准确。
如果弹窗相当于新开了一个窗口，那弹窗打开后不应该还能看到原页面自然过渡的动画，而且系统开销也会很大。如果只是页面内的透明遮罩，那它应该严格受页面组件生命周期约束，父页面一刷新，遮罩内容也应该更新。但实际表现是：自定义弹窗的UI状态和主页面是分离的，主页面业务状态变化不会直接导致弹窗内部临时状态重置。
更接近真相的描述是：使用CustomDialogController.open()时，鸿蒙的ArkUI框架会创建一个与此弹窗控制器绑定的UI子树节点，并把“将弹窗组件渲染到界面上层”这件事交给框架处理。这个独立的节点有自己的状态管理上下文。它虽然在视觉上覆盖在当前页面之上，但在组件树中并不依附于页面内部的某个具体容器。
正因如此，弹窗内部才能做到自己的滚动列表、输入框焦点、选中状态都不被外部页面打扰。这让我在写规格选择浮层时，不用反复去考虑页面侧状态刷新会不会波及弹窗。
2.2 为什么不推荐用Stack加Visibility做伪弹窗
我知道有些开发者会自己做一个“伪弹窗”：在页面底部放一层半透明遮罩，中间放一个需要时显示、不需要时隐藏的Column，用状态控制Visibility来切换。
这个方案原理上说得通，也确实是很多前端同学从Web开发迁移过来后最容易想到的做法。但它有一些长期维护时的隐患。
第一，原页面组件复用了同一个build方法，每当你更新页面上任何一个状态，页面组件会重新走渲染流程。伪弹窗虽然视觉上没变化，但内部子组件可能被重建，输入框焦点、列表滚动位置这类“非状态信息”很容易丢。
第二，伪弹窗需要开发者自己处理事件穿透。遮罩层如果包在Stack里，点击遮罩却没有关闭弹窗，你会发现在遮罩后面的页面按钮照样能接收到点击。你只能额外加一个透明层拦截事件，层级关系会越写越绕。
第三，弹窗的进出场动画，以及点击返回键关闭，这类系统能力在伪弹窗里都要手动实现。
这些痛点刚好就是CustomDialogController帮你保证的基线能力。它本身自带遮罩和点击外部关闭策略，弹窗内容并不是页面build方法里的同一个分支，所以不会遇到上面说的重建问题。
2.3 一个帮助理解的设计对比
你可以把页面想象成一个主舞台，页面里的普通组件是舞台上的固定布景。调用系统弹窗时，相当于舞台右侧临时推上来一个统一规格的小箱子，箱子里的内容有限，但操作简单。
而自定义弹窗，相当于舞台工作人员临时在布景前方搭建了一块独立的可移动台子。这块台子是提前制作好的“预制模块”（对应@CustomDialog装饰的组件），台子上有什么、怎么互动、什么时候撤下去，全部由你说了算，并且它和背后的固定布景互不干扰。
一旦建立起这个模型，后面看代码、踩坑的思路都会顺很多。
3. 从零封装一个确认浮层：原理、代码与生命周期
3.1 声明一个最小可用的@CustomDialog组件
在ArkUI里写自定义弹窗，入口是一个特殊装饰器：@CustomDialog。它作用于struct，我们不能直接把这个struct当成普通页面组件放进某个Column里。它的使用方式非常固定：先声明组件结构，再创建控制器实例，最后通过控制器的open()和close()方法控制显隐。
下面这个组件就是一个基础的确认弹窗，代码适用于HarmonyOS NEXT的ArkTS开发环境。
a复制