企业官网建设流程全解析

做 Flutter 开发的人都知道，Dialog 和 BottomSheet 是移动端交互里最常用的两种“弹出式交互”组件。我在 OpenHarmony 上跑 Flutter 应用大半年，从最开始跑 Hello World 到后来把整个应用的双端 UI 都迁过去，踩得最深、翻车最多的就是这类弹出层。今天不聊大框架，就把 Dialog 和 BottomSheet 在 OpenHarmony 上的实现细节、定制思路和排查经验一次性讲清楚，给准备做鸿蒙端 Flutter 适配的兄弟省点时间。

这篇文章的读者，我猜大概分三类：一类是正在评估 Flutter 能不能跑在 OpenHarmony 上的技术决策者，想看看最棘手的交互组件到底能不能做；一类是已经在做双端适配的开发者，弹窗出了玄学问题想找答案；还有一类纯粹是把 Flutter 当日常工具、想把弹窗做得更专业的产品型程序员。不管你是哪一类，都能从这篇文章里拿到颗粒度比较细的东西，而不是网上那些“复制一个 showDialog 就完事”的入门示例。

1. 先搞清楚一件事：弹出层在 OpenHarmony 上是谁在渲染

1.1 Flutter 的渲染栈在鸿蒙上有何不同

很多刚接触 OpenHarmony 的 Flutter 开发者会有一个误区，以为在鸿蒙上跑 Flutter，弹窗会走 ArkUI 的组件，或者至少要跟鸿蒙的页面做一层交互。实际上不是这样。OpenHarmony 的 Flutter 适配版 SDK（社区一般叫 ohos 分支，托管在 Gitee 的 OpenHarmony SIG 仓库下）做的工作，是把 Flutter Engine 的图形后端对接到了 OpenHarmony 的 Surface 上。Flutter 的 Widget 树、Element 树、RenderObject 树，以及最终的光栅化绘制，全部还是 Flutter 自己那一套。换句话说，Dialog 和 BottomSheet 在鸿蒙上依然是 Flutter Engine 画出来的，不是鸿蒙原生弹窗。

这个特性带来两个结果。好的一面是：同一套 Flutter 代码在 Android、iOS、OpenHarmony 上视觉表现完全一致，你做好的定制弹窗样式一次开发处处生效，不用为鸿蒙单独写一套 UI。麻烦的一面是：弹窗终究要落在系统窗口上，状态栏高度、底部导航条（手势条）避让、键盘弹起、多窗口拉伸这些能力，Flutter 原来在 Android 和 iOS 上是靠平台通道从系统侧拿数据的，在 OpenHarmony 上需要走 ohos 插件的适配实现。适配得好的版本，这些东西几乎无感；适配有 bug 的版本，弹窗位置就可能偏，或者安全区信息直接拿不到。

我个人建议，在做鸿蒙端适配之前，先把 Flutter SDK 的 ohos 分支版本固定下来，不要随便升级。社区目前常见的版本有 3.7.12-ohos、3.10.x-ohos、3.22.x-ohos 等，不同版本对 SafeArea、TextInput 的适配差异挺大。我实测下来，3.22.x 系列的 ohos 分支对弹出层的支持已经比较完整，但如果你用的是比较老的 3.7 系，有些安全区和键盘联动的问题可能需要自己打补丁。

1.2 Dialog 和 BottomSheet 的底层都是 OverlayEntry

不管你是用 showDialog 还是 showModalBottomSheet，最终都是往 Navigator 的 Overlay 里插入一个 OverlayEntry。Overlay 是 Flutter 里的一个独立层，负责把所有需要悬浮在页面之上的组件统一管理。Dialog 全屏盖一层半透明遮罩，BottomSheet 从底部滑入并带动画，这些效果的本质都是“往 Overlay 里塞一个带动画的组件”。

理解了这层关系，你在排查问题时思路就清晰了。弹层不显示，首先要怀疑的是“Overlay 在哪”——如果你的 Dialog 用完了一个被销毁的 context，或者页面被 push 到了一个没有 Overlay 的环境里，弹窗就找不到宿主。其次要怀疑的是“Overlay 之上还有什么”——比如你在某些场景下用了多个 Navigator，弹层可能插到了错误的 Navigator 上，被其他页面盖住。

OpenHarmony 上我遇到过一个比较典型的场景：应用接入了第三方的路由框架，页面栈是自建 Navigator，弹层用了外层 MaterialApp 的 Navigator。结果弹窗从底部出来时，被自建 Navigator 的页面盖了一半。解决办法是在 showDialog 和 showModalBottomSheet 里显式传 useRootNavigator: true，让弹层统一挂到根 Navigator 的 Overlay 上。这个参数在 Android 上往往可传可不传，但在鸿蒙的多 Navigator 场景下建议养成习惯，一律显式指定。

2. Dialog 的完整实现与样式定制要点

2.1 从 showDialog 的每个参数说起

先看最常见的一个最小实现：

Future<bool?> showConfirmDialog( BuildContext context, { required String title, required String message, }) { return showDialog<bool>( context: context, useRootNavigator: true, barrierDismissible: true, // 点击遮罩是否关闭 barrierColor: Colors.black.withValues(alpha: 0.45), // 遮罩颜色 builder: (context) { return AlertDialog( title: Text(title), content: Text(message), actions: [ TextButton( onPressed: () => Navigator.pop(context, false), child: const Text('取消'), ), FilledButton( onPressed: () => Navigator.pop(context, true), child: const Text('确定'), ), ], ); }, ); }

这段代码几乎每个 Flutter 项目里都有。我想强调几个容易忽略的点。

第一，showDialog 的返回类型是 Future<T?>，你在 builder 里用 Navigator.pop(context, value) 把结果带出去，调用方可以用 await 拿到返回值，再决定后续逻辑。很多人写弹窗喜欢在按钮 onPressed 里直接执行业务逻辑，结果逻辑和 UI 耦合在一起，后面想复用就很难受。我建议所有弹窗都设计成“纯 UI + 返回值”的形式，业务逻辑留在调用方处理，这样弹窗组件本身可以随便复制到别的页面。

第二，barrierDismissible 和 barrierColor 这两个参数，直接决定弹窗的交互手感。barrierDismissible 为 true 表示点击遮罩可以关闭弹窗，适合提示类场景；为 false 表示必须通过按钮关闭，适合强确认场景（比如“登录后才能继续”这种）。barrierColor 是遮罩颜色，默认是半透明黑，但如果你的弹窗需要突出内容（比如新手引导遮罩），可以把它改得更深，甚至配合 barrierLabel 做无障碍支持。我习惯在工具函数里把这些参数全部收敛成命名参数，这样调用方永远不需要去记 Flutter 的默认行为。

第三，关于 context 的生命周期。注意在异步后使用 context 的问题。比如你在网络请求返回后调用 showDialog，如果页面已经销毁，直接拿着旧 context 弹窗会崩溃。Flutter 新版 SDK 里，lint 规则 use_build_context_synchronously 会强制你在弹窗前检查 mounted：

if (!context.mounted) return; showDialog<void>(context: context, builder: (_) => const Dialog(...));

这个规则我强烈建议开起来。在鸿蒙端，页面销毁的回调时机跟 Android 略有差异，我遇到过不止一次“异步回来弹窗，结果页面已经被系统回收”的崩溃，加了 mounted 检查之后一次性解决。你如果看到弹层偶发不弹、控制台报 “Looking up a deactivated widget's ancestor is unsafe”，十有八九就是这个原因。

2.2 自定义 Dialog：把默认样式剥掉

AlertDialog 和 SimpleDialog 够用，但真正做产品，绝大多数时候要的是自定义弹窗。Flutter 提供了底层一点的 Dialog 组件，它只是一个带圆角背景的容器，你可以往里面塞任何 Widget。我做自定义弹窗时一般这么写骨架：

showDialog<void>( context: context, useRootNavigator: true, builder: (context) { return Dialog( insetPadding: const EdgeInsets.symmetric(horizontal: 40), backgroundColor: Colors.white, shape: RoundedRectangleBorder( borderRadius: BorderRadius.circular(20), ), clipBehavior: Clip.antiAlias, elevation: 8, child: SizedBox( width: double.infinity, child: Padding( padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 28), child: Column( mainAxisSize: MainAxisSize.min, children: [ const Text('套餐已到期', style: TextStyle(fontSize: 18, fontWeight: FontWeight.w600)), const SizedBox(height: 12), const Text('续费后可以继续使用高级功能，现在续费享 8 折优惠。', textAlign: TextAlign.center), const SizedBox(height: 24), Row( children: [ Expanded( child: OutlinedButton( onPressed: () => Navigator.pop(context), child: const Text('稍后再说'), ), ), const SizedBox(width: 12), Expanded( child: FilledButton( onPressed: () => Navigator.pop(context), child: const Text('立即续费'), ), ), ], ), ], ), ), ), ); }, );

这里几个参数值得说。insetPadding 控制弹窗距离屏幕边缘的距离，默认是 40，在平板上会显得弹窗很小，你可以按设备宽度动态调整，比如宽度小于 480 时用 24，宽度大于 600 时用 80。clipBehavior 设成 Clip.antiAlias 可以保证圆角背景里的内容不会溢出，如果你弹窗里有图片封面，记得把图片也包在同一个带圆角的 Clip 里，否则图片的直角会戳出来。elevation 影响阴影深度，鸿蒙设备上不同厂商的皮肤对阴影的处理不一样，实测给 8 左右比较稳妥，太深了在某些低端设备上会显得脏。

另外，如果你要做的是图片为主的弹窗（比如活动弹窗、广告弹窗），不要忘了用 GestureDetector 包住图片内容，让点击图片本身不触发关闭，只让关闭按钮和遮罩触发关闭。这是一个很小的产品细节，但非常影响体验。图片弹窗记得加上点击跳转的回调，图片加载失败时要有一个兜底背景，否则在弱网环境下弹窗会显示成一个白块，观感很差。

2.3 鸿蒙端 Dialog 的字体、圆角与动效适配

弹窗在鸿蒙端最容易暴露的问题其实是字体。OpenHarmony 设备默认字体是 HarmonyOS Sans，而 Flutter 的文本渲染默认走的是它自带的字体回退链。如果 ohos 分支的字体配置没做完善，弹出的中文内容可能在某些设备上显示成难看的默认字体，或者跟应用主题字体不一致。

我的处理方案是在应用入口统一配置主题字体：

final theme = ThemeData( fontFamily: 'HarmonyOS Sans', // 名称按实际打包的字体资源为准 // ... 其他主题配置 );

如果你的应用没有把 HarmonyOS Sans 字体打包进资源，那就别乱指定，让 Flutter 走默认回退。更稳的做法是只对弹窗里的数字、金额等关键文本做 fontFeatures 设置，保证等宽数字对齐，中文正文保持默认。另外注意 textScaler 的问题，有些鸿蒙设备系统字体缩放比例会设得很大，Dialog 里的 Row 按钮可能被挤爆，建议在弹窗层把 textScaler 固定一下，或者用 FittedBox 包住按钮文字。

动效方面，Dialog 默认的动画是 FadeTransition 加 ScaleTransition，从 0.85 放大到 1.0 同时淡入。这个在鸿蒙设备上我实际体感偏“软”，如果产品经理想要更干脆的弹出效果，可以用 showGeneralDialog 自定义过渡：

showGeneralDialog<void>( context: context, barrierDismissible: true, barrierLabel: '关闭', barrierColor: Colors.black.withValues(alpha: 0.5), transitionDuration: const Duration(milliseconds: 180), pageBuilder: (context, animation, secondaryAnimation) { return const Center(child: Dialog(...)); }, transitionBuilder: (context, animation, secondaryAnimation, child) { final curved = CurvedAnimation(parent: animation, curve: Curves.easeOutCubic); return FadeTransition( opacity: curved, child: ScaleTransition( scale: Tween<double>(begin: 0.92, end: 1).animate(curved), child: child, ), ); }, );

transitionDuration 设成 180ms 到 220ms 比较合适，太短显得突兀，太长在低端鸿蒙设备上会因为引擎丢帧显得卡。实测在 2K 分辨率的鸿蒙平板上，动画时长超过 300ms 且页面内容较复杂时，会出现明显的帧率波动。所以弹窗内容能多简单就多简单，复杂内容等弹层出现后再异步加载。

3. BottomSheet 的两种形态：模态与非模态的选择

3.1 showModalBottomSheet：隔离式弹层，多数场景都选它

BottomSheet 是 Flutter 里最被低估的一种交互组件。它从屏幕底部滑入，常用于菜单选择、筛选条件、评论编辑等场景。Flutter 提供了两个入口：showModalBottomSheet 和 showBottomSheet，它们的行为差别很大，选错会直接影响产品体验。

showModalBottomSheet 是一个模态弹层，弹出来后，背后的页面会被蒙住，用户必须关掉面板才能跟底层页面交互，这跟 Dialog 的行为一致。它的实现也是通过 OverlayEntry 插入 Overlay，而不是挂在 Scaffold 上。我通常优先用它，因为它隔离性好，旋转屏幕、切后台再回来，状态都能稳定保持。

来看带圆角头部和拖拽把手的常用写法：

Future<T?> showCommonBottomSheet<T>( BuildContext context, { required Widget child, double heightFactor = 0.65, }) { return showModalBottomSheet<T>( context: context, useRootNavigator: true, isScrollControlled: true, isDismissible: true, enableDrag: true, backgroundColor: Colors.transparent, builder: (context) { return FractionallySizedBox( heightFactor: heightFactor, child: Container( decoration: const BoxDecoration( color: Colors.white, borderRadius: BorderRadius.vertical(top: Radius.circular(24)), ), child: Column( children: [ const DragHandle(), Expanded(child: child), ], ), ), ); }, ); }

这里最关键的是 isScrollControlled。默认情况下，showModalBottomSheet 的高度是屏幕高度的 9/16，这是一个让人困惑的默认值，你可以理解为内容自适应，但实际很多场景下不够用。把 isScrollControlled 设为 true 之后，子组件可以自由决定高度，配合 FractionallySizedBox 或者 SizedBox 指定精确高度。如果弹层里要放 TextField，这一步是必须的，否则键盘一弹，输入框直接被顶出屏幕。

Draghandle 就是那个拖拽把手，我一般单独抽一个小组件：一个宽 36、高 4 的圆角矩形，颜色用灰色 300，顶部间距 12。注意这个把手只做视觉提示，真正的拖拽关闭逻辑由 showModalBottomSheet 自带的 enableDrag 处理。你要是自己给把手加 GestureDetector，反而可能会抢手势，导致面板拖不动。

3.2 showBottomSheet：挂在 Scaffold 上的持久面板

另一种是 showBottomSheet，它不通过 Overlay 实现，而是通过 Scaffold 的 BottomSheet 机制实现。它弹出后底层页面仍然可操作，属于非模态面板，适合那种“边看列表边编辑筛选条件”的场景。

这两者的选择，我的经验是：凡是需要用户“停下当前操作、做完选择再走”的场景，一律用 showModalBottomSheet；如果弹层只是一个辅助工具，用户可能要在弹层和页面之间来回操作，才考虑 showBottomSheet。但 showBottomSheet 有个问题，它跟 Scaffold 绑定，如果页面本身结构复杂（比如 TabBarView 切换），面板状态很容易被页面的重建打断。所以我的建议是：默认全部用 showModalBottomSheet，只在极少数明确需要非模态的场景才用 showBottomSheet，并且在代码里注释清楚为什么不用模态版本，防止后来人顺手改掉。

另外，showBottomSheet 返回的是 PersistentBottomSheetController，你可以留着这个控制器，用 controller.show() 和 controller.close() 手动控制面板的显示和关闭。不过这样做的时候要留意页面的生命周期，页面即将销毁时如果有未关闭的面板，最好在 dispose 里处理掉，否则会在控制台看到一堆 “A dismissed Dismissible widget” 之类的警告。

3.3 键盘弹起、安全区与手势冲突的处理

BottomSheet 比 Dialog 更容易踩的坑有三个，我一个个说。

第一个是键盘。弹层里有 TextField 时，键盘弹起会把 BottomSheet 推上去。处理方式是在 BottomSheet 内容的最外层用 viewInsets 感知键盘高度，然后给面板底部增加相同高度的 padding，否则输入框会被键盘压住：

builder: (context) { final bottomInset = MediaQuery.of(context).viewInsets.bottom; return Padding( padding: EdgeInsets.only(bottom: bottomInset), child: FractionallySizedBox( heightFactor: heightFactor, child: child, ), ); }

这里有个细节：拿到 viewInsets 的 context 必须在 BottomSheet 的 builder 内部，用外层的 context 拿到的永远是 0。另外，普通手机键盘高度通常在 280 到 350 之间，如果你发现 padding 加了但输入框还是被挡，检查一下是不是弹层本身高度超过了键盘收起后的可视区域。

第二个是安全区。鸿蒙设备底部有手势条，状态栏顶部有挖孔或者圆角，如果你的 BottomSheet 内容一直延伸到底部，会出现按钮被手势条挡住的问题。我在 OpenHarmony 上实测，ohos 分支对 MediaQuery.padding 的适配大部分版本是正常的，但偶尔某些版本会返回 0。安全做法是自己在面板容器里再套一层 SafeArea：

SafeArea( top: false, child: Column( children: [ /* 面板内容 */ ], ), )

第三个是手势冲突。BottomSheet 自带向下拖拽关闭的手势，如果弹层里放了一个竖直方向的 Slider 或者嵌套的 ListView，用户会发现在 ListView 顶部再下拉时，先触发的是 BottomSheet 关闭而不是列表的滚动。这个问题有一定概率在鸿蒙设备上更严重，因为鸿蒙上的事件分发时机跟 Android 不完全一致。我的处理办法：如果面板内容必须可滚动，就关闭 enableDrag，把关闭逻辑完全交给遮罩点击和显式按钮；如果内容不可滚动，保留 enableDrag，体验最好。你要在两者之间做取舍，别想着既保留拖拽又完全避免冲突。

4. 实操：搭一个带加载态和回调的完整弹出交互

4.1 工程初始化与 ohos 分支配置

讲完原理和单个组件的写法，我来说一个完整的实操过程。假设我们现在要在 OpenHarmony 上做一个“选择收货地址”的 BottomSheet，效果是：用户点击页面按钮，底部弹出地址列表，列表带加载状态，加载完成显示地址项，点击某项后关闭弹层并把结果回传给页面。

首先是环境。OpenHarmony 的 Flutter 开发，需要你用 ohos 分支的 Flutter SDK 替换官方 SDK。配置方式不复杂，但有个细节要注意：从 ohos 分支克隆下来的 SDK 路径，需要在 Flutter 环境变量里替换掉原来的 SDK 路径，然后重新执行 flutter doctor。我第一次自己配的时候就因为 PATH 里旧的 SDK 没有清除，导致 flutter 命令一直用的是官方分支，编译出来的产物在鸿蒙设备上跑不起来。装好之后检查一下：

flutter doctor -v

确认 Flutter 路径已经指向 ohos 分支，再看有没有提示 OpenHarmony toolchain 相关的信息。这一步没问题，再开新工程。你不确定当前 Flutter 是哪个分支，用 flutter --version 看一眼，一般 ohos 分支版本号后面会带 -ohos 后缀。

工程里要加鸿蒙的壳工程。当前 ohos 分支的模板一般会生成一个独立的鸿蒙工程目录（比如 harmony），这个目录是一个完整的 DevEco Studio 工程。你后续如果要在 Flutter 里调用鸿蒙原生能力（比如拉起鸿蒙的 IAP 支付、读图库），就是通过 MethodChannel 在这个壳工程里写原生逻辑。这部分跟你在 Android 上写平台通道的思路完全一致，只是宿主工程换成了鸿蒙的工程结构。

4.2 核心代码：弹层工具类与调用链

回到刚才的场景，我先封装一个统一的底部弹层组件。这个组件同时承担了加载、数据展示、回调三个职责：

class AddressPickerSheet extends StatefulWidget { const AddressPickerSheet({super.key}); @override State<AddressPickerSheet> createState() => _AddressPickerSheetState(); } class _AddressPickerSheetState extends State<AddressPickerSheet> { late Future<List<Address>> _future; Address? _selected; @override void initState() { super.initState(); _future = fetchAddressList(); // 网络请求 } @override Widget build(BuildContext context) { final bottomInset = MediaQuery.of(context).viewInsets.bottom; return Padding( padding: EdgeInsets.only(bottom: bottomInset), child: FractionallySizedBox( heightFactor: 0.6, child: Container( decoration: const BoxDecoration( color: Colors.white, borderRadius: BorderRadius.vertical(top: Radius.circular(24)), ), child: Column( children: [ const DragHandle(), const Text('选择收货地址', style: TextStyle(fontSize: 16, fontWeight: FontWeight.w600)), const SizedBox(height: 4), Expanded( child: FutureBuilder<List<Address>>( future: _future, builder: (context, snapshot) { if (snapshot.connectionState != ConnectionState.done) { return const Center(child: CircularProgressIndicator()); } if (snapshot.hasError) { return Center(child: Text('加载失败：${snapshot.error}')); } final items = snapshot.data ?? []; if (items.isEmpty) { return const Center(child: Text('暂无收货地址')); } return ListView.separated( itemCount: items.length, separatorBuilder: (_, __) => const Divider(height: 1, indent: 16, endIndent: 16), itemBuilder: (context, index) { final item = items[index]; return ListTile( title: Text(item.name), subtitle: Text(item.detail), trailing: _selected == item ? const Icon(Icons.check) : null, onTap: () { setState(() => _selected = item); Navigator.pop(context, item); }, ); }, ); }, ), ), ], ), ), ), ); } }

调用方代码很简单：

Future<void> _onPickAddress() async { final address = await showModalBottomSheet<Address>( context: context, useRootNavigator: true, isScrollControlled: true, backgroundColor: Colors.transparent, builder: (context) => const AddressPickerSheet(), ); if (address != null) { setState(() => _currentAddress = address); } }

这里有个关键设计：网络请求放在 State 的 initState 里发起，而不是在 builder 里发起。如果你在 build 方法里直接写 Future 赋值，每次重建都会重新请求，容易造成多余的网络调用。FutureBuilder 的 connectionState 会帮你区分加载中、成功、失败三个状态。加载动画用 CircularProgressIndicator 就够了，在鸿蒙上记得给弹层内容的宽度留足，Loading 转圈组件默认比较小，实际观感可以接受。

另外，FutureBuilder 的 future 一定要在 initState 里赋值并保存到字段，如果你在 build 里 new 一个 Future 传进去，每次 rebuild 都会重新创建 future，加载状态就会反复横跳。这个是我见过最多人踩的坑，不只是弹窗场景，任何 FutureBuilder 都是如此。

4.3 实测调优：高度、圆角与动画曲线

这个 Demo 跑上鸿蒙真机之后，还有几个参数我实际调过，记录一下。

高度：heightFactor 我最终定在 0.55 到 0.6 之间。低于 0.5 时地址列表可能显示不完整；高于 0.75 时在平板上会显得面板过重，用户感知上不像“底部弹层”而像“整个页面”。如果你的列表内容是可变的，建议用 ConstrainedBox 限制最大高度而不是固定高度因子。比如：

ConstrainedBox( constraints: BoxConstraints(maxHeight: MediaQuery.of(context).size.height * 0.7), child: child, )

这样内容少时面板自动收缩，内容多时最多占屏幕的 70%，不会出现只有一条数据却弹出一个超大面板的尴尬情况。

圆角：顶部圆角 24 在鸿蒙设备上跟系统原生弹层视觉比较接近。圆角小于 16 会显得生硬，大于 28 在屏幕较窄的设备上会露出两侧弧度过大的问题。如果你的弹层内容里有图片，记得把图片的顶部也裁成同样的圆角，方法是在图片外层包 ClipRRect(borderRadius: BorderRadius.vertical(top: Radius.circular(24)))。

动画曲线：showModalBottomSheet 默认的曲线是标准 ease 曲线，整体偏快。如果你想让弹层更有“顺滑上升”的感觉，可以包一层 AnimatedPadding 或者自定义 transitionAnimationController。不过我不建议在鸿蒙上频繁自定义 BottomSheet 动画，因为底层 Overlay 动画跟系统窗口动画叠在一起，自定义不当会造成明显的掉帧。保持默认，或者至多调一下 duration，是最稳妥的方案。

5. 常见问题排查与经验速查

5.1 弹层不显示，先查这三个位置

我在鸿蒙端遇到弹层不显示，基本逃不出三个原因。

第一是 context 失效。异步回调拿到 context 之后直接 showDialog，页面已经被系统回收。排查方法：弹窗之前打印 context.mounted，如果为 false，就是这里的问题。修复方式是在异步之后加 mounted 检查，或者用 State 里的 this.context，而不是回调参数里的 context。

第二是弹层被插到了错误的 Overlay。场景多半是自建 Navigator 跟根 Navigator 混用。记住前面的经验：showDialog 和 showModalBottomSheet 都显式传 useRootNavigator: true。你可以把弹层里的 Navigator.of(context) 打出来，看看它属于哪个 Navigator 栈。如果发现弹层显示在页面下面，基本就是这个原因。

第三是 z 序被原生窗口盖住。OpenHarmony 上 Flutter 应用如果同时存在原生页面组件（比如某些鸿蒙原生能力弹出的壳页面），Flutter 的 Overlay 是绘制在 FlutterView 内部的，原生窗口出现在 FlutterView 上层时，弹层会被盖住。这种情况无法靠 Flutter 代码解决，需要检查你的应用里有没有把原生页面以 addView 的方式叠在 FlutterView 上面。我有个项目接了扫码 SDK，扫完码回来弹层偶尔消失，排查到最后是扫码 SDK 的原生 View 遮挡了 Flutter 的一部分。

5.2 弹层被状态栏或导航条挡住

这个问题在鸿蒙设备上比 Android 更常见，因为鸿蒙设备底部的手势条区域比较大，不同厂商的偏移还不一样。如果 BottomSheet 底部按钮总是被手势条挡住，按下面的顺序排查。

先看 MediaQuery 的 padding 是否正确：

final padding = MediaQuery.of(context).padding; debugPrint('bottom padding = ${padding.bottom}');

如果 padding.bottom 为 0，说明 ohos 分支对这个设备的安全区适配有问题，你需要自己兜底，从系统侧拿安全区高度，或者用 BottomSheet 固定的底部安全高度（常见设备在 16 到 34 之间）。如果 padding 正常，那就检查你的弹层容器有没有被 SafeArea 包住。注意 SafeArea 不要加 top: false 就完事，底部必须保留：

SafeArea( top: false, bottom: true, minimum: const EdgeInsets.only(bottom: 16), child: child, )

5.3 返回键与关闭逻辑的细节

Android 和鸿蒙都有物理返回键（鸿蒙设备还有侧滑返回手势），弹层打开时按返回键，默认行为是关闭弹层而不是返回页面。Flutter 的 PopScope 可以控制这个行为，但在弹层场景里，我建议优先依赖默认行为，因为 showModalBottomSheet 本身已经监听了返回手势。

有一个细节容易忽略：当 BottomSheet 内容里有 TextField，并且键盘弹起时，按返回键应该先收键盘再关弹层。Flutter 的默认行为是键盘优先，但如果你的面板设置了 obscureText 之类的输入组件，个别版本会出现“返回键直接把弹层关了，键盘还留在屏幕上”的 bug。排查和规避方式是给 TextField 所在页面包一层 PopScope，在 onPopInvoked 里先 FocusScope.unfocus：

PopScope( onPopInvoked: (didPop) { if (!didPop) { FocusScope.of(context).unfocus(); } }, child: child, )

5.4 常见问题速查表

我在 OpenHarmony 上折腾 Flutter 弹层最大的体会是：这些组件本身不难，难的是跨端的边界情况太多，安全区、键盘、手势条、路由栈，任何一个环节换一个系统就可能翻车。所以我一直建议团队里的同学，凡是涉及弹出层的新功能，别只在模拟器里测，一定要上真机，而且最好在带手势条的全面屏设备上测一遍。弹层相关的 bug，绝大部分是模拟器上永远复现不出来的。

最后再分享一个小技巧：把你的 Dialog 和 BottomSheet 都封装成统一的工具函数，所有弹层参数（是否可点击遮罩关闭、是否开启动画、圆角大小、遮罩颜色）全部收敛到一处配置。这样换设备、换系统适配的时候，你只需要改一个文件，而不是满项目找 showDialog 调用点。这个习惯帮我省了大量的排查时间，值得坚持。