Sky Swiper

微信小程序轮播组件，支持Skyline渲染模式，提供流畅的滑动体验。

特性

• 🚀 基于Skyline渲染引擎，性能优秀
• 📱 支持水平和垂直滑动
• 🎯 可配置弹性回弹效果
• ⚡ 支持动画过渡
• 🔧 丰富的配置选项

重要说明

⚠️ 此组件必须在Skyline渲染模式下使用才能正常工作！

安装

npm install @an1r0ny/sky-swiper

使用方法

1. 启用Skyline渲染模式

在 app.json 中启用Skyline渲染模式：

{
  "renderer": "skyline",
  "rendererOptions": {
    "skyline": {
      "disableABTest": true
    }
  },
  "componentFramework": "glass-easel"
}

或者在页面的 page.json 中启用：

{
  "renderer": "skyline",
  "componentFramework": "glass-easel"
}

2. 安装依赖后构建npm

在微信开发者工具中：

1. 点击菜单栏 "工具" → "构建npm"
2. 确保构建成功

3. 在page.json中注册组件

{
  "usingComponents": {
    "sky-swiper": "@an1r0ny/sky-swiper/sky-swiper",
    "sky-swiper-slide": "@an1r0ny/sky-swiper/sky-swiper-slide"
  }
}

4. 在wxml中使用

<sky-swiper current="{{current}}" bind:change="onChange">
  <sky-swiper-slide>
    <view class="slide-content">slide 1</view>
  </sky-swiper-slide>
  <sky-swiper-slide>
    <view class="slide-content">slide 2</view>
  </sky-swiper-slide>
  <sky-swiper-slide>
    <view class="slide-content">slide 3</view>
  </sky-swiper-slide>
</sky-swiper>

开启循环轮播：

<sky-swiper current="{{current}}" circular="{{true}}" bind:change="onChange">
  <sky-swiper-slide>
    <view class="slide-content">slide 1</view>
  </sky-swiper-slide>
  <sky-swiper-slide>
    <view class="slide-content">slide 2</view>
  </sky-swiper-slide>
  <sky-swiper-slide>
    <view class="slide-content">slide 3</view>
  </sky-swiper-slide>
  <sky-swiper-slide>
    <view class="slide-content">slide 4</view>
  </sky-swiper-slide>
</sky-swiper>

5. 在js中处理事件

Page({
  data: {
    current: 0
  },
  onChange(e) {
    this.setData({
      current: e.detail.current
    });
  }
});

自定义滑块变换

你可以通过 setSlideTransform 方法设置自定义的滑块变换效果，实现各种炫酷的动画效果。

基本用法

// 获取组件实例
const swiperComponent = this.selectComponent('#my-swiper');

// 设置自定义变换函数
swiperComponent.setSlideTransform((distance, slideSize, pxPerRpx) => {
  'worklet';
  
  // distance: 当前滑块与中心位置的距离（可为负数）
  // slideSize: 滑块尺寸（水平模式为宽度，垂直模式为高度）
  // pxPerRpx: px与rpx的转换比例
  
  const offset = distance * slideSize;
  const scale = 1 - Math.abs(distance) * 0.2; // 缩放效果
  const opacity = 1 - Math.abs(distance) * 0.3; // 透明度效果
  
  return {
    transform: `translateX(${offset}px) scale(${scale})`,
    opacity: Math.max(0.1, opacity),
    transformOrigin: 'center'
  };
});

// 清除自定义变换，恢复默认效果
swiperComponent.clearSlideTransform();

变换函数参数说明

• distance: 当前滑块相对于中心位置的距离

  • 0: 当前显示的滑块
  • 1: 右侧/下方第一个滑块
  • -1: 左侧/上方第一个滑块
  • 支持小数，表示滑动过程中的中间状态

• slideSize: 滑块的尺寸（px）

  • 水平模式：滑块宽度
  • 垂直模式：滑块高度

• pxPerRpx: px与rpx的转换比例

  • 可用于将rpx单位转换为px：rpxValue / pxPerRpx

示例效果

卡片堆叠效果：

swiperComponent.setSlideTransform((distance, slideSize, pxPerRpx) => {
  'worklet';
  const offset = distance * slideSize;
  const scale = 1 - Math.abs(distance) * 0.1;
  const zIndex = 100 - Math.abs(distance);
  
  return {
    transform: `translateX(${offset}px) scale(${scale})`,
    zIndex: zIndex,
    transformOrigin: 'center'
  };
});

3D旋转效果：

swiperComponent.setSlideTransform((distance, slideSize, pxPerRpx) => {
  'worklet';
  const offset = distance * slideSize;
  const rotateY = distance * 45; // 旋转角度
  
  return {
    transform: `translateX(${offset}px) rotateY(${rotateY}deg)`,
    transformOrigin: 'center',
    transformStyle: 'preserve-3d'
  };
});

淡入淡出效果：

swiperComponent.setSlideTransform((distance, slideSize, pxPerRpx) => {
  'worklet';
  const offset = distance * slideSize;
  const opacity = Math.max(0, 1 - Math.abs(distance));
  
  return {
    transform: `translateX(${offset}px)`,
    opacity: opacity
  };
});

API

SkySwiper 属性

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | current | Number | 0 | 当前显示的滑块索引 | | bounce | Boolean | true | 是否开启回弹效果 | | vertical | Boolean | false | 是否为垂直滑动 | | withAnimation | Boolean | false | 切换时是否使用动画 | | cacheExtent | Number | 4 | 缓存范围 | | damping | Number | 20 | 阻尼系数 | | mass | Number | 2 | 质量 | | restDisplacementThreshold | Number | 0.01 | 静止位移阈值 | | restSpeedThreshold | Number | 2 | 静止速度阈值 | | disabled | Boolean | false | 是否禁用滑动 | | circular | Boolean | false | 是否开启循环轮播 | | minCircularSlides | Number | 4 | 启用循环轮播的最少滑块数量 |

SkySwiper 方法

| 方法名 | 参数 | 说明 | |--------|------|------| | setSlideTransform | transformFunction | 设置自定义滑块变换函数 | | clearSlideTransform | - | 清除自定义滑块变换函数 |

SkySwiper 事件

| 事件名 | 说明 | 返回值 | |--------|------|--------| | change | 滑块切换时触发 | { current: Number } | | transitionend | 动画结束时触发 | { current: Number } |

故障排除

如果手势滑动不生效，请检查：

1. ✅ 是否启用了Skyline渲染模式
2. ✅ 是否正确构建了npm包
3. ✅ 小程序基础库版本是否支持Skyline

开发

# 安装依赖
npm install

# 构建
npm run build

# 清理构建
npm run clean
```## 许可证

MIT