Skip to content

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 | string0-
navbar页面顶部导航栏形态:空值交给全局覆盖与内建默认string | number''-
enable是否开启吸顶booleantrue-
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,否则会压住状态栏图标。