Flutter在OpenHarmony上的实战：用基础布局组件构建待办清单

1. 先聊清楚：Flutter在OpenHarmony上到底能跑成什么样

做跨端开发这几年，我一直有个执念：一套UI代码能不能在尽可能多的系统上跑出接近原生的效果。Android、iOS、Web、Windows、macOS、Linux都试过了，Flutter的跨端能力确实没得挑。但当OpenHarmony的设备越来越多出现在我面前时，我意识到一个新的问题：Flutter能跑在OpenHarmony上吗？怎么跑？

先说结论：能跑，而且跑得比大多数人想象中要稳。OpenHarmony社区维护了一个专门的Flutter分支，从代码仓库到编译工具链都做了适配。我在RK3568开发板和鸿蒙模拟器上都实际跑过Flutter应用，基础布局组件、手势交互、动画、平台通道这些核心能力都能正常工作。拿待办清单这种典型的CRUD应用来练手，UI层面几乎没有遇到跨端迁移的障碍。

但这里有个关键认知要纠正：Flutter for OpenHarmony不是把官方Flutter直接拿过来用，而是OpenHarmony SIG组在Flutter官方代码基础上维护的一套分支。版本迭代节奏、依赖管理方式、原生插件的接入方式都和官方版有差异。你在pub.dev上随便拉一个插件，并不能保证它在OpenHarmony上能编译通过，因为很多插件底层依赖的是Android或iOS的原生API，OpenHarmony并没有这些接口。

所以我的建议是：别把Flutter for OpenHarmony想象成"什么都能跑的万能钥匙"，它更像一套正在快速成熟的工具链。适合你用它来做业务界面、状态管理、布局渲染、基础交互，遇到需要调用系统能力的地方，再通过平台通道（Platform Channel）去适配OpenHarmony侧的接口。比如你要调用鸿蒙的图库、拉起鸿蒙的IAP支付，就得走双层适配：Flutter层写Dart逻辑，OpenHarmony侧用ArkTS或C++实现原生接口，两边通过MethodChannel通信。

从我个人的实践看，用Flutter做OpenHarmony应用的UI层和业务逻辑，开发效率比直接用ArkUI写要高不少。尤其是如果你已经有一份Flutter代码库，迁移到OpenHarmony的成本主要在于适配原生依赖和测试验证，界面代码基本可以原封不动地保留。这对于团队里同时维护Android、iOS、鸿蒙多端应用的人来说，价值非常大。

2. 开工前的硬功夫：SDK、设备树与开发环境搭建

纸上谈兵没用，先把手上的开发环境理顺。我用的是Flutter for OpenHarmony的开源分支，仓库地址在Gitee上的OpenHarmony SIG组织下，搜索flutter_flutter就能找到。注意别从pub.dev或者flutter官网拉SDK，那个是官方分支，不支持OpenHarmony的编译目标。

2.1 拉取SDK分支与版本选择

我使用的是OpenHarmony-3.2-Release对应的Flutter分支，这个版本相对稳定，社区示例多，遇到问题也容易搜到解决方案。拉代码没什么特殊之处：

bash复制git clone https://gitee.com/openharmony-sig/flutter_flutter.git -b OpenHarmony-3.2-Release

拉下来之后，把bin目录配置到PATH环境变量里，然后运行flutter doctor检查环境。这里会看到一个细节：Flutter for OpenHarmony的doctor输出里，Android工具链那栏可能显示不正常，这是正常的，因为这套分支的编译目标不是APK，而是OpenHarmony的应用包。真正的检查项是看OpenHarmony SDK路径和编译工具是否识别到了。

2.2 设备树到底怎么选：不看文档看硬件

热搜里那句"openharmony的rk3568有许多设备树到底咋选"我太有感触了。RK3568这颗芯片被大量OpenHarmony开发板采用，但不同板子的外设配置千差万别，同一个芯片对应好几套设备树文件。选错了，轻则某些外设驱动加载失败，重则系统根本起不来。

我的经验是：别只看板子供货商的文档，直接看设备树文件里的硬件配置。把rk3568开头的.dts文件逐个打开，对照你手里板子的实际硬件去匹配。比如你的开发板用的是哪个型号的屏幕触摸IC、哪个WiFi模组、哪个音频编解码器，设备树里都有明确节点。匹配上了再编译烧录，成功率能提高一大截。纯小白的话，优先选DAYU200这种社区支持最充分的开发板，它的设备树配置被验证过太多次了，出问题的概率最低。

2.3 模拟器、x86电脑与真机的取舍

热搜里还有"鸿蒙模拟器电脑版""开源鸿蒙x86iso下载""电脑版x86 openharmony"这些词，说明很多人想先在电脑上把环境跑通，再上真机。这个思路没毛病，我一开始也是这么干的。

用模拟器或x86版本的OpenHarmony跑Flutter应用，优势在于调试迭代快，不用反复烧录开发板。但要注意架构差异带来的坑：x86模拟器上编译的Flutter运行时，搬到一个ARM架构的RK3568真机上，是没法直接跑的，必须分别编译出对应架构的产物。

所以我现在的流程是：先在模拟器上把UI和业务逻辑调通，再用RK3568真机做最终验证，重点测试性能、屏幕适配、字体渲染这些模拟器上不容易暴露的问题。

2.4 创建工程与HAP打包

工程创建上，Flutter for OpenHarmony的流程和官方Flutter基本一致：

bash复制flutter create todo_app
cd todo_app

但你在工程目录里会发现多了ohos目录，这就是OpenHarmony的壳工程。编译构建的时候，Flutter代码会被编译成so库，打包进OpenHarmony的应用安装包里。说到热词里的"可以打包成hap、hsp、har的鸿蒙demo"，要理清三者的区别：hap是应用安装包，hsp是动态共享包（类似Android的split APK），har是静态共享包（类似Android的AAR库）。Flutter for OpenHarmony编译出来的主应用会打成hap格式，如果你的业务里有模块需要动态加载，可以考虑把Flutter产物拆到har或hsp里。

这一步最容易出问题的是工程配置里的包名、签名信息和模块依赖。OpenHarmony对应用签名有严格校验，调试阶段需要在工程的build-profile.json5里配置签名信息，否则安装不到真机上。模拟器上还能放松一些，真机部署就绕不过去。

3. 动手之前先把界面切成块：待办清单的信息架构

正式开始写布局之前，我先讲讲为什么我把大量时间花在"画图"而非"写代码"上。Flutter的布局组件选择非常灵活，同一个界面可以有七八种实现方式，但如果一开始没想清楚界面结构，代码写到一半就会开始失控：这里嵌套太深、那里约束冲突、列表滑动和悬浮按钮互相遮挡，越往后改越痛苦。

3.1 待办清单的功能分区

这个系列文章的待办清单项目，我规划了四个核心区域：

• 顶部输入区：一个TextField输入框加一个添加按钮，用来录入新的待办事项。
• 主列表区：展示待办事项列表，每条待办就是一个卡片，包含完成状态勾选框、事项描述文本、删除按钮。
• 底部统计区：显示当前待办总数、已完成数量，以及一个清空已完成事项的按钮。
• 悬浮添加按钮：固定在右下角，点击以后聚焦到输入框，方便单手操作。

这四个区域分别对应Flutter里不同类型的布局容器：输入区适合用Row横向排列，列表区用ListView纵向滚动，底部统计区用Row或Column组合，悬浮按钮则用Stack进行层叠定位。

3.2 组件选型：什么场景用哪个容器

我列了一张组件选型表，把待办清单里每个界面区域和Flutter布局组件对应起来：

选完了组件，还要明确它们之间的嵌套关系。我的习惯是先画一个组件树的草图：ListView是页面的主干，它的item是Container卡片，每张卡片内部用Row排列勾选框和文本，文本部分可能还有Column做换行显示。Stack在最外层，悬浮按钮作为Stack的一个子组件定位在右下角。这样写代码的时候路径就非常清晰，不会出现"这个容器该包住谁"的犹豫。

3.3 为什么先规划布局再写代码

多数新手写Flutter布局的时候是"边写边调"：先堆一个Container上去，发现宽度不对，加个SizedBox；又发现位置不对，包一层Align；再发现和别的组件间距不对，再加Padding。这样一路叠下来，组件树会变得臃肿且难维护。

先规划信息架构，本质上是把"这个界面要完成什么交互、展示什么数据"想清楚，再推导出"什么容器适合承载这个交互"。代码只是把已经设计好的结构翻译成Flutter语法而已。这一步省下来的时间是惊人的，我实测过：直接上手写和先画结构再写，总耗时能差两倍以上，而且先规划的情况下Bug数量也少得多。

4. 从Container开始：一个卡片式待办项的诞生

Container是Flutter里出场率最高的布局组件，很多人觉得它太基础了没什么好讲，但其实Container是最容易写出"看起来能用、实际上有一堆隐藏问题"的组件之一。它本质上是一个语法糖，把多个更基础的组件（Padding、DecoratedBox、ConstrainedBox、Align等）的配置集中到一起，方便快速搭建界面。理解这一点，很多Container的诡异行为就说得通了。

4.1 Container的核心属性拆解

Container的常用属性可以分成四类：尺寸约束类（width、height、constraints）、装饰类（decoration、foregroundDecoration、shadow）、内外边距类（padding、margin）、对齐类（alignment）。

拿我们待办清单里的卡片来说，我要实现的效果是：白底、圆角、浅灰色阴影、内部文字有适当留白。对应的Container写法如下：

dart复制Container(
  margin: const EdgeInsets.symmetric(horizontal: 16, vertical: 6),
  padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 10),
  decoration: BoxDecoration(
    color: Colors.white,
    borderRadius: BorderRadius.circular(12),
    boxShadow: const [
      BoxShadow(
        color: Color(0x14000000),
        blurRadius: 8,
        offset: Offset(0, 2),
      ),
    ],
  ),
  child: Row(
    children: [
      Checkbox(value: item.isDone, onChanged: (v) {}),
      Expanded(
        child: Text(
          item.title,
          style: TextStyle(
            fontSize: 16,
            decoration: item.isDone ? TextDecoration.lineThrough : null,
          ),
        ),
      ),
      IconButton(
        icon: const Icon(Icons.delete_outline),
        onPressed: () {},
      ),
    ],
  ),
)

这段代码看起来简单，但里面有几个点值得展开说。

4.2 BoxDecoration的圆角与阴影细节

很多人在Container上设置圆角的时候会踩一个坑：只设置了borderRadius，没有设置BoxDecoration的背景色，结果圆角根本看不到效果。原因在于Container的圆角是装饰的一部分，而装饰（decoration）里的color、borderRadius、boxShadow、gradient、border这些属性是协同工作的。你只给Container设置color属性，其实相当于给decoration.color赋值，这时候如果再手动给decoration设置了borderRadius，decoratedBox会默认把color拆出来给BoxDecoration，此时如果你的圆角设置了，但背景色丢掉了，视觉上就看不到圆角裁剪效果。

正确的做法是像我上面写的，把颜色和圆角都放进BoxDecoration里，不要分开写Container的color属性。阴影也一样，BoxShadow的blurRadius和offset需要一起调，我给的这组参数在大多数屏幕上看起来像一层非常淡的悬浮阴影效果，用在卡片列表里不会显得太重。

另一个容易忽略的点是：BoxDecoration里的color一旦设置，Container的decoration就不允许再为null或其属性冲突。比如你既想在Container上设置border，又单独设置color，视觉上border能正常显示，但如果想换颜色，需要手动处理组合，否则会出现属性覆盖的问题，表现为颜色变了但border没变或者反之。

4.3 Container的约束传递机制

Container比较反直觉的地方在于它的约束传递逻辑：没有child的时候，Container在未指定尺寸的情况下会尽可能撑满父级给的约束；有child的时候，Container会自动调整尺寸去适配child的大小，同时会用自身的padding和margin把有效区域撑开。

这带来一个常见问题：你想让一个Container占满整个宽度，但又只给它传了child，发现它只包住了child的宽度。这时候不要用Align去强行拉宽，更优雅的做法是在Container外面套一个SizedBox或使用父级约束（例如把Container直接放在ListView的item里，item本身就撑满宽度）。我在待办清单的卡片上是让Container作为ListView的item直接渲染，所以宽度自动撑满，这个方案在OpenHarmony上实测下来没有问题。

4.4 在OpenHarmony上第一眼看到的差异

这块我要特别提一下：同样的Container代码，在Android模拟器上和在OpenHarmony开发板上渲染出的视觉效果会有细微差别，主要集中在阴影的模糊半径和圆角的抗锯齿效果上。OpenHarmony的图形渲染走的是自己的RenderService，对Flutter的PlatformView和部分绘制指令的支持还在完善中。我实测下来，BoxShadow的blurRadius在OpenHarmony上会比Android上显得略小、更实一些，如果对阴影细腻程度有严格要求的场景，建议在OpenHarmony上调试时单独跑一遍预览图，不要想当然认为两端渲染完全一致。

5. Row与Column撑起主骨架：输入区与列表区的线性布局

待办清单的界面骨架，无非就是一横一纵两条主线：横向排列输入框和按钮，纵向排列列表项。Flutter里的Row和Column分别处理这两种场景，它们的核心逻辑都源自Flex布局模型，理解了MainAxisAlignment和CrossAxisAlignment这两个轴的概念，这两个组件就吃透了一大半。

5.1 MainAxisAlignment与CrossAxisAlignment到底怎么理解

想象一根竹签串着几颗糖葫芦：竹签的方向就是主轴（MainAxisAlignment）方向，垂直于竹签的方向就是交叉轴（CrossAxisAlignment)方向。

• Row的主轴是水平方向，交叉轴是垂直方向
• Column的主轴是垂直方向，交叉轴是水平方向

主轴负责分配多余空间：MainAxisAlignment.start让子组件靠主轴的起点，center让它们在主轴中央，spaceBetween让组件之间的间距相等、首尾贴边，spaceEvenly则让首尾也保留和中间一样的间距。

交叉轴负责对齐方式：CrossAxisAlignment.start表示子组件靠交叉轴起点对齐，center表示在交叉轴方向居中，stretch则表示拉伸填满交叉轴方向的空间。

我用一张表把待办清单里最常见的组合列出来：

建议新手在写布局的时候，脑子里先想象一遍这两个轴的方向，想清楚了再下笔。很多人写出来的布局歪七扭八，十有八九是主轴和交叉轴搞混了。

5.2 Expanded与Flexible：空间的伸缩艺术

Row或Column里最常用的伸缩组件是Expanded和Flexible，它们是处理"剩余空间分配"的关键。

dart复制Row(
  children: [
    Expanded(
      child: TextField(
        controller: _controller,
        decoration: const InputDecoration(
          hintText: '输入新的待办事项',
          border: OutlineInputBorder(),
          contentPadding: EdgeInsets.symmetric(horizontal: 12, vertical: 8),
        ),
      ),
    ),
    const SizedBox(width: 12),
    ElevatedButton(
      onPressed: _addTodo,
      child: const Text('添加'),
    ),
  ],
)

这段代码里，Expanded包裹了TextField，它的作用是：让TextField吃掉Row中除去按钮之后的所有剩余宽度。没有Expanded的话，TextField会根据内容宽度自适应，当输入的文字越来越多，Row就会溢出，在屏幕上出现一条黄黑相间的警告条纹，OpenHarmony上也是同样的渲染逻辑。

Expanded和Flexible的区别，很多人记不住。说白了：Expanded是强制子组件填满分配的空间，子组件被拉伸到指定宽度，内容放不下就要考虑溢出处理；Flexible则允许子组件在分配的空间内灵活调整自身尺寸，设置了FlexFit.loose后子组件可以比分配的空间小，但不会超过。待办清单里我用的全是Expanded，因为需要稳定的输入区宽度。

这里有一个实用技巧：Row里面如果一个文本框加一个按钮，我习惯在按钮和文本框之间放一个固定宽度的SizedBox(width: 12)，这个间距在视觉上比按钮自带padding留出的空隙要协调得多。后面你去看Material Design的规范，标准间距也是8的倍数，12在紧凑场景下观感也很好。

5.3 文本溢出和基线对齐：两个必须在OpenHarmony上验证的点

在OpenHarmony上实测Row布局时，有两个和Android/iOS表现不同的点值得注意。

第一个是文本截断策略。Flutter中的Text默认在空间不足时会换行，但如果你在一行Row里放了一个Expanded包裹的Text，空间足够小的情况下会触发Text自身溢出或截断。OpenHarmony上的文本布局引擎对省略号的处理，实际效果是一个TextOverflow.ellipsis，但截断的位置判断和Android略有不同。我在待办列表的长文本中使用了overflow: TextOverflow.ellipsis，并且配合了maxLines: 1，两端表现基本一致，但个别标点符号处的截断位置会有差异。

第二个是交叉轴对齐的基线对齐。Row的crossAxisAlignment可以设置为CrossAxisAlignment.baseline，并指定textBaseline参数，让不同字号的文字在水平线上对齐。这个能力在Android上效果明显，但OpenHarmony上textBaseline的支持不够稳定，建议用CrossAxisAlignment.center代替，视觉差异很小，还省心。

6. Stack叠出层次感：悬浮添加按钮与空状态

列表应用里几乎都有一个悬浮按钮的习惯设计：固定在页面右下角，不管列表怎么滚，它都在那。这个效果的背后是Flutter的Stack组件，它的工作原理是让子组件从同一个原点开始叠放，配合Positioned可以指定子组件距离父组件四条边的偏移量。Stack非常适合处理"一个页面里既有主体滚动列表，又有固定悬浮元素"的场景。

6.1 Stack与Positioned的配合方式

Stack的布局思路和Row、Column完全不同。Row和Column把子组件一个接一个排开，Stack则是把子组件全部堆叠起来，后写的组件会覆盖在先写的组件之上。Positioned可以指定一个子组件相对于Stack四条边的距离，从而实现明确的覆盖定位。

待办清单的主页面结构是这样的：

dart复制Scaffold(
  body: Stack(
    children: [
      // 主体：待办列表
      Positioned.fill(
        child: ListView.builder(
          itemBuilder: ...,
        ),
      ),
      // 左上角：空状态提示
      if (_todos.isEmpty)
        const Positioned(
          left: 0,
          right: 0,
          top: 120,
          child: Center(
            child: Text('还没有待办事项，先添加一条吧'),
          ),
        ),
      // 右下角：悬浮按钮
      Positioned(
        right: 24,
        bottom: 24,
        child: FloatingActionButton(
          onPressed: () {
            FocusScope.of(context).requestFocus(_textFocus);
          },
          child: const Icon(Icons.add),
        ),
      ),
    ],
  ),
)

Positioned.fill是Stack里特别实用的一个用法，它让子组件填满Stack的整个区域，相当于四个方向偏移全为0并启用了loose约束。ListView作为填满整个区域的主体列表，滚动范围就是整个页面，悬浮按钮覆盖在列表之上互不干扰。

6.2 悬浮按钮和列表之间的触摸事件冲突

很多人用Stack做悬浮按钮以后，马上会遇到一个问题：按钮确实悬浮了，但列表滚动到按钮那个位置的时候，触摸事件会被按钮拦截，列表无法顺畅滑动。这其实不是Bug，Stack的命中测试规则就是"从最上面的子组件往下找"，谁在上层谁先响应触摸。

解决思路有两种：第一种，悬浮按钮用IgnorePointer和HitTestBehavior控制命中行为，但我不推荐，太绕了；第二种，把悬浮按钮从Stack里拿出来，直接放到Scaffold的floatingActionButton参数里。Scaffold对悬浮按钮的事件区域做了专门的优化处理，列表滚动时只有真正按到按钮上才会触发，手指在按钮旁边滑动时事件会穿透到列表。这是最优雅的解决方案。

所以我的建议是：能用Scaffold自带能力实现的，就不要手动做层叠，Flutter框架已经把手指的误触问题考虑好了，你用Stack硬做的反而容易踩坑。

6.3 空状态提示的层级关系

待办清单在没有数据的时候，列表区域是空白的，这时候需要显示提示文字。把它放在Stack里是因为它可以和列表共存于同一层，数据从空到有的过程不需要额外处理组件的显隐切换。

空状态的判定我用的是条件渲染：

dart复制if (_todos.isEmpty) const EmptyPlaceholder() else const TodoListView()

在Stack里的话，Positioned加Center的组合要注意一点：Positioned指定了left、right、top以后，子组件Center的宽度会受到position约束，实际效果可能与预期不同。如果你只是想在整个Stack的中间显示一行提示文字，可以简化为只写Center，不套Positioned。Stack中未使用Positioned包裹的子组件会自动根据Stack的alignment属性对齐，默认是topStart，改成alignment: Alignment.center就可以居中。

dart复制Stack(
  alignment: Alignment.center,
  children: [
    if (_todos.isEmpty)
      const Text(
        '暂无待办事项',
        style: TextStyle(color: Colors.grey, fontSize: 15),
      ),
    // 其他子组件
  ],
)

这个写法比Positioned + Center的组合更简洁，而且不容易出现约束溢出的问题。我在OpenHarmony上实测，Stack的alignment在两端表现一致，不会引入新的兼容性问题。

7. ListView + Padding：列表滚动与留白的正确姿势

待办清单的核心交互就是滚动浏览列表，这个部分我用了ListView.builder的高效模式。不过ListView在实际项目中踩坑不少，尤其是高度约束、滚动性能和Item间距这些问题，几乎每个新手都会碰一遍。

7.1 ListView.builder和ListView的取舍

ListView最基本的用法是传入一个children列表，一次性构建所有子项。这个做法在数据量少的时候没问题，但待办清单数据一旦超过几十条，就不太妙了：所有item会在一帧内全部构建，滚动性能会随着数据量增加而下降。

ListView.builder则是懒加载模式，它只构建当前视口内可见的item，滑动过程中动态复用和销毁。实测在OpenHarmony开发板上，ListView.builder滚动300条待办数据，帧率稳定，没有明显的卡顿或掉帧现象。所以待办清单里我毫不犹豫地选用了builder模式：

dart复制ListView.builder(
  padding: const EdgeInsets.only(bottom: 80, top: 8),
  itemCount: _todos.length,
  itemBuilder: (context, index) {
    final todo = _todos[index];
    return TodoCard(
      todo: todo,
      onToggle: () => _toggleTodo(index),
      onDelete: () => _deleteTodo(index),
    );
  },
)

7.2 padding与margin的真正区别

很多新手搞不清楚Padding和Margin的区别，我用一句话总结：Padding是组件内部的留白，它会影响组件自身内容物和边框之间的距离；Margin是组件外部的间距，它控制组件和兄弟组件或父容器之间的距离。

在待办清单里，每个卡片之间的间距我用的是Container的margin。这样写的好处是，卡片的装饰背景不会延伸到margin区域，视觉上每个卡片都是独立的块。如果误用Padding去控制卡片间距，你会发现卡片的背景色也一并延伸过去了，整个列表的层次感直接消失。

7.3 列表底部留白：悬浮按钮遮挡的关键

还有一个不容易注意到的细节是ListView的padding，我在上面写了padding: EdgeInsets.only(bottom: 80)。这个80像素的底部留白，是给悬浮按钮腾位置用的。如果不写这个padding，当列表滚动到最后一条待办时，最后一条会被悬浮按钮遮挡，用户无法完整看到最后一项的内容，点击删除或勾选都会受影响。

类似的坑还有顶部状态栏的遮挡。OpenHarmony的刘海屏和水滴屏设备越来越多，如果直接让ListView顶到屏幕顶部，状态栏区域会把列表内容挡住一部分。处理方案是给ListView增加顶部padding，或者包一层SafeArea。我实测下来，SafeArea在OpenHarmony上对状态栏高度的识别是准确的，优先推荐用SafeArea。

7.4 列表项刷新机制和状态保持

在待办清单里，勾选一个事项、删除一个事项，都要实时反映在列表上。这个数据刷新我用的是Flutter的标准方案：数据模型放在一个Controller里，列表组件监听Controller的变化，用setState触发重建。

ListView.builder在setState之后，只会重建视口内的可见item，而不是全部重建，这也是它性能好的原因之一。但有一个与之相关的"坑"：如果你在item里用了TextEditingController或者ScrollController，这些状态在item复用过程中可能会保留旧值或者丢失新值。待办列表的卡片本身不含可编辑控件，所以目前还没踩到这个坑。但如果你在列表里嵌入输入框，一定要在itemBuilder里为输入框创建独立的controller，并在item销毁时释放，否则会引发内存泄漏或文本错乱。

另外，在OpenHarmony上实测时，我发现在真机上快速滚动物列表再点击item，偶尔会出现"点击位置偏移"的现象。排查后确认不是Flutter布局的问题，而是OpenHarmony的触摸事件上报存在一个极短暂的延迟，快速滑动后立即点击时坐标采样出现偏差。解决方案是给ListView的item增加一个小延迟的点击响应保护，或者使用GestureDetector的behavior结合命中测试来处理。这个问题在后续的交互篇里我再细说。

8. 鸿蒙真机上的实测：字体、屏幕适配与常见报错排查

跑通布局只是第一步，真正上到鸿蒙真机调试，才会暴露出一堆这些组件在模拟器上看不到的问题。我把这几个阶段遇到的典型问题整理一下，给后来者一个排查的入手点。

8.1 字体渲染差异与全局配置

同样的Text代码，在Android和OpenHarmony上的字体渲染有明显差异。最突出的是中文字体：OpenHarmony默认字体和安卓的思源黑体在笔画粗细、字间距上都有区别，同一个字号在鸿蒙上看起来偏小、偏细。

我的处理办法是在MaterialApp里显式配置全局字体样式：

dart复制MaterialApp(
  theme: ThemeData(
    fontFamily: 'HarmonyOS Sans',
    textTheme: const TextTheme(
      bodyMedium: TextStyle(fontSize: 16, height: 1.4),
      bodyLarge: TextStyle(fontSize: 18, height: 1.4),
    ),
  ),
)

OpenHarmony系统内置了HarmonyOS Sans字体，只要指定fontFamily，它会在渲染时自动匹配。实测下来，显式指定字体后，中文的显示效果和鸿蒙原生应用基本一致，不再有"和UI稿偏差一个字号"的尴尬。高度height参数也建议统一设置，不同系统下默认行高不同，会让列表项之间的视觉间距产生偏差。

8.2 屏幕适配：从模拟器到真机的布局变形

我在模拟器上调好的界面，第一次跑到RK3568真机上，最大的感受就是"上下留白变大、左右变窄"。原因是模拟器和真机的宽高比、逻辑分辨率不同，固定尺寸的Container和SizedBox在两端表现不一致。

Flutter里的逻辑像素和物理像素的映射关系在不同设备上不同，如果你的布局大量使用固定尺寸，迁移到不同屏幕就会变形。待办清单项目里我尽量用Expanded、Flexible、aspectRatio这类相对布局来替代固定宽度。最后一个底部统计栏，我用了Row加Expanded均分三列，而不是给每个统计项固定宽度，这样无论是平板还是手机宽度下都能自适应。

8.3 常见报错与排查链路

我在开发过程中遇到过的、以及社区里高频出现的几个问题，整理成了一张排查表：

其中签名的问题是新手最常遇到的，也是最容易卡住的一环。第一次配置时需要在DevEco Studio里生成调试证书，并把证书的profile文件放到工程里，不少教程跳过这一步导致照着做也装不上。如果安装hap时报错，优先查看OpenHarmony的hilog日志，而不是去看Flutter的debug输出，很多时候Flutter侧没有异常信息，问题全在系统侧。

8.4 性能实测：在RK3568上的帧率表现

最后说点实际的性能数据。RK3568这颗芯片在OpenHarmony设备里算中端偏上，我在上面跑待办清单，流畅滚动200条列表数据的帧率稳定在55帧以上，偶尔在首次加载图片资源时会掉到40帧左右，但不影响操作手感。Container的阴影对渲染性能有一定影响，卡片数量多时阴影会加大GPU的填充率压力，如果对帧率有极致要求，可以去掉卡片阴影，改用边框加浅底色来勾勒层次感，视觉效果几乎一样，但渲染开销能降低不少。

从整体体验来看，Flutter for OpenHarmony已经具备实际项目开发的条件了。基础布局组件这块，Container、Row、Column、Stack、ListView在鸿蒙上运行稳定，没有出现需要绕开平台的阻断性问题。同样的布局代码在Android和OpenHarmony之间的迁移成本很低，只有字体、阴影细节和触摸事件这几个边角需要针对鸿蒙做额外适配。

这次我写的待办清单用的全部是Dart侧的基础布局组件，没有涉及任何OpenHarmony特定API，就已经能实现一个完整可用的界面和交互流程。等到后面聊状态管理、平台通道和数据库接入的时候，再来看这个项目如何升级成能真正落地的生产级应用。下一篇文章我计划围绕待办清单的数据持久化展开，聊聊本地数据库该选sqflite还是别的方案，以及数据变更后Flutter UI怎样高效刷新。