最近把一个想法落地成了可跑的Demo用Flutter在OpenHarmony上做手语学习App。起因很朴素身边有听障朋友交流时才发现手语不是随便比划两下就能学会的系统性的学习路径特别稀缺。我本来只想验证Flutter能不能在OpenHarmony上正常跑起来结果做着做着就把首页完整实现了过程中还踩了不少坑。这篇文章会把我从技术选型、环境搭建、首页信息架构到组件实现、性能调优的完整过程写下来重点放在首页实现。如果你正在做Flutter跨端应用、打算尝试OpenHarmony或者在做无障碍方向的产品这里面的很多结论可以直接复用。1. 项目定位与技术选型为什么是Flutter配合OpenHarmony1.1 手语学习真正在学什么手语不是“图片加文字说明”就能学会的。它跟大多数技能学习不一样有三个非常硬核的特点第一动作在时间轴上展开同一个手形运动方向不同语义完全不同第二空间方位决定语义手放在额头附近和放在胸前表达的内容是两回事第三学习过程高度碎片化用户可能在地铁上、排队时掏出手机看一分钟很难有整块时间坐在电脑前看长视频。这意味着手语学习App的核心根本不是内容堆叠而是视觉反馈的连续性和学习提醒的及时性。首页如果只是把几十个课程卡片扔给用户用户根本不知道今天该学什么。所以整个项目的信息架构从首页开始就要围绕“今天学什么”来设计而不是围绕“我们有什么内容”来设计。1.2 Flutter的OpenHarmony适配分支能承担多少先给结论纯Dart侧的UI、动画、滚动列表、状态管理完全可用涉及原生插件的部分要重新评估。Flutter在OpenHarmony上的适配分支主要工作是把它自己那套渲染引擎、输入事件、共享内存等底层能力接到OpenHarmony系统上。常规Widget的渲染和手势响应实测下来没有太大问题列表滚动、自定义绘制、路由跳转这些高频场景都能正常用。但插件生态还很稀薄这是最需要提前知道的事情。普通Flutter项目里一个video_player或camera插件就能搞定的事在OpenHarmony适配分支上未必有现成实现。而且不同适配分支能力差异很大有的分支自定义了媒体接口有的分支还在用最原始的PlatformChannel。所以在规划首页时我刻意把播放器、图片加载、网络请求这些能力都设计成了可替换接口。底层适配怎么变页面层都不需要跟着返工。1.3 为什么偏偏先把首页做扎实很多项目习惯从课程列表页开始做我这一轮反着来先把首页做透。原因有三个。第一首页是全局数据结构的浓缩课程模型、学习进度、打卡记录这些核心领域对象都会在首页结构里露头把它们理清后面所有页面都顺了。第二首页同时要处理动画、滚动、路由、本地存储等于把所有常见技术难点都过了一遍如果首页性能能稳住其他页面基本不会有大问题。第三首页是验证用户留存假设的最短路径——用户愿不愿意每天打开App往往在首页前30秒就决定了。把首页做到能用后面的课程详情、词典检索、练习模式只是往框架里填页面。2. 从零搭起OpenHarmony的Flutter工程环境准备与跑通验证2.1 三套SDK与版本对齐OpenHarmony开发需要三样东西Flutter SDK、OpenHarmony SDK、Node.js环境。注意这里Flutter SDK必须是适配分支版本不能用官方版本OpenHarmony SDK要包含系统接口和打包工具Node.js是部分构建脚本的运行时依赖。这三套环境的版本必须互相匹配这是整个项目最容易被忽略的坑。版本错位的典型症状是编译时报接口符号缺失、渲染回调注册方式对不上、打包产物无法安装。我吃过一次亏适配分支更新到新版本后OpenHarmony SDK还停留在旧版结果编译时出现一堆奇怪报错排查了半天才发现是SDK版本不匹配。判断版本是否匹配的办法也很土看适配分支自带的sample工程就行。克隆分支后先编译它的demo如果sample能跑起来说明你当前这套环境组合是可行的如果sample都编译不过去先别搞新项目把环境对齐再说。这一步的唯一目的就是排除环境因素干扰让后面的问题都归因到代码层面。2.2 创建工程时两个容易错的地方第一个坑不要直接执行flutter create。适配分支通常提供带OpenHarmony模板的创建方式或者自带sample工程可以直接复制改造。直接创建默认工程大概率不会生成OpenHarmony需要的ohos目录后面构建时根本找不到目标平台。我在项目初期就犯过这个错误反复折腾才发现是模板不对。第二个坑构建目标要明确。OpenHarmony应用最终打包成hap格式但调试阶段有些模拟器只认apk两种产物的签名配置不一样。建议在项目初始化时就把签名、证书指纹配置写入构建脚本避免每次打包都手动选一遍。这一步看似琐碎但它决定了你后面是“一条命令跑起来”还是“每次构建都靠运气”。2.3 先跑通一个“手语问候”验证页环境问题解决后不要直接开写首页先做一个比Hello World复杂一点的验证页显示一张手势图片、一段手语名称文字、一个点击按钮。创建并运行的命令大体如下具体以适配分支文档为准# 以适配分支文档提供的命令为准这里只是示意 flutter doctor -v flutter create --templateohos_app sign_demo flutter run -d device-id能跑通这个验证页等于验证了四件事Flutter渲染正常、中文字体加载正常、资源能被打进hap包、点击事件和路由能工作。这四件事都是首页实现的前提条件。尤其是中文字体如果验证页里中文显示成方框说明字体配置有问题那首页做出来也是白搭趁早解决。2.4 模拟器与真机的先后顺序首页开发阶段尽量用模拟器。模拟器调试方便代码修改后热重载速度快能快速迭代UI布局。但性能问题和播放器硬解问题必须上真机复现模拟器上的帧率数据参考价值有限。我习惯在模拟器上把UI和交互调顺再在真机上做一轮帧率和内存检查。手语App首页不涉及复杂摄像头能力这个顺序完全够用。如果你的首页已经要接摄像头做手势识别那就要提前把真机调试环境准备好。3. 首页信息架构先回答三个问题再动手画界面3.1 第一个问题用户打开App的头30秒在看什么我把首页当成一个30秒决策页。用户在地铁上、排队时打开它不需要导航应该直接被推到“今天可以学什么”。这30秒里前10秒应该看到今日课程和进度中间10秒决定要不要点进去最后10秒完成或延迟。如果首页一上来就是课程列表面对四五十张卡片用户决策成本太高大概率会直接退出。手语学习者还有两类差异听障用户希望马上进入手语内容健听学习者需要更多文字提示。所以首页不能做成纯文字或纯图形最好两者都有动作演示图为主文字说明为辅。在设计课程宫格卡片时我强制要求每张卡片同时包含图片、短标题、难度标签三类元素缺一不可。3.2 状态层把“已学词汇量”换成“今日完成度”很多学习类App首页喜欢放“累计词汇量”我一开始也放了。后来观察使用情况发现累计数字对老用户是成就对新用户是压力对手语学习者尤其不友好——会让人觉得“要学这么多才能看懂对话”直接放弃。最终我把顶部统计栏改成三块今日目标完成度、连续学习天数、本周学习次数。这三个指标都指向用户的下一次行动给用户一个“现在继续学”的动机。这个调整背后是一个很实在的产品逻辑首页统计栏的作用不是展示成果而是点燃行动。学了多少个词是过去式今天完成度是现在进行时。对碎片化学习场景现在进行时的驱动力大得多。3.3 行动层今日一课如何闭环今日一课卡片是整个首页的行动入口。一个完整的、能留住人的闭环是看到卡片点击开始观看动作演示完成打卡首页卡片状态变化。这个闭环要求卡片状态必须可追溯不能只是静态展示。我实现时把今日课程id存在本地打卡后立即更新进度条和卡片样式让用户产生连续感。这里有一个容易被忽略的细节如果用户今天已经学完了今日一课卡片应该直接显示“已完成”而不是继续显示“开始学习”。否则用户每次打开首页都要面对同一个任务提示会觉得很烦。状态管理的最小规则就是每个操作都要有可见的反馈每个状态都要能被当前页面表达。3.4 探索层课程宫格与分类导航探索层解决“今天不想学指定课程想自己逛逛”的需求。手语内容按场景分类比按难度分类更好用手指字母、日常问候、数字时间、情绪表达、医疗求助、交通出行。这些类别用户能直接联想到生活场景比“初级课、中级课”更有学习驱动力用户看到“医疗求助”会想“这个有用我学一下”而看到“三阶课程”只会犹豫。每个分类下再按难度细分但首页只展示分类入口和每类课程的封面图。课程难度数字可以在卡片角落用小标签呈现不要放在主标题位置。我踩过的教训是难度标签喧宾夺主后用户会把时间花在比较难度上而不是点进去学习。3.5 数据接口的预埋设计正式项目里首页课程大概率来自服务端但Demo阶段用本地JSON完全够。关键点是字段名按服务端标准来别图省事。我给Course模型设计了id、title、cover、description、duration、difficulty、tags、lessons八个字段任何一个都能在后端接口返回时一一对应。Repository接口定义为FutureListCourse fetchCourses()本地实现读JSON线上实现走网络页面层完全不知道数据来源。这样后续接服务端时不需要改动任何UI代码。4. 首页实现拆解数据模型、状态管理与关键组件4.1 数据模型的简洁设计数据模型不要过度设计但类型必须清晰。我给项目写的Course模型很朴素一个fromJson工厂就够用暂时不需要引入freezed那样重的代码生成工具class Course { final String id; final String title; final String cover; final String description; final int duration; // 分钟 final int difficulty; // 1-5 final ListString tags; final int lessonCount; const Course({ required this.id, required this.title, required this.cover, required this.description, required this.duration, required this.difficulty, required this.tags, required this.lessonCount, }); factory Course.fromJson(MapString, dynamic json) { return Course( id: json[id] as String, title: json[title] as String, cover: json[cover] as String, description: json[description] as String, duration: json[duration] as int, difficulty: json[difficulty] as int, tags: (json[tags] as List).castString(), lessonCount: json[lessonCount] as int, ); } }这种设计的好处是任何一个字段在后面做课程详情页、搜索页时都能直接用不用重新定义。字段命名也遵守了下划线转驼峰的服务端约定后端同学看到JSON就知道对应关系省去大量沟通成本。4.2 状态管理先用Provider别急着上Riverpod手语学习App首页的全局状态其实很少当前用户进度、今日课程、连学天数。用Provider的ChangeNotifier就能撑住。选择Provider而不是Riverpod理由很务实模板代码少把状态通知绑定到组件上很直观其他协作者上手也快。后续如果要加入学习记录同步、多页面共享复杂状态再迁移Riverpod也不迟。首页状态类大致长这样class HomeState extends ChangeNotifier { ListCourse courses []; Course? todayCourse; int streakDays 0; bool checkedInToday false; Futurevoid load() async { courses await courseRepository.fetchCourses(); todayCourse _pickTodayCourse(courses); streakDays calcStreakDays(await localStore.getCheckinDates()); checkedInToday await localStore.isCheckedInToday(); notifyListeners(); } void checkIn() { localStore.addCheckin(DateTime.now()); checkedInToday true; notifyListeners(); } }这里的关键设计是HomeState只负责聚合首页需要的数据不负责业务规则。比如“今天是第几天”这样的计算放在独立函数里方便单独测试。把业务逻辑从Widget里剥离出去之后页面组件会变得非常薄调试时只要盯住State就行。4.3 连续学习天数一个函数搞定本地打卡打卡记录用本地KV存储就够了每次打卡把当天日期写进去读取最近N天的记录数组从今天往前连续存在的天数合计起来就是连学天数。这个函数写起来很短但有几个细节必须注意int calcStreakDays(ListString dateKeys) { final set dateKeys.toSet(); var streak 0; var day DateTime.now(); while (true) { final key ${day.year}-${day.month}-${day.day}; if (set.contains(key)) { streak; day day.subtract(const Duration(days: 1)); } else { break; } } return streak; }第一个细节日期键必须用本地时区生成不能用UTC否则晚上十一点打卡会变成第二天连续天数就会断掉。第二个细节集合只存日期字符串不存时间戳这样去重逻辑最简单。第三个细节如果用户把系统时间往前调了这个函数会自然终止不会出现负数天数。小功能也要把边界情况想清楚这是首页稳定性的基础。4.4 今日一课卡片的交互闭环HomePage顶部放DailyLessonCard加载时根据HomeState.todayCourse决定状态未开始、进行中、已完成。点击“开始学习”进入课程详情路由返回后打卡按钮亮起点击打卡就调用checkIn。整个过程只用一两个回调就能完成不需要引入复杂的导航库。卡片视觉上我用了很大的进度环进度环颜色用语义色区分绿色表示已完成橙色表示进行中灰色表示未开始。这样用户扫一眼就知道今天的状态不需要读文字。进度环的动画用TweenAnimationBuilder实现默认值到目标值之间自动补间避免手动管理AnimationController。这个组件的好处是状态变化时动画自动播放用户能直观感受到打卡带来的进度变化。4.5 课程宫格与页面跳转课程宫格直接用GridView.builder就能满足关键是卡片本身不能太重。核心布局代码不复杂GridView.builder( padding: const EdgeInsets.all(16), gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount( crossAxisCount: 2, childAspectRatio: 1.5, crossAxisSpacing: 12, mainAxisSpacing: 12, ), itemCount: courses.length, itemBuilder: (context, index) CourseCard(course: courses[index]), )跳转时用Navigator.push传入Course对象而不是id字符串。原因很简单详情页需要立刻渲染标题和封面如果只传id详情页要先做一次网络请求才能拿到基础信息首帧会有明显的空白期。直接传对象详情页可以先渲染已知信息再异步加载更详细的课程内容。4.6 动作演示区的取舍关键帧动画兜底视频手语动作演示最理想的形式是视频但OpenHarmony适配分支的视频播放插件还不牢靠。我在首页动作演示区做了一个过渡方案用一组关键帧图片按时间切换来模拟动作过程。图片来自手语动画序列帧帧率控制在12fps占空间小还不会碰到视频硬解兼容问题。演示区组件对外只暴露play()和stop()两个方法内部用Timer驱动图片切换。将来视频能力成熟了只需要替换内部实现上层接口完全不用动。这个“接口不动、实现可换”的思路是整个首页能顺利跑通的关键。在平台生态不成熟的阶段隔离不稳定依赖比追求最新功能重要得多。把播放器抽象成ActionDemoPlayer接口视频和帧图只是它的两种实现业务的稳定性就不依赖某个具体插件的成熟度。5. 真正花时间的部分适配踩坑、性能与无障碍5.1 视频播放插件的“绕路”策略视频播放是这个项目最大的不可控因素。不同设备上解码能力差异大软件解码性能差硬解在部分模拟器上直接黑屏。与其死磕插件不如先做资源层抽象演示数据里同时放videoUrl和frameUrls两个字段页面只消费统一的接口。这样就算视频插件在某台机器上不能用首页还能通过帧图轮播保持功能完整。等适配成熟了把实现换成真正的播放器即可页面层无感知。这也是我最想分享的一点开发跨端应用时不要因为某个平台能力还不成熟就推迟核心功能。先用可靠的低配方案把流程跑通把依赖隔离好后续升级只是替换实现的问题。好的代码结构并不是为了好看而是为了给平台生态的演进留出缓冲空间。5.2 资源打包与图片加载的路径陷阱项目做到一半我遇到过课程封面图片路径全部正确但有几张图加载失败的情况。排查了半天才发现问题出在资源名大小写和JSON里的字段不一致。开发机是Windows环境文件系统大小写不敏感所以本地怎么跑都没问题但打hap包之后资源管理是大小写敏感的一旦路径对不上就直接加载失败。这个坑很隐蔽因为问题只在打包后的环境里出现开发阶段完全看不出来。解决办法也很机械项目从一开始就约定资源文件名统一小写下划线JSON里的路径必须和文件名逐字一致然后写一个脚本在CI里对比资源目录和JSON引用。人工核对早晚出错脚本才是可靠的。5.3 首页滚动掉帧的排查与修复首页如果每个课程卡片都放动画缩略图并自动播放GridView滑动时帧率会明显下降压力测试时容易掉到30帧以下。排查思路要先分清是CPU还是GPU问题。我这边看模拟器性能面板是CPU过载大量Timer在后台空转导致的。修复方案有三个第一动画只在卡片可见时开启离开视口立即暂停第二每个卡片包一层RepaintBoundary避免一个卡片重绘带动整页重绘第三图片统一走缓存并按尺寸裁剪减少解码大图的开销。另外注意GridView默认的cacheExtent会让屏幕外的卡片提前创建动画资源不要在build方法里直接启动而要放到可见回调里再触发。做完这三步滚动帧率能稳定在60帧左右。5.4 无障碍语义听障用户真正需要的细节做手语学习App最容易忽略的就是无障碍但手语App的很多使用者本身就是听障人士。首页组件不能只追求好看还要保证每一个人都能完整读取信息。我给所有卡片加了Semantics标签标注课程名称、难度、课程数量按钮的点击区域不小于44乘44逻辑像素封面图与背景的对比度做到4.5比1以上。听不到声音的用户依靠视觉和语义就能读完首页的全部信息。这个细节做起来不难但大部分普通应用都没做。做完之后使用时长变化是很明显的因为信息获取的障碍变小了用户滑动首页的动作就顺畅了。无障碍不是公益功能它是产品可用性的一部分。5.5 首页之后这个App还能往哪里长首页跑通之后后续有三个明确方向课程详情页拆成“动作演示加分步教学加练习反馈”三个区域练习模式用摄像头对手势做实时比划匹配学习记录上云实现多设备同步。还有离线资源包让没有网络的用户也能打开首页学课程。这些方向都在首页的数据模型和接口抽象上预留了位置后面只是加页面、不改地基的问题。特别是练习模式如果能做到摄像头比划和标准动作的相似度打分手语学习App就从一个内容浏览工具变成了真正的练习工具这是听障用户和健听学习者共同需要的核心场景。最后说点代码之外的话。我在这轮开发里最深的体会是技术选型再新最后还是要落到用户的真实使用场景上。手语学习App的视频播放、卡片布局、状态管理都可以继续优化但真正让它有用的是用户打开首页后知道今天该学什么、学完了有收获。把首页做扎实就是在为使用这类产品的人降低每一道门槛。这个项目我会继续迭代等课程详情和练习模式跑通之后再来分享后面的实现细节。