更新记录

1.0.3（2026-04-21）下载此版本

没有

平台兼容性

Smart Scroll 智能滚动组件，嵌套滚动，双重滚动

一个智能的滚动切换组件，自动处理页面滚动和内部滚动的平滑切换

✨ 特性

🎯 智能切换：自动检测滚动位置，无缝切换滚动模式
📐 动态适配：自动计算导航栏高度，适应不同设备
🚀 性能优化：内置节流、防抖、GPU加速等优化
🎨 灵活定制：三个插槽，完全自定义内容
🔄 滞回区间：避免临界点频繁切换，提供流畅体验
💪 TypeScript：完整的类型定义

使用场景

电商商品列表页面（顶部轮播图 + 分类商品）
资讯类应用（顶部Banner + 内容列表）
任何需要滚动切换的场景

📦 文件结构

smart-scroll/
├── smart-scroll.vue      # 组件主文件
├── index.js              # 导出入口
├── types.ts              # TypeScript 类型定义
├── README.md             # 完整文档
├── QUICK_START.md        # 快速开始指南
└── USAGE_TEMPLATE.vue    # 使用模板

🚀 快速开始

方式1：使用模板（推荐）

复制 USAGE_TEMPLATE.vue 到你的页面
根据需要修改插槽内容
完成！

方式2：最小化引入

<template>
  <smart-scroll>
    <template #nav>导航栏</template>
    <template #header>顶部内容</template>
    <template #content>主要内容</template>
  </smart-scroll>
</template>

<script setup>
import SmartScroll from '@/components/smart-scroll'
</script>

详细快速开始指南请查看 QUICK_START.md

2. 基础用法

<template>
  <SmartScroll>
    <!-- 导航栏插槽 -->
    <template #nav>
      <view class="custom-nav">
        <text>返回</text>
        <text>标题</text>
        <text>更多</text>
      </view>
    </template>

    <!-- 顶部内容插槽（如轮播图） -->
    <template #header>
      <image src="/static/banner.jpg" mode="aspectFill"></image>
    </template>

    <!-- 主要内容插槽 -->
    <template #content>
      <view class="left-menu">
        <view v-for="item in categories" :key="item.id">
          {{ item.name }}
        </view>
      </view>
      <view class="right-content">
        <view v-for="item in products" :key="item.id">
          {{ item.name }}
        </view>
      </view>
    </template>
  </SmartScroll>
</template>

3. 完整示例

<template>
  <SmartScroll 
    :throttle-time="300"
    :enable-scroll-buffer="5"
    :disable-scroll-buffer="30"
    @scroll-change="handleScrollChange"
  >
    <template #nav>
      <view class="nav-container">
        <view class="back-btn">←</view>
        <view class="title">商品列表</view>
        <view class="more-btn">⋮</view>
      </view>
    </template>

    <template #header>
      <view class="banner">
        <image 
          src="https://example.com/banner.jpg" 
          mode="aspectFill"
        ></image>
      </view>
    </template>

    <template #content>
      <view class="goods-container">
        <!-- 左侧分类菜单 -->
        <scroll-view scroll-y class="left">
          <view 
            v-for="(category, index) in categories" 
            :key="index"
            class="menu-item"
          >
            {{ category.name }}
          </view>
        </scroll-view>

        <!-- 右侧商品列表 -->
        <scroll-view scroll-y class="right">
          <view 
            v-for="(product, index) in products" 
            :key="index"
            class="product-item"
          >
            {{ product.name }}
          </view>
        </scroll-view>
      </view>
    </template>
  </SmartScroll>
</template>

<script setup>
import { ref } from 'vue'
import SmartScroll from '@/components/smart-scroll/smart-scroll.vue'

const categories = ref([
  { id: 1, name: '分类1' },
  { id: 2, name: '分类2' },
  // ...
])

const products = ref([
  { id: 1, name: '商品1' },
  { id: 2, name: '商品2' },
  // ...
])

const handleScrollChange = (data) => {
  console.log('滚动状态变化:', data.scroll)
}
</script>

<style scoped lang="scss">
.nav-container {
  height: 80rpx;
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 0 30rpx;
  background-color: #fff;
}

.banner image {
  width: 100%;
  height: 40vh;
}

.goods-container {
  display: flex;
  width: 100%;

  .left {
    width: 250rpx;
    background-color: #f5f5f5;

    .menu-item {
      height: 100rpx;
      line-height: 100rpx;
      text-align: center;
      border-bottom: 1rpx solid #eee;
    }
  }

  .right {
    flex: 1;
    background-color: #fff;
    margin-left: 20rpx;

    .product-item {
      height: 200rpx;
      line-height: 200rpx;
      padding: 0 20rpx;
      border-bottom: 1rpx solid #eee;
    }
  }
}
</style>

📖 API 文档

Props 属性

参数	说明	类型	默认值
throttleTime	滚动事件节流时间（毫秒）	number	300
enableScrollBuffer	启用内部滚动的缓冲距离（像素）	number	5
disableScrollBuffer	禁用内部滚动的缓冲距离（像素）	number	30

属性说明

throttleTime

控制滚动事件查询的频率
值越小响应越快，但性能开销越大
建议范围：200-500ms

enableScrollBuffer

内容区域到达导航栏下方多少像素时启用内部滚动
值越小，越早切换到内部滚动
建议范围：0-10px

disableScrollBuffer

内容区域远离导航栏多少像素时禁用内部滚动
与 enableScrollBuffer 形成滞回区间，避免频繁切换
建议范围：20-50px

🎯 Events 事件

事件名	说明	回调参数
scroll-change	滚动状态变化时触发	`{ scroll: boolean }`

事件示例

<SmartScroll @scroll-change="handleScrollChange">
  <!-- ... -->
</SmartScroll>

<script setup>
const handleScrollChange = (data) => {
  if (data.scroll) {
    console.log('已切换到内部滚动模式')
  } else {
    console.log('已切换到页面滚动模式')
  }
}
</script>

🎨 Slots 插槽

插槽名	说明
nav	导航栏区域
header	顶部内容区域（如轮播图、Banner）
content	主要内容区域

🔧 Methods 方法

通过 ref 可以调用组件暴露的方法：

<template>
  <SmartScroll ref="smartScrollRef">
    <!-- ... -->
  </SmartScroll>

  <button @click="handleClick">操作</button>
</template>

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

const smartScrollRef = ref(null)

const handleClick = () => {
  // 滚动到顶部
  smartScrollRef.value.scrollToTop(true)

  // 获取状态
  const state = smartScrollRef.value.getState()
  console.log(state)
}
</script>

scrollToTop

滚动到顶部并重置状态。

参数：

smooth (boolean, 可选): 是否平滑滚动，默认 true

示例：

// 平滑滚动
smartScrollRef.value.scrollToTop(true)

// 立即跳转
smartScrollRef.value.scrollToTop(false)

getState

获取组件当前状态。

返回值：

{
  scroll: boolean,      // 是否启用内部滚动
  isHidden: boolean,    // 外层scroll-view是否可滚动
  navHeight: number,    // 导航栏高度（像素）
  contentTop: number    // 内容区域顶部位置（像素）
}

示例：

const state = smartScrollRef.value.getState()
if (state.scroll) {
  console.log('当前处于内部滚动模式')
}

公开属性

属性名	说明	类型
scroll	当前是否启用内部滚动	boolean
isHidden	外层scroll-view是否可滚动	boolean

样式定制

组件提供了基础的样式优化（GPU加速、硬件加速等），你可以根据需求自定义样式：

// 导航栏样式
::v-deep .nav-section {
  // 你的样式
}

// 顶部内容样式
::v-deep .header-section {
  // 你的样式
}

// 内容区域样式
::v-deep .content-section {
  // 你的样式
}

性能优化建议

合理设置节流时间
- 高性能设备：200-300ms
- 低性能设备：400-500ms
调整缓冲距离
- 根据导航栏高度动态调整
- 一般设置为导航栏高度的 10%-20%
避免在插槽中使用大量复杂组件
- 使用虚拟列表处理长列表
- 图片使用懒加载
CSS 优化
- 组件已内置 GPU 加速
- 避免在滚动容器内使用复杂动画

注意事项

导航栏定位
- 导航栏不需要设置 position: fixed
- 组件会自动处理滚动逻辑
内容区域高度
- 组件会自动计算并设置内容区域高度
- 无需手动设置 height: 100vh
内部 scroll-view
- 在 content 插槽中使用 scroll-view 时
- 确保设置了正确的宽高和 scroll-y 属性
兼容性
- 支持 H5、小程序、App
- Uniapp 项目可直接使用

常见问题

Q: 滚动切换不流畅怎么办？

A: 尝试以下优化：

增加 throttleTime 值
增大 disableScrollBuffer 值，扩大滞回区间
检查是否有复杂的 DOM 操作或动画

Q: 如何获取当前滚动状态？

A: 通过 ref 访问：

const isScrolling = smartScrollRef.value.scroll

Q: 导航栏高度变化怎么办？

A: 调用 scrollToTop() 方法会重新获取导航栏高度，或者手动调用组件内部的 getNavHeight() 方法。

更新日志

v1.0.0

✨ 初始版本发布
✅ 智能滚动切换
✅ 动态高度计算
✅ 性能优化（节流、防抖、GPU加速）
✅ 完整的 TypeScript 支持

License

MIT

智能滚动组件，嵌套滚动，双重滚动，仿外卖的双重滚动 嵌套滚动 双重滚动