React Tiny Swiper

一个轻量级的 React 轮播组件，支持无限滚动、自动播放、缩放效果等功能。

特性

• 🚀 轻量级 - 体积小，性能优秀
• 📱 移动端友好 - 支持触摸手势，自动检测移动设备
• 🔄 无限滚动 - 支持无限循环轮播
• ⚡ 自动播放 - 可配置自动轮播功能
• 🎨 缩放效果 - 支持卡片缩放效果
• 🎯 TypeScript - 完整的 TypeScript 支持
• 🎪 灵活配置 - 丰富的配置选项

安装

npm install rc-tiny-swiper

基础用法

import React from 'react';
import Swiper from 'rc-tiny-swiper';

const data = [
  { id: 1, title: 'Slide 1' },
  { id: 2, title: 'Slide 2' },
  { id: 3, title: 'Slide 3' },
];

const App = () => {
  const renderItem = (item) => (
    <div style={{ 
      width: '200px', 
      height: '200px', 
      background: '#f0f0f0',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center'
    }}>
      {item.title}
    </div>
  );

  return (
    <Swiper
      list={data}
      renderItem={renderItem}
    />
  );
};

高级用法

无限滚动 + 自动播放

import React from 'react';
import Swiper from 'rc-tiny-swiper';

const App = () => {
  const data = [
    { color: 'red', text: 'Red' },
    { color: 'blue', text: 'Blue' },
    { color: 'green', text: 'Green' },
    { color: 'yellow', text: 'Yellow' },
  ];

  const renderItem = ({ color, text }) => (
    <div style={{
      width: '200px',
      height: '400px',
      background: color,
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      color: 'white',
      fontSize: '24px'
    }}>
      {text}
    </div>
  );

  return (
    <Swiper
      list={data}
      renderItem={renderItem}
      infinite
      autoPlay
      autoPlayDuration={3000}
      showPage
    />
  );
};

缩放效果

import React from 'react';
import Swiper from 'rc-tiny-swiper';

const App = () => {
  const data = [
    { color: 'red' },
    { color: 'blue' },
    { color: 'green' },
  ];

  const renderItem = ({ color }) => (
    <div style={{
      width: '160px',
      height: '400px',
      background: color,
    }} />
  );

  return (
    <div style={{ paddingLeft: '18px' }}>
      <Swiper
        list={data}
        renderItem={renderItem}
        scale={0.92}
        infinite
      />
    </div>
  );
};

使用 Ref 控制轮播

import React, { useRef } from 'react';
import Swiper, { SwiperMethods } from 'rc-tiny-swiper';

const App = () => {
  const swiperRef = useRef<SwiperMethods>(null);
  
  const data = [
    { color: 'red' },
    { color: 'blue' },
    { color: 'green' },
  ];

  const renderItem = ({ color }) => (
    <div style={{
      width: '200px',
      height: '400px',
      background: color,
    }} />
  );

  return (
    <div>
      <Swiper
        ref={swiperRef}
        list={data}
        renderItem={renderItem}
        infinite
      />
      <div>
        <button onClick={() => swiperRef.current?.pre()}>
          上一张
        </button>
        <button onClick={() => swiperRef.current?.next()}>
          下一张
        </button>
        <button onClick={() => swiperRef.current?.swiperTo(0)}>
          跳转到第一张
        </button>
      </div>
    </div>
  );
};

事件处理

import React from 'react';
import Swiper from 'rc-tiny-swiper';

const App = () => {
  const data = [
    { id: 1, title: 'Slide 1' },
    { id: 2, title: 'Slide 2' },
  ];

  const renderItem = (item) => (
    <div style={{ 
      width: '200px', 
      height: '200px', 
      background: '#f0f0f0' 
    }}>
      {item.title}
    </div>
  );

  return (
    <Swiper
      list={data}
      renderItem={renderItem}
      clickItem={(item) => console.log('点击了:', item)}
      triggerActive={(index) => console.log('当前索引:', index)}
      startTouch={() => console.log('开始触摸')}
      endTouch={() => console.log('结束触摸')}
    />
  );
};

API

SwiperProps

| 属性 | 类型 | 默认值 | 描述 | |------|------|--------|------| | list | Array<T> | [] | 轮播数据数组 | | renderItem | (item: T, index: number) => ReactNode | - | 渲染函数，必需 | | autoPlay | boolean | false | 是否自动播放 | | autoPlayDuration | number | 3000 | 自动播放间隔时间（毫秒） | | autoPlayTouchStop | boolean | false | 触摸时是否停止自动播放 | | infinite | boolean | false | 是否无限滚动 | | showPage | boolean | false | 是否显示页码 | | scale | number | 0 | 缩放比例（0-1之间的小数） | | fullContent | boolean | false | 是否全屏内容 | | initial | number | 0 | 初始显示索引 | | transitionDuration | number | 300 | 过渡动画时长（毫秒） | | disabledLeftAndRight | boolean | false | 是否禁用左右滑动 | | clickItem | (item: T) => void | - | 点击项目回调 | | triggerActive | (index: number) => void | - | 索引变化回调 | | triggerMovedActive | (index: number) => void | - | 移动中索引回调 | | startTouch | (...args: any[]) => void | - | 开始触摸回调 | | endTouch | (...args: any[]) => void | - | 结束触摸回调 | | scrollEnd | (...args: any[]) => void | - | 滚动结束回调 |

SwiperMethods

通过 ref 可以调用的方法：

| 方法 | 参数 | 描述 | |------|------|------| | swiperTo | (index: number) => void | 跳转到指定索引 | | next | () => void | 下一张 | | pre | () => void | 上一张 |

样式定制

组件使用 CSS 类名进行样式控制，你可以通过覆盖这些类名来自定义样式：

.wrap-swipper {
  /* 轮播容器样式 */
}

.wrap-swipper .swiper {
  /* 轮播内容区域样式 */
}

.wrap-swipper .swiper-item {
  /* 轮播项样式 */
}

.wrap-swipper .item {
  /* 页码指示器样式 */
}

注意事项

1. 移动端优化: 组件会自动检测移动设备并启用触摸事件
2. 性能优化: 使用 will-change: transform 和 transform: translateZ(0) 进行硬件加速
3. 无限滚动: 当启用无限滚动时，组件会自动复制首尾元素以实现无缝循环
4. 缩放效果: 缩放功能主要用于创建卡片式轮播效果
5. 事件处理: 组件支持鼠标和触摸事件，在桌面端和移动端都能正常工作

开发

# 安装依赖
npm install

# 构建
npm run build

# 查看示例
cd example
npm install
npm run dev

许可证

ISC

贡献

欢迎提交 Issue 和 Pull Request！