# Swiper

> 分类：`libs/animation/` · 档位：**采纳** · 更新时间：2026-11-17

## 1. 基本信息

| 项 | 内容 |
|---|---|
| 当前版本 | 以仓库内 `swiper-bundle.min.js` 为准 |
| License | MIT |
| 维护方 | Vladimir Kharlampidi（nolimits4web） |
| 仓库 / 文档 | https://github.com/nolimits4web/swiper · https://swiperjs.com |
| 最近 release | 见官方 releases |

## 2. 一句话定位

做"可拖拽 / 可切换的滑动容器"：轮播、缩略图联动、循环浏览、分页。
它只解决滑动交互，不负责页面滚动与时间轴动画。

## 3. 体积（本仓库实测）

| 引入方式 | raw | gzip |
|---|---|---|
| `swiper-bundle.min.js`（整包） | 151,701 B | **41,915 B** |
| `swiper-bundle.min.css` | 18,459 B | 4,849 B |

按需只引 `core + navigation + pagination + thumbs + autoplay` 可显著低于整包，**建议后续改为模块化 import**。

## 4. 核心 API

```js
const main = new Swiper('#lssThumbMain', {
  slidesPerView: 1,
  navigation: { nextEl: '.lss-next', prevEl: '.lss-prev' },
  pagination: { el: '.lss-pagination', clickable: true },
});

new Swiper('#lssThumbNav', {
  slidesPerView: 4,
  watchSlidesProgress: true,
  thumbs: { swiper: main },
});

// 销毁（容器被重渲染时必须）
main.destroy(true, true);
```

## 5. 适用 / 不适用

- **适用**：商品多图、多视角细节、颜色变体切换、可拖拽图集、需要分页/循环的展示模块。
- **不适用**：纯滚动驱动的横向叙事（那属于 ScrollTrigger / sticky 的职责）；全屏整页切换（可用 fullPage 类方案）。

## 6. 硬缺口与已知坑

- 整包体积偏大，必须按需模块化。
- 与平滑滚动库共存时，滑动区域需要 `data-lenis-prevent`，否则拖拽会与 Lenis 抢事件。
- 容器被重渲染（SPA / 局部刷新）会残留实例，必须 `destroy(true, true)` 后再初始化。
- 命令式 API，与 Alpine 这类声明式库需要 `x-init` 桥接。

## 7. 受限环境可用性

| 环境 | 结论 | 说明 |
|---|---|---|
| 无构建（`<script>`） | 可用 | 直接引 bundle |
| ESM / 打包器 | 可用 | 推荐模块化引入 |
| SSR | 需守卫 | 客户端初始化 |
| 客户端重渲染 | 可用 | 需 destroy / 重新 init |

## 8. 稳定性评分

| 维度 | 评分 | 依据 |
|---|---|---|
| 维护活跃度 | 5 | 长期高频维护 |
| 版本与破坏性变更 | 4 | 大版本有迁移指南 |
| 采用度 | 5 | 主流站点大量使用 |
| 体积与按需 | 3 | 整包偏大，模块化后改善 |
| 生态兼容 | 5 | 纯 JS，无框架绑定 |
| License | 5 | MIT |

## 9. 替代品对比

| 库 | 优势 | 劣势 | 何时选它 |
|---|---|---|---|
| Embla Carousel | 体积极小、无依赖、手感好 | 插件生态少，thumbs 需自己接 | 追求极致体积的简单滑动 |
| Splide | 无障碍支持好、功能全 | 体积仍偏大 | 需要 a11y 完整方案 |
| 原生 CSS scroll-snap | 零依赖 | 无分页/联动/循环控制 | 只做静态横滑 |
