@an1r0ny/skyline-swiper/README.md

微信小程序轮播组件 - 支持Skyline渲染模式

# Sky Swiper

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

## 特性

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

## 重要说明

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

## 安装

```bash
npm install @an1r0ny/sky-swiper
```

## 使用方法

### 1. 启用Skyline渲染模式

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

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

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

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

### 2. 安装依赖后构建npm

在微信开发者工具中：
1. 点击菜单栏 "工具" → "构建npm"
2. 确保构建成功

### 3. 在page.json中注册组件

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

### 4. 在wxml中使用

```xml
<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>
```

**开启循环轮播：**

```xml
<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中处理事件

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

## 自定义滑块变换

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

### 基本用法

```javascript
// 获取组件实例
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`

### 示例效果

**卡片堆叠效果：**
```javascript
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旋转效果：**
```javascript
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'
  };
});
```

**淡入淡出效果：**
```javascript
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

## 开发

```bash
# 安装依赖
npm install

# 构建
npm run build

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

MIT