做 HarmonyOS 应用的时候，最容易卡住的地方不是某一个组件不会写，而是页面一多之后，状态、数据、跳转和视觉风格开始互相影响。
中式美食这个项目也是这样。一开始只是想把首页推荐、菜谱详情这些页面做好，后面慢慢会遇到很多很实际的问题：
- 首页卡片怎么组织数据，才能方便后面复用？
- 详情页的收藏状态，怎么和收藏页保持一致？
- 搜索、分类、排行、食材这些入口，怎么让用户找到菜？
- 深色模式、主题色、底部 Tab、二级页返回，怎么不互相打架？
- 视频拆菜、自定义菜谱、笔记和我的厨房，怎么形成一个真正能长期使用的闭环？
所以这篇不是简单堆链接，而是把这一组文章按工程路线重新整理一下。你可以把它当成中式美食的 HarmonyOS 实战地图：想补哪一块，就从哪一块看。
本文验证环境
| 项目 | 版本或范围 |
|---|---|
| 开发工具 | DevEco Studio 6.0.0 Release |
| HarmonyOS SDK | API 20 |
| 语言与框架 | ArkTS 6.0 / ArkUI V2 |
| 工程模型 | Stage 模型 |
| 整理对象 | 中式美食 HarmonyOS 应用 |
| 主要关注 | 页面体验、本地仓储、状态同步、路由闭环、系列内链 |
这张表不是摆样子，主要是为了让读者知道：下面这些页面和代码思路，是围绕 ArkUI V2 和 Stage 模型下的真实业务应用整理出来的，不是脱离项目的概念整理。
先看这条主线
如果你是第一次看这个系列，建议按下面的顺序走：
| 顺序 | 模块 | 解决的问题 | 适合关注 |
|---|---|---|---|
| 01 | 首页推荐流 | 应用第一屏怎么组织内容和卡片 | 数据建模、推荐卡片、首屏体验 |
| 02 | 菜品详情页 | 一道菜的信息怎么讲清楚 | 详情结构、步骤、营养、收藏状态 |
| 03 | 搜索页 | 用户输入关键词后怎么给出靠谱结果 | 输入态、搜索历史、相关度排序 |
| 04 | 收藏状态 | 收藏按钮不是只改图标，还要有数据闭环 | ArkTS 持久化、页面同步 |
| 05 | 省市菜系页 | 地域和菜系如何做筛选联动 | 筛选模型、详情跳转、空态 |
| 06 | 视频拆菜页 | 从视频内容里提取可编辑菜谱 | 字幕因子、人工校对、草稿保存 |
| 07 | 深色模式 | 主题服务怎么影响全局页面 | ThemeService、色板、系统配置 |
| 08 | 自定义菜谱 | 用户自己创建的菜怎么进系统 | 表单解析、仓储、搜索合流 |
| 09 | 笔记体系 | 做菜笔记怎么回写到详情和我的厨房 | NoteRepository、读写连续性 |
| 10 | 排行榜页 | 排行不是摆数字，而是帮助用户决策 | 综合评分、人气切换、静态视觉 |
| 11 | 食材大全页 | 食材入口怎么做到可扫、可查、可跳转 | 分类联动、网格高度、检索入口 |
| 12 | 深夜食堂页 | 场景化入口怎么做得不乱 | 场景筛选、双列网格、夜宵入口 |
| 13 | 起源典故页 | 内容型页面怎么和菜谱详情连接 | 故事数据、卡片叙事、详情跳转 |
| 14 | 列表页筛选 | 关键词、排序、清空默认态如何协作 | 筛选体验、状态复位、列表稳定 |
| 15 | 我的厨房页 | 用户资产怎么集中展示 | 收藏统计、菜谱草稿、课堂入口 |
这条线看下来，基本就能看到一个业务应用从"页面能显示"，到"状态能持续"，再到"用户能反复回来用"的过程。
已发布文章入口
01. 首页推荐流：先把第一屏搭稳
HarmonyOS 实战｜中式美食首页推荐流：数据模型、推荐卡片与发布准备整理
这一篇适合先看。首页是整个应用的门面，推荐卡片、分类入口、今日推荐这些内容如果一开始没有拆清楚，后面详情、收藏、搜索都会跟着别扭。
我更推荐关注里面的数据组织方式：不要把 UI 写成一坨固定布局，而是先把菜品、推荐位、入口状态整理成清楚的模型，再让页面去渲染。
02. 菜品详情页：把一道菜讲完整
HarmonyOS 实战｜中式美食菜品详情页：食材、步骤、营养与收藏状态设计
详情页是典型的"看起来简单，做起来容易散"的页面。标题、图片、食材、步骤、营养信息、收藏按钮，每一块都不复杂，但合在一起就很考验层级。
这一篇的重点是：详情页不能只是展示字段，它要帮用户快速判断"这道菜我能不能做、值不值得收藏、下一步点哪里"。
03. 搜索页：输入态和结果排序要一起设计
HarmonyOS 实战｜中式美食搜索页：ArkUI V2 输入态、搜索历史与相关度排序
搜索页最容易被写成一个输入框加列表，但真正好用的搜索页，关键在搜索前、搜索中、搜索后这几个状态。
这里重点看三件事：输入态怎么反馈、搜索历史怎么存、相关度排序怎么让结果看起来"真的懂用户在找什么"。
04. 收藏状态：别让收藏只停在按钮动画
HarmonyOS 实战｜中式美食收藏状态：ArkTS 持久化封装、详情同步与收藏页刷新
收藏功能不是点一下变红这么简单。真正麻烦的是：详情页收藏了，收藏页要能看到；收藏页取消了，详情页回来也要同步；重启应用之后状态还不能丢。
这一篇适合关注 ArkTS 持久化封装，以及页面之间如何围绕同一份状态协作。
05. 省市菜系页：筛选联动要讲得通
HarmonyOS 实战｜中式美食省市菜系页：地域数据建模、筛选联动与详情跳转闭环
省市和菜系这种页面，很容易做成"按钮很多但用户不知道点完会发生什么"。所以这里的重点是筛选模型：省份、城市、菜系、结果列表之间要有稳定关系。
如果你在做内容型工具、生活服务类应用，这一篇的联动思路可以直接借鉴。
06. 视频拆菜页：把识别结果变成可编辑草稿
HarmonyOS 实战｜中式美食视频拆菜页：字幕因子提取、人工校对与自定义菜谱保存
视频拆菜这块比较有意思，因为它不是单纯展示页面，而是从识别结果进入人工确认，再进入菜谱草稿。
工程上最关键的是：识别结果不能直接当最终数据，要留出"可确认、可修改、可回看"的空间。这样用户才会觉得功能可靠。
07. 深色模式：主题服务要能照顾多页面
HarmonyOS 实战｜中式美食深色模式：ThemeService、全局色板与系统配置同步
深色模式不是把背景改黑就结束。中式美食这种有图片、有卡片、有标签、有底部导航的应用，如果色板没有统一，页面会很快变乱。
这一篇重点看 ThemeService 的思路：把颜色、状态和系统配置放在一个统一入口里，不要每个页面自己临时判断。
08. 自定义菜谱：用户内容也要进入全站能力
HarmonyOS 实战｜中式美食自定义菜谱：表单解析、UserDishRepository 与全站检索合流
用户自己创建的菜谱，如果只能停在一个孤立页面里，价值会很弱。更好的做法是让它进入搜索、收藏、详情、我的厨房这些全站能力。
这一篇适合看 Repository 的分层方式，以及用户数据怎么和内置数据合流。
09. 笔记体系：让用户回来时还能接着做
HarmonyOS 实战｜中式美食笔记体系：NoteRepository、详情页回写与我的厨房连续性
笔记功能的价值不在"能写字"，而在它能不能帮用户下次继续做。比如上次做到哪一步、有哪些调整、这道菜有没有踩坑。
这篇文章里可以重点看 NoteRepository 怎么把详情页和我的厨房串起来。
10. 排行榜页：排序规则要能帮助选择
HarmonyOS 实战｜中式美食排行榜页：综合评分、人气切换与首屏静态视觉兜底
排行榜页不是越热闹越好，核心是帮助用户做选择。综合评分、人气、推荐理由这些信息要有主次，不然用户看完还是不知道点哪一个。
这一篇适合关注首屏稳定性和排序切换的体验。
11. 食材大全页：检索入口要服务真实找菜场景
HarmonyOS 实战｜中式美食食材大全页：分类联动、网格稳定高度与食材检索入口设计
很多人打开美食应用不是先想好菜名，而是先看手里有什么食材。所以食材大全页更像一个反向找菜入口。
这一篇重点看分类联动、网格高度和检索入口，尤其适合做内容库、商品库、资料库类页面时参考。
12. 深夜食堂页：场景化页面要克制
HarmonyOS 实战｜中式美食深夜食堂页：场景筛选、双列网格与夜宵入口体验
深夜食堂这种页面很容易做得太氛围化，但真正有用的还是筛选和入口。用户不是来看海报的，是想快速找到"现在适合吃什么"。
这一篇可以看场景筛选和双列网格怎么配合。
13. 起源典故页：内容页也要能回到业务路径
HarmonyOS 实战｜中式美食起源典故页：故事数据筛选、卡片叙事与详情页跳转
起源典故页偏内容，但它不能和菜谱体系断开。故事看完之后，用户应该能继续去详情页、收藏页或相关菜系。
这一篇适合关注内容卡片和业务跳转之间的关系。
14. 列表页筛选：清空默认态很重要
HarmonyOS 实战｜中式美食列表页筛选体验：关键词命中、排序切换与清空回到默认态
列表页筛选最常见的问题是：筛选条件越来越多，用户不知道当前列表为什么是这样。
所以清空默认态、排序切换、关键词命中提示都很重要。它们不是小细节，而是列表页是否可信的关键。
15. 我的厨房页：把用户资产收回来
HarmonyOS 实战｜中式美食我的厨房页：收藏笔记统计、菜谱草稿入口与烹饪课堂展开态
我的厨房页像一个用户资产中心。收藏、笔记、自定义菜谱、视频拆菜草稿、课堂入口，都应该能在这里找到。
这一篇重点看"用户做过的事"怎么变成页面里的持续价值，而不是散落在各个功能里。
这些文章背后的工程分层
如果把中式美食拆成工程模块，大概可以这样理解：
ts
type AppModule =
| 'home'
| 'detail'
| 'search'
| 'favorite'
| 'region'
| 'video'
| 'theme'
| 'userDish'
| 'note'
| 'rank'
| 'ingredient'
| 'scene'
| 'story'
| 'profile';
interface SeriesRoute {
module: AppModule;
page: string;
repository?: string;
userValue: string;
}
const zhongShiMeiShiRoutes: SeriesRoute[] = [
{
module: 'home',
page: 'HomePage',
userValue: '打开应用后先看到今日推荐、分类入口和关键菜品',
},
{
module: 'detail',
page: 'DishDetailPage',
repository: 'FavoriteRepository',
userValue: '看清楚一道菜的食材、步骤、营养和收藏状态',
},
{
module: 'search',
page: 'SearchPage',
repository: 'SearchHistoryRepository',
userValue: '通过关键词、历史记录和相关度排序快速找到菜',
},
{
module: 'profile',
page: 'ProfileKitchenPage',
repository: 'NoteRepository / UserDishRepository',
userValue: '把收藏、笔记、草稿和课堂入口集中管理',
},
];我自己整理下来，一个 HarmonyOS 业务应用要长期维护，最好不要只按页面切。页面只是用户看到的结果，背后还要按这几层去想：
- UI 层：页面布局、卡片、列表、空态、底部导航。
- 状态层：收藏、搜索条件、主题、当前 Tab、二级页栈。
- 仓储层：Preferences、本地列表、用户菜谱、笔记、最近浏览。
- 路由层：首页到详情、分类到列表、我的厨房到草稿。
- 内容层：菜品、食材、故事、场景、视频拆菜结果。
页面写得漂亮只能解决第一眼的问题。真正让用户觉得这个应用能用，是状态和数据能不能接得住。
我最建议优先看的 4 篇
如果你时间不多，可以先看这 4 篇：
| 优先级 | 文章 | 为什么先看 |
|---|---|---|
| 1 | 搜索页 | 能看到输入态、历史记录、排序这些真实业务状态 |
| 2 | 收藏状态 | 能看到本地持久化和多页面同步 |
| 3 | 视频拆菜页 | 能看到"识别结果到人工确认"的产品闭环 |
| 4 | 我的厨房页 | 能看到用户资产如何收束到一个入口 |
这 4 篇基本覆盖了 ArkUI 页面、状态管理、本地数据和用户路径。看完再回头看首页、详情、排行榜、食材、故事页，会更容易理解为什么前面要这样拆。
做项目时最容易踩的坑
1. 页面先写完，数据模型后来补
这种写法前期很快，后期会越来越难改。比如首页推荐卡片、详情页、收藏页都要用到菜品数据，如果一开始字段随手写，后面每个页面都要补判断。
更稳的方式是先定一个核心模型，再让页面按需要取字段。
ts
interface Dish {
id: string;
name: string;
cover: ResourceStr;
region: string;
tags: string[];
score: number;
ingredients: string[];
steps: string[];
}这个模型不一定一开始就完美，但至少要让首页、详情、搜索、收藏都能围绕同一份数据说话。
2. 收藏、笔记、自定义菜谱各存各的
这会让"我的厨房"很难做。用户明明收藏过、写过笔记、保存过草稿，但页面上却找不到完整记录。
所以中式美食后面一直在做一件事：把用户行为收回来。收藏是收藏，笔记是笔记，自定义菜谱是自定义菜谱，但它们最后都要能回到我的厨房。
3. 搜索只搜菜名
美食应用里，用户不一定知道菜名。他可能只知道"鸡肉""夜宵""川菜""低脂"这些线索。
所以搜索页不能只匹配 name，还要考虑食材、标签、菜系、场景。哪怕第一版排序规则很简单，也比只搜标题强很多。
4. 主题服务分散在每个页面
每个页面自己判断深色模式，短期能跑，长期一定乱。卡片背景、文字色、边框、标签、底部 Tab 都会有细微差异。
更好的做法是把主题能力收敛成统一服务，让页面只关心"我要什么语义颜色"，不要每个页面都写一套判断。
后续怎么读更有效
如果你是为了做自己的 HarmonyOS 项目，不建议只收藏链接。更好的方式是每看一篇，就问自己三个问题：
- 这个页面解决了什么用户问题？
- 这个页面背后有没有需要持久化的数据？
- 这个页面会不会影响别的入口，比如搜索、收藏、我的厨房？
只要这三个问题能想清楚，页面就不容易写散。
小结
中式美食这个系列的价值，不在于某一个页面有多复杂，而在于它把一个真实应用拆成了很多可以复用的工程问题：推荐流、详情页、搜索、收藏、主题、笔记、视频拆菜、我的厨房。
这些问题在别的 HarmonyOS 应用里也会出现，只是内容从菜谱换成资料、商品、课程、笔记或工具而已。
如果你也在做 ArkUI 应用，可以先从搜索、收藏、本地仓储和我的厨房这几块看起。它们最能体现一个应用是不是只做了界面，还是已经开始形成自己的使用闭环。