资源描述
vue-sticker 是一款轻量、高性能的 Vue 粘性效果组件，支持滚动吸附（sticky）、动态阈值触发、平滑过渡、多级嵌套粘性及 SSR 友好渲染。适用于导航栏固定、侧边栏悬浮、表格表头冻结等场景，兼容 Vue 2.7+ 与 Vue 3（Options API / Composition API），零依赖，体积仅 ~3KB（gzip）。文档完善，开箱即用，显著提升长页面交互体验。
详细内容
## 框架简介与定位
`vue-sticker` 是一个专为 Vue 生态设计的轻量级粘性（Sticky）效果封装组件，旨在以声明式方式实现元素在滚动过程中的智能吸附行为。它不依赖第三方滚动库（如 IntersectionObserver 封装层），原生利用 `position: sticky` 并优雅降级至 JavaScript 模拟方案，兼顾性能、兼容性与易用性。定位为「开箱即用的生产级粘性工具」，适用于中后台系统、内容型网站及移动端适配项目。
## 核心特性
- ✅ **原生 `position: sticky` 优先 + 自动降级**：自动检测浏览器支持度，支持 IE11+（通过 JS fallback 实现）
- ✅ **滚动阈值灵活控制**：支持 `offsetTop`、`offsetBottom`、`boundaryElement` 等参数，精确控制吸附触发时机
- ✅ **多级嵌套粘性支持**：父子 `Sticker` 组件可协同工作，避免层级冲突与样式覆盖
- ✅ **平滑过渡动画集成**：内置 CSS 过渡类名（如 `sticker-enter`, `sticker-stuck`），支持自定义动画或配合 `animate.css`
- ✅ **SSR 友好 & TypeScript 支持**：提供完整类型定义（`@types/vue-sticker` 内置），服务端渲染时自动跳过初始化逻辑，无 hydration 错误
## 适用场景
- 顶部导航栏/面包屑在长页面中始终可见
- 表格（Table）表头（thead）滚动时固定显示
- 侧边栏目录树（TOC）随滚动动态吸附于视口右侧
- 商品详情页中“加入购物车”按钮悬浮定位
- 多步骤表单中操作栏（下一步/提交）保持可见
## 快速入门步骤
### 1. 安装
```bash
# Vue 3（推荐）
npm install vue-sticker
# 或 Vue 2.7+
yarn add vue-sticker
```
### 2. 基础使用（Vue 3 Composition API 示例）
```vue
<template>
<div class="page-container">
<Sticker :offset-top="80" class="nav-bar">
<header>我的导航栏</header>
</Sticker>
<main class="content">
<!-- 页面主要内容 -->
<p v-for="i in 100" :key="i">内容段落 {{ i }}</p>
</main>
</div>
</template>
<script setup>
import { Sticker } from 'vue-sticker'
</script>
<style scoped>
.nav-bar {
background: #fff;
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
.sticker-stuck {
transform: translateY(0);
transition: transform 0.2s ease-out;
}
</style>
```
> 💡 提示：最小示例只需引入 `Sticker` 组件并包裹目标元素，设置 `offset-top` 即可生效；无需额外初始化或监听事件。
## 生态与社区说明
- 官方文档托管于 GitHub Pages：[https://kamilocean.github.io/vue-sticker/#/](https://kamilocean.github.io/vue-sticker/#/)，含 API 参考、Demo 演示与常见问题解答
- 源码开源（MIT 协议）于 GitHub：[https://github.com/kamilocean/vue-sticker](https://github.com/kamilocean/vue-sticker)，欢迎 Issue 报错与 PR 贡献
- 社区活跃度中等，主要维护者持续更新兼容性补丁（如 Vue 3.4+ 响应式变更适配）
- 无官方 CLI 插件或 Nuxt 模块，但可通过 `nuxt.config.ts` 的 `build.transpile` 显式配置支持 Nuxt 3 项目