Flutter × OpenHarmony跨端实践：欢迎页UI设计与工程化落地

在 OpenHarmony 设备上跑 Flutter，大家习惯性担心的是"到底能不能跑起来"。但真正做过一轮项目你就会发现，能不能跑只是门槛，拦不住你；真正决定交付质量和维护成本的，往往是那些看起来"不就几个控件嘛"的页面。我们内部这套车辆维修管理系统就是一个典型例子——Android 平板、OpenHarmony 工控机、工程师手机，三个平台要上一套 UI，最后选型落在 Flutter × OpenHarmony 上，原以为大坑会在业务逻辑，结果折腾最久的，却是打开 App 第一眼看到的欢迎区域。

这篇文章就围绕"欢迎区域 UI 设计与工程化实现"来拆。不是教你照抄一个 Splash，而是把那一小块界面的设计思路、目录规划、主题管理、状态衔接、真机适配全部讲透。适合两类人看：一类是准备在 OpenHarmony 上落地 Flutter 的移动端开发，另一类是正在做维修车间信息化、需要一套跨端 UI 框架的团队。

1. 车辆维修系统的跨端困局：为什么 Flutter 会被摆上桌面

1.1 维修车间的设备环境比想象中更"脏"

如果你没去过维修车间调研，你很难理解"一套客户端"这三个字有多重。我们项目初期整理出来的运行设备有三类：前台的接待平板、车间工位上的 RK3568 工控盒子、以及管理人员手上的 Android 手机。这三类设备分辨率、内存、系统版本差距极大，尤其工控盒子很多是供应商预装好的固件，系统版本五花八门，唯一的共同点是都能联网。

这种环境下，传统做法是每个端配一个原生团队，或者干脆 WebView 套壳。但车辆维修管理系统要高频使用摄像头识别车牌、扫码查配件、离线记录工单，WebView 在弱网和相机调动上体验很拉胯，多原生又养不起团队。我们评估 Flutter 的时候，核心诉求不是"跨端炫技"，而是希望 UI 只写一遍，业务逻辑集中在 Dart 层，相机、扫码、文件读写这类能力留在平台通道里做。事实证明这个方向是对的，但代价是 OpenHarmony 这一端需要自己趟路。

1.2 Flutter 在 OpenHarmony 上的真实位置

先说结论：Flutter 在 OpenHarmony 上不是 Google 官方支持的开箱即用，而是 OpenHarmony 社区维护的适配分支。这意味着你在 pub.dev 上看到的大量插件，默认并不会为 OpenHarmony 生成对应实现，依赖原生能力的插件必须等适配或者自己写对接层。

我们当时选型时做了一轮插件可用性盘点，结果如下表：

这个盘点非常劝退人，但也帮我们定了基调：UI 层要尽可能"纯 Flutter"，任何涉及原生能力的模块都封装到独立 service 里，后续换平台只换 service 实现。这个决定直接影响了欢迎区域的实现方式——欢迎页里不要塞任何平台相关代码，把配置读取、数据预取全部抽象成接口。

1.3 跨端不是终点，工程化才是

很多团队做跨端，做到"三端能编译出 APK/HAP"就收工了，后面每次改需求都要三端回归，改一个 UI 颜色要动几个地方。我们这次把工程化提在前面，核心就一句话：让"改 UI"这件事变成修改配置和局部 Widget，而不是全员扑上去改页面。

欢迎区域是这个理念最好的试验田：它页面小、生命周期短、但涉及的工程节点多——路由跳转、主题读取、数据预取、启动屏管理、平台通道初始化。把这些点逐个工程化，比在工单列表这种复杂页面里硬套架构要高效得多，也更容易沉淀出团队自己的规范。

2. 欢迎区域拆解：只做"闪一下"的页面为什么也值得工程化

2.1 欢迎页不是启动图，它承担了三件事

先纠正一个常见误区：欢迎区域不等于 Splash 启动图。启动图是系统加载 App 时显示的静态图，而欢迎区域是 Flutter 首帧渲染出来的第一个页面。在我们系统里，这个区域实际承担了三件事：

第一，品牌与场所认知。维修车间的平板开机后直接停在欢迎页，前台人员能一眼确认系统在线、版本正常。这个页面上要有明显的系统名、Logo、当前维修厂名称，甚至当天日期和天气这种轻量信息也有用，车间师傅对"今天热不热"比看版本号更有感觉。

第二，初始化进度反馈。App 启动后通常要读本地缓存、拉一次配置、检查登录态。这些操作加起来可能只有一两秒，但如果没有过渡反馈，用户会觉得卡死了。欢迎页把初始化拆成几个步骤，用列表或进度条展示"正在加载本地数据""正在校验登录状态"，用户就知道系统没死，只是还没准备好。

第三，入口分流。打开系统后不是所有人都有权限直接进工单，有的账号是只读角色，有的需要先选工位。欢迎页在初始化完成后根据角色和上一场会话，自动跳转登录页或工作台，这个决策不要放在 main 函数里，而是放在欢迎页的业务逻辑里，因为只有欢迎页最清楚当前设备的状态。

2.2 从视觉稿到 Widget 树：布局怎么拆

我们的 UI 稿是一个 1280×800 的横屏平板设计稿，结构分四块：顶部品牌区、中间欢迎语与状态区、底部操作入口区、右上角版本信息。翻译成 Flutter 布局时，我建议用 Stack 做全屏背景层，再用 SafeArea 包一个 Column，让层级清晰。

下面是我们欢迎页 Widget 树的简化版本：

dart复制class WelcomePage extends StatelessWidget {
  const WelcomePage({super.key, required this.vm});

  final WelcomeViewModel vm;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          // 背景层：品牌渐变 + 纹理
          const Positioned.fill(child: WelcomeBackground()),
          // 前景层：根据初始化状态切换内容
          SafeArea(
            child: Column(
              children: [
                const Spacer(),
                _buildBrandArea(context),
                const SizedBox(height: 32),
                _buildStatusPanel(vm),
                const Spacer(),
                _buildActionButtons(context),
                _buildVersionInfo(vm.version),
              ],
            ),
          ),
        ],
      ),
    );
  }
}

注意这里我把页面分成了"背景层"和"前景层"。背景层是纯装饰，不需要响应点击，应该实现 const 构造；前景层才是业务内容。这样的好处是后续换肤、换节日背景只动背景层，业务代码零改动。很多新人在欢迎页里把所有控件平铺在一个 Column 下面，看起来也能跑，但下次改需求你得在几百行 Widget 里找位置，这不是工程化该有的样子。

2.3 四个屏幕尺寸的适配策略

前面提过我们的运行设备有平板、工控屏、手机。分辨率从 480×854 的手机到 1920×1080 的工控屏都有，横竖屏还会切换，欢迎页必须靠自适应布局而不是靠设计稿坐标堆叠。

我的做法是用 LayoutBuilder 拿到约束后，把屏幕分成"紧凑型"和"宽裕型"两档，再决定品牌区字号、操作区是横向排还是纵向排：

dart复制LayoutBuilder(builder: (context, constraints) {
  final isWide = constraints.maxWidth > 720;
  final brandSize = isWide ? 48.0 : 32.0;
  return Column(
    children: [
      _BrandTitle(fontSize: brandSize),
      if (isWide)
        Row(children: [..._actionButtons])
      else
        Column(children: [..._actionButtons]),
    ],
  );
})

这样做不是为了花哨，而是为了减少真机调试次数。OpenHarmony 工控盒子和 Android 平板的可视区域差异很大，如果在布局阶段不把适配规则定死，后面就要靠一堆 MediaQuery.size.width 判断到处打补丁。使用 LayoutBuilder 只分两档，逻辑简单，真机验证时只需覆盖窄屏手机和平板两种形态，中间的分辨率交给 Flutter 的弹性布局自己消化。

还有一点：SafeArea 在不同平台的表现不一样。Android 手机有状态栏和底部手势条，OpenHarmony 工控屏通常没有状态栏，SafeArea 在某些设备上会顶出多余空白。所以我们在欢迎页里没有无脑依赖 SafeArea 的默认行为，而是通过 MediaQuery.removePadding 显式处理，工控屏上把顶部 padding 清掉，让背景层真正铺满整个屏幕。

2.4 加载状态与过场动画的细节

欢迎页的细节往往体现在状态切换上。初始化过程通常有"加载中—加载成功—跳转"三步，如果加载失败还要有"重试"按钮，这个状态机建议用枚举而不是 bool：

dart复制enum InitStatus { loading, success, failure }

class WelcomeViewModel extends ChangeNotifier {
  InitStatus status = InitStatus.loading;
  String? errorMessage;

  Future<void> init() async {
    status = InitStatus.loading;
    notifyListeners();
    try {
      await _preloadLocalData();
      await _fetchRemoteConfig();
      status = InitStatus.success;
    } catch (e) {
      status = InitStatus.failure;
      errorMessage = e.toString();
    }
    notifyListeners();
  }
}

过场动画我用了一个非常克制的方式：背景层的渐变从透明到不透明用 600ms，品牌区的 logo 用 ScaleTransition 从 0.96 放大到 1.0，整体控制在 900ms 以内。不要加弹跳、平抛这些花哨动效，维修车间场景下用户要的是"快、稳、准"，动画只是掩盖加载延迟的手段，不是主角。

状态切换时还有一个很容易被忽略的问题：如果初始化失败，错误信息不要用默认的红色大字体铺满屏幕，而是展示一个图标、一行说明和一个"重新加载"按钮。工控机上用户大部分不是程序员，看到英文报错只会认为系统坏了，直接拔电重启，反而容易把 Flutter 缓存搞坏，进入"启动失败—拔电—再失败"的恶性循环。

3. 把欢迎页嵌进工程体系：目录、路由、主题与状态的协作

3.1 按业务垂直切分目录，别做"结构正确"的摆设

很多 Flutter 项目的 lib 目录是按类型排的：pages、widgets、models、services。这种目录在项目小的时候很清晰，项目一大了，你想找"欢迎页相关的模型"要跨四个目录翻，相当痛苦。我们这次按业务线垂直切分，每个业务一个顶层文件夹，内部再按类型分：

text复制lib/
├── app/
│   ├── app.dart
│   ├── router/
│   └── theme/
├── core/
│   ├── network/
│   ├── storage/
│   └── platform/
├── features/
│   ├── welcome/
│   │   ├── data/
│   │   ├── domain/
│   │   ├── presentation/
│   │   └── welcome_page.dart
│   ├── work_order/
│   ├── inventory/
│   └── customer/
└── shared/
    ├── widgets/
    └── utils/

欢迎页的代码全部收在 features/welcome/ 下面，页面、状态管理、数据源一目了然。有人会觉得这么小的页面分四个子目录过重，但对团队来说，这不是为了欢迎页，而是为了给后面 work_order、inventory 立一个可复制的高质量模板。新人照这个模板写，不会出现"业务代码全堆在 page 里"的情况。

3.2 启动路由与登录态决策

欢迎页处于路由最前端，启动流程其实是"main → WelcomePage → 登录页/工作台"这条链路。我们用的是 go_router，欢迎页不放路由表里做重定向，而是在初始化完成后用 context.pushReplacement 跳转，原因是：欢迎页的跳转依赖初始化结果，而 go_router 的 redirect 更适合全局统一的登录态判断，不适合页面内请求完成后才决定的场景。

dart复制Future<void> _handleInitComplete(BuildContext context) async {
  final result = await vm.init();
  if (!context.mounted) return;
  if (result == _InitResult.success && vm.session != null) {
    context.pushReplacement('/workbench');
  } else {
    context.pushReplacement('/login');
  }
}

有个细节容易翻车：如果在 pushReplacement 之前做了耗时请求，用户可能会在请求期间手动点击返回键，把 App 退到后台。我们后来在欢迎页加了 PopScope 拦截返回，只有初始化完成后才允许退出，这个处理看起来小，但在工控机上特别关键——工控机的返回键有时候会被误触，退出欢迎页会导致后面所有流程都乱了。

3.3 ThemeExtension 管理品牌色：换肤不换页面

车辆维修系统有很多品牌相关的颜色，比如主色、警示色、工单状态色。我们把这些颜色放在 ThemeExtension 里，而不是散落在各页面写死：

dart复制class AppColors extends ThemeExtension<AppColors> {
  const AppColors({
    required this.brand,
    required this.success,
    required this.warning,
    required this.danger,
  });

  final Color brand;
  final Color success;
  final Color warning;
  final Color danger;

  @override
  AppColors copyWith({Color? brand, Color? success, Color? warning, Color? danger}) {
    return AppColors(
      brand: brand ?? this.brand,
      success: success ?? this.success,
      warning: warning ?? this.warning,
      danger: danger ?? this.danger,
    );
  }

  @override
  AppColors lerp(AppColors? other, double t) {
    if (other == null) return this;
    return AppColors(
      brand: Color.lerp(brand, other.brand, t)!,
      success: Color.lerp(success, other.success, t)!,
      warning: Color.lerp(warning, other.warning, t)!,
      danger: Color.lerp(danger, other.danger, t)!,
    );
  }
}

然后通过 ThemeData.extensions 注册，页面里用 Theme.of(context).extension() 读取。这样欢迎页只需要关注品牌色变量，换主题时不用动页面代码。我们后期确实接了一个"夜间维修车间模式"，只加了另一套 AppColors，欢迎页零改动就适配了。

值得一提的细节是，ThemeExtension 里的颜色不要直接从 const 字面量拿，最好从设计令牌层读取。比如 AppColors.brand 的默认值来自 AppTokens.brandPrimary，这样设计侧改一个值，全端同步生效，不会出现"设计稿说改主色，开发在十个页面里手动替换"的尴尬。

3.4 欢迎页的数据源：本地配置与后端下发怎么搭

欢迎页要显示维修厂名称、版本号、初始化状态，这些数据从哪里来？我们的分工是：版本号、上次登录的账号信息、基础网络配置放本地存储；维修厂名称、公告、入口开关走后端下发，并缓存到本地。

本地存储我们选择了 hive 而不是 shared_preferences，原因是 OpenHarmony 上 shared_preferences 这类原生依赖插件的适配状态不如纯 Dart 的 hive 稳，而且 hive 可以存复杂对象，后续存工单草稿也用得上。欢迎页初始化时先读 hive 里的缓存，立即渲染出版本和名称，再异步拉取后端配置更新，这样即使弱网环境下 App 打开也不会白屏。

这里给一个实操建议：本地缓存要带版本号字段，后端配置加一个 configVersion。每次拉取先比对版本，不一致才全量更新，避免每次启动都重写 hive，延长工控机闪存的寿命。这个细节我们是在第一轮线上测试被一台设备频繁重启搞出来的教训——工控机的 Flash 写入寿命比手机差很多，扛不住每次启动都重写缓存。

4. OpenHarmony 真机踩坑实录：从能编译到能交付的五个坎

4.1 RK3568 设备树，到底该怎么选

OpenHarmony 的 RK3568 是出镜率最高的开发板，但很多人拿到板子第一步就卡住了：厂商给的固件文档一堆，设备树 dts 文件也一堆，到底该选哪个?

我的建议是：不要去看"最新的"，而是看三个东西——板子的 SoC 具体型号、内核版本、以及你的外设驱动。开发板厂商通常会提供一份对应自己板卡的 dts 配置，优先用厂商的；如果没有，再去 OpenHarmony 内核仓库里找与板子型号一致的 dts。选错了 dts 的表象经常很奇怪：有的能启动但屏幕不亮，有的是 USB 摄像头不出图，有的是网口不通。这些问题排查起来比改代码痛苦十倍，所以选 dts 之前一定把板卡型号确认清楚。

下面是我建议优先核对的一张检查表：

如果你是用官方 RK3568 标准系统镜像，设备树基本上已经默认配好，你只需要关注 overlay 配置里有没有打开你需要的 HDMI、MIPI-DSI、以太网节点。我们在项目里就遇到一个诡异问题：同一份镜像，在 A 厂商板子上以太网正常，在 B 厂商板子上只有第一个网口通。最后发现是 dts 里两个网口的 phy 地址配置不一样。这种问题没有任何速成解法，只能靠对比两个 dts 的差异定位。

4.2 新环境装 Flutter 的依赖地狱

团队里新同学搭 Flutter 环境，最容易卡在三个地方：SDK 版本、PATH 没生效、依赖包拉不下来。

先说 PATH。在 vscode 里装完 Flutter 插件并不等于 flutter 命令可用，需要把 flutter/bin 加进 PATH，而且 Windows 上改完环境变量后，已经打开的终端不会自动生效，必须新开一个终端。这个问题几乎每隔一段时间就会有人踩一次，建议团队文档里直接写"改完环境变量，关掉旧终端，重新开一个新的，用 where flutter 验证"。

再说依赖包。pub.dev 在部分网络环境下访问不稳定，flutter create 之后执行 flutter pub get 经常卡住。解决方式是在 pubspec_overrides.yaml 里配置可靠的镜像仓库地址，或者通过 PUB_HOSTED_URL 环境变量指向内部镜像源。这里有个额外提醒：镜像源要与你的 pub 版本兼容，否则会出现 metadata 解析错误，表现为"flutter 各个版本不对导致依赖包下不下来"。

最后是 Flutter 与 OpenHarmony 社区分支的版本匹配问题。OpenHarmony 适配分支通常落后于上游 Flutter 版本，我们锁定了固定的 Flutter SDK 版本，并在 CI 里使用同一套版本参数，禁止开发机随意升级。这样做的理由很现实：不锁定版本，你升级一次 Flutter 可能就要重新适配一遍插件，代价太大。

4.3 Flutter 与 OpenHarmony 原生模块的桥接边界

OpenHarmony 上很多原生能力没有现成 Flutter 插件，比如车牌识别和打印机。我们在设计时把所有原生调用收敛在 core/platform/ 下，通过 MethodChannel 对接，Dart 侧只暴露异步接口。

统一抽象接口的方案如下：

dart复制abstract class CameraService {
  Future<String> capturePlate();
}

class OpenHarmonyCameraService implements CameraService {
  static const _channel = MethodChannel('app.vehicle/camera');

  @override
  Future<String> capturePlate() async {
    final result = await _channel.invokeMethod('capturePlate');
    return result as String;
  }
}

页面层根本不关心当前跑在 Android 还是 OpenHarmony，只依赖 CameraService 接口。这样一来，欢迎页这种纯 UI 页面不会因为平台差异长出各种 if 分支。每次在三端跑 UI 冒烟测试时，也只需要 mock 掉 CameraService，不需要真机摄像头。

踩过的坑：MethodChannel 的方法名和参数类型一定要做契约文档，Dart 侧和 OpenHarmony 侧各写一版，并保证参数类型一致。我们遇到过 invokeMethod 传 int 过去，OpenHarmony 侧收到的是 double 导致类型转换崩溃的情况，最后靠日志排查才发现是隐式类型转换问题。从这个坑开始，我们要求所有桥接方法的参数都统一用 Map<String, Object> 包一层，从根源上避开类型歧义。

4.4 构建产物与签名：交付前一天才发现的坑

OpenHarmony 的应用打包是 HAP，不是 APK，签名机制也和 Android 完全不同。我们第一次给车间设备装 HAP 时，直接用默认签名装上，结果设备重开机后应用闪退——因为默认签名没有持久化到系统信任列表里。

后来规范化的做法是：在 OpenHarmony 工程的 signingConfigs 里明确配置自己的签名文件，并把签名证书、profile 文件纳入 git 管理（注意配置里不要提交私钥），CI 打包时统一加载。真机调试用 auto 签名问题不大，但交付给现场设备时一定要用正式的发布签名，否则现场改造升级会非常痛苦。

另外还有一个很实际的坑：HAP 安装到 RK3568 设备上，首次安装速度很慢，安装完桌面图标可能不刷新。这个不是代码问题，是 OpenHarmony 标准系统在部分设备上的 Launcher 刷新机制没做优化。我们现场安装后的处理方式是等待几秒或者重启一下 Launcher，不要反复重装。

4.5 用 UI 冒烟测试兜住欢迎页的回归风险

欢迎页虽然简单，但它是每次发布必须回归的页面。我们引入了一套轻量级的 Flutter widget 测试，覆盖三件事：布局关键元素存在、初始化成功会跳转、初始化失败会显示重试按钮。

dart复制testWidgets('welcome page renders brand title and version', (tester) async {
  final vm = WelcomeViewModel(preload: _FakePreloader());
  await tester.pumpWidget(const App(vm: vm));
  await tester.pumpAndSettle();

  expect(find.text('车辆维修管理系统'), findsOneWidget);
  expect(find.textContaining('v1.2.0'), findsOneWidget);
});

这类冒烟测试跑一次只要几十秒，但能在每次提交前把欢迎页的回归风险兜住。OpenHarmony 端的集成测试我们做得少一些，因为 HAP 打包和部署链路比 Android 慢，但至少保证 UI widget 测试在 CI 里全绿，再上真机。否则每次改完代码，光靠人肉点开欢迎页看一遍，迟早会漏。

对欢迎页这种有状态切换的页面，测试里比较容易忽略的是"失败态"的覆盖。我们一开始只测了成功路径，后来有一次网络模块改坏了，CI 没测出来，结果到现场发现所有设备都卡在欢迎页无法进入。从那之后，失败态的测试跟成功态同等重要，必须覆盖"加载失败—点重试—加载成功"的完整链路。

5. 重做一次我会坚持的三件事

5.1 版本组合锁定仓库化

如果现在让我把这套系统重新做一遍，我会把版本组合这件事提到最前面。第一天就锁定 Flutter SDK 版本和 OpenHarmony 适配分支的版本组合，写成 README 放进仓库根目录，违反这个版本组合的 PR 直接拒绝。版本漂移带来的插件兼容问题，是跨端项目最能消耗团队耐心的事情。

5.2 平台能力抽象前置化

所有平台能力从第一天就用接口抽象，不要因为"现在只有 Android"就先把平台调用写在页面里。我们在 OpenHarmony 落地时，最感谢的就是当初把 CameraService、StorageService 抽象出来了，欢迎页和工单页的迁移几乎没有改 UI 代码。抽象会多一点代码量，但换来的是一次性的架构安全感。

5.3 把欢迎页当成工程化样板间

把欢迎页当成工程化样板间来维护。它是所有新同学看的第一段代码，也是每次发布前必须回归的页面。花在欢迎页上的工程化投入，会在每一个后续页面上成倍放大。

说一个最近才发生的例子吧。上周一个新同学接手欢迎页的换肤需求，按照 features/welcome 的目录结构十分钟就理清了逻辑，改完提交 PR，CI 自动跑了 widget 测试，一切顺利。而我当年在另一个项目里，为了找一个页面状态管理文件翻了三个目录，改完还不敢保证不破坏别的地方。那一刻我更加确信，工程化的意义不是给架构师看的 PPT，而是让接手的人不用对着代码猜。希望你们也能把欢迎页这个最不起眼的入口，打造成团队最放心的样板。