# Embla Carousel

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

## 1. 基本信息

| 项 | 内容 |
|---|---|
| 当前版本 | 8.x |
| License | MIT |
| 维护方 | David Jerleke |
| 仓库 / 文档 | https://github.com/davidjerleke/embla-carousel · https://www.embla-carousel.com |
| 最近 release | 见官方 releases |

## 2. 一句话定位

无样式的轮播引擎：只负责拖拽、吸附、循环与滚动进度，UI（箭头、分页、缩略图）全部自建。
它换取的是极小体积与顺滑手感，代价是所有界面与无障碍都要自己补。

## 3. 体积

| 引入方式 | min | gzip |
|---|---|---|
| 核心（ESM） | 约 20 KB | 约 6–8 KB（待实测） |
| 插件（Autoplay / WheelGestures 等） | 按需 | 每个约 1–3 KB |

## 4. 核心 API

```js
import EmblaCarousel from 'embla-carousel';

const embla = EmblaCarousel(root, { loop: true, align: 'start' });

embla.on('select', () => { /* 更新分页/箭头状态 */ });
embla.scrollPrev();
embla.scrollNext();
embla.scrollTo(2);
embla.destroy();
```

插件按需引入：`embla-carousel-autoplay`、`embla-carousel-wheel-gestures`、`embla-carousel-auto-height`。

## 5. 适用 / 不适用

- **适用**：自定义视觉的滑动区、移动端性能敏感场景、需要精细控制吸附与拖拽手感。
- **不适用**：需要开箱分页、缩略图联动、无障碍完善（Swiper 更省事）。

## 6. 硬缺口与已知坑

- 没有任何默认样式：容器 `overflow:hidden`、轨道 `display:flex`、幻灯片宽度都要自己写。
- 无障碍要手写 `aria-roledescription`、按钮标签与键盘处理。
- `loop` 在幻灯片数量很少时行为特殊，需要实测。
- SSR 必须先判断浏览器再初始化；动态重建前 `destroy()`。
- 高度自适应要装 `auto-height` 插件，否则会按最高项撑开。

## 7. 受限环境可用性

| 环境 | 结论 | 说明 |
|---|---|---|
| 无构建（UMD） | 可用 | 提供独立构建 |
| ESM / 打包器 | 可用 | 推荐方式 |
| SSR | 需守卫 | 仅浏览器初始化 |
| 客户端重渲染 | 需处理生命周期 | `destroy()` 后重新 init |

## 8. 稳定性评分

| 维度 | 评分 | 依据 |
|---|---|---|
| 维护活跃度 | 5 | 持续迭代，issue 响应快 |
| 版本与破坏性变更 | 4 | 大版本有迁移说明 |
| 采用度 | 4 | 设计与前端社区使用较多 |
| 体积与按需 | 5 | 核心约 6–8 KB |
| 生态兼容 | 5 | 无依赖，框架无关 |
| License | 5 | MIT |

## 9. 替代品对比

| 库 | 优势 | 劣势 | 何时选它 |
|---|---|---|---|
| Swiper | 功能最全，分页/缩略图/无障碍开箱 | 体积大 | 需要完整功能 |
| Splide | 无障碍好、功能均衡 | 体积中等 | 通用轮播 |
| Glide.js | 轻、API 简单 | 功能较少 | 简单滑动 |
| Keen Slider | 多滑块与复杂布局 | 学习曲线 | 多项目滑动 |
