Sticky 吸顶
17:43说明
内容滚到距顶部 offsetTop 时固定在顶部,回滚即复位;吸顶期间外层占位锁住原内容高度,下方内容不会上跳。页面顶部结构用 navbar 声明,组件按端换算避让高度(状态栏 + 导航栏),页面里不用写平台判断。
滚动距离推荐用 usePageScroll() 取后传给 scroll-top,页面滚动与 scroll-view 容器滚动都能覆盖;不传时退化为组件内部节点观察,仅 H5 / 微信小程序可用,App 端必须传。
兼容性
| 平台 | 支持情况 |
|---|---|
| App | ✅ 支持(必须由页面或容器监听滚动并传入 scroll-top,不支持组件内部观察) |
| H5 | ✅ 支持(不传 scroll-top 时用 IntersectionObserver 内部观察) |
| 微信小程序 | ✅ 支持(页面滚动需在页面脚本注册 onPageScroll 并 setScrollTop,否则 scrollTop 恒为 0) |
示例
基础用法
用下方按钮切换 offset-top、bg-color、enable 与判定通道;吸顶线 = 导航栏底部 + offset-top,由组件按端自动换算。navbar 由页面结构(pages.json)决定,本页固定为 custom。
查看源码
vue
<template>
<!-- navbar 声明页面顶部结构,组件自己换算避让高度:
custom = 自绘导航栏(让出状态栏 + 导航栏);default = 原生导航栏(H5 让出导航栏高度,App/小程序不避让);
none = 无导航栏(只让出状态栏) -->
<scroll-view class="page" direction="vertical" @scroll="onScroll">
<view class="toolbar">
<ux-button size="small" text="offset-top 0" @click="setOffsetTop(0)"></ux-button>
<ux-button size="small" text="offset-top 60" @click="setOffsetTop(60)"></ux-button>
<ux-button size="small" :text="enabled ? '关闭吸顶' : '开启吸顶'" @click="toggleEnable"></ux-button>
</view>
<text class="state">{{ fixed ? '已吸顶' : '未吸顶' }} · navbar:custom</text>
<ux-sticky
:scroll-top="scrollTop"
navbar="custom"
:offset-top="offsetTop"
:bg-color="bgColor"
:z-index="1200"
:enable="enabled"
@fixed="onFixed"
@unfixed="onUnfixed"
>
<view class="bar">
<text class="bar-text">吸顶区域</text>
</view>
</ux-sticky>
<view v-for="(item, index) in rows" :key="index" class="row">
<text>列表内容 {{ item }}</text>
</view>
</scroll-view>
</template>
<script setup lang="ts">
import { usePageScroll } from '@/uni_modules/uview-pro-x';
// 页面滚动与容器滚动都写进同一个 ref,不用再分平台判断滚动发生在哪一层
const { scrollTop, onScroll, setScrollTop } = usePageScroll();
// 页面层滚动在页面脚本里注册:小程序端编译期靠这次调用给页面挂上滚动钩子
onPageScroll((e) => {
setScrollTop(e.scrollTop);
});
const offsetTop = ref(0);
// bgColor 可传主题色名(如 primary)或色值;片段里固定为 primary,只切换 offset-top 与 enable
const bgColor = ref('primary');
const enabled = ref(true);
const fixed = ref(false);
// 行数要够多,才能把吸顶区域推过固定线
const rows = ref<string[]>([]);
for (let i = 0; i < 16; i++) {
rows.value.push((i + 1).toString());
}
const setOffsetTop = (value: number) => {
offsetTop.value = value;
};
const toggleEnable = () => {
enabled.value = !enabled.value;
};
const onFixed = () => {
fixed.value = true;
};
const onUnfixed = () => {
fixed.value = false;
};
</script>
<style>
.page {
flex: 1;
}
.toolbar {
display: flex;
flex-direction: row;
padding: 8px;
}
.state {
padding: 0 8px 8px;
font-size: 13px;
}
.bar {
height: 44px;
padding: 0 16px;
display: flex;
align-items: center;
}
.bar-text {
color: #ffffff;
}
.row {
height: 56px;
margin: 8px;
background-color: #f2f3f5;
border-radius: 8px;
}
</style>独立页面演示
navbar 要和页面真实的顶部结构一致,吸顶线才会落在正确位置。下面两个页面分别用 pages.json 配置出「原生导航栏」和「无导航栏」两种真实结构。
使用说明
四条要点:navbar 跟页面结构保持一致、非标准导航栏传数值、滚动距离统一用 usePageScroll 取,以及不传 scroll-top 时的退化行为。
API
Props
| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
customStyle | 自定义根节点样式 | string | JsonObject | - | - |
customClass | 自定义根节点样式类 | string | '' | - |
offsetTop | 吸顶时与导航栏底部的距离 | number | string | 0 | - |
navbar | 页面顶部导航栏形态:空值交给全局覆盖与内建默认 | string | number | '' | - |
enable | 是否开启吸顶 | boolean | true | - |
bgColor | 吸顶背景色,空值时回退主题白色 | string | '' | - |
zIndex | 层级,空值回退主题层级 | number | string | '' | - |
scrollTop | 外部滚动距离,负数视为未提供 | number | string | -1 | - |
Events
| 事件名 | 说明 | 回调参数 | 版本 |
|---|---|---|---|
fixed | 开始吸顶时触发 | - | - |
unfixed | 取消吸顶时触发 | - | - |
Slots
| 插槽名 | 说明 | 版本 |
|---|---|---|
default | 吸顶的内容 | - |
注意事项
navbar必须与页面pages.json的navigationStyle一致,否则吸顶线会差一个状态栏或一个导航栏的高度:default(内建默认)—— 原生导航栏:H5 让出windowTop(导航栏高度),App / 小程序为 0(内容区原点已在导航栏下方);custom—— 自绘导航栏(如ux-navbar):让出状态栏 + 导航栏(H5 无状态栏,只叠 44px);none—— 页面不渲染导航栏:只让出状态栏(H5 为 0),不是「避让 0」;- 数值(如
"56")—— 自绘但高度非标准:状态栏 + 该数值。
navbar缺省是空串:先取全局componentProps['ux-sticky'].navbar,再回退内建default。全站自绘导航栏时在main.ts配一次即可,页面不必逐个声明。- App 端不支持内部观察:不传
scroll-top(或传负数)不会吸顶,开发期控制台提示一次。H5 / 小程序虽可用内部观察,但滚动发生在scroll-view容器内时它拿不到容器滚动,仍应传scroll-top。 - 微信小程序的
onPageScroll必须在页面脚本里注册(编译期靠这次调用给页面挂滚动钩子),只在组件内部监听会拿不到页面滚动距离。 - 同页多个吸顶实例:
@fixed/@unfixed不接收参数,用各自的独立 handler 区分,不再有index。 - 吸顶条背景要保持不透明,
z-index缺省 970(低于导航栏的 980),内容会从吸顶条下方滑过。 - 让吸顶条压住状态栏(真沉浸式)目前没有对应档位:App / 小程序只能用
navbar="none"配合负的offset-top(-statusBarHeight)变通,App 首帧状态栏高度可能为 0,会出现一次跳动;页面还必须是navigationStyle: custom,并自行叠padding-top: statusBarHeight,否则会压住状态栏图标。