Flutter在OpenHarmony上实现房间列表：从环境搭建到状态管理实战

房间列表这个功能，是我在做家具购买记录 App 时第一个从"单一页面"迈向"多房间数据管理"的转折点。OpenHarmony 设备上跑 Flutter，听着像是个折腾活儿，但实际走通之后，你会发现这套组合比想象中顺手。这篇文章不聊概念，直接把我实现房间列表的完整过程拆开给你看——从环境准备到 Provider 状态管理，再到 UI 布局和真机调试，每一步都附上我踩过的坑和当时的思考。

1. 为什么我用 Flutter 来写 OpenHarmony 应用

先说结论：如果你只想为鸿蒙生态写一个应用，ArkTS 确实是最正统的选择。但如果你的目标是"一套代码，多个平台都能跑"，或者你本身已经熟悉 Flutter 而不想再学一套 UI 框架，那 Flutter for OpenHarmony 是一条值得走的路。

1.1 Flutter 与 ArkTS 的选型取舍

我在决定技术方案时列过一张对比表：

对我这个场景来说，核心需求是快速迭代、界面统一、数据管理清晰，而且我手头已经有 Flutter 的开发经验，于是选择了 Flutter。唯一需要留意的就是你最终要构建ohostarget，这跟常规的apk或app构建流程不同，后面会细说。

1.2 Flutter for OpenHarmony 目前在实战中的成熟度

这个适配项目从官方flutter/flutter的ohos分支拉出来，社区一直在推进。我在实操过程中最有感触的一点是：纯 UI 层面和 Dart 逻辑层面可以完全复用，真正需要额外处理的是系统能力和原生插件。比如拍照、文件读写这种涉及原生能力的功能，需要确认 Flutter 插件是否已经有 OpenHarmony 的适配实现，或者是否要用通道自己写。

但这篇文章要做的房间列表相对简单，不涉及原生调用，核心就是干净的数据管理和 UI 表现，所以 Flutter 的适配问题基本不会碰到。

2. 开发环境搭建与工程初始化，这一步最容易劝退

如果你不是第一次接触 Flutter，环境搭建会很快；但如果你在 Windows 上同时想处理 OpenHarmony target，那有几个点需要特别小心。

2.1 安装 Flutter SDK 的 ohos 分支

这里必须强调一个容易踩的坑：不要直接下载普通 Flutter SDK，要使用适配了 OpenHarmony 的分支。常规 Flutter 的stable分支已经支持过了 OpenHarmony 的插桩构建，但为了保险我使用的是社区维护的flutter_flutter项目。

我的实际操作是这样的：

git clone -b dev https://gitee.com/openharmony-sig/flutter_flutter.git git clone -b dev https://gitee.com/openharmony-sig/flutter_engine.git git clone -b master https://gitee.com/openharmony-sig/flutter_packages.git

这三个仓库分别对应 Flutter 框架、引擎和插件仓库。克隆完成后，还需要准备 OpenHarmony 的 SDK，我使用的是通过 DevEco Studio 下载的ets和toolchains目录。

在配置完环境变量后，可以用以下命令验证：

flutter doctor

如果你在flutter doctor的输出里看到 OpenHarmony 的检测项，说明环境基本就位。这里有一个我踩过的坑：如果直接用官方渠道下载 Flutter SDK，执行flutter create --platforms=ohos会失败，因为它没有内置 ohos 的 platform 支持。

2.2 创建工程时不能漏掉的参数

工程创建这一步公式很简单：

flutter create --platforms=ohos,android .

我加了android是为了方便在 Android 模拟器上快速调试 UI 表现，毕竟 OpenHarmony 模拟器不是到处都有。如果你不需要 Android target，可以只保留ohos。

创建完之后检查pubspec.yaml，默认依赖是cupertino_icons，然后我追加了provider用于状态管理。

dependencies: flutter: sdk: flutter cupertino_icons: ^1.0.6 provider: ^6.1.2

2.3 DevEco Studio 与项目目录结构的关系

在 Flutter 工程生成后，你会看到一个ohos目录，这就是 OpenHarmony 的壳工程。你在 Flutter 层写的 Dart 代码会被编进这个壳里，最终打成.hap包。

用 DevEco Studio 打开ohos目录时，它会让你配置 SDK 路径，同时可能触发 Gradle 和 Cmake 的下载，这一步挺耗时。第一次打开时最好保持网络畅通，耐心等进度条走完。如果中途失败，直接在 DevEco 里执行菜单栏的File -> Sync and Refresh Project重试即可。

3. 房间数据模型与 Provider 状态管理设计

一个"房间列表"看似只是把几个房间名字展示出来，但实际上要考虑的数据问题不少：每个房间有哪些家具、家具花了多少钱、购买时间是什么时候、房间的封面图用什么占位。数据模型理清楚，后面的界面和交互才不会乱。

3.1 先定义 FurnitureItem 还是先定义 Room

我习惯从最细粒度的实体开始反推。这个 App 的核心实体是家具，家具归属于房间，所以先定义FurnitureItem，再定义Room会更自然。

class FurnitureItem { final String id; final String name; final String roomId; final double price; final String purchaseDate; final String imagePath; // 本地路径或网络 URL FurnitureItem({ required this.id, required this.name, required this.roomId, required this.price, required this.purchaseDate, this.imagePath = '', }); }

房间模型里除了房间名和 ID，还需要一个图标标识。考虑到"客厅""卧室""书房"这类固定分类，我直接用roomType枚举配合预设图标，避免让用户自己传图标文件。

enum RoomType { livingRoom, bedroom, kitchen, study, bathroom, other } class Room { final String id; final String name; final RoomType type; final List<FurnitureItem> furnitureList; Room({ required this.id, required this.name, required this.type, this.furnitureList = const [], }); }

3.2 Provider 的角色与为什么不用 setState

房间列表页面有一个典型场景：用户在房间 A 里新增了一件家具，返回列表时房间 A 的总价和家具数量要同步变化。如果只用setState管理，这种跨页面数据同步会变得很痛苦。

于是我用ChangeNotifier + Provider。这个方案不重，不需要引入 Bloc 那种复杂的事件流，学习成本低，当前项目规模下完全够用。

class RoomStore extends ChangeNotifier { List<Room> _rooms = []; List<Room> get rooms => List.unmodifiable(_rooms); void addRoom(Room room) { _rooms.add(room); notifyListeners(); } void addFurnitureToRoom(String roomId, FurnitureItem item) { final index = _rooms.indexWhere((r) => r.id == roomId); if (index != -1) { _rooms[index].furnitureList.add(item); notifyListeners(); } } void deleteFurniture(String roomId, String furnitureId) { ... } }

在main.dart里注入 Store：

void main() { runApp( ChangeNotifierProvider( create: (_) => RoomStore()..loadMockData(), child: const FurnitureApp(), ), ); }

组件内部读取数据就非常清爽了：

final roomStore = context.watch<RoomStore>();

这里就回答了热门搜索里的 "flutter provider 怎么用"——它的核心用法就是：定义 ChangeNotifier、在顶层传入、在需要的 Widget 里watch或read。

3.3 模拟数据的组织方式

在还没有接数据库之前，我直接在 Store 里构造了一批初始数据，用来验证 UI 效果。这里有一个值得分享的小技巧：把模拟数据的构建独立成一个方法，并在类型注解中统一使用List<Room>，以后替换成本地数据库或后端接口时，只需改动 Store 内部实现，View 层不用动。

void loadMockData() { _rooms = [ Room( id: 'room_1', name: '客厅', type: RoomType.livingRoom, furnitureList: [ FurnitureItem( id: 'f_1', name: '双人布艺沙发', roomId: 'room_1', price: 3199, purchaseDate: '2025-03-12', ), FurnitureItem( id: 'f_2', name: '实木茶几', roomId: 'room_1', price: 1299, purchaseDate: '2025-03-12', ), ], ), Room(id: 'room_2', name: '主卧', type: RoomType.bedroom, furnitureList: [...]), ]; notifyListeners(); }

4. 房间列表 UI 实现：从卡片布局到空状态处理

UI 这部分我走了三版：第一版用ListView堆卡片，比较保守；第二版改成了GridView双列，房间数量少时显得空旷；最终折中方案是不固定双列，而是让卡片自适应宽度，并保留底部的"添加房间"入口。

4.1 页面整体结构

房间列表页主要由三块组成：顶部的统计概览、中部的房间网格、右下角的悬浮添加按钮。统计概览和房间数据都来自 Provider，这样就不会出现"页面 A 加了房间、页面 B 总数没更新"的问题。

Scaffold( body: SafeArea( child: Consumer<RoomStore>( builder: (context, store, child) { if (store.rooms.isEmpty) { return const EmptyRoomView(); } return CustomScrollView( slivers: [ SliverToBoxAdapter(child: SummaryHeader(rooms: store.rooms)), SliverPadding( padding: const EdgeInsets.all(16), sliver: SliverGrid( gridDelegate: SliverGridDelegateWithMaxCrossAxisExtent( maxCrossAxisExtent: 220, mainAxisSpacing: 12, crossAxisSpacing: 12, childAspectRatio: 0.82, ), delegate: SliverChildBuilderDelegate( (context, index) => RoomCard(room: store.rooms[index]), childCount: store.rooms.length, ), ), ), ], ); }, ), ), floatingActionButton: FloatingActionButton( onPressed: _showAddRoomDialog, child: const Icon(Icons.add), ), )

注意我用的是Consumer，而不是context.watch，纯粹是因为 builder 里同时要使用 store 数据并处理空状态逻辑，这样包裹范围更明确。

4.2 房间卡片的信息层级与视觉表现

每张房间卡片里我放了四类信息：房间名称与类型、家具数量、总花费、封面图（没有真实图片时用图标）。信息层级要清楚，不能平均分配。

class RoomCard extends StatelessWidget { final Room room; const RoomCard({super.key, required this.room}); @override Widget build(BuildContext context) { final totalPrice = room.furnitureList.fold<double>( 0, (sum, item) => sum + item.price); return Card( clipBehavior: Clip.antiAlias, elevation: 0, shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(16)), child: InkWell( onTap: () { Navigator.of(context).push( MaterialPageRoute( builder: (_) => FurnitureListPage(roomId: room.id), ), ); }, child: Padding( padding: const EdgeInsets.all(14), child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Row( children: [ Container( width: 40, height: 40, decoration: BoxDecoration( color: Theme.of(context).colorScheme.primaryContainer, borderRadius: BorderRadius.circular(12), ), child: Icon(_iconForRoomType(room.type)), ), const SizedBox(width: 12), Expanded( child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Text(room.name, style: const TextStyle( fontSize: 16, fontWeight: FontWeight.w600)), const SizedBox(height: 4), Text('${room.furnitureList.length} 件家具 · ' '¥${totalPrice.toStringAsFixed(0)}', style: TextStyle( fontSize: 12, color: Colors.grey[600])), ], ), ), ], ), ], ), ), ), ); } }

这里有个容易忽略的点：点击卡片跳转到家具列表页面时，一定要传roomId，而不是传整个Room对象。因为家具列表页里可能会修改房间内的家具数据，如果直接传对象引用，会让数据流变得不可追踪；传 ID 后，家具列表页统一通过 Provider 获取最新房间数据，能有效避免"旧数据覆盖新数据"的问题。

4.3 自定义加载占位与空状态

联网加载或首次进入没有数据时，我设计了一个简易的骨架屏，让界面不会一下子空白。骨架屏的做法很直接：用灰底圆角块模拟"房间卡片"的尺寸，再配合一个轻微透明度动画。

class RoomCardSkeleton extends StatelessWidget { const RoomCardSkeleton({super.key}); @override Widget build(BuildContext context) { return Container( padding: const EdgeInsets.all(14), decoration: BoxDecoration( color: Colors.black.withValues(alpha: 0.03), borderRadius: BorderRadius.circular(16), ), child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Row( children: [ _SkeletonBox(width: 40, height: 40, borderRadius: 12), const SizedBox(width: 12), Expanded( child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ const _SkeletonBox(width: 80, height: 16), const SizedBox(height: 8), const _SkeletonBox(width: 120, height: 12), ], ), ), ], ), ], ), ); } }

空状态页面也不复杂，居中放一个"暂无房间"的图标和文字，外加一个"去添加房间"按钮。这样的交互闭环虽然简单，但实际体验会比白屏好很多。

4.4 添加房间弹窗的实现细节

默认条目里用的是中文类型，所以新增房间时我用了底部弹窗加表单的方式，而不是生硬的全屏页面。弹窗里包含房间名称输入框和类型选择器，确认后调用store.addRoom()。

一个细节：表单校验要阻止"房间名为空"的情况，用TextFormField的validator能顺手解决。同时，如果用户输入重名房间，我也是允许的——因为现实中可能有两个"储物间"。如果要做额外限制，可以在addRoom方法里判断同名，但这不是当前需求的重点。

5. 运行到 OpenHarmony 设备/模拟器的流程与踩坑记录

在写房间列表的过程中，我把应用跑到了 OpenHarmony 模拟器上，也插过真机。这个环节比普通 Flutter 开发要多几步，但也完全在可控范围内。

5.1 构建 ohos target 的正确姿势

首先确认你当前设备已连接，可以用hdc list targets查看。hdc 是 OpenHarmony 的命令行工具，类似于 adb。

接下来，运行：

flutter build hap --debug

如果你没有在--platforms里加ohos，这一步会报错说找不到 ohos platform。如果正常构建，你会在build/ohos目录下生成.hap文件。

然后使用 hdc 安装：

hdc install build/ohos/app/build/outputs/default/xxx.hap

这里有个常见问题：hdc 安装 .hap 时提示签名不对。OpenHarmony 默认情况下只允许安装带签名的 hap。如果调试阶段遇到这个问题，一种简单做法是在 DevEco Studio 里配置自动签名，或者生成调试证书导入。我在做 UI 层调试时，直接用 DevEco 的自动签名功能解决的，没有去折腾手动签名。

5.2 真机调试时的日志查看方法

运行后想看print日志，用hdc shell hilog即可。过滤 Flutter 的关键字的命令是：

hdc shell hilog | grep flutter

由于 Flutter 引擎在 ohos 上会把 Dart 侧的输出转发到 hilog，所以这个方式能覆盖绝大多数调试场景。相比之下，Flutter 默认的flutter logs在当前 OpenHarmony 适配下并不总是可用，优先用 hilog。

对了，还有一个很实用的小技巧：你可以在工程里通过debugPrint打印带 tag 的内容，然后 grep tag 的名称，例如：

debugPrint('[RoomList] refresh complete, total=${store.rooms.length}');

然后：

hdc shell hilog | grep "RoomList"

这样只看关心的日志，不会被引擎日志淹没。

5.3 与 Android 模拟器的差异点

OpenHarmony 模拟器的某些渲染表现和 Android 有细微差别。最明显的是中文字体的字重渲染，OpenHarmony 默认字体在某些像素密度下偏细，如果你的卡片文字用了FontWeight.w600，看起来可能不如 Android 上醒目。但这不影响布局和数据逻辑，发布到真机时按需微调 "fontFeature" 或字体 fallback 即可。

另外，热重载（hot reload）在 ohos target 上可用，但比 Android 稍微慢一点。我记得有一次修改了 Provider 的notifyListeners()调用时机，热重载后 UI 刷新正常，这得益于 Flutter 引擎的热重载机制在 OHOS 上已经跑通了。实测下来很稳，但还是建议不要频繁热重载改模型结构，容易遇到 Dart 侧 AOT/JIT 切换导致的编译缓慢。

6. 房间列表后续的可扩展方向

房间列表只是第一步。以我目前实现的数据模型，后续可以很顺畅地扩展这几个功能：

• 按房间查看家具明细：房间卡片点击进入家具列表页，数据源从Room.furnitureList取即可。
• 家具购买记录筛选：按日期范围、按价格区间筛选，可以在RoomStore上增加filteredRooms()方法，不影响现有页面结构。
• 房间排序与置顶：在Room实体上加一个sortWeight字段，然后在_rooms排序时处理。
• 持久化存储：现在loadMockData()是固定数据，后续可以换成sqflite（在 OpenHarmony 上可能需要找适配的数据库插件），或者直接写 JSON 文件存到应用沙盒目录。

我在写这个项目时最大的体会是：Flutter for OpenHarmony 的应用开发已经不再是"能跑 Demo"的程度，只要不碰深度系统能力，纯 Flutter 的业务页面完全可以平滑迁移到 OpenHarmony。房间列表这种典型的 CRUD + 状态管理场景，恰好是验证这套技术栈融合是否顺手的最佳试金石。

如果你也想在 OpenHarmony 上尝试 Flutter，建议从类似"名单管理""记账列表"这种小功能起步，先打通环境、再补状态管理，最后加交互细节。一条路径走顺了，后面再加花瓣组件、动画，都是锦上添花而已。