企业官网建设流程全解析

1. 为什么我把卡片网格放在了 OpenHarmony 适配的最前面

1.1 这盘布局需求从哪来，能解决什么问题

我在做的“模拟项目X”是一款需要同时交付 OpenHarmony 与 Android 双端的内容型应用，首页由“顶部运营位 + 分类 Tab + 卡片流”三个区块组成。其中卡片流又是一个相对独立的业务模块：它要承接文章、短视频、活动 banner、用户数据提醒等多种内容形态。团队当时评估了一轮自绘方案、原生方案和跨端方案，最后敲定的路线是“Flutter 负责全部 UI 和业务逻辑，OpenHarmony 原生只做系统能力与壳工程”。既然 Flutter 侧承担了绝大部分页面，首页卡片网格就成了整个项目里风险最高、又必须最先打通的模块。

为什么不是先做设置页、详情页，而是先啃卡片网格？因为卡片网格的约束条件最密集：它要同时处理多屏适配、异形卡片、图片加载、滚动性能、点击反馈和状态保持。这些点如果放在原生能力差异化很大的 OpenHarmony 上，能尽早暴露工具链、渲染管线、交互事件这些底层的兼容问题。这个阶段把坑踩平了，后面做任何列表型页面都会顺畅很多。

我常跟同行说一句话：卡片网格不是一个“布局样式”，它是一套完整的信息层级方案。小到卡片圆角、阴影、留白，大到网格列数、卡片宽高比、加载骨架屏，所有细节都会直接决定产品在用户眼中的专业度。把这块做成一个可以复用的基础组件，收益远大于单纯实现一个页面。

1.2 选 Flutter 在 OpenHarmony 上画卡片的理由

这个选择背后有几个具体因素。首先，Flutter 的渲染是自绘引擎，UI 表现不依赖宿主控件的实现，所以在 OpenHarmony 和 Android 上看到的是同一套绘制结果。卡片网格里既有渐变角标、圆角图片裁切，也有阴影和模糊效果，原生两套实现很容易差出几个像素，而 Flutter 只要保证引擎层跑通，视觉一致性就基本稳了。

其次，卡片网格这种高频滚动页面，性能瓶颈通常集中在“对象的创建与销毁”和“图片解码”上。Flutter 的列表组件天然支持懒加载，配合 const 构造、RepaintBoundary 这类手段，做性能调优的思路非常清晰。相比在 OpenHarmony 原生侧用自研容器写一套网格复用逻辑，Flutter 生态里现成的组件和社区案例明显更多，踩坑成本也更低。

还有一点，OpenHarmony 的 Flutter 适配链路已经过了“能不能跑”的阶段，但很多团队还停在“能跑 Demo，不敢上生产”的状态。我接这个项目时最想确认的，就是 Flutter 页面在 OpenHarmony 真机上到底能不能稳定承载一个首屏网格。事实证明可以，但前提是工程接入的每一步都得按规矩来。

2. 环境与工程链路：把 Flutter 页面装进 OpenHarmony 壳

2.1 SDK 与工具链的对齐

这是整个项目里最容易被低估的一步。Flutter 的 OpenHarmony 支持并不是官方 stable 分支默认带的能力，而是需要切换到专门适配 OpenHarmony 的 SDK 分支上。具体操作是：从一个可信的镜像仓库拉取含flutter_ohos相关组件的 SDK，再用这个 SDK 的 flutter 命令创建工程。

我踩的第一个坑就是版本对齐。OpenHarmony 侧的 SDK 分为 API 版本，Flutter 适配分支也有对应的适配版本，两者不匹配时，编译能过但运行期可能出现奇怪的崩溃，比如Failed to load dynamic library或者页面白屏。项目环境里我最终固定了这样一组工具链：

• OpenHarmony SDK：API 12 左右版本，使用命令行工具而不是完整 IDE；
• Flutter SDK：适配 OpenHarmony 的分支，Dart 版本跟随分支自带版本；
• 构建工具：使用hvigorw命令行编译 HAP 包；
• 真机部署：通过hdc命令安装和调试。

选命令行工具是因为在 CI 环境里要自动打包，而且个人开发时也不喜欢被 IDE 绑定。如果你习惯可视化操作，用官方 IDE 会方便一些，只是要留意 IDE 自带的 SDK 版本建议。

创建工程时，命令和平常有一点区别：

flutter create --platform ohos --org com.example.cardgrid card_grid_demo

这个命令会在常规的 android/ios 目录之外，额外生成一个ohos目录。如果你用的分支不支持--platform ohos，大概率是分支版本太老，或者安装时环境变量没指向正确路径。

2.2 工程配置里最容易出错的三个文件

OpenHarmony 壳工程里最重要的配置集中在三个文件，处理不好几乎是必然报错。

第一个是工程根目录的build-profile.json5，它声明了签名、产品形态和模块路径。开发调试时不一定要配正式签名，但至少要有一个本地调试签名，否则hvigorw assembleHap出来的包无法安装到真机。签名信息里的certificate、profile和signingConfigs是三个独立字段，缺一不可。我见过不少人只配了证书，忘了配 profile 文件，结果报错信息指向“签名校验失败”，很容易误以为是设备问题。

第二个是ohos模块下的module.json5，它描述应用包名、入口能力和系统能力声明。Flutter 页面启动时需要有一个Ability作为宿主，这里要声明：

{ "app": { "bundleName": "com.example.cardgrid", "versionCode": 1000000, "versionName": "1.0.0" }, "module": { "name": "entry", "type": "entry", "abilityBackToHome": true, "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "description": "app entry", "skills": [ { "entities": ["entity.system.home"], "actions": ["action.system.home"] } ] } ] } }

如果你在应用内部跳转、拉起页面时遇到“找不到 Ability”，先去检查bundleName和skills是否匹配壳工程的包名。包名一旦在签名、配置文件、Flutter 工程三处不一致，真机上就会出现“安装成功但无法启动”的现象。

第三个文件是ohos目录下的网络权限配置。网格里的图片大多走网络加载，如果没在module.json5的requestPermissions里声明网络访问权限，Flutter 侧图片缓存组件会一直报“Connection failed”而不是直接提示权限问题。我第一次遇到时查了半天网络库，最后才发现是权限声明漏了。

2.3 真机联调的最小验证闭环

配置完成后，我习惯先做一个最小验证，而不是直接把整个首页搬上去。最小验证的目标只有一个：确认 Flutter 页面能在 OpenHarmony 真机上渲染出一个可交互的简单页面。

具体流程是：

1. 先用flutter create自带模板跑一个最简单的页面；
2. 执行hvigorw assembleHap打包，或者通过 IDE 构建；
3. 用hdc install安装到真机；
4. 使用flutter attach或直接看日志确认 Dart isolate 正常启动；
5. 在页面上放一个点击后自增的计数器，确认事件链路通。

这一步看着简单，却是我觉得最值得花时间的环节。之前有团队直接在模拟器上验证，模拟器对图形栈的兼容和真机有差异，很多 OpenHarmony 真机上的渲染问题在模拟器上是复现不出来的。我在真机上遇到的第一个问题就是页面首帧正常，但滑动列表时偶发掉帧，后来定位到是默认字体加载路径的问题，这类问题在模拟器上几乎不会出现。

3. 先定卡片数据和网格算法，再动手画格子

3.1 卡片数据的模型怎么抽象

很多人一上来就写 GridView 的代码，忽略了一个关键点：卡片网格的质量首先由数据结构决定。卡片不止是“一张图 + 一行字”，它可能有视频封面、活动标签、用户头像、点赞数、有效期倒计时。如果数据模型不把这些显式建模，布局代码里就会塞满各种if判断和魔法字段，整个组件会越来越难维护。

我在模拟项目X里把卡片抽象成下面这样：

enum CardKind { article, video, activity, stats } class CardItem { final int id; final String title; final String subtitle; final String heroImage; final CardKind kind; final bool isFeatured; factory CardItem.fromJson(Map<String, dynamic> json) { return CardItem( id: json['id'] as int, title: json['title'] as String, subtitle: json['subtitle'] as String? ?? '', heroImage: json['heroImage'] as String? ?? '', kind: CardKind.values.firstWhere( (e) => e.name == json['kind'], orElse: () => CardKind.article, ), isFeatured: json['isFeatured'] as bool? ?? false, ); } }

抽象的关键不是把所有字段都塞进去，而是提炼出“所有卡片共有的能力”。比如isFeatured是用来控制宽卡和窄卡切换的开关，kind决定卡片右下角的角标类型。有了这个基础模型，后续在网格里做任何视觉变化，都不需要再回头改数据源结构。

3.2 网格委派的选型与参数推算

Flutter 里常见的网格委派有两种：SliverGridDelegateWithFixedCrossAxisCount和SliverGridDelegateWithMaxCrossAxisExtent。前者固定列数，后者根据屏幕宽度自动计算列数。我在卡片网格里几乎一律用后者，原因很实际：OpenHarmony 设备形态差异大，同一套代码可能在手机、平板甚至带屏设备上运行，固定列数在逻辑像素宽度变化时容易让卡片变得过宽或过窄。

实际配置我长这样：

const SliverGridDelegateWithMaxCrossAxisExtent( maxCrossAxisExtent: 280, mainAxisSpacing: 12, crossAxisSpacing: 12, childAspectRatio: 0.92, )

这里有一个很关键的推导过程，值得展开。maxCrossAxisExtent并不是“卡片实际宽度”，它只是一个目标上限。Flutter 引擎会根据可用宽度计算交叉轴方向能放多少个格子，计算方式是：

• 假设可用宽度为 W，目标宽度为 T，交叉轴间距为 S；
• 列数 n = (W / (T + S)).ceil()；精确一点：取大于等于(W + S) / (T + S)的最小整数；
• 卡片实际宽度 = (W - (n - 1) * S) / n。

举个例子，一台逻辑宽度为 360dp 的手机，页面左右 padding 各 16dp，可用宽度是 328dp，交叉轴间距 12dp。套进公式：n = 2，卡片实际宽度 = (328 - 12) / 2 = 158dp。如果childAspectRatio是 0.92，那么卡片高度就是 158 / 0.92 ≈ 171.7dp。这个高度对一张“标题 + 两行摘要 + 底部标签”的卡片来说刚好。

到了逻辑宽度 768dp 的平板：W = 736dp，n = 3，卡片实际宽度 = (736 - 24) / 3 ≈ 237dp，高度约 257dp。同样是“内容层多一点、留白多一点”，视觉比例能保持一致。

这也是为什么我不喜欢单独调childAspectRatio而不看推导过程。如果不懂这个换算，就很难解释为什么同一套代码在不同宽度下卡片高度表现完全不一样。

3.3 多机型下 childAspectRatio 的调法

调childAspectRatio是卡片网格里最磨人的事。user 反馈“卡片文字被截断”，或者“下面留白太多”，多半就是比例不对。我总结了一个经验：先确定卡片内部内容需要的“最小高度”，再去反推比例，而不是凭感觉定一个值。

具体方法是在网格里放一个内容完整、字段最多的卡片作为基准。用TextPainter或者直接临时把某张卡片的maxLines全部放开，让它自己撑开，再根据实际高度和宽度的比值来设定childAspectRatio。当然，运行期做自适应高度会让网格失去固定滚动高度的优势，所以实际项目中还是得权衡：如果每张卡片高度差异很大，就别用固定比例，改用SliverGridDelegateWithFixedCrossAxisCount配合“内容不确定的部分放在底部或固定高度区域”。

还有一个小技巧：文档里提到的mainAxisExtent是个被用得很少但很实用的参数。如果你不想算比例，可以设定固定的主轴高度，比如mainAxisExtent: 180，卡片高度就恒定在 180dp。这个值配合内部Column的Expanded布局，能极大减少“文字溢出”的问题。代价是宽度变化时卡片的宽高比会动态变化，但很多场景下这并不影响视觉。

4. GridView 构建卡片网格的布局细节

4.1 用 itemBuilder 动态生成卡片单元

网格主体的实现没有太多悬念，核心就是GridView.builder。builder 构造的懒加载机制保证了只有进入可视区域的 item 才会真正构建，这也是首屏和大列表能保持流畅的根本原因。

GridView.builder( padding: const EdgeInsets.all(16), gridDelegate: _gridDelegate, itemCount: _cards.length, itemBuilder: (context, index) { final item = _cards[index]; return _CardGridItem( key: PageStorageKey('card_grid_${item.id}'), item: item, ); }, )

注意这里的PageStorageKey。滚动一个长网格再切走页面，回来后如果发现滚动位置不对，多半就是少了它。尤其是 OpenHarmony 原生页面和 Flutter 页面之间存在系统级页面切换时，PageStorageKey能帮你在PageStorage里保住滚动偏移量，这个比自己去记录ScrollController.offset要省事。

_CardGridItem的内部结构以Card为外壳，加InkWell做水波纹。这里有一个视觉细节：如果直接把InkWell放在Card外层，点击时水波纹会被圆角裁掉一半；正确做法是把InkWell放在Card的内部，配合clipBehavior: Clip.antiAlias，让水波纹顺着圆角走。

class _CardGridItem extends StatelessWidget { final CardItem item; const _CardGridItem({super.key, required this.item}); @override Widget build(BuildContext context) { final theme = Theme.of(context); return RepaintBoundary( child: Card( margin: EdgeInsets.zero, clipBehavior: Clip.antiAlias, elevation: 0, color: theme.colorScheme.surfaceContainerLow, shape: RoundedRectangleBorder( borderRadius: BorderRadius.circular(16), ), child: InkWell( onTap: () => context.read<CardGridController>().toggleLike(item.id), child: Padding( padding: const EdgeInsets.all(12), child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ _HeroImage(item: item), const SizedBox(height: 8), Text( item.title, maxLines: 2, overflow: TextOverflow.ellipsis, style: theme.textTheme.titleMedium, ), const Spacer(), Row( mainAxisAlignment: MainAxisAlignment.spaceBetween, children: [ _KindBadge(kind: item.kind), _ActionButtons(item: item), ], ), ], ), ), ), ), ); } }

4.2 卡片内部布局的约束与伸缩设计

卡片内部的Column是整套布局的难点，难点在于：网格单元的高度其实是“被固定”的，不是内容决定高度。固定高度下，如果内容太长，要么溢出，要么被裁剪；如果内容太短，底部会出现大片空白。

我的处理原则是把卡片内部分成三部分：固定高度的顶部区（图片）、弹性标题区、固定高度的底部区（标签 + 按钮）。中间用Spacer或Expanded撑满剩余空间。Spacer在Column里本质是一个Expanded的空组件，它能把底部区域“顶”下去，保证无论标题是一行、两行，卡片底部的元素始终对齐到同一高度。

这里有一个容易翻车的地方：如果Column放在了高度不确定的容器里，Spacer会直接报错，因为它在主轴没有边界的情况下无法计算弹性比例。所以用这个模式前，一定确保上层是网格单元，或者能给到确定高度的组件。

图片区域使用AspectRatio或固定高度SizedBox来控制。我倾向于用固定高度加width: double.infinity，再让图片用BoxFit.cover裁切，这样能避免网络图片加载出来后被拉伸变形。

4.3 混合卡片规格的排布策略

真实项目里往往不只是等宽等高的小卡片，还会有“大卡 + 小卡”的组合。比如一个运营活动卡片需要跨两列，或者某个重点文章要占更大的视觉面积。网格委派本身不支持“一行里某个 item 横跨两格”，需要靠布局策略去拆。

我试过两种方案。第一种是把大卡也放进小卡网格，但内部用“两倍宽度”的视觉设计，比如图片铺满、文字更多。但这样做会浪费网格单元内的大量空间，因为单格里的 content 容量有限。第二种更有效：干脆不用同一个 GridView，而是用CustomScrollView加SliverGrid和SliverToBoxAdapter混排。重点卡片用SliverToBoxAdapter放一个全宽卡片，后面的普通卡片继续用网格。首屏需要重点曝光的内容就是那几个，混排不需要太高的动态性，这方案简单可靠。

如果要求极其复杂的瀑布流效果，比如每个卡片高度都不同，那就要引入staggered_grid_view这类第三方库。但在 OpenHarmony 适配初期，我建议优先降低复杂度，先把固定比例的网格做到性能和稳定性全部达标。瀑布流带来的动态高度在列表缓存和滚动跳变上的问题，适配成本要高得多。

5. 卡片交互、状态管理与双端差异

5.1 状态管理选型与卡片状态的更新方式

卡片网格的交互通常包括点赞、收藏、展开/收起、跳转详情。这些状态如果全部用setState写在页面里，随着卡片数量增长会越来越难维护。我在这里用Provider，理由很朴素：它足够轻，心智负担小，而且对 OpenHarmony 的 Flutter 适配没有额外依赖。

CardGridController负责所有卡片级状态：

class CardGridController extends ChangeNotifier { final Set<int> _likedIds = {}; final Set<int> _expandedIds = {}; bool isLiked(int id) => _likedIds.contains(id); bool isExpanded(int id) => _expandedIds.contains(id); void toggleLike(int id) { if (!_likedIds.add(id)) { _likedIds.remove(id); } notifyListeners(); } void toggleExpand(int id) { if (!_expandedIds.add(id)) { _expandedIds.remove(id); } notifyListeners(); } }

在 itemBuilder 里通过context.read拿到控制器，用context.select精确订阅单个 id 的状态，避免整页重建。这里的关键点是：状态变更要尽量“精确通知”，而不是把整个 controller 丢进Consumer里等待全局刷新。卡片网格的 item 数量一多，全局刷新就会在低端 OpenHarmony 真机上造成肉眼可见的卡顿。

5.2 展开、收藏、返回手势的状态处理

卡片展开是一个特别容易引发连锁反应的交互。如果只改变单张卡片的高度，网格的其他卡片位置会跟着跳动，体验很差。我的做法是：展开状态不是“改变这张卡片的高度”，而是在卡片内部做内容层的显隐动画。具体来说是保持网格单元高度不变，内部内容从单行摘要变成多行摘要，或者从隐藏详情变成展开详情，变化区域高度用固定高度差值来控制。

这个“固定高度差值”的思路是我在真机上反复调出来的。Flutter 的AnimatedContainer或AnimatedSize都不适合直接在网格单元里做高度动画，因为网格布局对高度的感知是“瞬间完成”的，不会跟着动画过渡。你在动画中间帧看到的效果往往是其他卡片已经跳到位了，只有当前卡片还在慢慢长高。所以我干脆用AnimatedCrossFade或AnimatedSwitcher做两层内容的切换，动画只作用于卡片内部，不影响网格排布。

收藏图标的反馈也一样，用AnimatedSwitcher在两个图标之间做小缩放/渐隐切换：

AnimatedSwitcher( duration: const Duration(milliseconds: 200), transitionBuilder: (child, animation) => ScaleTransition( scale: animation, child: child, ), child: Icon( liked ? Icons.favorite : Icons.favorite_border, key: ValueKey(liked), color: liked ? theme.colorScheme.error : null, ), )

返回手势在双端也有差异需要注意。Android 侧的系统返回在 Flutter 里通常由PopScope拦截，而 OpenHarmony 的侧滑返回手势在部分版本上会把 Flutter 页面直接退出，而不是触发Navigator.maybePop。如果你发现用户从详情页侧滑返回时跳到了应用外，多半就是这个问题。我的临时方案是在卡片详情页入口处禁用侧滑返回，或者在宿主侧把手势事件传给 Flutter 处理。

5.3 调用 OpenHarmony 系统能力时的通道隔离

卡片网格虽然只是 UI，但免不了要调用振动、剪贴板、日期选择、相册这类系统能力。Flutter 侧统一走MethodChannel，但 OpenHarmony 侧和 Android 侧的实现在插桩方式上完全不同。

我遇到过最典型的问题是：在 Android 上写好的MethodChannel调用，跑到 OpenHarmony 上直接抛MissingPluginException。原因很直接——OpenHarmony 需要的“原生插件”还没有注册到壳工程的 Application 初始化阶段。Flutter 的插件注册机制在两种宿主上的加载路径不一样，Android 自动通过GeneratedPluginRegistrant注册，OpenHarmony 需要手动在入口 Ability 里调用对应插件的Register(req, binding)。

所以我做的第一件事是梳理出“哪些能力真的需要原生侧支持”。能通过 Flutter 插件生态解决的，优先用 Flutter 生态；生态覆盖不到的，再在 OpenHarmony 侧写最小 ETS 插件。写的一个简单通道长这样：

const platform = MethodChannel('com.example.cardgrid/haptics'); Future<void> triggerHaptic(int level) async { try { await platform.invokeMethod<void>('trigger', {'level': level}); } on MissingPluginException { // 模拟器或未注册原生端时静默失败 } }

捕获MissingPluginException是个好习惯。接入新环境的时候，系统能力是否就绪是个未知数，不能让一次振动失败把整个卡片点击流程都打断。

6. 性能调优和 OpenHarmony 真机问题排查

6.1 网格列表的构建优化

首屏 20 张卡片、滚动加载 200 张卡片，这是我用来评定网格性能的最低标准。Flutter 的GridView.builder已经很能打，但代码写得不注意，仍然会在低端设备上露馅。

第一个优化点是避免 itemBuilder 内部创建临时对象。卡片内部每次 build 都重新格式化时间字符串、重新计算颜色值，这些都是不必要的消耗。把计算结果缓存在 CardItem 里，或者做成 memo 化的 getter。

第二个优化点是const构造。虽然网格里的卡片通常不是 const，但内部的静态文本、间距、部分装饰组件可以用 const 标记。Flutter 对 const widget 有专门的重建跳过处理，能减少大量 build 成本。

第三个优化点是给每张卡片的外层包RepaintBoundary。这点在视觉上无感知，但对滚动性能的帮助很明显。它能让单张卡片的内容变化不触发附近卡片的重绘。在模拟项目X的卡片上，图片加载完成、图标变色这些操作都发生在RepaintBoundary内，网格其他位置不会跟着“闪”一下。

6.2 图片解码与内存抖动的处理

图片是卡片网格的大头。网络缩略图如果直接用网络原图，在 OpenHarmony 真机上会造成两个问题：内存峰值高、图片模糊后清晰的过程非常突兀。

我采用的是“三级策略”：优先加载本地缓存的小图，滚动静止后再加载高清图；加载过程中显示纯色占位；图片组件固定设置cacheWidth，把解码后的像素宽度限制在卡片实际所需的两倍以内。最后这一点特别重要。Flutter 里的Image组件如果不设置cacheWidth或cacheHeight，会把网络图片按原始分辨率解码，一张相机照片两三千万像素，即便显示区域只有几百像素，内存里照样给你解成完整大图。网格一屏能同时显示 6 张这种图，内存直接告警。

在 OpenHarmony 上我还遇到一个奇怪现象：部分图片加载失败后，回调一直不返回，导致占位组件无限转圈。排查后确认是图片缓存库的磁盘写入路径在 OpenHarmony 沙盒上有兼容问题。解决办法是把缓存目录切换到应用专属文件目录，而不是默认的临时目录。

6.3 热重载、AOT 与疑难日志的定位思路

开发时用热重载很爽，但 OpenHarmony 适配阶段的热重载并不像 Android 那么无脑。有时候改完代码，页面显示正常，但一触发平台通道调用就崩溃，或者布局参数出现错乱。遇到这种情况不要反复热重载，直接把应用杀掉重新跑一次。

我总结了一套真机排错流程，命中率很高：

1. 观察flutter run终端日志里的 Dart 侧异常；
2. 用hdc shell hilog查看 OpenHarmony 原生侧日志；
3. 如果崩溃发生在原生侧，优先怀疑插件注册、签名、权限三个方向；
4. 如果是渲染层异常，检查是不是用了不兼容的字面量颜色或字体；
5. 如果怀疑是 AOT 编译问题，用 debug 模式跑一遍做对照。

这里想强调一下“双日志”的概念。OpenHarmony 上 Flutter 页面崩溃时，Dart 侧错误可能被吞掉，只在原生侧留下崩溃堆栈。你要是不看hilog，光盯 Flutter 终端，很容易觉得“没有报错但应用闪退了”。把两边的日志放在同一个时间轴上看，定位速度会快很多。

还有一个小细节：flutter attach在 OpenHarmony 上不一定每次都能成功连接，尤其是应用启动了多个 Ability 实例的时候。遇到 attach 不上的情况，先确认当前前台页面是否是 Flutter 入口页，如果不是，先切回入口页再 attach。

7. 这次实战留下的几条硬经验

7.1 后续扩展的方向与工程建议

卡片网格这个模块跑通后，我建议不要停在这一个页面上。可以把它抽成通用组件库，至少包括“网格参数计算器”和“卡片模型转换器”两部分。网格参数计算器负责根据设备宽度、间距、目标卡片宽度自动算出childAspectRatio或mainAxisExtent；卡片模型转换器负责把服务端下发的各种字段映射到统一的 CardItem 结构。

在 OpenHarmony 应用里，后续如果要接“原子化服务”或“桌面卡片”这类系统级入口，网格数据模型还能复用。卡片 UI 只要在 Flutter 侧生成可渲染的 widget 树，宿主侧用组件方式嵌入即可。现在做的数据抽象越干净，后面承接新形态的成本就越低。

7.2 我的最后提醒

如果你正准备在 OpenHarmony 上做第一个 Flutter 网格页面，我最后给三条基于实际体验的提醒。

第一，尽量早地在真机上跑真实数据，不要用模拟器或者假数据拖太久。网格性能、图片内存、滚动跟手这些指标，只有真实设备、真实网络、真实图片尺寸才能暴露问题。我在项目中用一套本地 mock 数据测了一个多月，换到线上真实图片资源后立刻发现图片解码内存问题，前期很多“性能优化”其实都没打在点子上。

第二，把配置文件当成代码一样管理，纳入版本控制，记录改动原因。module.json5、build-profile.json5这些文件在多人协作里特别容易被乱改。某次调试签名不小心替换了默认签名配置，第二天整个团队打的包都无法安装，排查了一早上才发现是配置文件被误提交。

第三，卡片网格不是一次性做完就结束的模块。内容型产品的卡片样式会不断迭代，今天加一个角标，明天加一个背景色。定义好统一的卡片模型和网格布局入口，后面的迭代才不会被一小撮样式差异拖成泥潭。

模拟项目X还在继续往前走，卡片网格已经从最初的“一个页面”长成了“一套组件”。OpenHarmony 设备的用户现在每天能稳定刷到首页卡片流，没有收到明显性能投诉。回头看，当初把它放在适配第一位是个正确的决定，所有跨端开发的体系和规矩，都是从这张小小的网格里长出来的。