Flutter鸿蒙适配实战：首页顶部横幅模块从0到1

我第一次在 HarmonyOS 6.0 真机上跑通这个用 Flutter 开发的垃圾回收应用时，最顺利的并不是复杂的地图回收点位，也不是微信登录，反而是首页最不起眼的顶部横幅模块。这让团队所有人都很意外，因为大部分人一听到“Flutter + 鸿蒙”就默认会有一堆编译问题、渲染问题、异步问题，但真正把模块拆开之后你会发现，只要前期把数据模型、图片加载、手势交互和缓存策略想清楚，这套页面在鸿蒙桌面上反而比在公司老的 Android 测试机上表现得更稳定。

这篇文章就以这个“垃圾回收 App 的顶部横幅模块”为具体案例，完整讲一遍从需求拆解、Flutter 工程配置、UI 实现到鸿蒙 6.0 真机调试的完整链路。如果你正打算做 Flutter 应用迁移到鸿蒙，或者刚好要处理首页轮播图这类基础模块，可以按这篇的经验直接抄作业。文章不会只给你几段代码，而是把每一步背后的取舍、踩过的坑、排查方法都写清楚，方便你在自己的项目中避开同样的问题。

1. 需求解读：顶部横幅在垃圾回收 App 里到底承担什么角色

很多人做首页横幅时，第一反应就是“拿个 PageView 放几张图，加个小圆点，完事”。但实际放到垃圾回收应用里，顶部横幅并不是单纯拿出来好看的，它对用户转化、信息触达和品牌引导都有非常明确的业务作用。不把这个需求想清楚，后面实现再漂亮也没用。

1.1 用户的真实使用路径

这个 App 的使用场景通常是这样的：用户打开首页，第一眼看到的就是顶部横幅区。在这个区域内，用户可能会看到四类信息：

1. 官方运营活动，比如“旧衣回收满 10 公斤返 20 元优惠券”；
2. 垃圾分类指南，用插画形式告诉用户“塑料瓶、纸箱、旧家电分别属于什么分类”；
3. 回收员招募公告，点击之后进入报名页；
4. 附近回收网点的临时调整通知，比如“本周六站点暂停服务”。

这些内容有个共同特点：更新频率高、有明确的点击目标和落地页、图片设计感强。如果按普通列表或者文字通知的形式放，用户根本不会注意，运营同学也无法把入口做得很吸睛。顶部的轮播横幅就是承担“高位曝光 + 点击导入”的模块。

也就是说，这个模块并不只是一个“UI 组件”，而是一个包含数据下发、图片加载、轮播控制、埋点统计、深链跳转的完整业务模块。我在做需求梳理时，把所有相关方拉到一个群后，才意识到项目真正的复杂度不在轮播动画，而是在如何让运营侧能高效配置、客户端能稳定加载、异常情况不至于白屏。

1.2 为什么选择 Flutter 来碰鸿蒙 6.0

团队选择 Flutter 的原因很现实：已有 Android 和 iOS 两套代码，其中 Flutter 实现的核心业务已经占到 70% 以上，如果鸿蒙 6.0 单独走 ArkUI 重写，人力成本至少翻三倍。Flutter 做跨端的优势在于，UI 层渲染由 Flutter 引擎自己控制，底层平台差异被屏蔽在少量平台通道代码中，所以把现有 Flutter 模块迁到鸿蒙，理论上只要解决两个问题：一是 Flutter 引擎能否在 HarmonyOS 6.0 上跑起来，二是平台相关的插件能不能有对应适配。

顶部横幅模块恰恰是对这两个问题都比较友好的模块。它不依赖地图、相机、短信等重系统服务，只涉及网络请求、图片加载、页面跳转、事件埋点，而这些能力在鸿蒙上都有相对成熟的 Flutter 插件或平台通道方案。更关键的是，这个模块只在首页第一屏展示，性能压力不大，即使鸿蒙上的 Flutter 引擎做不到 120fps，也不会有明显感知。

所以我给团队的建议是：如果想把 Flutter 业务过渡到鸿蒙，可以从顶部横幅这种“UI 展示为主、平台依赖少”的模块入手，先打通链路，再逐步替换地图、支付、扫码等重插件。这个节奏比第一版就直接全量上鸿蒙要安全得多。

1.3 横幅模块的核心需求清单

在动手写代码之前，我先把需求拆成了四层，每一层都有明确验收标准：

• 展示层：支持单图、多图轮播；有标题和副标题展示区域；支持指示器；横竖屏不崩溃。
• 数据层：接口返回横幅列表，字段包含 bannerId、跳转链接、图片地址、排序权重、展示时长；接口异常时使用本地缓存兜底。
• 交互层：轮播自动播放，用户按住暂停，松手恢复；滑动时不触发跳转；点击横幅跳到对应落地页；部分运营位需要登录态。
• 性能层：首帧不需要等图片全部加载完，使用内存缓存 + 磁盘缓存，避免列表滑动卡顿；图片不能 OOM；切到后台后轮播计时器停止，回到前台恢复。

这四条看起来简单，但每一项在鸿蒙上都会遇到一些细节问题。比如轮播自动播放如果处理不当，页面切到后台再回来时可能会出现连续快速翻页的“抽风”现象；又比如图片缓存用的路径在鸿蒙上可能跟 Android 不一样，导致缓存失效。这些我都会在后面的章节里具体说明。

2. 工程准备：让 Flutter 工程先跑在 HarmonyOS 6.0 上

顶部横幅模块要做完，第一步必须是让 Flutter 工程能在 HarmonyOS 6.0 上编译、安装、运行。这个环节如果不顺，后面的 UI 代码全是空中楼阁。鸿蒙 6.0 的 SDK 版本和 Flutter 引擎的适配版本之间有严格的对应关系，很多编译错误其实都是版本不匹配造成的。

2.1 Flutter 的鸿蒙适配分支怎么选

目前社区已经有面向 OpenHarmony/HarmonyOS 的 Flutter 适配分支，通常在官方 Flutter SDK 的基础上增加一个“ohos”目录，用来承载鸿蒙原生壳工程。选分支的时候不能只看版本号，要看三件事：

1. 是否支持 Stage 模型。旧版 Fa 模型在鸿蒙开发里已经边缘化，顶部横幅如果要用鸿蒙原生页面跳转，用 Stage 模型更省心。
2. 引擎编译产物是否包含 ArkTS loader。Flutter 插件在鸿蒙上运行，需要从 Dart 层通过通道调到 ArkTS 层，社区适配分支如果没把这条链路打通，很多插件都无法使用。
3. 网络库和图片库是否适配。横幅模块大量依赖图片加载，如果分支没有处理 downloadManager 或者 socket 适配，图片会一直转圈。

我这边实测下来，建议直接用社区维护时长较久、issue 回复率高的 flutter_flutter 鸿蒙分支。具体版本号不写死，因为这类分支更新很快，但你 clone 时要注意看分支对应的是 Flutter 3.13、3.16 还是 3.22，不同大版本对 Dart 语言的约束会有差异。最好和团队现有 Flutter 版本保持一致，便于同步主工程的代码。

2.2 创建工程与目录结构

工程创建过程和普通 Flutter 工程相似，但多了鸿蒙壳工程相关文件和资源配置。一个可用项目的核心目录大约是这样的：

bash复制my_recycling_app/
├─ lib/
│  ├─ main.dart
│  ├─ pages/
│  │  └─ home/
│  │     └─ banner/
│  ├─ models/
│  │  └─ banner_item.dart
│  └─ services/
│     └─ banner_service.dart
├─ ohos/
│  ├─ entry/
│  │  ├─ src/main/
│  │  │  ├─ ets/
│  │  │  ├─ resources/
│  │  │  └─ module.json5
│  └─ build-profile.json5
├─ pubspec.yaml
└─ build.gradle

这里有一个比较重要的细节：ohos 目录中的壳工程必须保留 module.json5 中的包名和签名信息，不能直接拿 Android 的 applicationId 去代替。鸿蒙的包名规则和 Android 不完全一致，如果包名不一致，真机安装的时候会提示“安装失败”，而且很难定位到原因。

我在第一次创建工程时就是没注意这点，把 Android 的 com.example.recycling 直接复制过去，结果 hvigor 编译通过，安装到鸿蒙 6.0 模拟器时反复失败。后来查了日志才发现是 module.json5 里的 bundleName 和签名证书的包名不一致。

2.3 引擎链接与依赖管理

Flutter 工程的依赖管理还是用 pubspec.yaml，但在鸿蒙编译时，需要把 Flutter 引擎作为本地依赖链进壳工程。也就是说，你拉取的鸿蒙 Flutter 分支会提供对应的 flutter.har 或引擎源码路径，壳工程通过 build-profile.json5 里的 dependencies 引用它，而不是从远程 maven 仓库自动拉取。

普通依赖则建议做最小化处理。在横幅模块里，我尽量只使用 Dart 层可以完成的方案，比如网络请求就用 dio，图片缓存用 cached_network_image。这两个库在 Flutter 社区生态里已经很成熟，鸿蒙适配分支一般也会对它们的平台通道做兼容。如果遇到 MissingPluginException，不要急着换库，先检查插件在鸿蒙壳工程里有没有注册进入。

另外要注意，鸿蒙侧的网络权限需要在 module.json5 的 requestPermissions 里显式声明。否则你会出现一个诡异现象：Android 上图片能加载，鸿蒙上一直显示加载失败，抓日志也看不到明显报错，其实就是网络权限没开。而且鸿蒙对明文网络请求默认限制比较严格，如果后端图片接口是 http://，还需要在网络安全配置里放开，否则也会加载失败。我后面会在常见问题表里再列一次。

3. 顶部横幅模块的 UI 设计与数据模型

工程跑通后，接下来要考虑的就是 UI 结构和数据模型。不要一上来就写 PageView，先把页面层级、尺寸、数据字段定好，后面做三分只花一分力。

3.1 先画清楚“一屏”的层级

顶部横幅在首页的位置是固定的：顶部状态栏下方、搜索框上方。它的高度不能随便定，要结合设计稿和真机适配。我这边设计稿给的是 160dp 高，宽度为屏幕宽度。但鸿蒙 6.0 上有各种挖孔屏、刘海屏，如果直接按设计稿写死高度，有些设备上横幅会被状态栏重叠。

所以建议外层套一个 SafeArea，再在里面放横幅容器。横幅本体用 AspectRatio 或者固定高度配合 MediaQuery 来做。我最终选择的是固定高度 160，加上左右 12dp 的 margin，然后用 ClipRRect 把圆角裁出来。这样既符合运营同学对视觉的要求，又不至于在小屏上把顶部区域撑得太大。

层级关系大致是：

dart复制Widget buildBannerArea(List<BannerItem> banners) {
  return SafeArea(
    bottom: false,
    child: Padding(
      padding: const EdgeInsets.symmetric(horizontal: 12),
      child: ClipRRect(
        borderRadius: BorderRadius.circular(16),
        child: SizedBox(
          height: 160,
          child: BannerSwiper(banners: banners),
        ),
      ),
    ),
  );
}

bottom: false 的原因是这个模块只关心上方挖孔区域，底部有底部导航栏负责处理安全区，不需要在这里额外加边距。

指示器也不要放在横幅外面，那样容易产生“视觉断层”。优雅的做法是用 Stack 把指示器叠在横幅右下角，背景用半透明黑色圆角容器包裹，这样不管图片是亮色还是暗色，指示器都能看清。

3.2 数据与接口设计

接口返回格式建议不要直接塞一堆 JSON 字段到 UI 层，先抽出一个干净的 BannerItem 模型。我在项目里是这么写的：

dart复制class BannerItem {
  final String id;
  final String title;
  final String subtitle;
  final String imageUrl;
  final String jumpUrl;
  final int duration;
  final int sort;

  BannerItem({
    required this.id,
    required this.title,
    required this.subtitle,
    required this.imageUrl,
    required this.jumpUrl,
    this.duration = 4,
    this.sort = 0,
  });

  factory BannerItem.fromJson(Map<String, dynamic> json) {
    return BannerItem(
      id: json['id']?.toString() ?? '',
      title: json['title'] ?? '',
      subtitle: json['subtitle'] ?? '',
      imageUrl: json['imageUrl'] ?? '',
      jumpUrl: json['jumpUrl'] ?? '',
      duration: json['duration'] ?? 4,
      sort: json['sort'] ?? 0,
    );
  }
}

这里有个不显眼但很重要的字段：duration。不同横幅的展示时长可能不一样，运营希望重要活动多停留 2 秒，普通科普图片待 3 秒就够了。如果全模块共用一个轮播间隔，运营侧就得靠视频或动画来“欺骗”用户停留，体验很差。所以我让每个 banner 都带有自己的展示时长，轮播到下一张时读取当前页的 duration 来重置计时器。

接口异常时怎么办？不要直接给一个空的列表，那样首页会有一块空白很难看。我在本地预置了一份默认横幅数据，包含 3 张图片和默认落地页，接口超时或返回空数组时直接走本地默认配置。这个策略对“临时断网”场景非常有效，至少用户打开首页时视觉上是完整的。

3.3 主题、字号与安全区适配

Flutter 的 ThemeData 在鸿蒙上会有一点色差问题，尤其是鸿蒙系统开启了“深色模式”后，如果 Theme 没有适配，横幅上的标题文字可能会看不清。我处理的方法是：在横幅内部不继承全局主题，而是自己定义一层固定的文字样式。

图片本身已经具有丰富色彩，所以叠在图片上的标题不能直接用白色，也不能直接用黑色。我一般会在图片底部加一层从透明到黑色的渐变遮罩，然后文字统一用白色，这样不管运营传的是亮色图还是暗色图，文字可读性都有保障。

安全区适配除了第一节提到的 SafeArea 之外，还要关注鸿蒙上的“应用内旋屏”。垃圾回收 App 虽然业务上以竖屏为主，但用户可能开启了自动旋转，横屏时横幅高度不变、宽度变大，图片会横向拉伸。为了避免变形，图片用 BoxFit.cover，同时限制最大显示宽度为逻辑宽度的 1.5 倍，超出部分裁掉，以保证主体内容不变形。

我在真机上实测过，鸿蒙 6.0 对于屏幕旋转的处理比早期版本要好，但 Flutter 引擎在旋转瞬间会有一个白屏或闪屏的现象。在横幅模块这种高频出现的场景里，建议在 main.dart 里锁定竖屏，除非产品明确要求支持横屏。

4. 轮播与交互实现：从静态横幅到可运营模块

基础 UI 和数据模型定好之后，进入核心实现部分。顶部横幅最重要的交互是两件事：自动轮播和手动滑动。这两个操作会互相干扰，处理不好会出现常见的“手一放就跳页”“后台回来疯狂翻页”等 bug。

4.1 用 PageView 还是自研横向滑动

很多教程会建议直接用 PageView.builder，我也同意，但前提是你得理解它为什么适合这场景。PageView 内部维护了一个 PageController，天然支持一页一页滑动，配合物理滚动精度和页面缓存属性，几乎不用自己写手势判断。

唯一的弊端是：如果只有一页或两页，PageView 在视觉上无法做到“无限循环”的直观效果。业内常见的方案是把首页的最后一个元素复制到开头、第一个元素复制到结尾，形成虚拟无限轮播，然后监听滑动位置跳转。

顶部横幅的轮播数量通常不会太多，我建议直接用最简单的“到达最后一页后跳回第一页”方式，不追求丝滑的无限循环。因为垃圾回收应用里的横幅数量通常在 3 到 5 张，即使最后瞬间回滚到第一页，用户也只是轻微不适，完全能接受。无限循环方案还容易引入页面跳变闪烁，维护成本更高。

核心结构如下：

dart复制class BannerSwiper extends StatefulWidget {
  final List<BannerItem> banners;
  const BannerSwiper({super.key, required this.banners});
  @override
  State<BannerSwiper> createState() => _BannerSwiperState();
}

class _BannerSwiperState extends State<BannerSwiper> {
  late final PageController _pageController;
  Timer? _timer;
  int _current = 0;

  @override
  void initState() {
    super.initState();
    _pageController = PageController(viewportFraction: 1);
    _startTimer();
  }

  void _startTimer() {
    _timer?.cancel();
    if (widget.banners.length < 2) return;
    final duration = widget.banners[_current].duration;
    _timer = Timer.periodic(Duration(seconds: duration), (timer) {
      _nextPage();
    });
  }

  void _nextPage() {
    if (!mounted || widget.banners.isEmpty) return;
    final next = (_current + 1) % widget.banners.length;
    _pageController.animateToPage(
      next,
      duration: const Duration(milliseconds: 400),
      curve: Curves.easeInOut,
    );
  }
  // 略
}

_startTimer 里的核心思路是：每次翻页后都读取当前 banner 的 duration 来重置定时器，这样一个 5 秒的运营位后面不会因为前面一个 3 秒的 banner 而乱节奏。

4.2 自动播放与手势打断

自动播放最大的坑是这个场景：用户在手动滑动过程中，Timer 还在计时，结果手指还没松开，页面就被 Timer 强行触发了 animateToPage，造成手势和动画打架，体验非常割裂。解决办法是在手势开始时取消 Timer，手势结束时重新启动 Timer，并且重置页码索引。

监听手势有两个位置：NotificationListener 包裹 PageView，或者监听 PageController 的滑动状态。我推荐第一种，更直观：

dart复制NotificationListener<UserScrollNotification>( 
  onNotification: (notification) {
    if (notification.direction == ScrollDirection.forward ||
        notification.direction == ScrollDirection.reverse) {
      _timer?.cancel();
    } else {
      _startTimer();
    }
    return false;
  },
  child: PageView.builder(...),
)

这样还有一个好处，用户上下滑动首页列表导致顶部横幅离开屏幕时，也能通过滚动通知感知到，从而停止 Timer，减少无谓的资源消耗。不过滚动通知只能感知手势，不能感知“页面是否可见”，所以还需要配合 Widget 的声明周期来控制 Timer。

在 Flutter 里，监听 App 前后台切换可以使用 WidgetsBindingObserver：

dart复制@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  if (state == AppLifecycleState.resumed) {
    _startTimer();
  } else if (state == AppLifecycleState.paused ||
      state == AppLifecycleState.inactive) {
    _timer?.cancel();
  }
}

这个处理很关键。如果不取消 Timer，应用退到后台之后，Dart 的 Timer 仍然会继续执行，直到操作系统冻结进程。用户再次回到前台时，页面位置和 Timer 的位置可能已经不同步，就会出现“刚打开应用就猛跳好几页”的现象。

4.3 图片加载、占位与内存回收

顶部横幅的图片基本来自运营后台，尺寸可能就是一张 750×360 的大图。如果直接塞到 Image.network，在低端机上加载三张图就可能出现内存告警。我统一使用 cached_network_image 的 CachedNetworkImageProvider，并设置 memCacheWidth 来控制缓存尺寸。

以推荐的 160dp 高度为例，按 2.0 像素密度换算，实际显示宽度大概是 360dp * 2.0 = 720px。但设计图有 margin 12 和 viewportFraction 1，最终图片宽度约 336dp，换算后 672px。我设置 memCacheWidth: 700，既保证清晰度，又避免解码一张 1080p 大图到内存里浪费空间。

dart复制Image(
  image: CachedNetworkImageProvider(
    banner.imageUrl,
    memCacheWidth: 700,
  ),
  fit: BoxFit.cover,
  errorBuilder: (context, error, stackTrace) => _buildPlaceholder(context),
  placeholder: (context, url) => _buildPlaceholder(context),
)

占位图建议用纯色容器加一个中央小图标，而不是直接用本地图片。因为本地图片要打进安装包，占空间不说，颜色调起来也麻烦。用一个带主题色的 Container 足够。

内存回收方面，横幅页面销毁时要把 PageController 释放，把 CachedNetworkImageProvider 的缓存按 bannerId 清理掉。虽然 cached_network_image 自带 LRU 缓存，但运营换图后旧图会一直存在磁盘里，时间久了会占几十兆空间。我在项目里做了一个简单的清理逻辑：每次请求新横幅列表成功后，将本地缓存中不再出现的图片 URL 逐个 evict 出来。

4.4 点击跳转与埋点

点击横幅跳转看起来简单，但这里有个需求细节：不同 banner 的跳转方式不一样，有的跳内部 WebView，有的跳原生商城页，有的只是展示一个弹窗。为了不把 BannerSwiper 组件和所有页面耦合，我在模型里增加一个 jumpType 字段，点击事件统一发到一个回调接口，由上层 HomePage 去分发。

Flutter 侧只需要把事件抛上去：

dart复制onTap: () {
  if (banner.jumpUrl.isEmpty) return;
  widget.onBannerTap?.call(banner);
}

埋点同样走回调，在组件内部只上报“banner 曝光数”和“banner 点击数”，不要在 BannerSwiper 里直接写业务统计代码。我把埋点参数统一封装到一个 BannerTrackHelper 里，组件只管展示和交互，统计的逻辑放在按钮回调里。

鸿蒙 6.0 上的页面跳转要注意 FlutterBoost 或原生路由栈是否兼容的问题。如果跳转用 Navigator.push，在纯 Flutter 页面里没问题，但如果落地页是鸿蒙原生页面，就需要通过平台通道调起鸿蒙的 Ability。顶部横幅本质上是一个 Flutter 入口，跨原生跳转时要注意 context 不能跨层乱用，传参也要走 JSON 序列化，不能直接传 Dart 对象。

5. HarmonyOS 6.0 真机调试与兼容问题实录

如果只在模拟器上跑，横幅模块一般三个月都不会出问题。但一旦发到真机上，各种兼容问题就会集中冒出来。这一章我整理了自己在鸿蒙 6.0 真机调试时遇到的典型问题和排查办法，都是可以直接参考的实战记录。

5.1 编译打包链路

鸿蒙 Flutter 工程的编译过程我用完整命令跑过，和 Android 类似但细节不同。关键命令是：

bash复制flutter pub get
hvigorw assembleHap --mode module -p product=default

hvigorw 是鸿蒙的构建工具，由 HarmonyOS SDK 提供。编译时最容易遇到的问题是 SDK 版本和 Flutter 适配分支中的“鸿蒙 SDK 最低版本”不一致。比如分支要求 API 12，但项目里配置的 compileSdkVersion 是 API 10，就会报一堆不兼容错误。

打包时尽量用 flutter build hap 或分支提供的专用脚本，不要直接改 gradle 参数。因为 Flutter 的鸿蒙引擎产物需要和 HAP 包一起打包，手动打包容易出现引擎文件缺失或放错目录的问题。

我踩过比较深的一个坑是：鸿蒙 Flutter 版本和当前 Flutter SDK 的 flutter tool 不匹配，导致 flutter pub get 可以过，但 build 命令一直找不到鸿蒙引擎。后来去看了分支说明才发现需要额外设置环境变量指定鸿蒙 Flutter SDK 的 path，并且要重新执行 flutter doctor 让工具链识别到 ohos 部分。

5.2 真机运行调试与日志

通过 hdc 连接真机后，日志可以这样查看：

bash复制hdc shell hilog | grep -i flutter

如果你在 Flutter 侧用了 debugPrint，日志会打出来。但鸿蒙系统的日志过滤规则比 Android 更细，默认日志等级是 Info，如果你的打印是 Debug，会被过滤，看不到输出。建议直接设置日志过滤为 debug 再抓。

横幅图片加载不出来时，我一般先用浏览器直接访问图片 URL，确认是不是图片服务本身对鸿蒙的 UA 做了限制。有次运营图片使用了某个防盗链服务，浏览器能打开，App 里一直 403，排查到最后发现是 referer 被策略拒绝。解决办法是让后端把图片服务接入到 App 的域名白名单里，或者在请求时配置合法的 referer。

鸿蒙对 http 明文流量的限制比较严格，如果后端还没有上 HTTPS，那确实很头疼。解决办法不是让客户端绕过限制，而是尽快让后端配置好 HTTPS 证书。这个话题不适合展开讲，但它确实是做跨端应用时逃不开的基础要求。

5.3 横幅模块高频问题速查表

下表是我自己整理的问题速查，按项目的实际出现频率做了排序，方便你遇到类似情况时快速定位。

这些问题的共同点在于，它们大多不是 Flutter 代码本身写错了，而是在“跨平台桥接”和“系统能力差异”这两层出了偏差。排查这类问题的思路一定要清晰：先分清是 Flutter 层问题、平台通道问题，还是操作系统限制。如果在 Flutter 里看到 MissingPluginException，99% 是插件没注册；如果在鸿蒙侧看到 permission denied，99% 是权限配置问题；只有当你确认 Flutter 层逻辑都正常时，才去考虑引擎适配和 API 版本的坑。

6. 写在最后：我的一点实操体会

这次做顶部横幅模块，最大的收获并不是写了一个轮播组件，而是找到了 Flutter 业务向鸿蒙迁移的安全切入点。顶部横幅模块麻雀虽小，五脏俱全，它涉及网络层、UI 层、缓存层、平台通道和生命周期管理，把这一条链路打通后，后续的地图模块、用户中心模块都能按照同样的方法往下推进。

我个人在实际操作中的体会是：做跨端适配时，不要一开始就追求“所有功能都完美兼容”，而应该把一个高频老实的模块打磨到可用状态，再逐步扩展。顶部横幅就是一个很好的起点，因为它对平台能力依赖少，但又能暴露很多兼容性问题，比如权限、字体、安全区、横竖屏、手势冲突。这些坑如果等到集成地图、支付时再一起爆出来，排查成本会翻好几倍。

还有一点小建议：无论以后鸿蒙适配分支怎么升级，做好关键模块的测试用例都很有必要。顶部横幅的测试用例不要只写 UI 能不能渲染，而是把断网、弱网、后台恢复、快速滑动、横竖屏切换这些实际场景都覆盖到。很多时候你感觉“明明没有改代码，怎么突然崩了”，其实都是某个底层 SDK 版本变化引起的，而完整的用例正好能在第一时间告诉你到底哪个环节出了问题。如果你也正在把 Flutter 项目迁到鸿蒙，希望这篇分享能帮你少踩几个坑。