把 Flutter 跑在 OpenHarmony 上做应用很多人一听就觉得“又要从零学一套新的 UI 框架了”。我接某高校宿舍管理系统的跨端需求时也是这个反应移动端要跑 Android楼栋自助终端要跑 OpenHarmony最怕的就是同一套界面写两遍。结果做下来发现Flutter 在 OpenHarmony 上的工作方式比想象中顺畅真正需要额外处理的是适配层的版本对齐和几个平台差异点。这篇我准备用项目里最典型的“欢迎区域”作为例子把从跨端选型到组件树规划从核心源码到实测适配的完整过程拆开讲代码可以直接抄走当模板。适合正在折腾 Flutter OpenHarmony 的你也适合想看看一套 UI 代码如何在不同系统上保持一致体验的团队参考。1. 为什么是 Flutter OpenHarmony而不是重学一套 ArkUI先说清楚当时面对的选择。宿舍管理系统的使用对象有两类一类是新生和楼管手里大概率是普通 Android 手机另一类是放在楼道里的自助终端屏幕大、系统定制跑的是 OpenHarmony。如果按传统思路走手机端一套技术栈自助终端另一套技术栈UI 还原度、交互细节、验收标准全是双份工作。我当时也认真评估过 ArkTS/ArkUI。它作为 OpenHarmony 的原生方案离系统能力最近如果项目只面向 OpenHarmony 一个平台我会毫不犹豫选它。但我们的现状是存量代码里已经有 Flutter 业务组件团队对 Flutter 的掌握也更熟需要的是一条“从 Android 平滑覆盖到 OpenHarmony”的路线而不是再养一个平行技术栈。三个维度的对比大概是这样对比维度FlutterArkTS/ArkUI团队上手成本已有 Dart 基础即可延续需要重新学习声明式 UI 与状态管理双端覆盖能力一套代码可跑 Android / OpenHarmony原生能力只在 OpenHarmony 上有效UI 表现一致性自绘渲染跨端差异小平台原生控件系统版本差异需适配OpenHarmony 适配程度已有社区适配工程能跑但需对齐版本原生最优系统能力调用依赖插件适配部分能力有缺口直接调用链路短为什么“欢迎区域”这种界面特别适合用 Flutter 来做因为它本质上是自绘型 UI。一个问候语、一张学期信息卡片、一列今日待办、一组快捷入口这些内容不依赖系统原生控件Flutter 渲染引擎在 OpenHarmony 上把 Skia 图形栈跑起来之后呈现效果和 Android 端可以做到高度一致。越是这种“整页都是自定义布局”的界面Flutter 越占优势。但选 Flutter 不是没有代价。OpenHarmony 上的 Flutter 适配工程目前是跟着特定版本走的这意味着你不能无脑用最新版 Flutter SDK而是要先查适配工程对应的 Flutter tag再基于那个版本创建工程。否则编译产物进 OpenHarmony 设备后要么跑不起来要么运行一段时间后随机闪退。我们最终是锁定了一个经过验证的版本组合把 Flutter SDK 固定下来升级前先在测试机上完整回归一遍才敢动版本。这一点是后面所有开发工作的前提也建议你做类似选型时第一个确认。2. 欢迎区域拆解把视觉稿“翻译”成一颗组件树“欢迎区域”听起来只是一张静态欢迎页实际上它承担了好几个信息层级先让用户看到自己的名字、确认身份再获取他今天需要知道的信息比如楼栋宿舍、辅导员、今日待办最后给他可操作的动作入口比如报修、签到、查询。信息层级决定了 UI 层级所以我建议先把视觉稿拆成块再动手写代码。我们在设计稿里把欢迎区域分成了五块。最上面是渐变背景的问候头部里面是姓名、日期和一句状态文案下面是学期信息卡片展示楼栋、宿舍号、辅导员和报到状态再往下是今日待办列表底部是四个快捷入口还有个装饰性的品牌落款放在最下方。请注意这里有一个重要决定欢迎区域本身不滚动。宿舍管理系统的首页下方还有业务列表如果把所有东西都放进一个滚动容器两个滚动方向会打架用户操作体验会很怪。把视觉块转成组件树的过程就是不断问“这个模块内部是横排还是竖排、需要不需要层叠”的过程。我们最后得到的结构大致是WelcomeScreen └── SafeArea └── Column ├── GreetingHeader │ └── Stack │ ├── Container (渐变背景 半透明装饰圆) │ └── Column (问候语) ├── SemesterCard │ └── Container (圆角 阴影) │ └── Row │ ├── Icon │ └── Column (楼栋/宿舍号/辅导员) ├── TodayNotice │ └── Expanded │ └── ListView / 空状态 └── QuickActions └── GridView.count这里每个选择都有讲究。外层用 Column 而不用 ListView是因为欢迎区域高度我们希望控制在单屏内Column 足够且更可控问候头部用 Stack是为了能在渐变背景上叠一层半透明圆作为装饰而不影响文字排版学期信息卡片内部用 Row 是因为“图标 多行文本”是最经典的组合比堆两个 Widget 再手动对齐要稳今日待办必须用 Expanded 包住否则在不同屏幕尺寸下很容易出现底部溢出的问题。尺寸策略也值得单独说。设计稿通常基于手机竖屏比例但楼栋自助终端的逻辑分辨率并不一定是标准手机比例可能接近 4:3 甚至更宽。如果在这些组件里写死像素值小屏手机和大屏平板上总有一个要出问题。所以我们统一约定欢迎区域只使用相对布局和约束比例关键容器用 EdgeInsets 统一控制内边距列表区域用 Expanded 吸收剩余空间不写死高度只有卡片圆角、图标大小这类视觉常量用固定值。这套约定在后续适配 OpenHarmony 大屏时帮了大忙。3. 核心源码解析欢迎区域的每个 Widget 到底在干什么这一节我们直接进源码。我会按“骨架 → 问候头部 → 信息卡片 → 待办列表 → 快捷入口”的顺序拆把每个 Widget 存在的理由和坑都交代清楚。3.1 页面骨架为什么最外层是 SafeArea Column先看页面的总体结构class WelcomeScreen extends StatefulWidget { const WelcomeScreen({super.key, this.userName 新同学}); final String userName; override StateWelcomeScreen createState() _WelcomeScreenState(); } class _WelcomeScreenState extends StateWelcomeScreen { override Widget build(BuildContext context) { return Scaffold( body: SafeArea( child: Column( children: const [ GreetingHeader(), SemesterCard(), TodayNotice(), QuickActions(), ], ), ), ); } }最外层放 SafeArea 是必须的。OpenHarmony 设备以及部分 Android 定制终端的屏幕顶部有系统状态栏或圆角区域不做 SafeArea问候文字会被裁切或者顶进系统栏里。Column 作为主轴容器让四个模块天然保持自上而下的顺序。这里没有用 ListView默认欢迎区域不滚动就避免了嵌套滚动问题。有人会问为什么 WelcomeScreen 是 StatefulWidget 但 build 里什么都没 setState。这是因为页面组件的 state 未来要接管数据加载和刷新当前阶段只是把静态骨架搭好后面接真实数据时不用切换组件类型。这算是一个“为下一步留接口”的写法不算过度设计。3.2 问候头部Stack 叠加渐变与问候语问候头部是整个页面视觉的重心也是花心思最多的部分。直接看代码class GreetingHeader extends StatelessWidget { const GreetingHeader({super.key, required this.userName}); final String userName; String _greetingByHour(int hour) { if (hour 12) return 早上好; if (hour 18) return 下午好; return 晚上好; } override Widget build(BuildContext context) { final hour DateTime.now().hour; final greeting _greetingByHour(hour); return Container( width: double.infinity, padding: const EdgeInsets.fromLTRB(24, 32, 24, 32), decoration: BoxDecoration( gradient: const LinearGradient( colors: [Color(0xFF2B6CB0), Color(0xFF38B2AC)], begin: Alignment.topLeft, end: Alignment.bottomRight, ), borderRadius: const BorderRadius.only( bottomRight: Radius.circular(40), ), ), child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Text($greeting$userName, style: const TextStyle( fontSize: 28, fontWeight: FontWeight.w600, color: Colors.white, )), const SizedBox(height: 8), Text(欢迎回到宿舍今天也要元气满满, style: const TextStyle( fontSize: 14, color: Color(0xCCFFFFFF), )), ], ), ); } }这里有几个细节值得讲。颜色直接用 Color(0xFF2B6CB0) 而不是 Colors.blue是因为品牌色要全局统一后面主题章节会再讲。问候语按小时分三种虽然逻辑很简单但确实能提升“这个页面有在认真对待我”的感觉。bottomRight 单边圆角 40 是有意为之让头部和下面的信息卡片之间形成一个自然过渡弧线比直上直下柔和很多。Stack 的运用我稍微提一下实际项目里我们还在这个 Container 里叠了一层带半透明圆形的装饰做法是在 Stack 中先画一个大圆再在上层放文字。如果你也想做类似装饰建议圆的颜色用 Colors.white 的 5%~10% 透明度的版本视觉效果最干净不会抢正文信息。3.3 学期信息卡片Container 圆角阴影与 Row 信息布局接下来是学期信息卡片。它负责把楼栋、宿舍号、辅导员这些高频信息放在用户第一眼能看到的位置class SemesterCard extends StatelessWidget { const SemesterCard({super.key, required this.dormInfo}); final DormInfo dormInfo; override Widget build(BuildContext context) { return Container( margin: const EdgeInsets.fromLTRB(16, 16, 16, 0), padding: const EdgeInsets.all(16), decoration: BoxDecoration( color: Colors.white, borderRadius: BorderRadius.circular(16), boxShadow: const [ BoxShadow( color: Color(0x1A000000), blurRadius: 12, offset: Offset(0, 4), ), ], ), child: Row( children: [ const Icon(Icons.apartment, color: Color(0xFF2B6CB0)), const SizedBox(width: 12), Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Text(${dormInfo.building} ${dormInfo.room}), const SizedBox(height: 4), Text(辅导员${dormInfo.counselor}, style: const TextStyle( fontSize: 13, color: Color(0xFF666666), )), ], ), ], ), ); } }这里我想多说一句“为什么用 BoxShadow 而不是 elevation”。有些人图省事直接给 Card 组件加 elevation确实能出阴影但阴影的模糊半径、偏移量、颜色完全不受控不同系统上的渲染还略有差异。我们用 Container BoxShadow是因为大屏终端的像素密度和手机不一样自定义阴影参数可以保证在两种设备上呈现一致的距离感。DormInfo 只是一个极简数据类承载 building、room、counselor 三个字段。注意这里没有把网络请求塞进组件UI 组件只负责消费外部传入的数据这个边界在后面接真实接口时非常重要。3.4 今日待办Expanded 接管剩余空间与空状态设计今日待办区域展示了“今天有什么需要处理的事”本质上是一个可变高度列表。最稳的写法是让它在页面里获得剩余高度Expanded( child: notices.isEmpty ? const _EmptyNotice() : ListView.separated( padding: const EdgeInsets.symmetric(horizontal: 16), itemCount: notices.length, separatorBuilder: (_, __) const SizedBox(height: 8), itemBuilder: (context, index) { final notice notices[index]; return _NoticeRow(notice: notice); }, ), )这里两个关键点。第一Expanded 替代固定高度。如果给待办区域一个固定高度小屏手机会溢出大屏平板上又浪费空间Expanded 让列表自动吃掉卡片下面的剩余高度两种屏幕都不会出问题。第二空状态不是可选项。宿舍管理系统的场景里新生报到完成前可能没有任何待办如果直接显示空白区域用户会觉得页面坏了所以必须有一个 _EmptyNotice 组件用一张温和的插图和一句“今天没有待办事项”来抵消空白感。_NoticeRow 内部我用了行内圆点作为时间标记左侧一个小圆点代表优先级右侧是通知标题和发布时间。这些细节看起来琐碎但正是欢迎区域“信息层级”的体现高优先级任务通过颜色差异一眼就能识别。3.5 快捷入口GridView 与 ActionCard 的拆解底部四个快捷入口是“报修”“签到”“查寝表”“缴费”在 UI 上用等宽网格排列GridView.count( crossAxisCount: 4, shrinkWrap: true, physics: const NeverScrollableScrollPhysics(), padding: const EdgeInsets.symmetric(horizontal: 8), mainAxisSpacing: 8, crossAxisSpacing: 8, children: actions .map((action) ActionCard(action: action)) .toList(), )crossAxisCount 用 4是因为四入口的场景在手机宽度和楼栋终端宽度下都能保持合理的图标尺寸。shrinkWrap: true 是为了让 GridView 在 Column 里按内容高度收缩否则它默认会试图占满无限高度直接导致布局报错配合 NeverScrollableScrollPhysics彻底关闭网格自身的滚动能力避免和上层滚动容器冲突。每个入口单独抽成 ActionCard 组件内部就是一个 Icon Text 的纵向组合外加一个轻量水波纹反馈。抽组件的意义在于后续如果要给某个入口加“小红点角标”或“禁用态”只需要在 ActionCard 内部做条件渲染不会影响页面其他代码。4. 让欢迎区域“活”起来数据、状态与刷新时机静态界面跑通只是第一步。欢迎区域真正的挑战是把用户名、宿舍信息、今日待办这些数据正确地填进来并且在合适的时间刷新。这里我采用了“ViewModel Repository”的分层思路而不是直接在组件里写网络请求。4.1 数据边界UI 组件不碰网络在这个项目里欢迎区域涉及三类数据用户资料、学期配置、今日待办。它们分别来自本地缓存和远端接口。为了让 UI 层保持干净我定义了一个欢迎数据聚合接口由 Repository 层把三个数据源合并成一个 WelcomeData 返回。UI 组件只需要知道 WelcomeData 里有 userName、dormInfo、notices、actions 这几个字段完全不关心它背后是缓存还是 HTTP。这样设计最大的好处是后续接口调整时UI 代码可以做到零改动。比如原来辅导员信息是从用户资料接口返回的后来改成学期配置接口返回只需要改 Repository 的聚合逻辑页面组件不用动。4.2 状态管理为什么用一个简单的 ChangeNotifier欢迎区域的状态其实不复杂加载中、加载失败、加载成功。用 setState 也能写但一旦涉及“回到前台刷新”“下拉重试”“跨页面更新待办数量”这些场景setState 会让组件越来越臃肿。我最后选择的是一个轻量 ViewModelclass WelcomeViewModel extends ChangeNotifier { WelcomeViewModel(this._repository); final WelcomeRepository _repository; WelcomeData? _data; bool _loading true; String? _error; Futurevoid load() async { _loading true; _error null; notifyListeners(); try { _data await _repository.fetchWelcomeData(); } catch (e) { _error 加载失败; } finally { _loading false; notifyListeners(); } } }选择 ChangeNotifier 而不是直接上重状态管理框架是因为欢迎区域是页面级局部状态不值得引入全局 Store。真正进入业务列表、跨页面共享登录态之后再考虑全局状态管理方案也不迟。用 notifier 的好处是加载逻辑和 UI 渲染完全解耦后面加缓存、加重试机制都很自然。4.3 三态 UI骨架屏而不是转圈基于 ViewModel 的状态页面渲染逻辑分成三态if (viewModel.loading) { return const WelcomeSkeleton(); } if (viewModel.error ! null) { return ErrorRetry(onRetry: viewModel.load); } return WelcomeContent(data: viewModel.data!);这里有个容易踩坑的点加载中状态不要用全屏转圈。欢迎区域是页面首屏如果每次进入都先转圈再出内容视觉跳动感特别强。我们用了一块和最终布局等价的灰色骨架屏用户会觉得页面在正常加载体验平滑很多。骨架屏的做法很简单就是几块淡灰色圆角矩形占位不需要额外引入组件库。错误状态也考虑了很多。自助终端如果网络断了不应该白屏或者无限转圈而是在页面中央显示“加载失败”和重试按钮。因为我们面向的是宿舍管理场景有时楼栋终端网络不稳定重试按钮远比自动轮询靠谱。4.4 刷新时机回到前台和跨天切换欢迎区域有两个刷新时机容易被忽略App 从后台回到前台时待办状态可能已经变化需要重新拉取日期跨天后问候语应从“晚上好”变成“早上好”。第二个场景如果只靠 build 里的 DateTime.now() 判断不会自动刷新必须借助生命周期监听。我用了 WidgetsBindingObserver 监听 AppLifecycleState.resumed在每次回到前台时对比一下上次访问的日期如果日期变了或者远程数据标记变了就重新调一次 load()。这套逻辑不复杂但能把“页面看着像是活的”这个体验做好。顺带说一句欢迎区域的问候语尽量不要用每分钟定时器去刷新太消耗资源按“前台恢复 日期变化”两个触发点刷新就够了。5. OpenHarmony 平台上碰到的几个真实适配问题跑通跨端之后真正的难点开始在适配层浮出水面。这一节是实测过程中踩到的坑每个都值得记录。5.1 编译与运行版本对齐是第一道关OpenHarmony 上的 Flutter 不能直接用最新版 Flutter SDK 编译。我们一开始图省事本地 Flutter 版本比适配工程要求的版本新了一个小版本结果产物安装到设备后界面能出但点击事件偶尔失效。排查了一圈才发现是适配层和 Flutter 引擎版本不匹配。解决方式很朴实把 Flutter SDK 固定到适配工程文档指定的版本重新创建项目再移植页面代码。另外OpenHarmony 设备的运行链路也比普通手机多几步包括设备进入开发者模式、配置调试证书、通过工具安装产物。建议第一次跑通时最好准备一台固定的测试设备把所有环节完整走一遍之后每次迭代就顺畅了。5.2 尺寸与 dpiMediaQuery 不是万能的楼栋自助终端的屏幕比例和手机差很多有的是 4:3有的接近 16:10而且系统 dpi 设置各不相同。直接用 MediaQuery.of(context).size 去算布局宽度在某些设备上会出现卡片被拉伸或者间距失真。我的建议是涉及整页布局时用 LayoutBuilder 拿父容器约束而不是全局屏幕尺寸。比如快捷入口的网格间距用 maxWidth 的 2% 计算比固定 12 更稳。另外欢迎区域的渐变背景在大屏上容易出现“竖屏渐变”的生硬感建议把渐变方向固定为对角线视觉上能掩盖不少比例差异。5.3 中文字体打包字体远比依赖系统字体可靠部分 OpenHarmony 定制设备的中文字体不完整Text 会出现缺字、方框或者回退异常。尤其像“你”“好”这类常用字一般没问题但一些生僻字或特定符号就可能挂掉。我们最后统一走的是“打包字体”路线把一款开源中文字体文件放进 assets/fonts在 MaterialApp 的 theme 里配置 fontFamily确保所有设备用同一套字体渲染。这里有一个性能提示全系统全局替换字体后首帧渲染会稍微变慢但欢迎区域本身就是首屏这个 trade-off 是值得的。如果你只在欢迎区域需要特殊字体也可以只在该区域单独指定 TextStyle(fontFamily: ...)减小影响面。5.4 系统能力调用先确认插件在 OpenHarmony 端可用欢迎区域的快捷入口里我们原本想做“一键报修”带定位功能但在适配层检查后发现对应的定位插件在 OpenHarmony 端还没有完整实现。强行调用会导致崩溃或静默失败。我的建议是凡是涉及相机、定位、蓝牙这类系统能力的插件在排期阶段就要逐个验证 OpenHarmony 端的可用性。如果插件不支持就把入口设计成纯前端跳转 辅助表单模式先保证功能链路完整等适配插件到位后再替换成原生能力调用。宁可第一步朴素一点也不要在一个跑不通的坎上卡住整个页面。5.5 性能与动画大屏设备上的重绘控制欢迎区域虽然控件不多但渐变背景、卡片阴影、列表滚动这些元素叠加起来在低配置大屏设备上容易出现帧率波动。我做了三件事第一所有静态组件尽可能标注 const 构造减少 build 阶段的对象创建第二用 RepaintBoundary 把渐变头部包一层避免列表滚动时整个头部跟着重绘第三减少 setState 的粒度数据刷新只更新对应的内容区域而不是整页重建。水波纹反馈在部分 OpenHarmony 设备上也有些不一致Material 默认的 InkWell 在某些定制设备上几乎看不到反馈。后来我在 ActionCard 里加了一层轻量的透明度动画点击时图标短暂变淡再恢复体验就统一了。这种小细节往往是实际跑设备才能发现的问题。最后聊聊我的整体感受。这套欢迎区域真正花时间的不是写 Text、Container、GridView 这些控件而是前期把组件边界、数据边界、平台差异想清楚。我在项目里犯过的最大错误是把待办列表数据和欢迎卡片状态耦合在一个 State 里结果每次通知刷新都带着整页重绘拆开之后大屏设备上的帧率明显稳了。如果你也在做类似系统建议从第一天就把 ViewModel 和 Repository 的壳搭好即使现在往里面填的都是静态数据。后面再接真实接口、加新入口时你就会发现这些前期约束帮你省下的时间远超想象。
把 Flutter 跑在 OpenHarmony 上做应用很多人一听就觉得“又要从零学一套新的 UI 框架了”。我接某高校宿舍管理系统的跨端需求时也是这个反应移动端要跑 Android楼栋自助终端要跑 OpenHarmony最怕的就是同一套界面写两遍。结果做下来发现Flutter 在 OpenHarmony 上的工作方式比想象中顺畅真正需要额外处理的是适配层的版本对齐和几个平台差异点。这篇我准备用项目里最典型的“欢迎区域”作为例子把从跨端选型到组件树规划从核心源码到实测适配的完整过程拆开讲代码可以直接抄走当模板。适合正在折腾 Flutter OpenHarmony 的你也适合想看看一套 UI 代码如何在不同系统上保持一致体验的团队参考。1. 为什么是 Flutter OpenHarmony而不是重学一套 ArkUI先说清楚当时面对的选择。宿舍管理系统的使用对象有两类一类是新生和楼管手里大概率是普通 Android 手机另一类是放在楼道里的自助终端屏幕大、系统定制跑的是 OpenHarmony。如果按传统思路走手机端一套技术栈自助终端另一套技术栈UI 还原度、交互细节、验收标准全是双份工作。我当时也认真评估过 ArkTS/ArkUI。它作为 OpenHarmony 的原生方案离系统能力最近如果项目只面向 OpenHarmony 一个平台我会毫不犹豫选它。但我们的现状是存量代码里已经有 Flutter 业务组件团队对 Flutter 的掌握也更熟需要的是一条“从 Android 平滑覆盖到 OpenHarmony”的路线而不是再养一个平行技术栈。三个维度的对比大概是这样对比维度FlutterArkTS/ArkUI团队上手成本已有 Dart 基础即可延续需要重新学习声明式 UI 与状态管理双端覆盖能力一套代码可跑 Android / OpenHarmony原生能力只在 OpenHarmony 上有效UI 表现一致性自绘渲染跨端差异小平台原生控件系统版本差异需适配OpenHarmony 适配程度已有社区适配工程能跑但需对齐版本原生最优系统能力调用依赖插件适配部分能力有缺口直接调用链路短为什么“欢迎区域”这种界面特别适合用 Flutter 来做因为它本质上是自绘型 UI。一个问候语、一张学期信息卡片、一列今日待办、一组快捷入口这些内容不依赖系统原生控件Flutter 渲染引擎在 OpenHarmony 上把 Skia 图形栈跑起来之后呈现效果和 Android 端可以做到高度一致。越是这种“整页都是自定义布局”的界面Flutter 越占优势。但选 Flutter 不是没有代价。OpenHarmony 上的 Flutter 适配工程目前是跟着特定版本走的这意味着你不能无脑用最新版 Flutter SDK而是要先查适配工程对应的 Flutter tag再基于那个版本创建工程。否则编译产物进 OpenHarmony 设备后要么跑不起来要么运行一段时间后随机闪退。我们最终是锁定了一个经过验证的版本组合把 Flutter SDK 固定下来升级前先在测试机上完整回归一遍才敢动版本。这一点是后面所有开发工作的前提也建议你做类似选型时第一个确认。2. 欢迎区域拆解把视觉稿“翻译”成一颗组件树“欢迎区域”听起来只是一张静态欢迎页实际上它承担了好几个信息层级先让用户看到自己的名字、确认身份再获取他今天需要知道的信息比如楼栋宿舍、辅导员、今日待办最后给他可操作的动作入口比如报修、签到、查询。信息层级决定了 UI 层级所以我建议先把视觉稿拆成块再动手写代码。我们在设计稿里把欢迎区域分成了五块。最上面是渐变背景的问候头部里面是姓名、日期和一句状态文案下面是学期信息卡片展示楼栋、宿舍号、辅导员和报到状态再往下是今日待办列表底部是四个快捷入口还有个装饰性的品牌落款放在最下方。请注意这里有一个重要决定欢迎区域本身不滚动。宿舍管理系统的首页下方还有业务列表如果把所有东西都放进一个滚动容器两个滚动方向会打架用户操作体验会很怪。把视觉块转成组件树的过程就是不断问“这个模块内部是横排还是竖排、需要不需要层叠”的过程。我们最后得到的结构大致是WelcomeScreen └── SafeArea └── Column ├── GreetingHeader │ └── Stack │ ├── Container (渐变背景 半透明装饰圆) │ └── Column (问候语) ├── SemesterCard │ └── Container (圆角 阴影) │ └── Row │ ├── Icon │ └── Column (楼栋/宿舍号/辅导员) ├── TodayNotice │ └── Expanded │ └── ListView / 空状态 └── QuickActions └── GridView.count这里每个选择都有讲究。外层用 Column 而不用 ListView是因为欢迎区域高度我们希望控制在单屏内Column 足够且更可控问候头部用 Stack是为了能在渐变背景上叠一层半透明圆作为装饰而不影响文字排版学期信息卡片内部用 Row 是因为“图标 多行文本”是最经典的组合比堆两个 Widget 再手动对齐要稳今日待办必须用 Expanded 包住否则在不同屏幕尺寸下很容易出现底部溢出的问题。尺寸策略也值得单独说。设计稿通常基于手机竖屏比例但楼栋自助终端的逻辑分辨率并不一定是标准手机比例可能接近 4:3 甚至更宽。如果在这些组件里写死像素值小屏手机和大屏平板上总有一个要出问题。所以我们统一约定欢迎区域只使用相对布局和约束比例关键容器用 EdgeInsets 统一控制内边距列表区域用 Expanded 吸收剩余空间不写死高度只有卡片圆角、图标大小这类视觉常量用固定值。这套约定在后续适配 OpenHarmony 大屏时帮了大忙。3. 核心源码解析欢迎区域的每个 Widget 到底在干什么这一节我们直接进源码。我会按“骨架 → 问候头部 → 信息卡片 → 待办列表 → 快捷入口”的顺序拆把每个 Widget 存在的理由和坑都交代清楚。3.1 页面骨架为什么最外层是 SafeArea Column先看页面的总体结构class WelcomeScreen extends StatefulWidget { const WelcomeScreen({super.key, this.userName 新同学}); final String userName; override StateWelcomeScreen createState() _WelcomeScreenState(); } class _WelcomeScreenState extends StateWelcomeScreen { override Widget build(BuildContext context) { return Scaffold( body: SafeArea( child: Column( children: const [ GreetingHeader(), SemesterCard(), TodayNotice(), QuickActions(), ], ), ), ); } }最外层放 SafeArea 是必须的。OpenHarmony 设备以及部分 Android 定制终端的屏幕顶部有系统状态栏或圆角区域不做 SafeArea问候文字会被裁切或者顶进系统栏里。Column 作为主轴容器让四个模块天然保持自上而下的顺序。这里没有用 ListView默认欢迎区域不滚动就避免了嵌套滚动问题。有人会问为什么 WelcomeScreen 是 StatefulWidget 但 build 里什么都没 setState。这是因为页面组件的 state 未来要接管数据加载和刷新当前阶段只是把静态骨架搭好后面接真实数据时不用切换组件类型。这算是一个“为下一步留接口”的写法不算过度设计。3.2 问候头部Stack 叠加渐变与问候语问候头部是整个页面视觉的重心也是花心思最多的部分。直接看代码class GreetingHeader extends StatelessWidget { const GreetingHeader({super.key, required this.userName}); final String userName; String _greetingByHour(int hour) { if (hour 12) return 早上好; if (hour 18) return 下午好; return 晚上好; } override Widget build(BuildContext context) { final hour DateTime.now().hour; final greeting _greetingByHour(hour); return Container( width: double.infinity, padding: const EdgeInsets.fromLTRB(24, 32, 24, 32), decoration: BoxDecoration( gradient: const LinearGradient( colors: [Color(0xFF2B6CB0), Color(0xFF38B2AC)], begin: Alignment.topLeft, end: Alignment.bottomRight, ), borderRadius: const BorderRadius.only( bottomRight: Radius.circular(40), ), ), child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Text($greeting$userName, style: const TextStyle( fontSize: 28, fontWeight: FontWeight.w600, color: Colors.white, )), const SizedBox(height: 8), Text(欢迎回到宿舍今天也要元气满满, style: const TextStyle( fontSize: 14, color: Color(0xCCFFFFFF), )), ], ), ); } }这里有几个细节值得讲。颜色直接用 Color(0xFF2B6CB0) 而不是 Colors.blue是因为品牌色要全局统一后面主题章节会再讲。问候语按小时分三种虽然逻辑很简单但确实能提升“这个页面有在认真对待我”的感觉。bottomRight 单边圆角 40 是有意为之让头部和下面的信息卡片之间形成一个自然过渡弧线比直上直下柔和很多。Stack 的运用我稍微提一下实际项目里我们还在这个 Container 里叠了一层带半透明圆形的装饰做法是在 Stack 中先画一个大圆再在上层放文字。如果你也想做类似装饰建议圆的颜色用 Colors.white 的 5%~10% 透明度的版本视觉效果最干净不会抢正文信息。3.3 学期信息卡片Container 圆角阴影与 Row 信息布局接下来是学期信息卡片。它负责把楼栋、宿舍号、辅导员这些高频信息放在用户第一眼能看到的位置class SemesterCard extends StatelessWidget { const SemesterCard({super.key, required this.dormInfo}); final DormInfo dormInfo; override Widget build(BuildContext context) { return Container( margin: const EdgeInsets.fromLTRB(16, 16, 16, 0), padding: const EdgeInsets.all(16), decoration: BoxDecoration( color: Colors.white, borderRadius: BorderRadius.circular(16), boxShadow: const [ BoxShadow( color: Color(0x1A000000), blurRadius: 12, offset: Offset(0, 4), ), ], ), child: Row( children: [ const Icon(Icons.apartment, color: Color(0xFF2B6CB0)), const SizedBox(width: 12), Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Text(${dormInfo.building} ${dormInfo.room}), const SizedBox(height: 4), Text(辅导员${dormInfo.counselor}, style: const TextStyle( fontSize: 13, color: Color(0xFF666666), )), ], ), ], ), ); } }这里我想多说一句“为什么用 BoxShadow 而不是 elevation”。有些人图省事直接给 Card 组件加 elevation确实能出阴影但阴影的模糊半径、偏移量、颜色完全不受控不同系统上的渲染还略有差异。我们用 Container BoxShadow是因为大屏终端的像素密度和手机不一样自定义阴影参数可以保证在两种设备上呈现一致的距离感。DormInfo 只是一个极简数据类承载 building、room、counselor 三个字段。注意这里没有把网络请求塞进组件UI 组件只负责消费外部传入的数据这个边界在后面接真实接口时非常重要。3.4 今日待办Expanded 接管剩余空间与空状态设计今日待办区域展示了“今天有什么需要处理的事”本质上是一个可变高度列表。最稳的写法是让它在页面里获得剩余高度Expanded( child: notices.isEmpty ? const _EmptyNotice() : ListView.separated( padding: const EdgeInsets.symmetric(horizontal: 16), itemCount: notices.length, separatorBuilder: (_, __) const SizedBox(height: 8), itemBuilder: (context, index) { final notice notices[index]; return _NoticeRow(notice: notice); }, ), )这里两个关键点。第一Expanded 替代固定高度。如果给待办区域一个固定高度小屏手机会溢出大屏平板上又浪费空间Expanded 让列表自动吃掉卡片下面的剩余高度两种屏幕都不会出问题。第二空状态不是可选项。宿舍管理系统的场景里新生报到完成前可能没有任何待办如果直接显示空白区域用户会觉得页面坏了所以必须有一个 _EmptyNotice 组件用一张温和的插图和一句“今天没有待办事项”来抵消空白感。_NoticeRow 内部我用了行内圆点作为时间标记左侧一个小圆点代表优先级右侧是通知标题和发布时间。这些细节看起来琐碎但正是欢迎区域“信息层级”的体现高优先级任务通过颜色差异一眼就能识别。3.5 快捷入口GridView 与 ActionCard 的拆解底部四个快捷入口是“报修”“签到”“查寝表”“缴费”在 UI 上用等宽网格排列GridView.count( crossAxisCount: 4, shrinkWrap: true, physics: const NeverScrollableScrollPhysics(), padding: const EdgeInsets.symmetric(horizontal: 8), mainAxisSpacing: 8, crossAxisSpacing: 8, children: actions .map((action) ActionCard(action: action)) .toList(), )crossAxisCount 用 4是因为四入口的场景在手机宽度和楼栋终端宽度下都能保持合理的图标尺寸。shrinkWrap: true 是为了让 GridView 在 Column 里按内容高度收缩否则它默认会试图占满无限高度直接导致布局报错配合 NeverScrollableScrollPhysics彻底关闭网格自身的滚动能力避免和上层滚动容器冲突。每个入口单独抽成 ActionCard 组件内部就是一个 Icon Text 的纵向组合外加一个轻量水波纹反馈。抽组件的意义在于后续如果要给某个入口加“小红点角标”或“禁用态”只需要在 ActionCard 内部做条件渲染不会影响页面其他代码。4. 让欢迎区域“活”起来数据、状态与刷新时机静态界面跑通只是第一步。欢迎区域真正的挑战是把用户名、宿舍信息、今日待办这些数据正确地填进来并且在合适的时间刷新。这里我采用了“ViewModel Repository”的分层思路而不是直接在组件里写网络请求。4.1 数据边界UI 组件不碰网络在这个项目里欢迎区域涉及三类数据用户资料、学期配置、今日待办。它们分别来自本地缓存和远端接口。为了让 UI 层保持干净我定义了一个欢迎数据聚合接口由 Repository 层把三个数据源合并成一个 WelcomeData 返回。UI 组件只需要知道 WelcomeData 里有 userName、dormInfo、notices、actions 这几个字段完全不关心它背后是缓存还是 HTTP。这样设计最大的好处是后续接口调整时UI 代码可以做到零改动。比如原来辅导员信息是从用户资料接口返回的后来改成学期配置接口返回只需要改 Repository 的聚合逻辑页面组件不用动。4.2 状态管理为什么用一个简单的 ChangeNotifier欢迎区域的状态其实不复杂加载中、加载失败、加载成功。用 setState 也能写但一旦涉及“回到前台刷新”“下拉重试”“跨页面更新待办数量”这些场景setState 会让组件越来越臃肿。我最后选择的是一个轻量 ViewModelclass WelcomeViewModel extends ChangeNotifier { WelcomeViewModel(this._repository); final WelcomeRepository _repository; WelcomeData? _data; bool _loading true; String? _error; Futurevoid load() async { _loading true; _error null; notifyListeners(); try { _data await _repository.fetchWelcomeData(); } catch (e) { _error 加载失败; } finally { _loading false; notifyListeners(); } } }选择 ChangeNotifier 而不是直接上重状态管理框架是因为欢迎区域是页面级局部状态不值得引入全局 Store。真正进入业务列表、跨页面共享登录态之后再考虑全局状态管理方案也不迟。用 notifier 的好处是加载逻辑和 UI 渲染完全解耦后面加缓存、加重试机制都很自然。4.3 三态 UI骨架屏而不是转圈基于 ViewModel 的状态页面渲染逻辑分成三态if (viewModel.loading) { return const WelcomeSkeleton(); } if (viewModel.error ! null) { return ErrorRetry(onRetry: viewModel.load); } return WelcomeContent(data: viewModel.data!);这里有个容易踩坑的点加载中状态不要用全屏转圈。欢迎区域是页面首屏如果每次进入都先转圈再出内容视觉跳动感特别强。我们用了一块和最终布局等价的灰色骨架屏用户会觉得页面在正常加载体验平滑很多。骨架屏的做法很简单就是几块淡灰色圆角矩形占位不需要额外引入组件库。错误状态也考虑了很多。自助终端如果网络断了不应该白屏或者无限转圈而是在页面中央显示“加载失败”和重试按钮。因为我们面向的是宿舍管理场景有时楼栋终端网络不稳定重试按钮远比自动轮询靠谱。4.4 刷新时机回到前台和跨天切换欢迎区域有两个刷新时机容易被忽略App 从后台回到前台时待办状态可能已经变化需要重新拉取日期跨天后问候语应从“晚上好”变成“早上好”。第二个场景如果只靠 build 里的 DateTime.now() 判断不会自动刷新必须借助生命周期监听。我用了 WidgetsBindingObserver 监听 AppLifecycleState.resumed在每次回到前台时对比一下上次访问的日期如果日期变了或者远程数据标记变了就重新调一次 load()。这套逻辑不复杂但能把“页面看着像是活的”这个体验做好。顺带说一句欢迎区域的问候语尽量不要用每分钟定时器去刷新太消耗资源按“前台恢复 日期变化”两个触发点刷新就够了。5. OpenHarmony 平台上碰到的几个真实适配问题跑通跨端之后真正的难点开始在适配层浮出水面。这一节是实测过程中踩到的坑每个都值得记录。5.1 编译与运行版本对齐是第一道关OpenHarmony 上的 Flutter 不能直接用最新版 Flutter SDK 编译。我们一开始图省事本地 Flutter 版本比适配工程要求的版本新了一个小版本结果产物安装到设备后界面能出但点击事件偶尔失效。排查了一圈才发现是适配层和 Flutter 引擎版本不匹配。解决方式很朴实把 Flutter SDK 固定到适配工程文档指定的版本重新创建项目再移植页面代码。另外OpenHarmony 设备的运行链路也比普通手机多几步包括设备进入开发者模式、配置调试证书、通过工具安装产物。建议第一次跑通时最好准备一台固定的测试设备把所有环节完整走一遍之后每次迭代就顺畅了。5.2 尺寸与 dpiMediaQuery 不是万能的楼栋自助终端的屏幕比例和手机差很多有的是 4:3有的接近 16:10而且系统 dpi 设置各不相同。直接用 MediaQuery.of(context).size 去算布局宽度在某些设备上会出现卡片被拉伸或者间距失真。我的建议是涉及整页布局时用 LayoutBuilder 拿父容器约束而不是全局屏幕尺寸。比如快捷入口的网格间距用 maxWidth 的 2% 计算比固定 12 更稳。另外欢迎区域的渐变背景在大屏上容易出现“竖屏渐变”的生硬感建议把渐变方向固定为对角线视觉上能掩盖不少比例差异。5.3 中文字体打包字体远比依赖系统字体可靠部分 OpenHarmony 定制设备的中文字体不完整Text 会出现缺字、方框或者回退异常。尤其像“你”“好”这类常用字一般没问题但一些生僻字或特定符号就可能挂掉。我们最后统一走的是“打包字体”路线把一款开源中文字体文件放进 assets/fonts在 MaterialApp 的 theme 里配置 fontFamily确保所有设备用同一套字体渲染。这里有一个性能提示全系统全局替换字体后首帧渲染会稍微变慢但欢迎区域本身就是首屏这个 trade-off 是值得的。如果你只在欢迎区域需要特殊字体也可以只在该区域单独指定 TextStyle(fontFamily: ...)减小影响面。5.4 系统能力调用先确认插件在 OpenHarmony 端可用欢迎区域的快捷入口里我们原本想做“一键报修”带定位功能但在适配层检查后发现对应的定位插件在 OpenHarmony 端还没有完整实现。强行调用会导致崩溃或静默失败。我的建议是凡是涉及相机、定位、蓝牙这类系统能力的插件在排期阶段就要逐个验证 OpenHarmony 端的可用性。如果插件不支持就把入口设计成纯前端跳转 辅助表单模式先保证功能链路完整等适配插件到位后再替换成原生能力调用。宁可第一步朴素一点也不要在一个跑不通的坎上卡住整个页面。5.5 性能与动画大屏设备上的重绘控制欢迎区域虽然控件不多但渐变背景、卡片阴影、列表滚动这些元素叠加起来在低配置大屏设备上容易出现帧率波动。我做了三件事第一所有静态组件尽可能标注 const 构造减少 build 阶段的对象创建第二用 RepaintBoundary 把渐变头部包一层避免列表滚动时整个头部跟着重绘第三减少 setState 的粒度数据刷新只更新对应的内容区域而不是整页重建。水波纹反馈在部分 OpenHarmony 设备上也有些不一致Material 默认的 InkWell 在某些定制设备上几乎看不到反馈。后来我在 ActionCard 里加了一层轻量的透明度动画点击时图标短暂变淡再恢复体验就统一了。这种小细节往往是实际跑设备才能发现的问题。最后聊聊我的整体感受。这套欢迎区域真正花时间的不是写 Text、Container、GridView 这些控件而是前期把组件边界、数据边界、平台差异想清楚。我在项目里犯过的最大错误是把待办列表数据和欢迎卡片状态耦合在一个 State 里结果每次通知刷新都带着整页重绘拆开之后大屏设备上的帧率明显稳了。如果你也在做类似系统建议从第一天就把 ViewModel 和 Repository 的壳搭好即使现在往里面填的都是静态数据。后面再接真实接口、加新入口时你就会发现这些前期约束帮你省下的时间远超想象。
