Skip to content

Sticky — Pin to Top ​

17:43

Description ​

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 ​

PlatformSupport
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
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>

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 ​

PropertyDescriptionTypeDefaultVersion
customStyle自定义根节点样式string | JsonObject--
customClass自定义根节点样式类string''-
offsetTop吸顶时与导航栏底部的距离number | string0-
navbar页面顶部导航栏形态:空值交给全局覆盖与内建默认string | number''-
enable是否开启吸顶booleantrue-
bgColor吸顶背景色,空值时回退主题白色string''-
zIndex层级,空值回退主题层级number | string''-
scrollTop外部滚动距离,负数视为未提供number | string-1-

Events ​

EventDescriptionParamsVersion
fixed开始吸顶时触发--
unfixed取消吸顶时触发--

Slots ​

SlotDescriptionVersion
default吸顶的内容-

Notes ​

  • navbar must match the page's navigationStyle, otherwise the pinned line is off by a status bar or a navbar height:
    • default (built-in default) — native navbar: H5 insets windowTop (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 navbar default is an empty string: it reads componentProps['ux-sticky'].navbar first, then falls back to the built-in default. Configure it once in main.ts when 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 a scroll-view, so passing scroll-top is still recommended.
  • On WeChat Mini Program onPageScroll must 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 / @unfixed take no arguments; use separate handlers instead of the old index.
  • Keep the pinned background opaque; z-index defaults 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 negative offset-top (-statusBarHeight) as a workaround; the first frame may report a status bar height of 0 and jump once. The page must also use navigationStyle: custom and add padding-top: statusBarHeight itself, otherwise the pinned bar covers the status bar icons.