用Flutter打造跨平台手作教程记录本：从Android到鸿蒙适配实战

身边不少做手工的朋友都问过我同一个问题：你那些步骤图是怎么记得这么清楚的？其实不是我记忆力好，而是从很久以前开始，我就强迫自己把每次做皮具、绕线首饰、木作的完整过程，都沉淀成一份可以复用的教程。试过相册存图、备忘录写字、群里发消息，结果就是素材散落一地，真到要整理的时候，连一张过程图都找不到。后来我直接用手里的工具——Flutter，做了一款跨平台的手工DIY教程记录本，中文名叫“手作手账本”，核心就一句话：记录每一个创意时刻。这次除了Android和iOS，我还同步把鸿蒙端接上了，等于把跨平台开发这件事，从环境搭建到最终出包，完整地踩了一遍。

这篇文章适合两类人：一类是想做内容创作工具的Flutter开发者，可以参考核心模块设计和数据组织；另一类是公司要求同时出鸿蒙版本、但还不知道怎么落地的跨平台团队。我会把适配过程中的关键决策、实际操作的步骤、踩过的坑都写出来，尽量让文字可以直接当操作手册用。

1. 先想清楚“记录什么”，再谈用什么框架写

很多人一上来就问Flutter能不能跑鸿蒙、性能怎么样，我反而觉得产品逻辑没理清之前，聊框架都是空的。手工DIY教程记录本不是普通笔记软件，它的核心是把一个非线性、碎片化的创作过程，整理成一条可复现的线性教程。这个定位决定了整个技术方案。

1.1 一本手账真正要解决的事：把灵感变成教程

我最初的版本做得极其简单：一个列表加一个富文本编辑框，拍照就往里塞。用了一周发现问题严重——手作过程里最值钱的信息是“顺序”和“依赖关系”。比如绕线饰品，先弯骨架再缠线，最后固定配件，顺序乱了成品就废。而相册里的照片天然只有拍摄时间，没有步骤关系，事后根本排不回来。

所以重新设计时，我确定了几条产品底线：

• 记录单位不是“一条笔记”，而是“一个项目”，项目内部有步骤，步骤有顺序。
• 每一步可以挂多张图、一段文字、一个预估工时和一个难度标签。
• 材料清单和项目绑定，方便回头统计成本。
• 支持“进度状态”流转：灵感、备料、制作中、已完成。
• 所有数据必须本地优先，没有网络也能随时记录。

这些底线直接决定了数据模型的长相。后面章节会给出具体表结构和Dart类设计。这里我只想说一句：如果你要把手作过程做好，请把“教程”当成一等公民来设计，而不是把“日记”和“相册”拼在一起。

1.2 跨平台方案横评：为什么是Flutter而不是别家

标题里带了“跨平台”，那免不了把主流方案摆出来比一轮。我做这个应用时的备选有Flutter、uniapp、Electron、Tauri，以及Kotlin Multiplatform。最终选了Flutter，理由很实际。

比较下来，Flutter的优势不只是“一套代码两端跑”，而是它的UI自绘机制让复杂界面在不同设备上的表现差异最小。对我这个应用来说，步骤编辑器里有大量的拖拽排序、图片卡片堆叠、左右手滑动操作，用uniapp那种偏Web的渲染方式，到了中低端设备上很容易变成纸片人体验。

关于鸿蒙适配我还多说一句：现在的适配不是“官方Flutter开箱即用”，而是基于HarmonyOS的SDK和Flutter引擎做了一层桥接。你在工程里仍然写Dart，但构建目标变成了鸿蒙应用包（HAP）。这个我在下一章详细说。

2. Flutter工程接入鸿蒙：从SDK到工程结构再造

这一章是整个跨平台开发里最容易让新人放弃的地方。很多人以为装上Flutter、建个项目就能直接打鸿蒙包，真到了flutter build才发现根本没有这个target。我花了一整个周末才把链路走通，下面把这些步骤拆开讲。

2.1 环境准备：两个IDE和一个特殊分支

要完成鸿蒙侧的Flutter开发，你至少需要：

• DevEco Studio：鸿蒙应用的集成开发环境，负责编译HAP、管理SDK、跑模拟器。
• HarmonyOS SDK：通过DevEco Studio的SDK Manager下载，里面包含API、工具链和系统镜像。
• 适配过鸿蒙的Flutter SDK：这不是从flutter官网直接下的那个，而是走OpenHarmony适配分支的引擎，需要单独clone并切换分支。

我当时把原版Flutter SDK路径和适配版SDK路径分开维护，通过环境变量切换：

export FLUTTER_ROOT=/path/to/flutter-ohos export PATH=$FLUTTER_ROOT/bin:$PATH flutter doctor

这里有个容易踩的坑：如果你本机的Android Studio、DevEco Studio同时存在，flutter doctor会扫描到两套工具链，有时会报设备冲突。我的做法是只保留适配版SDK的路径映射，Android开发归Android开发，鸿蒙开发通过独立的shell环境启动，两个环境互不干扰。

2.2 工程的目录结构：多了一个“壳工程”

Flutter标准工程结构是lib/、android/、ios/，接入鸿蒙之后，工程里还会出现一个鸿蒙壳工程目录，里面是用ArkTS写的入口和桥接代码。结构大概是这样：

my_handbook/ ├── lib/ # 所有Dart业务代码 ├── android/ # Android壳工程 ├── ios/ # iOS壳工程 ├── ohos/ # 鸿蒙壳工程 │ ├── entry/ │ │ └── src/main/ │ │ └── ets/ # ArkTS入口，承载Flutter引擎 │ └── build-profile.json5 └── pubspec.yaml

我建议把鸿蒙壳工程当成一个独立模块看待，不要在里面写太多业务逻辑，它的职责就是启动Flutter引擎、注册平台通道。业务代码全部留在lib/，这样三个平台共享同一个Dart包，维护起来才轻松。

鸿蒙壳工程的创建不需要手动写，我用的方式是先创建一个标准Flutter项目，再用适配工具把鸿蒙壳工程生成出来。生成完先跑一次空壳，确认HAP能装上，再往里面集成业务代码。别一上来就把整个项目搬进去，否则排查问题时你根本分不清是Flutter报错还是壳工程报错。

2.3 大文件拆分：Dart的part关键字在这里帮了忙

接入过程中我遇到一个工程组织问题：教程记录本的功能模块越来越多，但Dart没有原生的“多文件Class”概念，所有Class拆分都需要通过import和part来组织。part和part of这套机制，很多人只在别人的源码里见过，真正在项目里用的时候还挺有用。

我的做法是把“教程编辑器”这个大文件拆成几个part文件，让同一个库内的私有方法可以跨文件访问。类似这样：

// editor.dart part 'editor_steps.dart'; part 'editor_materials.dart'; class CraftEditor { // 主逻辑 }

这样拆的好处是：编辑器内部状态、步骤渲染、材料面板这三大块可以分文件维护，同时共享主库的私有变量，减少写大量getter。但part也有个坑——一旦使用part，编辑器里的命名空间会扩大，两个子文件里的同类方法容易重名覆盖。我的经验是只在“内聚度高、共享私有状态强烈”的模块里使用part，普通页面还是老老实实用import。结构清晰永远比少写几行import重要。

3. 教程记录本的数据设计与状态管理：Cubit和轻量数据库

数据层是这个应用的命脉。我经历过“用共享Preferences存一切”的惨痛阶段，到项目里有几百个步骤时，读写卡顿、数据错乱、图片路径丢失全都来了。所以从重做第一版开始，我就坚持用一个正经的关系型数据库，并用状态管理框架把UI和持久化隔离。

3.1 数据模型：项目、步骤、材料，三张表打底

手工DIY教程记录本的核心模型，我用三张表表达：

class CraftProject { final String id; String title; String coverPath; ProjectStatus status; List<CraftStep> steps; List<MaterialItem> materials; } class CraftStep { final String id; final String projectId; String title; String description; List<String> imagePaths; int orderIndex; int durationMinutes; String difficulty; } class MaterialItem { final String id; final String projectId; String name; int quantity; String unit; double cost; }

数据库我用了sqflite，并在表上建了索引。步骤查询按projectId + orderIndex排序，材料按projectId查询。数据量级在千条以内，不用上太重型的ORM，保持SQL直观。

这里有个设计细节值得分享：步骤的图片不是存一张大图，而是存原图路径加压缩图路径两个字段。原图用于导出和打印，压缩图用于列表展示和快速加载。缩略图在拍摄后异步生成，生成完再更新数据库记录，避免主线程卡顿。

3.2 为什么状态管理选Cubit而不是Bloc

项目刚开始时我用的是Bloc，事件驱动确实规范，但写着写着就发现成本太高。每个页面改动都要定义Event、写State、处理Mapper，对于教程记录本这种“局部状态为主、交互微操作多”的工具类应用，有点大炮打蚊子。

后来我换成Cubit，它是Bloc的轻量版，不强制事件流，直接调方法修改状态。例如步骤排序时的状态更新：

class StepListCubit extends Cubit<List<CraftStep>> { StepListCubit() : super([]); Future<void> reorder(int oldIndex, int newIndex) async { final steps = List<CraftStep>.from(state); if (oldIndex < newIndex) newIndex -= 1; final item = steps.removeAt(oldIndex); steps.insert(newIndex, item); emit(steps); } }

这种写法的好处是UI层代码干净，直接context.read<StepListCubit>().reorder(...)就行，不需要为每个动作单独定义Event。当然Cubit也有它的边界：如果你要做全局审计、复杂状态回溯，还是Bloc更合适。我的判断标准很简单——“编辑器内的状态”用Cubit，“跨页面共享且需要回放的状态”才考虑Bloc。

3.3 状态持久化：每次变更是写数据库还是写内存

我采用的方式是“内存优先、定时落盘”。用户拖拽排序、修改文字、添加图片时，所有操作只改内存中的Cubit状态，界面即时响应；等到用户切换页面或点击保存时，才批量写入数据库。

这个设计和很多人的直觉相反，他们喜欢每次编辑都立刻更新数据库。但手作过程里用户会一边拍照片一边写备注，连续几十次操作，每次都做数据库事务，很容易卡顿。我的方案是：快速操作全部在内存，离开编辑页或App退到后台时统一保存。唯一要注意的是确保保存回调覆盖到所有退出路径，否则用户辛苦记的步骤就丢了。

4. 图片密集场景下的平台通道实战：相册通路与系统事件

记录本应用的一个核心动作是“拍一张步骤图”。在普通Android/iOS上，我直接用了现成的image_picker插件；但在鸿蒙端，第三方插件支持参差不齐，有些包还没适配。这就逼着我自己动手写平台通道。

4.1 为什么非要动平台通道：插件鸿蒙化的现实

跨平台开发的一个常见幻觉是“用了Flutter就有所有插件”。实际上鸿蒙生态里的Flutter插件数量远不如Android/iOS，图片选择、相册多选、缩略图读取这类能力，很多pub包要么没有鸿蒙端实现，要么只实现了部分接口，装上以后直接调不通。

我的策略是先查插件是否有ohos/目录，没有就优先绕行。比如相册图片缩略图，我直接通过MethodChannel调鸿蒙侧系统接口，绕开了不可靠的第三方包。

MethodChannel读取最近20张图片缩略图，Dart侧代码如下：

static const _channel = MethodChannel('com.handbook/album'); Future<List<AlbumImage>> loadRecentImages({int limit = 20}) async { final List? result = await _channel.invokeMethod( 'loadRecentImages', {'limit': limit}, ); return result ?.map((e) => AlbumImage.fromJson(Map<String, dynamic>.from(e as Map))) .toList() ?? []; }

鸿蒙壳工程里，用ArkTS实现同名Channel并返回图片列表，注册后即可调用。这里最需要注意的是MethodChannel的名字必须两端完全一致，大小写都不能差；以及返回的数据结构要和Dart侧约定好，我踩过的坑是侧返回了带引号的字符串，Dart侧按JSON解析，费了半小时才定位到类型问题。

4.2 EventChannel：监听相册变化，补上“拍完要立刻用”的闭环

MethodChannel解决的是“主动拉取”，但教程记录本还有一个高频场景：用户拍完一张过程照，App要第一时间提醒“是否把这张照片挂到当前步骤”。这就属于“原生到Flutter的持续事件推送”，是EventChannel的典型应用。

我在Dart侧写了一个事件流：

class AlbumObserver { static const _eventChannel = EventChannel('com.handbook/album_events'); Stream<AlbumImage> onNewImage() { return _eventChannel .receiveBroadcastStream() .cast<String>() .map((path) => AlbumImage(path: path)); } }

鸿蒙侧在相册数据变化回调里，把新增图片的路径通过EventSink.success推给Dart层。这样用户拍照的一瞬间，App就能弹出浮动提示。这里也有个容易忽略的细节：EventChannel必须有收听方才能推送，如果Dart侧页面没在监听，原生侧的sink会把事件丢掉。所以我的做法是在进入编辑页时开启监听，离开页面时关闭，避免事件积压和内存泄漏。

4.3 图片压缩链路：从拍摄到展示，三步不能省

手机原生拍出来的照片动辄3MB以上，如果直接放进Flutter列表，加载速度会非常难看。我在压缩链路里做了三步：

1. 拍摄成功后，立即用原生侧生成宽边为1080px的预览图。
2. 预览图存入应用缓存目录，数据库记录路径。
3. Flutter加载时，Image组件的cacheWidth设为720，让引擎从解码阶段就减少内存占用。

这一步做完，列表滚动立刻变顺。别小看cacheWidth，很多卡顿不是渲染问题，而是图片解码带来的内存和CPU开销。

5. 没有真机时怎么调鸿蒙：模拟器、云真机与抓包

做鸿蒙开发遇到的最大尴尬是手边没有鸿蒙手机。我一度以为只能干瞪眼，后来把能用的工具都试了一遍，发现调试路径其实比想象中多。

5.1 设备从哪来：模拟器、预览器、云真机

• DevEco Studio自带模拟器，可以在SDK Manager里下载系统镜像，启动后用hdc连接，和Android的adb用法高度相似。
• Previewer可以在不启动模拟器的情况下预览ArkTS页面，适合调试壳工程UI和通道注册。
• 远程云真机属于付费服务，偶尔用于做真机上的性能和相机验证。

我的常用路径是：业务逻辑在Flutter测试中跑，壳工程界面用Previewer，整机验证用模拟器，只有涉及相机、相册、传感器时才去申请云真机。真机最大的价值是验证平台通道是否真的被原生侧响应了，很多通道问题模拟器上是看不出来的。

5.2 从Android侧先跑通业务，再切换鸿蒙target

这个策略帮我省了非常多时间。教程记录本的数据模型、Cubit状态、编辑页面，绝大部分代码与平台无关，我先是把它跑在Android模拟器上，把所有逻辑和UI调稳定。等到Engineering Ready了，才切到鸿蒙target验证平台通道和壳工程。

切换方式是在工程里维护两个构建配置，一个Android target，一个鸿蒙target。flutter run默认跑Android，鸿蒙侧用DevEco Studio打开壳工程单独构建。一开始很多人把这当成两条死链路，其实它们共享同一个lib/目录，业务代码改一遍，两端同时生效。

5.3 Charles抓鸿蒙包：证书和代理的坑

联调接口时免不了要抓包，Charles在鸿蒙上的抓包流程和Android类似，但有细微差别。手机和电脑连同一个Wi-Fi，设置代理后手机上需要安装Charles的HTTPS证书，否则只能看到CONNECT请求，看不到明文内容。

和Android相比，鸿蒙的系统证书信任策略更严格，用户自己安装的证书默认不被应用信任。我查了一圈发现，需要在鸿蒙的设置里进入“证书管理”，手动开启对应用户证书的信任开关。装好之后，HTTPS解密才能生效。另外鸿蒙抓包不能像Android一样直接adb给所有应用装证书，每个应用是否信任用户证书还跟它的网络安全配置有关。如果发现某个应用还是抓不到包，先检查是不是应用自身配置了只信任系统证书。

5.4 跨平台一致性检查清单

调完鸿蒙之后，我整理了一张CheckList，每次发版前都要过一遍：

• 图片选择、保存图片到相册是否正常。
• 系统字体缩放时，步骤标题是否溢出。
• 深色模式下，卡片背景和文字对比度是否达标。
• 从后台恢复时，Cubit状态是否从数据库正确恢复。
• 无网络状态下，新增项目能不能正常保存。

这张清单看着基础，但每一条都在某个平台上出过问题。跨平台开发的成本，很大程度就耗在这些“两端不一致”的细节上。

6. Impeller渲染优化和几个“手不跟手”的体验细节

功能做完整后，我开始抠体验。手工DIY记录本的使用场景很特殊：用户可能在操作台旁边，一手拿着材料，另一手在手机上记录，这时候任何卡顿、掉帧、点击无反馈，都会让人当场血压上升。这一章说几个我实际调过的体验点。

6.1 Impeller渲染引擎：到底有没有用

Flutter这几年一直在推Impeller渲染引擎，用于替代原来的Skia。它的核心优势是引擎预编译shader，避免了Skia那种“新页面首次绘制时频繁编译shader导致的掉帧”。

我在鸿蒙适配分支上做了切换测试，直观感受是：列表页首次滚动的掉帧明显减少，步骤编辑页里大量圆角卡片、阴影叠加这类场景，渲染稳定性好了不少。但注意，Impeller并非在所有设备上默认开启，你需要在构建配置里显式打开编译开关。老设备上如果发现新引擎兼容性有问题，可以随时切回Skia。我的建议是：先把开关打开，用真机跑一遍核心场景，如果遇到纹理异常再回退，别因为网上的言论提前劝退。

6.2 TabBar切换动画：取消掉才是跟手

记录本的主界面有几个Tab：灵感、进行中、完成、材料库。默认的TabBar样式带一个滑动动画，实际体验下来，切换时总感觉慢半拍。后来我在点击事件里直接改了选中的索引，不触发自带动画：

TabController controller; void switchTab(int index) { if (controller.index == index) return; controller.animateTo(index, duration: Duration.zero); }

把动画时长设为零，不代表界面变得生硬，反而是让切换更直接。对工具型应用来说，“快”就是最好的反馈。这里我学到的一个底层道理：动画不是越多越好，有些高频交互的动画只会让人觉得App反应慢。

6.3 列表滚动卡顿：别让图片解码拖垮帧率

步骤列表里每一行都可能有图片，这也是最容易掉帧的地方。除了前面提到的cacheWidth，还有一个技巧是给图片组件加gaplessPlayback: true，让图片切换时不闪白。

最理想的方案是列表只显示缩略图，等用户点开大图时才加载原图。我测试下来，1080px预览图在手机上显示已经足够清晰，2024年的中端机跑这个列表都能稳帧。

6.4 发布前的包体和签名

HarmonyOS出包需要配置签名文件。我用自动签名模式，把签名信息放到配置里，方便CI打包。包体方面，Flutter引擎本身会占用一部分体积，教程记录本全量构建后约在40MB左右，其中引擎占了一半以上，这个体积在可接受范围内。如果后续做轻度化，可以考虑拆分so库按ABI加载，当前阶段没这个必要。

最后分享一个我坚持了很久的习惯：每完成一个版本的记录本开发，我都会用它在真实的手作过程中记录一条完整的教程。这个动作比任何测试用例都管用，它能让你迅速发现“数据丢失”“步骤排序不对”“图片加载慢”这类用户才会在意的问题。工具是给自己用的，就一定要把自己当成最挑剔的用户。