HarmonyOS7嵌套吸附页面实战：多层滚动容器下的吸附协作

前言

一旦页面里出现嵌套滚动，很多细节都会开始复杂起来。外层容器怎么滚、内层卡片怎么吸附、手势冲突怎么避免，这些都不是纸面上看 API 能解决的。这个案例很有实践价值。 我自己看这类案例时，通常不会先背属性，而是先判断它到底在解决什么页面问题。这个习惯很有用，因为一旦知道“它是给谁用、解决什么场景”，后面的代码就不容易看散。

嵌套吸附页面 这一页真正有意思的地方，不是把效果堆出来，而是它把 多层滚动容器下的吸附协作 这件事说得比较落地。这篇我会按“先看到什么、再点什么、最后哪里变化”的顺序去讲，适合第一次复刻这个案例时照着走。

这类写法尤其适合落在 首页复合信息流、嵌套推荐区、多模块大屏页 这些场景里，所以我下面不会只讲“组件怎么写”，而是更关心“放进页面之后为什么这样组织”。

先把这页在干什么看明白

我建议先不要着急顺着源码往下滚。先回答一个更实际的问题：嵌套吸附页面 这个页面，用户一进来第一眼会看到什么，接着又会去操作哪里。结构感一旦建立起来，后面的代码就不容易看散。

页面里额外定义的数据模型包括：Item。如果后面准备接接口，我更建议把这些类型继续收口成更直白的业务命名。

这篇我会按“先看到什么、再点什么、最后哪里变化”的顺序去讲，适合第一次复刻这个案例时照着走。

嵌套吸附最怕的不是代码多，而是滚动职责混乱

这页的isShow仍然只是展示开关，真正有价值的是外层纵向Scroll和内层横向Scroll的协作。外层负责分区浏览，内层负责每个分区里的卡片选择。

我会按两层结构来读：

• 外层分区：推荐、热门、最新这些 section 决定用户纵向浏览的模块边界。
• 内层卡片：每个 section 里的items决定横向卡片流，适合展示同一分组下的多个候选内容。
• 吸附职责分离：外层负责模块停靠，内层负责卡片聚焦，不要让两层抢同一个手势目标。

真实首页、推荐页、大屏模块页经常会遇到这种结构。这里最值得学的，是先把滚动层级分清楚。

哪几个函数最值得先看

读函数别贪多。对 嵌套吸附页面 这种页面来说，真正有阅读价值的往往是那几段会改状态、触发交互或者推动页面切换的逻辑。

• 这个案例没有太多额外方法，核心价值主要集中在页面结构和组件组合方式。

我自己读这类方法时，通常只抓一条线：谁触发、谁被改、页面哪里立刻有反馈。把这三件事连起来，很多交互代码一下就顺了。

第一段关键代码：页面是怎么被带起来的

这一段建议慢一点看。它通常决定了页面初始状态，也决定了后续哪些区域会跟着刷新。

@StateisShow:boolean=truebuild(){Column(){if(this.isShow){Column(){Text('嵌套吸附').fontSize(18).fontWeight(FontWeight.Bold).fontColor('#8E44AD').margin({bottom:4})Text('外层垂直 Scroll START 吸附 + 内层水平 Scroll CENTER 吸附').fontSize(12).fontColor(DEMO_SUBTEXT_COLOR).margin({bottom:12})}.width('100%').alignItems(HorizontalAlign.Start)Scroll(){Column(){ForEach([{label:'推荐',items:['#E91E63','#2196F3','#4CAF50','#FF9800']},{label:'热门',items:['#9C27B0','#00BCD4','#FF5722','#607D8B']},{label:'最新',items:['#795548','#CDDC39','#03A9F4','#FF6B6B']}],(section:ScrollsnapNestedLayoutItem,idx:number)=>{Column(){Text(section.labelasstring).fontSize(15).fontWeight(FontWeight.Bold).fontColor(DEMO_THEME_COLOR).margin({bottom:8,left:8})

这一段我通常不会一下翻过去，而是先确认下面这几个判断点：

• @State字段到底在控制显示、选择、跳转结果还是模式切换。
• 默认值是不是合理，页面一打开会不会就落在一个可理解的状态上。
• 字段命名能不能让后来的人一眼看懂用途，而不是还要翻半天 UI。

第二段关键代码：真正决定交互手感的地方

这段代码的重点是数据层级：外层section.label决定模块标题，内层section.items决定横向卡片。代码结构和页面结构一一对应，后面接真实推荐数据会比较自然。

/** * 嵌套吸附页面 */import{PRESET_COLORS,generateListItems,DEMO_BG_COLOR,DEMO_CARD_COLOR,DEMO_THEME_COLOR,DEMO_SUBTEXT_COLOR}from'./types'interfaceScrollsnapNestedLayoutItem{label:stringitems:string[]}@Entry@Componentstruct ScrollsnapNestedLayout{@StateisShow:boolean=truebuild(){Column(){if(this.isShow){Column(){Text('嵌套吸附').fontSize(18).fontWeight(FontWeight.Bold).fontColor('#8E44AD').margin({bottom:4})Text('外层垂直 Scroll START 吸附 + 内层水平 Scroll CENTER 吸附').fontSize(12).fontColor(DEMO_SUBTEXT_COLOR).margin({bottom:12})}

代码读到这里，我通常会顺手补三件事，不然后面很容易只看热闹：

1. 这个交互入口接收的到底是什么输入。
2. 输入进来之后，代码改了哪个状态，或者触发了哪次导航。
3. 变化发生后，用户最先感知到的反馈会落在哪个区域。

这三个问题串起来之后，这一页基本就不只是“看过”，而是真的读懂了。

把页面跑起来之后，建议你这样操作一遍

文章讲再多，都不如自己把页面点一遍。尤其是 嵌套吸附页面 这种带明显交互结果的页面，只看代码很难建立手感。

1. 先进入页面，确认首屏是不是把嵌套吸附页面的主题交代清楚。
2. 盯住核心展示区，观察默认状态下最醒目的内容是什么。
3. 主动触发一次关键交互，比如点击、滑动、跳转、返回、切换或者选择。
4. 回头检查状态区、提示区、标题区或者附属信息有没有跟着变化。
5. 最后再打开源码，对照刚才那次交互，把状态变化链路串起来。

如果这五步你能边操作边说清楚页面发生了什么，后面再换成自己的数据和交互，心里会稳很多。

如果我把它迁进正式项目

示例页最大的风险，就是你觉得“这不难”，结果真要迁进项目里，发现数据、样式、交互边界全要补。这里提前把这些坑说开。

• 吸附滚动别只调参数，子项尺寸、容器留白和预览区域通常比 API 本身更影响体感。
• 如果页面同时存在自由浏览和精准停靠两种需求，最好把吸附开关当成正式状态来设计。
• 只要页面里有重复块，就别硬撑着手写到底；早点抽成小组件，后面改样式和改交互都会轻松很多。
• 示例数据最好和布局代码分开放，不然后面一接接口，页面文件很容易立刻变臃肿。

这个案例为什么值得留一份

它真正值得保留的地方，不只是效果能跑出来，而是写法相对克制。你以后回来翻，会发现它很适合当中间层模板。

• 页面结构比较稳，后续不管是换数据还是换皮肤，成本都不会特别高。
• 状态数量总体可控，适合拿来练“一个页面里如何分配职责”这件事。
• 组件参数和页面目标之间关系比较直观，不太会出现“能跑但看不懂为什么这么配”的情况。

完整代码

下面保留整理过命名的完整 ArkTS 代码，方便你直接对照学习。这里已经去掉原始的 Demo 命名，改成了更贴近当前案例语义的名称。

/** * 嵌套吸附页面 */import{PRESET_COLORS,generateListItems,DEMO_BG_COLOR,DEMO_CARD_COLOR,DEMO_THEME_COLOR,DEMO_SUBTEXT_COLOR}from'./types'interfaceScrollsnapNestedLayoutItem{label:stringitems:string[]}@Entry@Componentstruct ScrollsnapNestedLayout{@StateisShow:boolean=truebuild(){Column(){if(this.isShow){Column(){Text('嵌套吸附').fontSize(18).fontWeight(FontWeight.Bold).fontColor('#8E44AD').margin({bottom:4})Text('外层垂直 Scroll START 吸附 + 内层水平 Scroll CENTER 吸附').fontSize(12).fontColor(DEMO_SUBTEXT_COLOR).margin({bottom:12})}.width('100%').alignItems(HorizontalAlign.Start)Scroll(){Column(){ForEach([{label:'推荐',items:['#E91E63','#2196F3','#4CAF50','#FF9800']},{label:'热门',items:['#9C27B0','#00BCD4','#FF5722','#607D8B']},{label:'最新',items:['#795548','#CDDC39','#03A9F4','#FF6B6B']}],(section:ScrollsnapNestedLayoutItem,idx:number)=>{Column(){Text(section.labelasstring).fontSize(15).fontWeight(FontWeight.Bold).fontColor(DEMO_THEME_COLOR).margin({bottom:8,left:8})Scroll(){Row(){ForEach(section.itemsasstring[],(color:string,i:number)=>{Column(){Text(\`\${i+1}\`).fontSize(36).fontWeight(FontWeight.Bold).fontColor('#FFFFFF')}.width(120).height(120).backgroundColor(color).borderRadius(12).justifyContent(FlexAlign.Center).margin({right:10})})}.padding({left:4,right:4})}.width('100%').height(140).scrollable(ScrollDirection.Horizontal).scrollBar(BarState.Off).scrollSnap({snapAlign:ScrollSnapAlign.CENTER})}.width('100%').backgroundColor(DEMO_CARD_COLOR).borderRadius(12).padding(12).margin({bottom:12})})}.padding({left:4,right:4})}.width('100%').height(460).scrollBar(BarState.Auto).scrollSnap({snapAlign:ScrollSnapAlign.START}).backgroundColor('#F5F6FA')}Text('嵌套吸附页面 - 嵌套吸附：双层 Scroll 不同吸附模式').fontSize(12).fontColor('#999999').margin({top:12})}.width('100%').height('100%').backgroundColor('#F5F6FA').padding(16)}}

收个尾

嵌套吸附页面 这一页我建议你至少亲手改一次。哪怕只是换一组数据、调一个布局、补一个状态字段，你都会比只看文章更快进入自己的节奏。