ApplySwiper

与苹果动画一样丝滑的 Vue3 卡片轮播组件

一个高性能、流畅的卡片轮播组件，灵感来自 Apple Store 应用的卡片滑动效果。支持触摸手势、橡皮筋边界效果、速度感应等特性。

✨ 特性

• 🎯 流畅动画 - 采用 cubic-bezier 缓动函数，实现类似苹果的丝滑动画
• 📱 触摸友好 - 完美支持触摸手势，支持快速滑动和拖拽
• 🎨 高度可定制 - 支持自定义卡片宽度、间距、边距等
• 🔄 橡皮筋效果 - 边界处的橡皮筋回弹效果，提升用户体验
• 🚀 性能优化 - 使用 transform 和 will-change 优化渲染性能
• 💪 TypeScript 支持 - 完整的类型定义

📦 安装

npm install applyswiper

或使用 yarn:

yarn add applyswiper

或使用 pnpm:

pnpm add applyswiper

🚀 快速开始

全局注册

import { createApp } from 'vue';
import ApplySwiper from 'applyswiper';
import 'applyswiper/dist/style.css';

const app = createApp(App);
app.use(ApplySwiper);

局部引入

<template>
  <ApplySwiper
    :items="cardList"
    card-width="480rpx"
    gap="20rpx"
    start-margin="40rpx"
    end-margin="40rpx"
    @change="handleChange"
  >
    <template #default="{ item, index }">
      <view class="card">
        <image :src="item.image" class="card-image" />
        <view class="card-title">{{ item.title }}</view>
      </view>
    </template>
  </ApplySwiper>
</template>

<script setup>
import { ref } from 'vue';
import { ApplySwiper } from 'applyswiper';

const cardList = ref([
  { image: 'https://example.com/1.jpg', title: '卡片 1' },
  { image: 'https://example.com/2.jpg', title: '卡片 2' },
  { image: 'https://example.com/3.jpg', title: '卡片 3' },
]);

const handleChange = (index) => {
  console.log('当前卡片索引:', index);
};
</script>

<style scoped>
.card {
  background: #fff;
  border-radius: 16rpx;
  overflow: hidden;
  box-shadow: 0 4rpx 20rpx rgba(0, 0, 0, 0.1);
}

.card-image {
  width: 100%;
  height: 300rpx;
  object-fit: cover;
}

.card-title {
  padding: 20rpx;
  font-size: 28rpx;
  font-weight: 500;
}
</style>

📖 API

Props

| 属性 | 类型 | 默认值 | 说明 | |-----|------|--------|------| | items | Array | [] | 必填，卡片数据数组 | | card-width | String | '480rpx' | 卡片宽度（支持 rpx 单位） | | gap | String | '20rpx' | 卡片之间的间距 | | start-margin | String | '40rpx' | 左侧边距 | | end-margin | String | '40rpx' | 右侧边距 | | current | Number | 0 | 当前显示的卡片索引 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | change | (index: number) | 卡片切换时触发，返回当前卡片索引 |

Slots

| 插槽名 | 参数 | 说明 | |--------|------|------| | default | { item: any, index: number } | 自定义卡片内容 |

🎨 使用示例

基础用法

<template>
  <ApplySwiper :items="items">
    <template #default="{ item }">
      <div class="card">{{ item.title }}</div>
    </template>
  </ApplySwiper>
</template>

<script setup>
import { ref } from 'vue';
import { ApplySwiper } from 'applyswiper';

const items = ref([
  { title: '卡片 1' },
  { title: '卡片 2' },
  { title: '卡片 3' },
]);
</script>

自定义尺寸

<template>
  <ApplySwiper
    :items="items"
    card-width="600rpx"
    gap="30rpx"
    start-margin="60rpx"
    end-margin="60rpx"
  >
    <template #default="{ item }">
      <div class="large-card">{{ item.title }}</div>
    </template>
  </ApplySwiper>
</template>

监听切换事件

<template>
  <ApplySwiper :items="items" @change="onCardChange">
    <template #default="{ item, index }">
      <div class="card">
        <div class="index">{{ index + 1 }}</div>
        <div class="title">{{ item.title }}</div>
      </div>
    </template>
  </ApplySwiper>
</template>

<script setup>
import { ref } from 'vue';
import { ApplySwiper } from 'applyswiper';

const items = ref([
  { title: '卡片 1' },
  { title: '卡片 2' },
  { title: '卡片 3' },
]);

const onCardChange = (index) => {
  console.log('切换到卡片:', index);
  // 可以在这里执行其他操作，如数据加载、埋点等
};
</script>

🎯 动画效果

组件使用 cubic-bezier(0.34, 1.8, 0.64, 1) 缓动函数，配合以下特性实现流畅的动画效果：

• 速度感应: 根据滑动速度自动切换卡片
• 橡皮筋效果: 边界处的弹性回弹
• 惯性滚动: 快速滑动时的惯性效果
• 精准停靠: 自动对齐到最近的卡片

🔧 开发

方式 1：通过 Vite 开发服务器（推荐）

# 安装依赖
npm install

# 启动开发服务器
npm run dev

然后在浏览器中访问显示的本地地址（通常是 http://localhost:5173）

方式 2：直接在浏览器中打开（无需构建）

直接用浏览器打开 example/index.html 文件即可预览效果，无需安装依赖或运行服务器。

构建发布版本

# 构建组件库
npm run build

构建后的文件将输出到 dist 目录。

📝 注意事项

1. 组件同时支持 rpx（uni-app）和 px（普通浏览器）单位
2. 在 uni-app 中使用 rpx，在普通 Vue 项目中使用 px
3. 需要在支持触摸事件的环境中使用（或使用鼠标拖拽）
4. 确保传入的 items 数组不为空

📄 License

ISC

👨‍💻 Author

wangwei

🤝 Contributing

欢迎提交 Issue 和 Pull Request！

如果这个项目对你有帮助，请给一个 ⭐️ Star 支持一下！