源码获取

如果你想一边对照文章一边实操，建议直接把示例工程拉到本地。项目 Git 地址：https://gitcode.com/HarmonyOS_Samples/CommonListFlows。

很多人第一次打开示例工程，手比脑子快。

目录还没看明白，就先点进页面源码；源码还没看懂，又开始改样式。结果最基础的一步反而没做对: 工程到底有没有正常跑起来，四个场景是不是都能完整走通。

这件事听着土，但真别跳过。

因为这个项目后面讲的多类型列表、Tab 吸顶、分组吸顶、二级联动，全部都建立在“你已经能把工程稳定跑起来”这件事上。第一步没站稳，后面再努力，心里也是虚的。

先搞清楚，这个工程到底在练什么

CommonListFlows 不是一个完整业务 App，它更像一本专门练 List 的习题册。

项目首页只做了一件事: 把 4 个常见列表流场景摆到你面前。

• 多类型列表项场景
• Tab 吸顶场景
• 分组吸顶场景
• 二级联动场景

这 4 页的价值不在于业务，而在于套路特别典型。你以后做资讯流、商城页、城市选择页、分类页，绕来绕去基本都逃不出这些结构。

如果你是刚碰 ArkUI 的小白，我建议别乱跳着学，就按首页顺序来。前面几页在给后面打地基，这个顺序不是随便摆的。

版本先别卡死，先确认环境能打通

仓库 README 里写的是 HarmonyOS 5.0.5 及以上。你这套教程标题统一带 HarmonyOS7，这个没问题，但理解上别走偏。

更准确的说法是: 文章按 HarmonyOS7 关键词来写，讲解按当前项目真实代码来拆。

也就是说，你现在最该确认的不是版本口号，而是这些东西有没有准备好:

• DevEco Studio 能正常打开 HarmonyOS 工程
• 本机可用 SDK 已经装好
• 模拟器或真机至少有一个能运行

只要这些打通，后面练 List、Navigation、Tabs、Scroller 这些能力就是顺的。

工程导入以后，先盯住这几个文件

别一进项目就从头翻到尾，那样效率很低。

这个工程真正该先看的，是 entry/src/main/ets 下面这几块:

• entryability/EntryAbility.ets：应用入口
• pages/Index.ets：首页目录
• pages/HomePage.ets：多类型列表
• pages/ManagerPage.ets：Tab 吸顶
• pages/CityList.ets：分组吸顶
• pages/CategoryPage.ets：二级联动

如果你以前写 Web 喜欢先找 main.ts，那到了 ArkUI 里，思路要稍微转一下。这里先抓 EntryAbility 和页面组件，效率会高很多。

为什么一启动就会进首页

入口代码其实很直白，关键就这一段:

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err) => {
      AppStorage.setOrCreate('uiContext', windowStage.getMainWindowSync().getUIContext())
      if (err.code) {
        return
      }
    })
  }
}

这里真正决定首屏的是 loadContent('pages/Index')。

你先把这句记牢: 程序起来以后，默认加载的是 Index 页面。

很多新手后面找不到页面入口，不是不会写页面，而是连“页面是从哪进来的”都没先确认。这一步看清楚，后面读项目会省很多劲。

首页其实就是一张目录页

Index.ets 没有复杂业务，它就是把你送进四个场景页。

@Entry
@Component
struct Index {
  @Provide('pageInfo') pageInfo: NavPathStack = new NavPathStack()

  build() {
    Navigation(this.pageInfo) {
      Column() {
        Button($r('app.string.multiple_types_list'))
          .onClick(() => this.pageInfo.pushPathByName('HomePage', null))

        Button($r('app.string.top_tab_list'))
          .onClick(() => this.pageInfo.pushPathByName('ManagerPage', null))

        Button($r('app.string.group_ceiling'))
          .onClick(() => this.pageInfo.pushPathByName('CityList', null))

        Button($r('app.string.secondary_linkage'))
          .onClick(() => this.pageInfo.pushPathByName('CategoryPage', null))
      }
    }
  }
}

你可以把它当成一个训练导航页。

这一页最值得你先看懂的，不是按钮长什么样，而是四个页面之间的进入关系。路径一旦顺了，后面每篇教程你都会轻松不少。

工程跑起来以后，别只看首页

很多人把首页打开，看到界面出来了，就默认工程没问题。

这个判断太早了。

更稳的做法是把四个入口都点一遍，至少确认下面这些点:

1. 多类型列表页能正常下拉、滑动和触底。
2. Tab 吸顶页顶部搜索区、内容 Tab、底部 Tab 都能切换。
3. 城市分组页标题能吸顶，右侧字母能点击跳转。
4. 二级联动页左边分类和右边内容能同步滚动。

只要这四步都通，后面你再去拆源码，心里就是有底的。

真正容易卡住的，不是代码，而是这几个小坑

1. 工程能打开，但运行不起来

这种情况十有八九不是页面写错了，而是 SDK、签名或者运行设备没配对。别一上来怀疑源码，先检查环境。

2. 页面能进，图片却没显示

这个项目依赖 resources/base/media 里的图片资源。导入不完整、资源没同步，都会让你误以为页面写坏了。

3. 首页能点，目标页不跳

先别急着改逻辑，先核对 pushPathByName() 里的页面名有没有和实际页面保持一致。路由名写错，是最常见的低级坑。

4. 模拟器和真机感觉不一样

列表滚动、吸顶、嵌套滚动这种交互，对运行环境本来就敏感。我的建议很直接: 能上真机就尽量上真机。

这一整套文章，最推荐的阅读顺序

如果你真是从零开始，别一上来就啃二级联动。那页知识点最密，容易把人看烦。

更稳的顺序是这样:

• 先把工程跑通
• 再看首页入口和跳转关系
• 再学 HomePage 的多类型列表骨架
• 接着看刷新、加载更多和分组吸顶
• 最后再攻 Tab 联动和左右联动

照着这个顺序走，难度会平很多。

最后一句

学这类示例工程，最怕两件事: 还没跑起来就急着改，页面能动了又不知道为什么能动。

这一篇的任务其实很朴素，就是先把项目跑通，把四个场景全部看全。别嫌这一步基础，它反而最值钱。基础没站稳，后面每一页你都会读得心里发虚；基础一旦站稳，后面那些看着复杂的页面，真的就没那么吓人了。