Flutter + OpenHarmony 实战：家庭药箱应用的开发与适配记录

1. 为什么我选了 Flutter 来开发鸿蒙版家庭药箱应用

先交代一下背景。我手上这个家庭药箱管理 App，最初的版本是用原生 Android 写的，功能也不算复杂：记录家里存了什么药、什么时候过期、谁在吃什么药。真正让我动了迁移念头的是家里长辈用药这件事——药品种类一多，过期药、重复买药的问题就开始暴露，我需要在手机端快速定位“哪盒药快过期了”，同时最好能跨平台跑起来，毕竟家里人的手机并不统一。

Flutter 是我比较熟悉的技术栈，而 OpenHarmony 这边已经有不少团队在推进 Flutter 的适配工作。前后对比了一下成本，用 Flutter 直接跑在 OpenHarmony 设备上，既能复用大部分业务逻辑，又能避开维护两套 UI 的麻烦。单就“家庭药箱管理”这个场景来说，它属于典型的列表密集型应用：药品条目、分类筛选、过期提醒，本质上都是在和数据列表打交道。而 Flutter 的列表构建方式——无论是 ListView 还是性能更强的 ListView.builder，在同类型 App 里都是最顺手的那一档。

这篇实战记录会聚焦两件事：一是怎么把一个 Flutter 工程跑上 OpenHarmony 设备，二是药品列表这个核心模块的具体实现方式，包括数据结构设计、界面拆分、状态管理和一点鸿蒙适配的坑。适合两类人看，一类是已经会 Flutter 基础但没跑过鸿蒙的开发者，另一类是想做跨平台应用但不确定 Flutter 在鸿蒙生态里能不能撑起实际业务的产品/技术负责人。

我当时的想法很直接：先做一个能在 OpenHarmony 模拟器里跑起来、能正常增删改查药品的 MVP，再慢慢补通知提醒、扫码录入这些外围能力。整个过程中踩的坑不少，尤其是环境配置和 Flutter 插件在鸿蒙端的兼容性问题，这篇文章都会摊开讲。

2. 开干之前的环境准备和工程初始化

2.1 这套组合拳：Flutter 3.x + OpenHarmony SDK 的版本匹配

先说版本。Flutter 官方主分支对 OpenHarmony 的支持一直没有正式合入，实际可用的是社区维护的分支。我在搭建环境时的具体版本组合如下：

• Flutter SDK：使用 OpenHarmony 社区维护的 flutter_flutter 分支，版本基于 Flutter 3.22.x 定制。
• OpenHarmony SDK：API 12 的 public SDK，配套 DevEco Studio 5.0 使用。
• 设备镜像：rk3568 的 dayu200 开发板镜像，以及本地模拟器镜像。

版本匹配是第一个大坑。OpenHarmony 自身迭代非常快，API 版本一变，Flutter 引擎的适配层没跟上就会出各种莫名其妙的问题。我的建议是，不要盲目装最新的 Flutter 版本，直接用社区分支默认锁定的版本。你可以这样确认当前分支的版本：

bash复制git clone https://gitee.com/openharmony-sig/flutter_flutter.git -b master
cd flutter_flutter
flutter --version

我当时拉下来的版本是 3.22.2，这个版本对应 OpenHarmony API 12 的适配是相对稳定的。如果你用了 API 13 的 SDK，大概率会遇到编译不过或者运行时报 so 库不匹配的问题。社区分支每周都有更新，但别追新，稳定压倒一切。

2.2 环境变量和工具链配置，一次配对的实操记录

在 macOS 上，我把 OpenHarmony 的命令行工具和 Flutter 的路径都加进了 ~/.zshrc：

bash复制export DEVECO_SDK_HOME=/Users/xx/Library/OpenHarmony/Sdk
export PATH=$PATH:/Users/xx/Library/OpenHarmony/command-line-tools/bin
export PATH=$PATH:/Users/xx/flutter_flutter/bin

配置完记得执行 source ~/.zshrc，或者新开终端窗口。很多教程没说这一步，结果用户配完路径发现命令依然找不到，其实就是终端会话没刷新。这里提一个热搜里常见的现象——“path 需要新终端生效”，说的就是这个问题，不是环境变量配错了，是当前 shell 会话没重载。

工程方面，我不建议直接用 DevEco Studio 创建工程，因为 DevEco 默认模板生成的是纯 ArkTS 工程，和 Flutter 的接入方式不匹配。正确的入口是用 Flutter 命令行创建：

bash复制flutter create --platforms=ohos family_medicine_cabinet

如果你的 Flutter 分支支持 ohos 平台，上面的命令会直接生成 ohos/ 目录，这里面是 OpenHarmony 的工程壳子。如果命令不支持，需要手动用 flutter_flutter 仓库里提供的 flutter_tools 补丁，这属于分支切换不彻底的坑，一般重装 Flutter 能解决。

3. 家庭药箱 App 的整体架构与数据层设计

3.1 先想清楚“家庭药箱”到底管理什么

很多人在做这种工具类 App 的时候容易一上来就写 UI，结果做到一半发现数据结构撑不住业务逻辑。我设计这个应用时，先画了一张简单的数据关系图：

• 药品基础信息：名称、通用名、规格、生产厂家、生产批号。
• 库存与位置：数量、存放位置（比如“客厅药箱”“厨房抽屉”）。
• 效期信息：生产日期、有效期至、开封后有效期。
• 用药人信息：谁在用这个药、用药频次和剂量。
• 提醒配置：是否需要过期提醒、提前几天提醒。

围绕这五点，核心的数据模型就可以确定了。药品列表绝不是只存一个药名那么简单，你要让这个列表真正可用，必须把维度考虑全。尤其“存放位置”这个字段，看起来很不起眼，但家里人找药的时候这是最高频的筛选条件。

3.2 建一个干净的 Medicine 模型，用 Dart 怎么写

我用 Dart 定义了一个 Medicine 类，这里做了最核心的字段抽象：

dart复制class Medicine {
  final String id;
  final String name;
  final String genericName;
  final String specification;
  final String location;
  final int quantity;
  final DateTime productionDate;
  final DateTime expiryDate;
  final List<String> users;
  final bool isPrescription;

  const Medicine({
    required this.id,
    required this.name,
    required this.genericName,
    required this.specification,
    required this.location,
    required this.quantity,
    required this.productionDate,
    required this.expiryDate,
    required this.users,
    required this.isPrescription,
  });

  bool get isExpiringSoon {
    final daysLeft = expiryDate.difference(DateTime.now()).inDays;
    return daysLeft >= 0 && daysLeft <= 30;
  }

  bool get isExpired => expiryDate.isBefore(DateTime.now());

  factory Medicine.fromJson(Map<String, dynamic> json) {
    return Medicine(
      id: json['id'] as String,
      name: json['name'] as String,
      genericName: json['genericName'] as String,
      specification: json['specification'] as String,
      location: json['location'] as String,
      quantity: json['quantity'] as int,
      productionDate: DateTime.parse(json['productionDate'] as String),
      expiryDate: DateTime.parse(json['expiryDate'] as String),
      users: (json['users'] as List<dynamic>).cast<String>(),
      isPrescription: json['isPrescription'] as bool,
    );
  }
}

这个模型的用了几个布尔计算属性，isExpiringSoon 和 isExpired，在实际渲染的时候能直接用来打标签。为什么要单独抽出来而不是在 UI 层写判断？因为同一个药品在列表页、详情页、提醒通知里都要用这两个状态，写在模型层可以避免逻辑散落到各处，后面加单元测试也方便。

3.3 本地持久化选型：Hive 还是 SQLite？

家庭药箱数据量并不大，一个家庭一般几十上百种药品，根本到不了 SQLite 需要发力的量级。我在 Flutter 侧做的选型是 Hive，一个轻量级的 NoSQL 数据库：

• 纯 Dart 实现，不依赖原生代码，跨平台一致性极好，在 OpenHarmony 上跑没有任何额外适配成本。
• 读写速度对几十条数据来说绰绰有余。
• 支持类型安全的 Adapter，可以直接存储 Medicine 对象。

当然如果你要做的功能涉及复杂的联表查询（比如按药品关联多条用药记录、做统计报表），那 SQLite 会是更稳的选择。sqflite 这个库在 OpenHarmony 端的支持度取决于社区适配，实测下来基础使用没问题，但如果你碰到插件无法加载的情况，优先检查插件是否实现了 ohos 平台的接口。

3.4 仓库层：把数据操作和 UI 解耦

我用一个 MedicineRepository 来封装所有数据操作。UI 层不直接碰 Hive，而是调仓库接口：

dart复制class MedicineRepository {
  final Box<Medicine> _box;

  MedicineRepository(this._box);

  List<Medicine> getAllMedicines() {
    return _box.values.toList();
  }

  Future<void> addMedicine(Medicine medicine) async {
    await _box.put(medicine.id, medicine);
  }

  Future<void> deleteMedicine(String id) async {
    await _box.delete(id);
  }

  Future<void> updateQuantity(String id, int newQuantity) async {
    final medicine = _box.get(id);
    if (medicine != null) {
      await _box.put(id, _copyWithQuantity(medicine, newQuantity));
    }
  }

  List<Medicine> getExpiringMedicines(int days) {
    final now = DateTime.now();
    return _box.values.where((m) {
      final diff = m.expiryDate.difference(now).inDays;
      return diff >= 0 && diff <= days;
    }).toList();
  }
}

这个仓库层的好处是，以后如果要把本地存储换成服务端同步，只需要替换仓库的实现，UI 层代码完全不用动。在做列表这种核心功能时，这个边界一定要划清楚，不然越到后面越难维护。

4. 药品列表页面：从设计到实现

4.1 页面信息架构与布局设计

药品列表页是整个 App 的门面，一打开就要让用户快速回答三个问题：我有什么药、药在哪、哪些快过期了。

我的布局结构是这样：

• 顶部：标题栏 + 药品数量统计。
• 搜索区：按药名和位置模糊搜索。
• 筛选区：Tab 切换“全部 / 即将过期 / 已过期”。
• 主体：药品卡片列表，左对齐药名和规格，右侧是数量和过期状态标签。
• 浮动按钮：添加药品的入口。

这个布局对应的 Flutter Widget 树，核心部分是这样组织的：

dart复制Scaffold(
  appBar: AppBar(
    title: const Text('家庭药箱'),
    actions: [
      IconButton(
        icon: const Icon(Icons.search),
        onPressed: () => _showSearchBar(),
      ),
    ],
  ),
  body: Column(
    children: [
      _buildFilterTabs(),
      Expanded(
        child: _buildMedicineList(),
      ),
    ],
  ),
  floatingActionButton: FloatingActionButton(
    onPressed: _openAddMedicinePage,
    child: const Icon(Icons.add),
  ),
)

4.2 药品卡片的设计思路

药品卡片我没有用传统的 Card 组件，而是自己用 Container 拼了一个，原因是 Card 默认的圆角、阴影和边距在鸿蒙端的 Flutter 渲染上偶尔会有边界溢出问题，自己控制样式反而更干净。卡片内部结构如下：

• 第一行：药品名 + “处方药”标签（如果需要）。
• 第二行：规格 + 存放位置，用一个小图标分隔。
• 第三行：剩余数量 + 过期状态标签，快过期和已过期用不同颜色区分。

这里要说一下“剩余数量”的展示方式。数字本身很直观，但实际用药场景里，家里人更在乎的是“还够吃几天”。所以我额外加了一个 daysLeft 计算，通过日剂量和剩余数量的比值来估算，这个逻辑可以在之后做提醒模块时直接复用。

4.3 状态管理：我选了 Provider 而不是 Riverpod

状态管理这块，很多教程一上来就推荐 Riverpod 或者 Bloc，但对于这个量级的 App，Provider 足够了，学习成本低，代码也直观。

先定义一个 MedicineListViewModel：

dart复制class MedicineListViewModel extends ChangeNotifier {
  final MedicineRepository _repository;
  List<Medicine> _allMedicines = [];
  String _searchQuery = '';
  MedicineFilter _currentFilter = MedicineFilter.all;

  MedicineListViewModel(this._repository);

  List<Medicine> get medicines => _applyFilterAndSearch();

  Future<void> loadMedicines() async {
    _allMedicines = _repository.getAllMedicines();
    notifyListeners();
  }

  Future<void> addMedicine(Medicine medicine) async {
    await _repository.addMedicine(medicine);
    await loadMedicines();
  }

  List<Medicine> _applyFilterAndSearch() {
    var result = _allMedicines;
    if (_searchQuery.isNotEmpty) {
      result = result.where((m) {
        return m.name.contains(_searchQuery) ||
            m.location.contains(_searchQuery) ||
            m.genericName.contains(_searchQuery);
      }).toList();
    }
    switch (_currentFilter) {
      case MedicineFilter.expiring:
        result = result.where((m) => m.isExpiringSoon && !m.isExpired).toList();
        break;
      case MedicineFilter.expired:
        result = result.where((m) => m.isExpired).toList();
        break;
      case MedicineFilter.all:
        break;
    }
    return result;
  }
}

然后通过 ChangeNotifierProvider 注入到 Widget 树顶层：

dart复制void main() {
  WidgetsFlutterBinding.ensureInitialized();
  final box = await Hive.openBox<Medicine>('medicines');
  final repository = MedicineRepository(box);
  runApp(
    ChangeNotifierProvider(
      create: (_) => MedicineListViewModel(repository)..loadMedicines(),
      child: const FamilyMedicineApp(),
    ),
  );
}

这个方案的直接好处是：药品的增删改查到列表界面的刷新，是一条非常清晰的数据流，出了问题能很快定位是 ViewModel 的问题还是 View 渲染的问题。

4.4 列表实现：ListView.builder 的性能细节

药品列表在几十条数据量级下，用 ListView 和 ListView.builder 的性能差异几乎感知不到。但为了以后扩展，我还是用了 ListView.builder，它的懒加载机制保证了我后续如果接入扫码入库功能，药品数量涨到几百上千时列表不会卡顿。

dart复制Widget _buildMedicineList() {
  return Consumer<MedicineListViewModel>(
    builder: (context, vm, child) {
      final medicines = vm.medicines;
      if (medicines.isEmpty) {
        return const _EmptyPlaceholder();
      }
      return ListView.builder(
        padding: const EdgeInsets.fromLTRB(16, 8, 16, 80),
        itemCount: medicines.length,
        itemBuilder: (context, index) {
          final medicine = medicines[index];
          return MedicineCard(
            key: ValueKey(medicine.id),
            medicine: medicine,
            onTap: () => _openDetailPage(context, medicine),
            onDelete: () => vm.deleteMedicine(medicine.id),
          );
        },
      );
    },
  );
}

这里有两个细节要强调：key 必须用 ValueKey(medicine.id)，这样 Flutter 能精确追踪每个卡片对应哪条数据，做增量更新时不会把整个列表重新渲染；列表底部留 80 像素的 padding，是为了防止最后一张卡片被悬浮按钮遮住。

5. OpenHarmony 端的适配与问题排查记录

5.1 从 rk3568 到模拟器，选设备时我踩过的坑

这里必须多说一句设备树的问题。热搜词里有一条“openharmony 的 rk3568 有许多设备树到底咋选”，这个问得非常好，我当时也卡了很久。rk3568 开发板（典型如 dayu200）在不同厂商的定制板上，设备树是不通用的。烧录镜像时选错设备树，最常见的结果是屏幕不亮或者触摸失灵。我的建议是，如果你不确定自己的板子是哪个型号，直接看开发板背面的丝印和官方文档，而不要凭感觉选。如果只是验证 Flutter 应用逻辑，优先用 OpenHarmony 官方模拟器，省掉硬件层面所有麻烦。

模拟器有一个好处，就是 Flutter 热重载可以直接生效。我第一次在模拟器上跑 flutter run 的时候，很惊讶热重载在 OpenHarmony 上也能这么流畅，这对我来说是最加分的点。

5.2 Flutter 插件在鸿蒙端的兼容性

Flutter 生态最怕的就是插件不支持。表格里列一下我在这个项目里用到的插件和鸿蒙端的状态：

这里重点说一下 image_picker。热搜里有“flutter如何调用鸿蒙的图库”，这个问题很典型。OpenHarmony 有自己的图片选择器能力，但 Flutter 的 image_picker 插件默认支持 Android 和 iOS 平台，在鸿蒙端要依赖 OpenHarmony 社区的分支或者自己写 MethodChannel 调用鸿蒙的 PhotoViewPicker。我当时为了实现“拍药品包装盒上传”这个小功能，选择了直接调用鸿蒙原生的 PhotoViewPicker，通过 MethodChannel 桥接回来。如果你不想碰原生代码，可以先跳过这个功能，或者用社区 fork 的实现。

5.3 IAP 支付和其他原生能力的接入

热搜词里还有“flutter兼容鸿蒙拉起iap支付”。这个要提前说明白，OpenHarmony 的应用内支付服务和 Android 的 Google Play Billing 是完全不同的体系，Flutter 的 in_app_purchase 插件在鸿蒙端没有办法直接工作。你需要找到鸿蒙 SDK 自带的 IAP SDK，自己封装 MethodChannel 暴露给 Flutter 调用。这个工作量不算小，而且涉及实名认证、软著等合规流程，如果只是学习实战，我建议优先把核心业务功能做好，支付这类能力等产品真正要上线时再接也不迟。

6. 几个值得记录的界面体验细节

6.1 空状态的交互设计

列表页一开始最容易忽略的就是空状态。刚安装完 App，一打开看到空列表，用户会觉得很蒙。我做了一个带插画的空状态页面，文案是“药箱还是空的，点右下角添加第一盒药吧”，同时把添加按钮的引导箭头画了出来。实际用下来，这个页面虽然简单，但对新用户的理解成本降低非常明显。

6.2 过期状态的多色标签

过期状态我用三种颜色区分：

• 正常：绿色标签“有效期至 2026-08-12”。
• 30 天内过期：橙色标签“即将过期，剩余 24 天”。
• 已过期：红色标签“已过期 5 天”。

颜色的对比度都经过测试，在户外光线下也能看清。字体大小选择的是 12sp 的小标签，配合卡片主标题的 16sp，形成了明确的信息层级。

6.3 搜索框的展示与隐藏

搜索框我没有一直放在页面上，而是放在 AppBar 的 action 里，点击图标后展开成 TextField，并自动弹出键盘。这样做的原因是，药品列表页的主要操作路径是“看列表 → 点进详情”或“加药”，搜索只是辅助功能，一直占着顶部会压缩列表空间。展开和收起用了 AnimatedContainer 做平滑动画，体验上顺滑很多。感兴趣的话还可以把搜索历史做成本地记录，方便下次快速查找。

7. 碰到最多的五个问题及排查方法

7.1 Hive 初始化时报错 “Box not found”

这通常发生在清空应用数据之后，旧的 Box 文件被系统清了，但逻辑里还在尝试直接打开。解决办法是在打开之前检查：

dart复制if (!Hive.isBoxOpen('medicines')) {
  await Hive.openBox<Medicine>('medicines');
}

7.2 Flutter 插件在编译时提示 “Unsupported operation”

这个要区分两种情况。第一，插件本身没有 OHOS 平台的实现，运行时会直接抛 MissingPluginException；第二，插件有实现，但你用的是旧的插件缓存。针对第二种情况，执行以下命令清缓存：

bash复制flutter clean
rm -rf ohos/.hvigor
flutter pub get

7.3 热重载后页面没有变化

这个原因很多，我遇到的主要是状态管理的问题。如果在 initState 里加载了数据，热重载不会重新执行 initState，所以数据状态还停留在上一次。解决办法是不要依赖 initState 里的副作用，把数据加载放到 ViewModel 的构造函数里，或者手动触发热重启（大写的 R 键）。

7.4 中文字体显示为方框

OpenHarmony 镜像上如果缺少对应的字体文件，中文字符会显示为豆腐块。解决方案是在 Flutter 侧通过 Google Fonts 库动态加载字体，或者把中文字体文件打包进 assets 资源里，在 MaterialApp 的 theme 中统一设置。

7.5 列表滚动时出现白屏闪烁

这个大概率是设备 GPU 渲染和 Flutter 引擎的兼容问题。尝试在 main() 里关掉硬件加速，或者调低动画曲线档位：

dart复制// 在 runApp 之前执行
if (Platform.isOpenHarmony) {
  // 通过 FlutterEngine 配置关闭部分硬件加速
}

如果是真机出现且无法解决，检查系统版本和 Flutter 分支的已知 issue，必要时升级 OpenHarmony 系统镜像。

8. 一些额外想分享的经验和后续扩展方向

最后聊点实际的体会。做这个项目的过程中，我最大的感受是：Flutter 在 OpenHarmony 上已经不是“能不能跑”的问题了，而是“跑得稳不稳、插件全不全”的问题。对于业务逻辑比较常规、依赖第三方原生插件不多的应用，Flutter 完全能撑起鸿蒙端的开发。尤其是状态管理、数据持久化、UI 构建这三大块，代码可以在 Android、iOS、OpenHarmony 之间无缝复用，省下的工程量非常可观。

后续我会在这个项目上继续做几件事：把通知提醒能力接上，让药品过期提醒能真正推送到手机通知栏；完善药品详情页，加上用药说明的拍照识别；最后再优化一下布局，适配鸿蒙平板的横屏模式。如果你想拿这个项目练手，建议从药品列表的增删改查开始，跑通整条链路之后再逐步加功能。踩坑的过程中如果遇到问题，欢迎对照这篇文章里的排查思路一条条过，大部分情况都能快速定位。