鸿蒙 uni-app x 吸顶布局 sticky-section 组件限

鸿蒙专家

吸顶布局在鸿蒙 uni-app x 中的适用范围
列表页分类标题、通讯录字母索引、筛选栏等场景都需要吸顶。uni-app x 提供 sticky-header 和 sticky-section：sticky-header 是单个吸顶元素，sticky-section 是吸顶分组容器，内部包含 sticky-header 和列表内容。单个吸顶可用 sticky-header，多个吸顶用 sticky-section 包裹，每个分组内放一个 sticky-header。但在鸿蒙平台不能照搬普通写法，建议统一用 sticky-section。

鸿蒙兼容性与限制
鸿蒙 4.71 开始支持（系统版本 5.0.5），HarmonyOS(Vapor) 5.08 版本支持。API 版本低于 17 不支持，需要自行监听滚动实现吸顶。鸿蒙平台限制有三点：sticky-header 只能作为 sticky-section 的子元素，不能直接放在 list-view 下；sticky-header 和 sticky-section 不支持 CSS 样式，不要通过 class 和 style 设置样式；鸿蒙平台暂不支持 padding 属性，需把内边距等样式放到子元素上。

正确结构与错误写法
错误或可能不生效的写法：

2. <list-view>
3.   <sticky-header>...</sticky-header>
4.   <list-item>...</list-item>
5. </list-view>

复制代码

正确写法：

2. <list-view>
3.   <sticky-section>
4.     <sticky-header>
5.       <view style="padding: 10px 15px; background-color: #F5F5F5;">
6.         <text>吸顶标题</text>
7.       </view>
8.     </sticky-header>
9.     <list-item v-for="i in 20" :key="i">
10.       <text>内容 {{i}}</text>
11.     </list-item>
12.   </sticky-section>
13. </list-view>

复制代码

样式不能设置在 sticky-header 上，必须下沉到子元素。例如不要给 sticky-header 设置背景和 padding，而应在内部 view 上设置。

典型场景与关键配置
分类列表吸顶：用 sticky-section v-for 循环分组，内部 sticky-header 放分类标题，list-item 放组内条目，设置 :push-pinned-header="true"。筛选栏吸顶：在 list-view 中先放 Banner、推荐等 list-item，再放 sticky-section，内部 sticky-header 放筛选栏，下面放列表内容。通讯录字母索引：按字母分组，sticky-header 显示 group.letter。多个吸顶标题停靠：多个 sticky-section 的 sticky-header 会依次停靠在前一个末尾。push-pinned-header 控制吸顶元素是否被上推：true 会被后面的吸顶标题上推；false 不会被上推，会覆盖前一个。

分类列表关键结构：

2. <list-view style="flex: 1;">
3.   <sticky-section v-for="(group, gIndex) in groupList" :key="gIndex" :push-pinned-header="true">
4.     <sticky-header>
5.       <view style="padding: 10px 15px; background-color: #F5F5F5; border-bottom: 1px solid #eee;">
6.         <text style="font-size: 15px; font-weight: bold; color: #333;">{{group.title}}</text>
7.       </view>
8.     </sticky-header>
9.     <list-item v-for="(item, index) in group.items" :key="gIndex + '-' + index" style="padding: 15px; border-bottom: 1px solid #eee;">
10.       <text style="font-size: 15px; color: #333;">{{item.name}}</text>
11.     </list-item>
12.   </sticky-section>
13. </list-view>

复制代码

完整页面组合思路
完整实战页面通常包含轮播图、推荐区、吸顶筛选栏和商品列表。list-view 开启下拉刷新，用 refresher-enabled、refresher-triggered、refresherrefresh 控制。Banner 和推荐区放在普通 list-item 中，筛选栏和商品列表放进一个 sticky-section，sticky-header 放 tabs，list-item 循环 productList。数据通过 loadProducts 生成，onRefresh 中 setTimeout 后重新加载并 uni.showToast。这个结构可以同时验证吸顶、刷新和列表渲染。

与鸿蒙原生吸顶的对比
鸿蒙原生开发中，吸顶使用 Sticky 属性，常见结构是 List 内放 ListItemGroup，ListItemGroup 的 header 通过 Builder 生成，并在 List 上设置 .sticky(StickyStyle.Header)。uni-app x 的 sticky-header + sticky-section 与原生 ListItemGroup + Sticky 类似，但组件化写法更直观。需要注意的是，鸿蒙平台版本和 API 版本是前置条件，低于 API 17 时不能依赖该能力，需要自行监听滚动实现吸顶。

踩坑清单
1. 鸿蒙平台必须用 sticky-section 包裹 sticky-header，直接放在 list-view 下可能不生效。
2. sticky-header 和 sticky-section 不支持 CSS 样式，不要写 class 或 style，样式放到子元素。
3. 鸿蒙平台暂不支持 padding 属性，sticky-header 上设置 padding 无效，需通过子 view 设置。
4. API 版本低于 17 不支持，需要准备滚动监听兜底。
5. push-pinned-header 按场景选择：需要被后续标题上推时用 true；需要覆盖前一个标题时用 false。
6. 确认系统版本：鸿蒙 4.71 开始支持（系统版本 5.0.5），HarmonyOS(Vapor) 5.08 支持。

结论
在鸿蒙平台使用 uni-app x 做吸顶，核心不是组件名，而是遵守平台适配规则：统一用 sticky-section，sticky-header 只作为其子元素；样式和 padding 下沉到子元素；确认系统与 API 版本；用 push-pinned-header 控制停靠行为。按这套结构，分类列表、筛选栏、通讯录字母索引等吸顶场景都可以在鸿蒙上稳定落地。

热心网友1

楼主整理得挺细的，这个坑确实容易踩。我之前也以为 sticky-header 可以直接放在 list-view 下面，看了你说的正确结构才明白鸿蒙下最好统一用 sticky-section 包起来，而且样式不能直接挂在 sticky-header 上，要下沉到里面的 view，不然可能不生效。push-pinned-header 的 true 和 false 区别也很实用，多个吸顶标题依次停靠还是被上推覆盖，一下就清楚了。 想请教一下，API 低于 17 时自行监听滚动实现吸顶，有没有比较稳妥的思路？另外你最后提到的完整页面组合里，轮播图、推荐区、筛选栏吸顶和商品列表放在同一个 list-view 中，下拉刷新和 sticky-section 同时用时有没有需要特别注意的地方？分类列表那段结构我准备照着试一下，感谢分享。

热心网友3

感谢楼主分享，整理得很清楚，尤其是鸿蒙平台那几条限制很关键。之前很容易踩坑的地方就是把 sticky-header 直接放在 list-view 下，或者给 sticky-header、sticky-section 加 class 和 style，结果样式不生效。你强调的“sticky-header 只能作为 sticky-section 的子元素”“样式必须下沉到内部子元素”“鸿蒙暂不支持 padding 要放到子元素上”这几点很实用。 分类列表、筛选栏、通讯录字母索引这几个场景也讲得很直观，尤其是 sticky-section 配合 v-for 和 push-pinned-header 的用法。push-pinned-header 为 true 会被后面的吸顶标题上推，false 会覆盖前一个，这个区别对多个吸顶停靠很重要。完整页面组合思路里，把 Banner、推荐放普通 list-item，筛选栏和商品列表放进同一个 sticky-section，同时结合下拉刷新，结构比较清晰，准备照着试试。 另外 API 版本低于 17 需要自行监听滚动实现吸顶这个提醒也很重要，不然低版本很容易出现兼容问题。帖子最后和鸿蒙原生吸顶对比部分好像还没写完，期待后续补全。

热心网友3

感谢分享，这篇把鸿蒙 uni-app x 吸顶的关键限制讲得很清楚。之前最容易忽略的就是 sticky-header 不能直接放在 list-view 下，必须由 sticky-section 包起来；另外样式不能通过 class 或 style 加到 sticky-header、sticky-section 上，padding 也得放到内部子元素，这点确实和普通写法不一样。push-pinned-header 的 true 和 false 区别、多个吸顶标题依次停靠，以及分类列表、筛选栏、通讯录字母索引这几个场景都很有参考价值。完整页面组合思路里，Banner 和推荐区放普通 list-item，筛选栏和商品列表放同一个 sticky-section，再加上下拉刷新，整体结构很实用。想问下低于 API 17 时自行监听滚动实现吸顶，有没有比较推荐的判断方式？这个坑应该不少人会碰到。