Sticky 粘性布局 - Vant 4

Sticky 粘性布局

介绍

Sticky 组件与 CSS 中 position: sticky 属性实现的效果一致，当组件在屏幕范围内时，会按照正常的布局排列，当组件滚出屏幕范围时，始终会固定在屏幕顶部。

引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from'vue'; import { Sticky } from'vant'; const app = createApp(); app.use(Sticky);

🎯 代码演示

📌 基础用法

将内容包裹在 Sticky 组件内，轻松实现粘性定位效果！滚动页面时，内容会自动吸附在屏幕顶部。

<template>
  <div class="demo-sticky">
    <van-sticky>
      <van-button type="primary" style="margin-left: 15px;">
        基础用法
      </van-button>
    </van-sticky>
  </div>
</template>

<style>
.demo-sticky {
  height: 150vh;
  padding-top: 50px;
  background: linear-gradient(180deg, #f7f8fa 0%, #fff 100%);
}
</style>

📏 吸顶距离

通过 offset-top 属性精确控制吸顶距离，让组件与顶部保持合适的间距，避免遮挡重要内容！

<template>
  <div class="demo-sticky">
    <van-sticky :offset-top="50">
      <van-button type="warning" style="margin-left: 115px;">
        吸顶距离 50px
      </van-button>
    </van-sticky>
  </div>
</template>

<style>
.demo-sticky {
  height: 150vh;
  padding-top: 50px;
  background: linear-gradient(180deg, #f7f8fa 0%, #fff 100%);
}
</style>

📦 指定容器

通过 container 属性指定容器，组件会智能地保持在容器范围内，不会超出容器边界！

<template>
  <div class="demo-sticky">
    <div ref="container" class="scroll-container">
      <van-sticky :container="container">
        <van-button type="success" style="margin-left: 215px;">
          指定容器
        </van-button>
      </van-sticky>
      <div class="content">
        <p v-for="i in 20" :key="i">容器内容 {{ i }}</p>
      </div>
    </div>
  </div>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const container = ref(null);
    return { container };
  },
};
</script>

<style>
.scroll-container {
  height: 300px;
  overflow-y: auto;
  background: #fff;
  border: 1px solid #ebedf0;
  border-radius: 6px;
}

.content {
  padding: 15px;
}

.content p {
  margin: 10px 0;
  padding: 10px;
  background: #f7f8fa;
  border-radius: 4px;
}
</style>

⬇️ 吸底距离

设置 position="bottom" 让组件吸附在底部，通过 offset-bottom 控制与底部的距离！

<template>
  <div class="demo-sticky">
    <van-sticky position="bottom" :offset-bottom="50">
      <van-button type="danger" style="margin-left: 15px;">
        吸底距离 50px
      </van-button>
    </van-sticky>
  </div>
</template>

<style>
.demo-sticky {
  height: 150vh;
  padding-top: 50px;
  background: linear-gradient(180deg, #f7f8fa 0%, #fff 100%);
}
</style>

📋 API

🎛️ Props

参数	说明	类型	默认值
position	📍 吸附位置，可选值为 bottom	string	top
offset-top	📏 吸顶时与顶部的距离，支持 px``vw``vh``rem 单位，默认 px	*number	string*
offset-bottom	📐 吸底时与底部的距离，支持 px``vw``vh``rem 单位，默认 px	*number	string*
z-index	🔢 吸顶时的 z-index	*number	string*
container	📦 容器对应的 HTML 节点	Element	-

🎪 Events

事件名	说明	回调参数
change	🔄 当吸顶状态改变时触发	isFixed: boolean
scroll	📜 滚动时触发	{ scrollTop: number, isFixed: boolean }

📘 类型定义

组件导出以下类型定义，方便在 TypeScript 项目中使用：

import type { StickyProps, StickyPosition } from 'vant';

🎨 主题定制

🎭 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-sticky-z-index	99	🔢 粘性定位时的层级，确保组件在正确的层级显示

📚 相关文档

🧭 导航组件

• NavBar 导航栏 - 页面顶部导航，常与 Sticky 配合使用
• Tab 标签页 - 标签页切换，支持粘性定位
• Tabbar 标签栏 - 底部标签栏导航
• IndexBar 索引栏 - 索引导航，支持粘性定位

📦 布局组件

• Col 布局 - 栅格列组件
• Space 间距 - 设置组件之间的间距

🔧 工具组件

• ConfigProvider 全局配置 - 全局配置组件样式和主题