Sticky — Pin to Top
17:43Description
Pins content to the top once it reaches offsetTop from the top and releases on scroll back; while pinned the wrapper keeps the original height, so the content below never jumps. Declare the page top structure with navbar and the component resolves the inset (status bar + navbar) per platform, so the page needs no platform branching.
Pass the scroll distance from usePageScroll() to scroll-top — it covers both page scrolling and scroll-view scrolling. Without it the component falls back to its internal intersection observer, which only works on H5 and WeChat Mini Program; App always needs scroll-top.
Compatibility
| Platform | Support |
|---|---|
| App | ✅ Supported (must listen to scrolling in the page or container and pass scroll-top; the internal observer is not available) |
| H5 | ✅ Supported (falls back to an IntersectionObserver when scroll-top is absent) |
| WeChat Mini Program | ✅ Supported (page scrolling needs onPageScroll registered in the page script calling setScrollTop, otherwise scrollTop stays 0) |
Examples
Basic usage
Switch offset-top, bg-color, enable and the detection channel below; the pinned line = navbar bottom + offset-top, resolved per platform inside the component. navbar follows the page structure (pages.json) and is fixed to custom on this page.
View source
<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>Standalone page demos
navbar must match the page's real top structure so the pinned line lands correctly. The two pages below reproduce the native-navbar and no-navbar structures through pages.json.
Usage notes
Four rules: keep navbar in sync with the page structure, pass a number for non-standard navbar heights, read the scroll distance from usePageScroll, and mind the fallback when scroll-top is absent.
API
Props
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
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
| Event | Description | Params | Version |
|---|---|---|---|
fixed | 开始吸顶时触发 | - | - |
unfixed | 取消吸顶时触发 | - | - |
Slots
| Slot | Description | Version |
|---|---|---|
default | 吸顶的内容 | - |
Notes
navbarmust match the page'snavigationStyle, otherwise the pinned line is off by a status bar or a navbar height:default(built-in default) — native navbar: H5 insetswindowTop(the navbar height), App / Mini Program inset 0 (the content area already starts below the navbar);custom— self-drawn navbar (e.g.ux-navbar): status bar + navbar (H5 has no status bar, so 44px only);none— page renders no navbar: status bar only (0 on H5), not "no inset at all";- a number (e.g.
"56") — self-drawn navbar with a non-standard height: status bar + that number.
- The
navbardefault is an empty string: it readscomponentProps['ux-sticky'].navbarfirst, then falls back to the built-indefault. Configure it once inmain.tswhen the whole site draws its own navbar. - App has no internal observer: without
scroll-top(or with a negative value) nothing pins and a single warning is logged in development. H5 / Mini Program can observe internally, but the observer cannot see scrolling inside ascroll-view, so passingscroll-topis still recommended. - On WeChat Mini Program
onPageScrollmust be registered in the page script — the compiler relies on that call to attach the scroll hook to the page. - Multiple pinning areas on one page:
@fixed/@unfixedtake no arguments; use separate handlers instead of the oldindex. - Keep the pinned background opaque;
z-indexdefaults to 970 (below the navbar's 980) and content slides underneath the pinned bar. - Pinning over the status bar (true immersive) has no dedicated option yet: on App / Mini Program use
navbar="none"with a negativeoffset-top(-statusBarHeight) as a workaround; the first frame may report a status bar height of 0 and jump once. The page must also usenavigationStyle: customand addpadding-top: statusBarHeightitself, otherwise the pinned bar covers the status bar icons.