企业官网建设流程全解析

最近在 OpenHarmony 设备上用 Flutter 做商城类应用，把分类导航模块从零到一完整落地了。所谓分类导航模块，就是用户在商城 App 里进入“分类”Tab 后看到的那个页面：左边是一级分类列表，右边是商品陈列，顶部有搜索入口，部分版本还带城市定位、购物车角标。模块看起来不大，但牵扯到数据结构设计、列表联动、状态同步、跨端适配和性能优化，信息量并不小。这篇文章把我实际操作中的方案选型、实现细节、踩过的坑都摊开讲，给准备在 OpenHarmony 生态里玩 Flutter 的朋友做参考。

1. 项目背景与方案选型

1.1 OpenHarmony + Flutter 的组合价值

先说结论：这套组合的核心价值是用一套 Dart 代码同时覆盖 OpenHarmony 设备和其他移动平台，不需要为每个系统各写一套 UI。OpenHarmony 作为开源操作系统底座，近几年在带屏设备、平板和智能硬件上出现得越来越多，而 Flutter 的优势是渲染一致性和开发效率。两者组合起来，相当于把同一套家具搬到不同户型的房子，墙面和尺寸不一样，但内部设计和摆放逻辑可以保持一致。

在做分类导航模块之前，我先在一个带屏设备上跑了一个最基本的 Flutter Hello World，确认渲染链路是通的。实际体验下来，普通列表页面、图片加载、基础动画都能稳定运行。但要注意，不是所有 Flutter 插件都能在 OpenHarmony 上直接使用。官方维护的常用插件大多有对应适配，但像定位、蓝牙、传感器这类依赖系统能力的能力，需要确认有没有 OpenHarmony 实现，如果没有，就得用平台通道自己封装。

所以我的建议是：不要一上来就把整个商城 App 都迁过去，而是先挑一两个功能闭环、交互典型、数据依赖不复杂的模块做验证。分类导航模块恰好符合这些条件。

1.2 为什么选“商城分类导航”作为实战切入点

分类导航是商城信息架构的核心入口。用户带着明确目的进商城时，大概率会先来这里找品类；用户漫无目的逛的时候，也依赖分类导航做引导。这个页面一旦体验不好，直接影响的是整条转化链路。

从技术角度看，分类导航模块覆盖了很多典型需求：

• 多级分类数据结构设计。
• 左侧一级分类与右侧内容的联动切换。
• 商品列表的网格化展示。
• 搜索入口和结果过滤。
• 状态在多个组件之间同步。

这些需求在 Flutter 里都有相对成熟的套路，放到 OpenHarmony 上做又会多一层适配问题。比如列表滚动帧率、图片解码内存、点击响应延迟，都需要在真机上实测。拿这个模块练手，既能验证跨端能力，又能沉淀一套可以复用的组件代码，后续再做订单、购物车、个人中心这些页面，路子就清晰了。

相反，如果第一个模块就选直播、AR 试穿或者复杂支付，大概率会被系统能力和三方 SDK 兼容性卡住，到最后很难分清是 Flutter 框架的问题，还是 OpenHarmony 系统能力的问题。先做分类导航，是成本和收益最平衡的选择。

2. 环境准备与工程搭建

2.1 开发环境与工具链

在实际动手之前，先要把环境理清楚。OpenHarmony 上的 Flutter 开发，不是装了官方标准 Flutter SDK 就能直接跑，需要安装带有 OpenHarmony 平台支持的 Flutter SDK 分支，同时保证 Dart SDK 版本和 IDE 版本对齐。我这里用到的是基于某个稳定 Flutter 版本做的 OpenHarmony 适配分支，具体版本号不展开，因为适配分支更新比较快，用的时候以官方文档标注的版本为准。

环境准备大致分成四步：

1. 安装带 OpenHarmony 支持的 Flutter SDK，并配置PATH环境变量。
2. 安装 OpenHarmony SDK 和配套 IDE，在 IDE 里配置 SDK 路径。
3. 创建 Flutter 工程，在工程中启用 OpenHarmony 作为目标平台。
4. 连接带屏设备或启动模拟器，配置调试签名，保证应用能正常安装。

这里有一个容易踩的坑：OpenHarmony SDK 和 IDE 版本必须匹配。我一开始用的是较新的 IDE 配旧版 SDK，应用能编译但安装到设备上总是失败，最后查了半天发现是 SDK 版本不兼容。建议安装前先看下官方兼容矩阵，能省很多时间。

我自己的调试顺序是先模拟器后真机。模拟器适合验证 UI 布局和交互逻辑，但帧率、内存占用、图片加载速度这些性能指标，模拟器参考价值有限，必须真机跑一遍。尤其是列表快速滑动时的表现，模拟器和真机的差异很明显。

2.2 工程结构与依赖配置

工程创建好之后，我先把目录结构定了下来。分类导航模块虽然不算大，但如果所有代码都堆在 main.dart 里，后面扩展筛选、排序、品牌列表会很痛苦。我目前采用的目录结构是：

lib/ main.dart models/ category.dart product.dart pages/ category_page.dart search_page.dart widgets/ category_left_list.dart product_grid.dart search_bar.dart state/ category_store.dart assets/ mock/ category_data.json

models 放数据模型，state 放状态管理，widgets 放可复用组件，pages 放页面级代码。这样分层的好处是，后续如果要把 mock 数据换成后端接口，只需要改 state 层的数据加载逻辑，UI 层完全不用动。

数据先用本地 JSON 文件模拟，这是做这类页面最高效的方式。先把 UI 和交互跑通，再接入真实接口，不要把第一版就绑死在网络请求上。

pubspec.yaml里的依赖也很简单：

name: mall_category_module description: OpenHarmony Flutter category navigation module. publish_to: 'none' version: 1.0.0+1 environment: sdk: '>=3.0.0 <4.0.0' dependencies: flutter: sdk: flutter provider: 6.1.2 flutter: uses-material-design: true assets: - assets/mock/

状态管理我只用了 provider，没有再引额外的大框架。分类导航模块的状态不算复杂，用一个ChangeNotifier完全够用。不要为了炫技把 Riverpod、Bloc 都引进来，在 OpenHarmony 上要额外考虑包体积，能轻则轻。

3. 分类导航模块的数据设计与状态管理

3.1 数据模型设计

商城分类数据通常有两种组织方式：一种是平铺列表，用 parentId 维护层级；另一种是嵌套结构，父分类直接包含子分类或商品。分类导航页的第一版，我推荐用嵌套结构，因为页面展示逻辑非常直接。

我现在用的数据模型是这样的：

class Category { final String id; final String name; final String icon; final List<Product> productList; Category({ required this.id, required this.name, required this.icon, this.productList = const [], }); factory Category.fromJson(Map<String, dynamic> json) { return Category( id: json['id'].toString(), name: json['name'], icon: json['icon'] ?? '', productList: (json['products'] as List? ?? []) .map((e) => Product.fromJson(e)) .toList(), ); } } class Product { final String id; final String title; final String image; final double price; Product({ required this.id, required this.title, required this.image, required this.price, }); factory Product.fromJson(Map<String, dynamic> json) { return Product( id: json['id'].toString(), title: json['title'], image: json['image'], price: (json['price'] as num).toDouble(), ); } }

id 字段必须保证全局唯一。我在做左右列表定位时踩过一次坑：两个分类的商品 id 重复，导致 Flutter 在 diff 复用组件时出现错乱，列表滚动后高亮项和内容对不上。后来所有 item 都加了ValueKey，并且保证 id 唯一，问题才消失。这是很容易忽略的细节，尤其是用 mock 数据时，随手复制 JSON 很容易搞出重复 id。

categories 的 JSON 结构大概是：

[ { "id": "1", "name": "手机数码", "icon": "assets/images/phone.png", "products": [ {"id": "1001", "title": "智能手机", "image": "assets/images/p1.png", "price": 2999}, {"id": "1002", "title": "蓝牙耳机", "image": "assets/images/p2.png", "price": 399} ] } ]

3.2 状态管理与数据流

分类导航模块里需要共享的状态主要有四个：

• 当前选中的一级分类 id。
• 分类数据列表。
• 搜索关键词。
• 右侧列表当前的滚动位置对应的分类 id。

我统一放在CategoryStore里管理。

class CategoryStore extends ChangeNotifier { List<Category> _categories = []; String _selectedCategoryId = ''; String _keyword = ''; String _currentSectionCategoryId = ''; List<Category> get categories => List.unmodifiable(_categories); String get selectedCategoryId => _selectedCategoryId; String get keyword => _keyword; String get currentSectionCategoryId => _currentSectionCategoryId; void loadCategories(List<Category> data) { _categories = data; if (_categories.isNotEmpty) { _selectedCategoryId = _categories.first.id; _currentSectionCategoryId = _selectedCategoryId; } notifyListeners(); } void selectCategory(String id) { _selectedCategoryId = id; _currentSectionCategoryId = id; notifyListeners(); } void updateKeyword(String keyword) { _keyword = keyword; notifyListeners(); } void updateCurrentSection(String id) { if (_currentSectionCategoryId == id) return; _currentSectionCategoryId = id; notifyListeners(); } List<Product> get visibleProducts { if (_categories.isEmpty) return []; final category = _categories.firstWhere( (c) => c.id == _selectedCategoryId, orElse: () => _categories.first, ); if (_keyword.isEmpty) return category.productList; return category.productList .where((p) => p.title.contains(_keyword)) .toList(); } }

为什么选择ChangeNotifier而不是在每个页面里用setState？因为左侧列表、右侧商品区域、顶部搜索框都会读取同一份状态，如果用setState，就得在每个组件里重复传参，还要手动处理组件间同步，很容易漏掉某个更新点。用provider做依赖注入，页面里直接context.watch<CategoryStore>()，哪些组件需要刷新就只刷新哪些组件，数据流更清晰。

这里有个经验：不要在build方法里频繁创建新的CategoryStore实例，也不要把整个 store 都暴露给所有组件监听。比如搜索框只需要读取keyword，左侧列表只需要读取selectedCategoryId，右侧列表需要读取visibleProducts和currentSectionCategoryId。如果整个 store 被 watch，任何字段变化都会导致所有组件 rebuild，白白浪费性能。后面我会用Selector做局部监听。

4. UI 骨架与导航交互实现

4.1 整体布局拆解

分类导航页的整体结构是一个典型的左侧导航加右侧内容布局。我用的 Flutter 代码骨架是这样：

@override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: const Text('分类'), actions: [ IconButton( icon: const Icon(Icons.search), onPressed: () { Navigator.push( context, MaterialPageRoute(builder: (_) => const SearchPage()), ); }, ) ], ), body: Column( children: [ Expanded( child: Row( crossAxisAlignment: CrossAxisAlignment.start, children: const [ SizedBox(width: 88, child: LeftCategoryList()), Expanded(child: RightProductList()), ], ), ), ], ), ); }

左侧分类栏宽度我一开始写死成了 88 逻辑像素。在手机竖屏上这个宽度刚好能放下四个字以内的分类名，但到了平板或者横屏设备上就显得太窄，商品区域被挤压。后来改成根据屏幕宽度动态计算：左侧宽度是screenWidth * 0.22，但最小 80、最大 120。这种按比例适配的方法在 OpenHarmony 的多种屏幕尺寸上更稳。

右侧商品列表不要直接放一个GridView，因为商品需要按分类区块展示。我采用的方案是右侧用一个ListView.builder，每一个 item 对应一个分类区块，区块内部再用GridView.count展示商品。GridView.count需要设置shrinkWrap: true和physics: NeverScrollableScrollPhysics()，不然会出现垂直滚动冲突。

4.2 左侧分类栏与右侧商品列表联动

这里的联动有两层意思：第一层是点击左侧分类，右侧切换到对应分类的商品；第二层是右侧滚动时，左侧高亮项跟随变化。我先讲最常用的基础版，再讲进阶版。

基础版：左侧列表点击后，直接切 store 里的selectedCategoryId，右侧的visibleProducts随之变化，右侧列表回到顶部。

class LeftCategoryList extends StatelessWidget { const LeftCategoryList({super.key}); @override Widget build(BuildContext context) { final store = context.watch<CategoryStore>(); final categories = store.categories; return ListView.builder( itemCount: categories.length, itemBuilder: (context, index) { final category = categories[index]; final selected = category.id == store.selectedCategoryId; return InkWell( key: ValueKey(category.id), onTap: () { store.selectCategory(category.id); }, child: Container( height: 56, color: selected ? Colors.white : Colors.transparent, alignment: Alignment.center, child: Text( category.name, style: TextStyle( fontWeight: selected ? FontWeight.w600 : FontWeight.normal, color: selected ? Colors.black : Colors.grey[700], ), ), ), ); }, ); } }

右侧商品列表直接消费visibleProducts，注意右侧列表在分类切换时要滚回顶部。我是在store.selectCategory之后，用右侧列表的ScrollController执行jumpTo(0)。

进阶版：右侧不是单个分类的商品，而是把所有分类的商品都聚合在一个长列表里，左侧点击后右侧滚动到对应分类位置，右侧滚动时左侧高亮跟随。这种交互在头部和垂直电商 App 里很常见，视觉上更像“逛全场”。

实现的关键是给每个分类区块一个GlobalKey：

final Map<String, GlobalKey> _blockKeys = {}; GlobalKey _keyForCategory(String categoryId) { return _blockKeys.putIfAbsent(categoryId, () => GlobalKey()); }

右侧列表 item 构建时，用这个 key 包裹每个分类区块。点击左侧分类后：

void _scrollToCategory(String categoryId) { final key = _blockKeys[categoryId]; final context = key?.currentContext; if (context == null) return; Scrollable.ensureVisible( context, duration: const Duration(milliseconds: 300), curve: Curves.easeInOut, alignment: 0, ); }

alignment: 0很重要，它保证目标区块滚动到视口顶部，而不是只要“可见就行”。我第一次没加这个参数，点击后列表只把目标区块露出一点点，体验很怪。

右侧滚动监听逻辑则是反过来：在右侧列表滚动时，遍历_blockKeys，找到当前距离视口顶部最近的区块，更新左侧高亮。我用的方式是每个区块在构建时通过RenderBox计算它到屏幕顶部的距离，取最小且大于-itemHeight/2的那个作为当前区块。

这个进阶版不建议在商品数量非常大的时候用，因为GlobalKey和ensureVisible在列表项特别多时会有性能损耗。如果每个一级分类下面有成百上千个商品，还是老老实实用基础版，每次只渲染一个分类的商品。

4.3 搜索、定位与其他辅助能力

分类导航页顶部除了标题，通常还放搜索框。我这里的处理不是直接在页面上放一个TextField，而是用一个看起来像搜索框的按钮，点击后进入独立搜索页。这样做的好处是不需要在分类页维护搜索输入状态，搜索页可以专门负责键盘、历史记录、热门搜索等逻辑。

在 OpenHarmony 上做搜索页时，需要注意软键盘弹起后的布局问题。我用的是Scaffold的resizeToAvoidBottomInset默认行为，搜索框固定在顶部，搜索历史和结果列表在键盘弹起时自动避让，实测大部分输入法都能正常处理。

城市定位这个模块我放在了分类页左侧栏顶部，显示当前城市名称，点击后进入城市选择页。这里如果要做自动定位，需要获取定位权限，在 OpenHarmony 上涉及权限声明和平台通道。我第一版没有接真实定位，而是先用 mock 城市，把页面流程跑通，后续再通过MethodChannel调用系统定位能力。

还有一个容易忽略的细节：购物车角标。分类页的 AppBar 上往往带一个购物车图标和角标数字。这个数字需要和全局购物车状态同步，所以我把它也放进了 provider 的状态树中，点击购物车图标时跳转购物车页。

5. 关键问题排查与性能优化

5.1 常见问题速查表

在 OpenHarmony + Flutter 的组合下做分类导航，遇到的问题很有规律。我整理了一个速查表，基本覆盖了我实际踩过的坑：

表格里的每一条都是我在真机调试时实际遇到过的。其中“切分类时整个页面刷新卡顿”最典型，刚开始整个页面context.watch<CategoryStore>()，一改侧边栏，搜索框和左侧列表全部重建。后来把左侧列表改成只监听selectedCategoryId，右侧商品区域只监听visibleProducts，刷新范围一下小了很多，帧率明显上来。

5.2 性能优化与真机调试心得

分类导航模块的性能瓶颈主要集中在三处：列表重建、图片解码、滚动联动计算。

列表重建方面，我的做法是尽量使用const构造函数，让 Flutter 在 rebuild 时跳过没有变化的组件。比如商品 grid item 的外层容器、分类名 text 的 style，能写成 const 就写成 const，减少不必要的 diff 计算。

图片解码是我在这类页面里遇到的最大问题。商城商品图往往很大，Flutter 在加载图片时会先把整张图解码到内存，再做绘制。分类导航页一屏可能显示十几个商品缩略图，如果原图都是几 MB 的高清图，内存压力非常大。我整理图库时统一生成了 400x400 的缩略图，并在Image.network上设置了cacheWidth: 400，让 Flutter 解码时直接按目标宽度解码，内存占用降了差不多一半。换成本地资源图片时，用ResizeImage做同样处理。

滚动联动计算的优化，主要是避免在滚动监听里做重复工作。每次滚动都遍历所有分类区块的RenderBox，在分类数量超过 20 个时会有可感知的 CPU 开销。我的优化是缩小遍历范围：只在当前高亮分类的前后 3 个区块里找最近的区块，其他区块直接跳过。实测在分类数量 30 个左右的页面，流畅度提升很明显。

真机调试还有一个容易忽略的点：OpenHarmony 不同设备的分辨率差异很大。同样一个childAspectRatio: 0.8的商品网格，在手机上看刚好，在平板上商品图会被拉得很大。所以我没有把商品缩略图的宽高比写死，而是通过MediaQuery拿到屏幕宽度，计算每行商品数量，再推算出合适的childAspectRatio。这样在手机和平板上都能自动适配。

性能工具方面，我会在跑真机时抓一段帧率数据，重点看滚动时有没有掉帧。如果发现掉帧，先看是不是图片解码卡了主线程，再看是不是列表项在滚动过程中被频繁重建。绝大多数分类页卡顿问题都能在这两步里找到原因。

6. 写在最后的几点工程习惯

这个分类导航模块做完之后，我沉淀了几条习惯，不一定适用于所有项目，但在 OpenHarmony + Flutter 的实战里确实帮我少走了不少弯路。

第一，动手写 UI 之前，先把数据结构画出来。分类导航这种页面，UI 只是表象，数据流才是核心。左侧列表、右侧商品、搜索词、当前高亮之间的依赖关系，画一张状态图比写十屏代码都管用。

第二，mock 数据一定要模拟真实后端字段。很多人图快，直接在代码里 new 一个Category，字段名和真实接口不一致，后面换接口时到处改代码。我从一开始就用 JSON 文件 +fromJson解析，后面接入真实接口时，只要改数据加载部分就行。

第三，所有尺寸和颜色不要散落在组件里。左侧栏宽度、商品网格列数、分类项高度、选中颜色，我都提成了常量文件。后面做深色模式或者适配折叠屏，只需要改常量，不用动组件逻辑。

第四，在 OpenHarmony 上做 Flutter，要先跑通最小闭环再堆功能。每个新能力都先在真机上验证能不能跑，比如图片缓存、滚动联动、键盘避让，真机没问题再往后做。模拟器上的流畅不能代表真实设备体验，这一点我吃过不少亏。

分类导航模块算不上很复杂的业务模块，但它把列表、状态、联动、适配、性能这些基本功都占全了。把它在 OpenHarmony 上完整跑通，后面再去做订单、购物车、个人中心这些页面，心里会踏实很多。如果最近你也在研究 OpenHarmony 上跑 Flutter，不妨从分类导航这个模块入手，你会很快摸清这套技术栈的脾气。