# Alpine.js

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

## 1. 基本信息

| 项 | 内容 |
|---|---|
| 当前版本 | v3 线 |
| License | MIT |
| 维护方 | Caleb Porzio |
| 仓库 / 文档 | https://github.com/alpinejs/alpine · https://alpinejs.dev |
| 最近 release | 见官方 releases |

## 2. 一句话定位

在**服务端已渲染好的 HTML** 上补一层声明式状态：`x-data` / `x-show` / `x-for` / `x-on`。
它不负责渲染整页、不管路由，也不替代构建工具。

## 3. 体积

| 引入方式 | 体积 |
|---|---|
| 完整构建 | 约 15 KB（gzip，官方口径） |
| CSP 构建 | 略大，适配严格 CSP |

## 4. 核心 API

```html
<div x-data="{ color: 'black', open: false }">
  <button @click="color = 'blue'">蓝</button>
  <img :src="`/img/${color}.webp`" :class="{ 'is-active': color === 'blue' }">
  <div x-show="open" x-transition>面板</div>
</div>
```

```js
// 动态插入的区块（SPA / 局部刷新）需要手动初始化
Alpine.initTree(element);
Alpine.destroyTree(element);
```

## 5. 适用 / 不适用

- **适用**：颜色/规格切换、Tab、开合面板、移动端菜单、表单小状态；服务端渲染页面（Rails、Django 或任意模板引擎）。
- **不适用**：复杂单页应用的路由与数据层；高频动画（交给动画库）。

## 6. 硬缺口与已知坑

- 与命令式库（Swiper、Anime.js）是两种范式，需要 `x-init` 桥接，并注意销毁顺序。
- 严格 CSP 环境要用 CSP 构建，不能用内联表达式求值。
- 逻辑写多后会散落在 HTML 属性里，复杂度上来时应改用真正的组件方案。
- `x-for` 大列表性能一般，长列表需分页或虚拟滚动。

## 7. 受限环境可用性

| 环境 | 结论 | 说明 |
|---|---|---|
| 无构建（`<script defer>`） | 可用 | 官方主推用法 |
| ESM / 打包器 | 可用 | 支持模块化引入 |
| SSR | 友好 | 状态直接写在服务端渲染的 HTML 上 |
| 客户端重渲染 | 可用 | 容器重渲染后需 `Alpine.initTree` |

## 8. 稳定性评分

| 维度 | 评分 | 依据 |
|---|---|---|
| 维护活跃度 | 4 | 稳定迭代，节奏较缓 |
| 版本与破坏性变更 | 5 | v3 长期稳定 |
| 采用度 | 4 | 服务端渲染社区广泛使用 |
| 体积与按需 | 4 | 约 15 KB gzip，可接受 |
| 生态兼容 | 5 | 无框架绑定，任意后端可用 |
| License | 5 | MIT |

## 9. 替代品对比

| 库 | 优势 | 劣势 | 何时选它 |
|---|---|---|---|
| petite-vue | 体积更小（~6 KB） | 生态与指令较少 | 只需极简声明式绑定 |
| htmx | 以请求为中心，几乎不写 JS | 不适合纯前端状态 | 交互主要是局部刷新 |
| 原生 `<details>` + 少量 JS | 零依赖 | 状态复杂后难维护 | 简单开合 |
