鸿蒙 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 控制停靠行为。按这套结构，分类列表、筛选栏、通讯录字母索引等吸顶场景都可以在鸿蒙上稳定落地。