在把 Flutter 应用迁到 OpenHarmony 上跑通之后我接到的第一个实战需求就是给生活助手 App 加一个日记本功能。这个功能看起来不大但要真正做得顺手涉及的数据存储、状态管理、权限适配、页面性能样样都是硬骨头。折腾完一轮之后我把完整实现过程整理了出来包括环境准备、数据结构设计、存储选型、核心页面编码和最终踩坑记录希望给正在做 Flutter for OpenHarmony 迁移的开发者一些可以直接抄作业的参考。1. 从“跨端开发”视角看 OpenHarmony 上的 Flutter1.1 为什么需要在 OpenHarmony 上跑 Flutter这年头做客户端开发最烦的就是一套业务逻辑写好几遍。Android 一套、iOS 一套如果还想覆盖 OpenHarmony再单独维护一套原生工程人力成本直接翻倍。Flutter 的优势在于渲染引擎自绘不依赖系统原生控件所以理论上只要能提供一套稳定的平台插件桥接就能把业务代码完整跑起来。OpenHarmony 这边对 Flutter 的适配已经走过了从“能跑 Demo”到“能上生产功能”的阶段我查了一圈资料再结合自己跑通的经验结论是常规 UI 页面、列表、表单、网络请求、本地存储这些能力已经完全具备落地条件。需要说明的是这里的 Flutter for OpenHarmony 并不是简单的“把工程复制过去改个包名”而是需要额外配置 OpenHarmony 的 SDK 环境、引入适配插件、处理好页面生命周期和系统权限的差异。我把这次日记本功能当作一块试金石某种意义上它覆盖了一个典型业务模块的大部分常见场景有输入、有列表、有图片、有持久化都趟通了后面做其他模块就有底气了。1.2 环境准备与工程初始化先说环境我用的组合是Flutter SDK 配合 OpenHarmony SDK开发工具采用支持 OpenHarmony 工程的 IDE。你可以把 OpenHarmony SDK 理解成构建和调试 OpenHarmony 应用的基础库集合它里面既有系统 API也有编译链接需要的工具链。首次配置流程我建议按这个顺序来安装 Flutter SDK并切换到稳定分支。这个步骤很常规下载完压缩包解压把bin目录加进系统环境变量就行。安装支持 OpenHarmony 的 IDE建议官方版本避免第三方定制版带来的未知问题。在 IDE 里配置 OpenHarmony SDK 路径启动后会要求你指定 SDK 所在目录一般默认是安装目录下的sdk文件夹。配置hdc工具它是连接真机或模拟器的命令行工具类似 Android 的 adb。配置好之后hdc list targets能看到设备。在工程里启用 OpenHarmony 平台。Flutter 新建工程默认不会生成 OpenHarmony 目录需要执行平台添加命令生成ohos目录作为原生壳工程。我第一次跑通的时候卡在 SDk 路径识别上IDE 一直提示找不到工具链。后来发现是自己的环境变量里残留了旧版本的路径把旧路径清干净再重新指定 SDK 位置问题就解决了。这里多说一句不同版本的 SDK 对 Flutter 适配插件的版本要求不一样不要盲目升级先确认当前 Flutter 版本所配套的插件版本再去下载 SDK能省很多折腾时间。1.3 工程结构变化与版本对照初始化完毕之后你会看到工程里多出若干新目录目录或文件作用ohosOpenHarmony 原生工程入口负责应用壳、权限声明、原生插件注册ohos/entry/src/main/module.json5权限和模块配置类似 Android 的 AndroidManifestlib/Flutter 业务代码完全跨平台复用ohos/oh-package.json5OpenHarmony 侧的三方依赖声明我建议把工程模板里自带的示例代码清空直接从main.dart写起。不要尝试用 Android 的思维硬套 OpenHarmony 的配置虽然两者有很多相似概念但模块配置的写法差异很大。版本这块我直接给个参考组合Flutter 使用较新的稳定分支OpenHarmony SDK 使用 4.x 系列稳定版本。这个组合在我测试下来编译速度、调试稳定性和插件兼容性都相对理想。如果你刚好要用某款带原生依赖的 Flutter 插件一定要去确认它对 OpenHarmony 的适配情况没有适配的原生插件是跑不起来的这是此次实战里最大的限制因素。2. 日记本功能的需求拆解与数据设计2.1 最小可用功能清单日记本听起来简单但“简单”和“简陋”之间差着一整套细节设计。我一开始列功能清单时只写了“新增日记、编辑日记、查看列表”等真正动手才发现至少还需要“删除确认、草稿保存、内容时间排序、心情标签、图片附带”这些能力。不做全Demo 是跑通了但用户实际用起来会非常别扭。最终我给这个模块圈定的最小可用范围是首页展示日记列表按照更新时间倒序排列。点击“写日记”进入编辑页支持标题、正文、心情、天气、图片。列表页支持下拉刷新和上滑加载更多数据量大时不卡顿。日记详情页支持富文本阅读和图片查看。本地持久化断网可用不依赖服务端。支持删除和修改。这个范围刚好把 Flutter 的常用能力全部覆盖了一遍又没有引入实时同步、多端协同这些容易失控的需求。如果你正在做类似的项目我建议也先砍掉“云同步”这种看起来很酷但工作量巨大的部分先把单机体验做到顺滑再去谈能力扩展。2.2 数据模型的字段取舍数据模型是日记本功能的地基后面所有页面的编写都依赖它。我最终设计的日记数据模型包含这些字段字段类型说明idString主键用 UUID 生成避免自增主键在同步时的冲突titleString标题可为空contentString正文内容纯文本moodString心情例如“开心”“平静”“低落”weatherString天气情况imageListListString图片路径列表createdAtint创建时间戳毫秒级updatedAtint最后更新时间戳isFavoritebool是否收藏方便以后做筛选这里说一个字段设计的思考时间戳为什么不直接用字符串格式2025-01-01 12:00:00而是用毫秒整数因为日记列表经常需要按时间排序和按日期过滤整数时间戳比较大小、转成日期字符串都很快而且跨平台传输时不会有格式解析差异。显示的时候再通过格式化函数转成可读文本就行。图片字段我选了 List 存储路径字符串而不是把图片转成 Base64 塞进数据库。原因很简单Base64 会让数据库体积爆炸而且读取时要把全部数据加载到内存容易卡顿。存路径配合图片缓存目录既保证了性能又方便以后迁移到服务端时直接上传文件。2.3 存储方案对比与选型数据持久化方案在 Flutter 里有很多种但放到 OpenHarmony 平台上选择范围会缩小一些。我在实际项目里对比了三种方案最终结合可靠性做了取舍轻量键值存储适合存放用户偏好设置比如主题色、是否首次启动。如果日记只用它查询、排序、分页会写得很别扭不建议。文件存储适合保存大体积的图片或者导出的文本文件。如果日记正文直接写文件每次修改都要全量覆盖删除、检索、加密都比较麻烦而且并发写入容易出问题。数据库存储结构化数据的最佳选择。日记本身就是典型的“有字段、要筛选、要排序”的结构化数据数据库天然适合。最终我选择在 OpenHarmony 平台使用 SQLite 作为底座上层封装一个 DAO 层。代码里不用平台私有 API直接用sqflite插件的 OpenHarmony 适配版本。这里我提个关键点你拿到手的三方依赖命名可能和 Android 端完全同名但实际的底层实现已经切换成了 OpenHarmony 的驱动所以务必确认依赖来源不要从 Android 仓直接拉。数据库表结构很简单建表语句参考CREATE TABLE diary ( id TEXT PRIMARY KEY, title TEXT, content TEXT, mood TEXT, weather TEXT, imageList TEXT, createdAt INTEGER NOT NULL, updatedAt INTEGER NOT NULL, isFavorite INTEGER DEFAULT 0 );imageList字段用 JSON 数组字符串存储读取时反序列化成 List。为了以后表结构升级我在数据库初始化时加了版本号后续如果需要加字段直接在onUpgrade里处理不需要删表重建。3. 核心页面实现与交互细节3.1 列表页渲染性能与交互选择日记列表页是用户看到的第一屏也是性能敏感区域。我一开始图省事直接用ListView塞进一个完整列表日记数量到一百条左右时滑动就有点不跟手了。后来换成了ListView.builder按需构建 item加上固定 item 高度后滑动流畅度立刻上来了。列表项我封装成了独立的 Widget 组件卡片内部展示标题、内容摘要、心情标签和更新时间。排版上要注意摘要最多两行多的用省略号截断不然不同卡片高度不一视觉上会显得非常乱。卡片点击进入详情页长按弹删除确认框。删除操作我做了二次确认因为日记属于用户比较在意的内容误删代价高。下拉刷新我用的是RefreshIndicator在 OpenHarmony 上表现正常没有遇到兼容性问题。上滑加载更多则需要自己监听滚动位置我综合采用滚动通知判断“滚动位置接近底部时”触发分页逻辑每页加载 20 条。分页的好处不只是减少数据库查询还在于减少首屏构建的组件数量间接提升启动速度。有个经验值得分享列表页的 item 缓存一定要开AutomaticKeepAliveClientMixin可以帮你在列表滚动时保留滚动位置和页面状态。如果不开从详情页返回列表时列表会重新加载数据用户就感觉 App 很“呆”。开了之后返回列表几乎无感刷新体验直接上一个档次。3.2 编辑器草稿保存与软键盘处理编辑器是整个日记本功能里最容易出“阴间问题”的地方。我先说状态页面包含标题输入框、正文输入框、心情选择、图片添加按钮。正文输入框我设置自动换行和最大长度避免用户无限输入导致内存压力过大。草稿保存是我觉得最值得做的一个功能。用户写日记时切走应用或误触返回内容就丢了这是非常劝退的体验。我用TextEditingController监听输入变化配合 500 毫秒防抖把内容写进数据库表里的一个独立草稿字段。防抖的意思是如果用户连续输入每次输入事件都会重置计时器直到用户停顿 500 毫秒才执行保存避免每敲一个字符就触发一次磁盘写入那会极其耗电且卡顿。这个思路很简单实测下来非常稳。软键盘遮挡的问题一开始我用的是调整布局resizeToAvoidBottomInset在 Android 和 OpenHarmony 上表现不太一样。OpenHarmony 对软键盘的弹出高度计算存在略微差异我最终用Scaffold的默认行为配合SingleChildScrollView包住输入区实测下来没有出现键盘挡住正文区域的情况。心情选择我用一排ChoiceChip实现选中的心情会改变卡片主题色。颜色映射直接做成常量表不要用散落在各处的魔法色值。这里有个小的交互细节选择心情后要立刻把新心情写入当前编辑状态否则用户切页返回时会发现心情没了原因就是编辑页面内存重建后状态没有恢复。3.3 详情页与图片查看详情页做的事情是把列表页点击的日记 ID 作为参数传入然后从数据库里按 ID 重新查询。这里有个很重要的经验不建议直接把整个日记对象通过路由参数传递因为这样占内存且数据可能过期详情页自己从数据库查一次永远是最可靠的。正文展示我用纯文本加换行处理富文本渲染虽然容易做但对于日记类内容引入过重的语法解析库并不划算日常写日记的人不会用 Markdown 语法。当然如果你想做得更高级可以在后续版本里加但第一版尽量保持“所见即所得”。图片查看在这个场景里属于刚需我用InteractiveViewer实现了捏合缩放和双击放大。OpenHarmony 对手势支持比较完整跑出来没有延迟感。图片列表平铺在页面底部点击任意一张会打开大图预览左右滑动切换图片。图片加载时如果读取失败我会展示一个占位图标避免白屏让用户以为应用崩溃了。4. 系统能力接入与平台差异适配4.1 图片选择与权限声明日记本要附图就绕不开相册访问权限。OpenHarmony 的权限模型和 Android 类似但在module.json5里声明的写法完全不同。这里我不展开全部字段只强调最关键的一句话所有涉及用户隐私的系统能力必须先声明权限再在运行时动态申请。不要假设只要声明了权限就能直接调用运行时弹窗授权后的回调如果被忽略UI 上毫无反应用户会认为功能是坏的。图片选择的实现我推荐优先用系统提供的相册选择能力而不是自己遍历文件目录做相册 UI。自己去扫图片是又慢又复杂还要处理各种图片格式和权限边界。系统选择器可以直接返回图片 URI 列表再从 URI 拷贝到应用私有目录。拷到私有目录这个动作对日记本场景尤其重要因为系统相册里的图片可能被用户删除或改名如果日记只存了一个外部引用之后图片打不开就很尴尬。4.2 平台差异从 Android 经验迁移的注意点做过 Android 的朋友在 OpenHarmony 上写代码最容易踩的坑是路径语义不一致。Android 的content://和file://体系在 OpenHarmony 里不能照搬需要走 OpenHarmony 自己的统一资源标识符。我在适配时写了一个路径转换工具函数统一做两层处理如果是网络图片直接使用完整 URL。如果是本地图片先判断是否已经被拷贝到了应用目录如果是则直接用绝对路径否则先执行拷贝。这两步转换让页面代码不用关心图片来源全部走同一个加载接口省了很多分支。你在自己项目里也可以封装类似工具核心思想是“让上层代码只见到统一对象具体差异下沉到工具层”。再有一点系统通知渠道的配置在两个平台上也不一样。日记本功能暂时没做定时提醒如果后续要做“每日写日记提醒”务必检查 notification 配置里的渠道 ID 和权限声明否则通知发不出来还会直接崩溃。4.3 状态管理与异步安全Flutter 开发绕不开 state 管理。这个项目我选的是轻量的ChangeNotifier配合provider没有引入重量级状态管理库。为什么这么选因为项目体量小页面跳转简单全局共享的状态只有“当前日记列表”和“草稿状态”引入复杂状态管理反而是负担。这不是说那个方案不好而是说每个项目都有自己的复杂度边界工具要为场景服务。异步安全是我这次特别注意的点。日记保存、图片拷贝都是耗时操作绝不能直接放在主线程里同步执行。我在 DAO 层全部用了async/await同时给数据库操作加了超时保护避免底层无响应时 UI 一直转圈。有个细节值得提异步操作完成后更新 UI 前要检查mounted。Flutter 页面在异步返回前有可能已经被销毁此时再执行setState会直接报错。这个问题在真机调试时很隐蔽因为发生概率不高但一旦用户快速切页就会触发。我的处理方式是封装一个安全状态更新函数内部统一判断mounted所有页面更新入口都走这个函数基本杜绝了这个崩溃点。5. 测试、联调与常见问题排查5.1 真机联调流程模拟器跑 Flutter 的 OpenHarmony 工程是可以的但要想验证输入法、相册权限、真实存储读写这些能力强烈建议上真机。联调前做三件事打开开发者模式、开启 USB 调试、确认 hdc 能识别设备。这三步任何一个没就位IDE 里都会显示“未找到设备”或者“target not found”。调试时我推荐同时开两个终端一个跑flutter run实时看日志一个用hdc shell查看系统日志。Flutter 层级的打印会走 Flutter 日志通道而原生插件、权限弹窗等系统行为的日志走系统通道只看其中一个容易漏掉关键线索。我这次调试图片选择权限时就是因为只看 Flutter 日志没注意到系统日志里的权限拒绝原因白折腾了半天。热重载在 Flutter 层面很好用修改 Dart 代码后按r键几秒内就能看到效果。但请记住一个边界如果修改了 OpenHarmony 原生配置比如权限声明、原生插件版本热重载不一定生效此时需要全量重新编译安装。我建议改原生代码前先想清楚是否必要否则每次全量编译的时间成本累积起来很可观。5.2 常见问题速查表我把这次开发里遇到的典型问题按出现频率整理成了表格按这个顺序排查能少走很多弯路。问题描述可能原因解决方法应用启动后白屏原生工程未正确注册 Flutter 入口检查ohos工程里的 Ability 配置是否注册了 FlutterAbility数据库操作报“表不存在”初始化时未执行建表语句确认在数据库初始化回调里执行了CREATE TABLE图片加载显示空白路径未加 file 前缀或文件未拷贝统一走路径转换工具函数输入框被键盘遮挡页面未处理软键盘变化用SingleChildScrollView包住输入区列表滚动掉帧item 组件太重或未固定高度改用ListView.builder并设置itemExtent点击日记返回后列表丢失滚动位置未保留页面状态使用AutomaticKeepAliveClientMixin权限弹窗不出现运行时未动态申请权限必须在 UI 触发动作后再调用权限请求中文字符串出现乱码编码不一致或文件格式错误统一将源码文件保存为 UTF-8 编码5.3 几个容易被忽略的坑这些坑我在网上搜不到现成资料基本是靠自己踩出来的分享出来避免后人重复踩第一个坑是“数据库放在哪”。OpenHarmony 应用在不同机型上的目录结构并不是百分百一致如果你硬编码了某台机器上的绝对路径换一台设备就跑不通。正确做法是通过路径接口获取应用私有目录在私有目录下再拼接数据库文件名。这个思路用户数据隔离也更加安全。第二个坑是“时间显示格式”。OpenHarmony 上部分默认字体对中文日期展示了奇怪的效果最后发现是 locale 设置没有跟随系统。解决方案是在应用初始化时手动设置本地化上下文强制使用中文环境。如果不设手机系统切到英文模式时日记日期会变成英文有些用户会觉得不贴身。第三个坑是关于图片缓存目录的清理。日记里引用的图片如果被系统缓存清理删掉了详情页打开时就会显示加载失败。我的处理办法是在图片加载失败的回调里显示“图片已过期”的占位文案而不是默默白屏。至少用户知道发生了什么而不是觉得应用有鬼。第四个坑是列表分页时的一个边界当数据库只有 20 条数据时首页一次加载 20 条就不会触发上滑分页。但如果用户在编辑页删除了几条返回列表后要重新刷新总条数否则会出现“明明还有数据但列表底部提示没有了”的错觉。我在删除操作成功后强制触发列表刷新必要时让列表回到顶部避免混乱。6. 一些后续可以做的扩展功能跑完基础版本后我其实有留几个待办项算是给这个模块预留的扩展空间。如果你们团队的规划也想往这个方向走可以参考一下。第一个可以扩展的是全文搜索。当前数据层已经用了数据库搜索就不是什么难事添加一个搜索入口对标题和正文做模糊匹配即可。难点在于搜索结果的展示体验是跳转详情还是列表里高亮关键词这个交互需要细抠。第二个是日记模板。有一部分用户写日记并不喜欢自由发挥更习惯有固定模板比如“今天做了什么”“今日感恩”“天气预报”。做一套模板选择器把模板字段提前注入编辑器能明显提升用户持续记录的动力。第三个是数据导出。OpenHarmony 用户的本地数据如果没有导出机制一旦换机迁移成本就会很高。后续可以考虑把日记导出成 Markdown 或 PDF 文件让用户保留个人数据的主权。这个功能技术上不难但是涉及到文件生成、编码兼容、大文件处理需要单独一个版本去做。做完整套实现后我个人最大的体会是Flutter for OpenHarmony 的组合已经不再只是“可以在上面跑跑 Demo”而是确实能承载一个常规业务模块的完整落地。日记本功能从头到尾没有依赖任何服务端全部本地完成说明这套跨端方案在基础性能和数据持久化上已经有足够的工程可用性。最后再分享一个小技巧写这类多页面业务模块时我习惯在工程里单独维护一个页面路由表所有页面跳转都通过统一的导航方法完成。这样以后要增加跳转参数、加埋点、做统一拦截都只需要改一个文件不用满工程找跳转点。这个习惯帮我省了非常多麻烦也推荐给刚转到 Flutter 开发的朋友。 
长河君 · 2026/10/18 8:31:43 · 阅读 1.2k Flutter迁移OpenHarmony实战：日记本功能完整实现
在把 Flutter 应用迁到 OpenHarmony 上跑通之后我接到的第一个实战需求就是给生活助手 App 加一个日记本功能。这个功能看起来不大但要真正做得顺手涉及的数据存储、状态管理、权限适配、页面性能样样都是硬骨头。折腾完一轮之后我把完整实现过程整理了出来包括环境准备、数据结构设计、存储选型、核心页面编码和最终踩坑记录希望给正在做 Flutter for OpenHarmony 迁移的开发者一些可以直接抄作业的参考。1. 从“跨端开发”视角看 OpenHarmony 上的 Flutter1.1 为什么需要在 OpenHarmony 上跑 Flutter这年头做客户端开发最烦的就是一套业务逻辑写好几遍。Android 一套、iOS 一套如果还想覆盖 OpenHarmony再单独维护一套原生工程人力成本直接翻倍。Flutter 的优势在于渲染引擎自绘不依赖系统原生控件所以理论上只要能提供一套稳定的平台插件桥接就能把业务代码完整跑起来。OpenHarmony 这边对 Flutter 的适配已经走过了从“能跑 Demo”到“能上生产功能”的阶段我查了一圈资料再结合自己跑通的经验结论是常规 UI 页面、列表、表单、网络请求、本地存储这些能力已经完全具备落地条件。需要说明的是这里的 Flutter for OpenHarmony 并不是简单的“把工程复制过去改个包名”而是需要额外配置 OpenHarmony 的 SDK 环境、引入适配插件、处理好页面生命周期和系统权限的差异。我把这次日记本功能当作一块试金石某种意义上它覆盖了一个典型业务模块的大部分常见场景有输入、有列表、有图片、有持久化都趟通了后面做其他模块就有底气了。1.2 环境准备与工程初始化先说环境我用的组合是Flutter SDK 配合 OpenHarmony SDK开发工具采用支持 OpenHarmony 工程的 IDE。你可以把 OpenHarmony SDK 理解成构建和调试 OpenHarmony 应用的基础库集合它里面既有系统 API也有编译链接需要的工具链。首次配置流程我建议按这个顺序来安装 Flutter SDK并切换到稳定分支。这个步骤很常规下载完压缩包解压把bin目录加进系统环境变量就行。安装支持 OpenHarmony 的 IDE建议官方版本避免第三方定制版带来的未知问题。在 IDE 里配置 OpenHarmony SDK 路径启动后会要求你指定 SDK 所在目录一般默认是安装目录下的sdk文件夹。配置hdc工具它是连接真机或模拟器的命令行工具类似 Android 的 adb。配置好之后hdc list targets能看到设备。在工程里启用 OpenHarmony 平台。Flutter 新建工程默认不会生成 OpenHarmony 目录需要执行平台添加命令生成ohos目录作为原生壳工程。我第一次跑通的时候卡在 SDk 路径识别上IDE 一直提示找不到工具链。后来发现是自己的环境变量里残留了旧版本的路径把旧路径清干净再重新指定 SDK 位置问题就解决了。这里多说一句不同版本的 SDK 对 Flutter 适配插件的版本要求不一样不要盲目升级先确认当前 Flutter 版本所配套的插件版本再去下载 SDK能省很多折腾时间。1.3 工程结构变化与版本对照初始化完毕之后你会看到工程里多出若干新目录目录或文件作用ohosOpenHarmony 原生工程入口负责应用壳、权限声明、原生插件注册ohos/entry/src/main/module.json5权限和模块配置类似 Android 的 AndroidManifestlib/Flutter 业务代码完全跨平台复用ohos/oh-package.json5OpenHarmony 侧的三方依赖声明我建议把工程模板里自带的示例代码清空直接从main.dart写起。不要尝试用 Android 的思维硬套 OpenHarmony 的配置虽然两者有很多相似概念但模块配置的写法差异很大。版本这块我直接给个参考组合Flutter 使用较新的稳定分支OpenHarmony SDK 使用 4.x 系列稳定版本。这个组合在我测试下来编译速度、调试稳定性和插件兼容性都相对理想。如果你刚好要用某款带原生依赖的 Flutter 插件一定要去确认它对 OpenHarmony 的适配情况没有适配的原生插件是跑不起来的这是此次实战里最大的限制因素。2. 日记本功能的需求拆解与数据设计2.1 最小可用功能清单日记本听起来简单但“简单”和“简陋”之间差着一整套细节设计。我一开始列功能清单时只写了“新增日记、编辑日记、查看列表”等真正动手才发现至少还需要“删除确认、草稿保存、内容时间排序、心情标签、图片附带”这些能力。不做全Demo 是跑通了但用户实际用起来会非常别扭。最终我给这个模块圈定的最小可用范围是首页展示日记列表按照更新时间倒序排列。点击“写日记”进入编辑页支持标题、正文、心情、天气、图片。列表页支持下拉刷新和上滑加载更多数据量大时不卡顿。日记详情页支持富文本阅读和图片查看。本地持久化断网可用不依赖服务端。支持删除和修改。这个范围刚好把 Flutter 的常用能力全部覆盖了一遍又没有引入实时同步、多端协同这些容易失控的需求。如果你正在做类似的项目我建议也先砍掉“云同步”这种看起来很酷但工作量巨大的部分先把单机体验做到顺滑再去谈能力扩展。2.2 数据模型的字段取舍数据模型是日记本功能的地基后面所有页面的编写都依赖它。我最终设计的日记数据模型包含这些字段字段类型说明idString主键用 UUID 生成避免自增主键在同步时的冲突titleString标题可为空contentString正文内容纯文本moodString心情例如“开心”“平静”“低落”weatherString天气情况imageListListString图片路径列表createdAtint创建时间戳毫秒级updatedAtint最后更新时间戳isFavoritebool是否收藏方便以后做筛选这里说一个字段设计的思考时间戳为什么不直接用字符串格式2025-01-01 12:00:00而是用毫秒整数因为日记列表经常需要按时间排序和按日期过滤整数时间戳比较大小、转成日期字符串都很快而且跨平台传输时不会有格式解析差异。显示的时候再通过格式化函数转成可读文本就行。图片字段我选了 List 存储路径字符串而不是把图片转成 Base64 塞进数据库。原因很简单Base64 会让数据库体积爆炸而且读取时要把全部数据加载到内存容易卡顿。存路径配合图片缓存目录既保证了性能又方便以后迁移到服务端时直接上传文件。2.3 存储方案对比与选型数据持久化方案在 Flutter 里有很多种但放到 OpenHarmony 平台上选择范围会缩小一些。我在实际项目里对比了三种方案最终结合可靠性做了取舍轻量键值存储适合存放用户偏好设置比如主题色、是否首次启动。如果日记只用它查询、排序、分页会写得很别扭不建议。文件存储适合保存大体积的图片或者导出的文本文件。如果日记正文直接写文件每次修改都要全量覆盖删除、检索、加密都比较麻烦而且并发写入容易出问题。数据库存储结构化数据的最佳选择。日记本身就是典型的“有字段、要筛选、要排序”的结构化数据数据库天然适合。最终我选择在 OpenHarmony 平台使用 SQLite 作为底座上层封装一个 DAO 层。代码里不用平台私有 API直接用sqflite插件的 OpenHarmony 适配版本。这里我提个关键点你拿到手的三方依赖命名可能和 Android 端完全同名但实际的底层实现已经切换成了 OpenHarmony 的驱动所以务必确认依赖来源不要从 Android 仓直接拉。数据库表结构很简单建表语句参考CREATE TABLE diary ( id TEXT PRIMARY KEY, title TEXT, content TEXT, mood TEXT, weather TEXT, imageList TEXT, createdAt INTEGER NOT NULL, updatedAt INTEGER NOT NULL, isFavorite INTEGER DEFAULT 0 );imageList字段用 JSON 数组字符串存储读取时反序列化成 List。为了以后表结构升级我在数据库初始化时加了版本号后续如果需要加字段直接在onUpgrade里处理不需要删表重建。3. 核心页面实现与交互细节3.1 列表页渲染性能与交互选择日记列表页是用户看到的第一屏也是性能敏感区域。我一开始图省事直接用ListView塞进一个完整列表日记数量到一百条左右时滑动就有点不跟手了。后来换成了ListView.builder按需构建 item加上固定 item 高度后滑动流畅度立刻上来了。列表项我封装成了独立的 Widget 组件卡片内部展示标题、内容摘要、心情标签和更新时间。排版上要注意摘要最多两行多的用省略号截断不然不同卡片高度不一视觉上会显得非常乱。卡片点击进入详情页长按弹删除确认框。删除操作我做了二次确认因为日记属于用户比较在意的内容误删代价高。下拉刷新我用的是RefreshIndicator在 OpenHarmony 上表现正常没有遇到兼容性问题。上滑加载更多则需要自己监听滚动位置我综合采用滚动通知判断“滚动位置接近底部时”触发分页逻辑每页加载 20 条。分页的好处不只是减少数据库查询还在于减少首屏构建的组件数量间接提升启动速度。有个经验值得分享列表页的 item 缓存一定要开AutomaticKeepAliveClientMixin可以帮你在列表滚动时保留滚动位置和页面状态。如果不开从详情页返回列表时列表会重新加载数据用户就感觉 App 很“呆”。开了之后返回列表几乎无感刷新体验直接上一个档次。3.2 编辑器草稿保存与软键盘处理编辑器是整个日记本功能里最容易出“阴间问题”的地方。我先说状态页面包含标题输入框、正文输入框、心情选择、图片添加按钮。正文输入框我设置自动换行和最大长度避免用户无限输入导致内存压力过大。草稿保存是我觉得最值得做的一个功能。用户写日记时切走应用或误触返回内容就丢了这是非常劝退的体验。我用TextEditingController监听输入变化配合 500 毫秒防抖把内容写进数据库表里的一个独立草稿字段。防抖的意思是如果用户连续输入每次输入事件都会重置计时器直到用户停顿 500 毫秒才执行保存避免每敲一个字符就触发一次磁盘写入那会极其耗电且卡顿。这个思路很简单实测下来非常稳。软键盘遮挡的问题一开始我用的是调整布局resizeToAvoidBottomInset在 Android 和 OpenHarmony 上表现不太一样。OpenHarmony 对软键盘的弹出高度计算存在略微差异我最终用Scaffold的默认行为配合SingleChildScrollView包住输入区实测下来没有出现键盘挡住正文区域的情况。心情选择我用一排ChoiceChip实现选中的心情会改变卡片主题色。颜色映射直接做成常量表不要用散落在各处的魔法色值。这里有个小的交互细节选择心情后要立刻把新心情写入当前编辑状态否则用户切页返回时会发现心情没了原因就是编辑页面内存重建后状态没有恢复。3.3 详情页与图片查看详情页做的事情是把列表页点击的日记 ID 作为参数传入然后从数据库里按 ID 重新查询。这里有个很重要的经验不建议直接把整个日记对象通过路由参数传递因为这样占内存且数据可能过期详情页自己从数据库查一次永远是最可靠的。正文展示我用纯文本加换行处理富文本渲染虽然容易做但对于日记类内容引入过重的语法解析库并不划算日常写日记的人不会用 Markdown 语法。当然如果你想做得更高级可以在后续版本里加但第一版尽量保持“所见即所得”。图片查看在这个场景里属于刚需我用InteractiveViewer实现了捏合缩放和双击放大。OpenHarmony 对手势支持比较完整跑出来没有延迟感。图片列表平铺在页面底部点击任意一张会打开大图预览左右滑动切换图片。图片加载时如果读取失败我会展示一个占位图标避免白屏让用户以为应用崩溃了。4. 系统能力接入与平台差异适配4.1 图片选择与权限声明日记本要附图就绕不开相册访问权限。OpenHarmony 的权限模型和 Android 类似但在module.json5里声明的写法完全不同。这里我不展开全部字段只强调最关键的一句话所有涉及用户隐私的系统能力必须先声明权限再在运行时动态申请。不要假设只要声明了权限就能直接调用运行时弹窗授权后的回调如果被忽略UI 上毫无反应用户会认为功能是坏的。图片选择的实现我推荐优先用系统提供的相册选择能力而不是自己遍历文件目录做相册 UI。自己去扫图片是又慢又复杂还要处理各种图片格式和权限边界。系统选择器可以直接返回图片 URI 列表再从 URI 拷贝到应用私有目录。拷到私有目录这个动作对日记本场景尤其重要因为系统相册里的图片可能被用户删除或改名如果日记只存了一个外部引用之后图片打不开就很尴尬。4.2 平台差异从 Android 经验迁移的注意点做过 Android 的朋友在 OpenHarmony 上写代码最容易踩的坑是路径语义不一致。Android 的content://和file://体系在 OpenHarmony 里不能照搬需要走 OpenHarmony 自己的统一资源标识符。我在适配时写了一个路径转换工具函数统一做两层处理如果是网络图片直接使用完整 URL。如果是本地图片先判断是否已经被拷贝到了应用目录如果是则直接用绝对路径否则先执行拷贝。这两步转换让页面代码不用关心图片来源全部走同一个加载接口省了很多分支。你在自己项目里也可以封装类似工具核心思想是“让上层代码只见到统一对象具体差异下沉到工具层”。再有一点系统通知渠道的配置在两个平台上也不一样。日记本功能暂时没做定时提醒如果后续要做“每日写日记提醒”务必检查 notification 配置里的渠道 ID 和权限声明否则通知发不出来还会直接崩溃。4.3 状态管理与异步安全Flutter 开发绕不开 state 管理。这个项目我选的是轻量的ChangeNotifier配合provider没有引入重量级状态管理库。为什么这么选因为项目体量小页面跳转简单全局共享的状态只有“当前日记列表”和“草稿状态”引入复杂状态管理反而是负担。这不是说那个方案不好而是说每个项目都有自己的复杂度边界工具要为场景服务。异步安全是我这次特别注意的点。日记保存、图片拷贝都是耗时操作绝不能直接放在主线程里同步执行。我在 DAO 层全部用了async/await同时给数据库操作加了超时保护避免底层无响应时 UI 一直转圈。有个细节值得提异步操作完成后更新 UI 前要检查mounted。Flutter 页面在异步返回前有可能已经被销毁此时再执行setState会直接报错。这个问题在真机调试时很隐蔽因为发生概率不高但一旦用户快速切页就会触发。我的处理方式是封装一个安全状态更新函数内部统一判断mounted所有页面更新入口都走这个函数基本杜绝了这个崩溃点。5. 测试、联调与常见问题排查5.1 真机联调流程模拟器跑 Flutter 的 OpenHarmony 工程是可以的但要想验证输入法、相册权限、真实存储读写这些能力强烈建议上真机。联调前做三件事打开开发者模式、开启 USB 调试、确认 hdc 能识别设备。这三步任何一个没就位IDE 里都会显示“未找到设备”或者“target not found”。调试时我推荐同时开两个终端一个跑flutter run实时看日志一个用hdc shell查看系统日志。Flutter 层级的打印会走 Flutter 日志通道而原生插件、权限弹窗等系统行为的日志走系统通道只看其中一个容易漏掉关键线索。我这次调试图片选择权限时就是因为只看 Flutter 日志没注意到系统日志里的权限拒绝原因白折腾了半天。热重载在 Flutter 层面很好用修改 Dart 代码后按r键几秒内就能看到效果。但请记住一个边界如果修改了 OpenHarmony 原生配置比如权限声明、原生插件版本热重载不一定生效此时需要全量重新编译安装。我建议改原生代码前先想清楚是否必要否则每次全量编译的时间成本累积起来很可观。5.2 常见问题速查表我把这次开发里遇到的典型问题按出现频率整理成了表格按这个顺序排查能少走很多弯路。问题描述可能原因解决方法应用启动后白屏原生工程未正确注册 Flutter 入口检查ohos工程里的 Ability 配置是否注册了 FlutterAbility数据库操作报“表不存在”初始化时未执行建表语句确认在数据库初始化回调里执行了CREATE TABLE图片加载显示空白路径未加 file 前缀或文件未拷贝统一走路径转换工具函数输入框被键盘遮挡页面未处理软键盘变化用SingleChildScrollView包住输入区列表滚动掉帧item 组件太重或未固定高度改用ListView.builder并设置itemExtent点击日记返回后列表丢失滚动位置未保留页面状态使用AutomaticKeepAliveClientMixin权限弹窗不出现运行时未动态申请权限必须在 UI 触发动作后再调用权限请求中文字符串出现乱码编码不一致或文件格式错误统一将源码文件保存为 UTF-8 编码5.3 几个容易被忽略的坑这些坑我在网上搜不到现成资料基本是靠自己踩出来的分享出来避免后人重复踩第一个坑是“数据库放在哪”。OpenHarmony 应用在不同机型上的目录结构并不是百分百一致如果你硬编码了某台机器上的绝对路径换一台设备就跑不通。正确做法是通过路径接口获取应用私有目录在私有目录下再拼接数据库文件名。这个思路用户数据隔离也更加安全。第二个坑是“时间显示格式”。OpenHarmony 上部分默认字体对中文日期展示了奇怪的效果最后发现是 locale 设置没有跟随系统。解决方案是在应用初始化时手动设置本地化上下文强制使用中文环境。如果不设手机系统切到英文模式时日记日期会变成英文有些用户会觉得不贴身。第三个坑是关于图片缓存目录的清理。日记里引用的图片如果被系统缓存清理删掉了详情页打开时就会显示加载失败。我的处理办法是在图片加载失败的回调里显示“图片已过期”的占位文案而不是默默白屏。至少用户知道发生了什么而不是觉得应用有鬼。第四个坑是列表分页时的一个边界当数据库只有 20 条数据时首页一次加载 20 条就不会触发上滑分页。但如果用户在编辑页删除了几条返回列表后要重新刷新总条数否则会出现“明明还有数据但列表底部提示没有了”的错觉。我在删除操作成功后强制触发列表刷新必要时让列表回到顶部避免混乱。6. 一些后续可以做的扩展功能跑完基础版本后我其实有留几个待办项算是给这个模块预留的扩展空间。如果你们团队的规划也想往这个方向走可以参考一下。第一个可以扩展的是全文搜索。当前数据层已经用了数据库搜索就不是什么难事添加一个搜索入口对标题和正文做模糊匹配即可。难点在于搜索结果的展示体验是跳转详情还是列表里高亮关键词这个交互需要细抠。第二个是日记模板。有一部分用户写日记并不喜欢自由发挥更习惯有固定模板比如“今天做了什么”“今日感恩”“天气预报”。做一套模板选择器把模板字段提前注入编辑器能明显提升用户持续记录的动力。第三个是数据导出。OpenHarmony 用户的本地数据如果没有导出机制一旦换机迁移成本就会很高。后续可以考虑把日记导出成 Markdown 或 PDF 文件让用户保留个人数据的主权。这个功能技术上不难但是涉及到文件生成、编码兼容、大文件处理需要单独一个版本去做。做完整套实现后我个人最大的体会是Flutter for OpenHarmony 的组合已经不再只是“可以在上面跑跑 Demo”而是确实能承载一个常规业务模块的完整落地。日记本功能从头到尾没有依赖任何服务端全部本地完成说明这套跨端方案在基础性能和数据持久化上已经有足够的工程可用性。最后再分享一个小技巧写这类多页面业务模块时我习惯在工程里单独维护一个页面路由表所有页面跳转都通过统一的导航方法完成。这样以后要增加跳转参数、加埋点、做统一拦截都只需要改一个文件不用满工程找跳转点。这个习惯帮我省了非常多麻烦也推荐给刚转到 Flutter 开发的朋友。