资源描述
class-change.js 是一个轻量级（<1KB）前端 JavaScript 微库，专为声明式 CSS 类名动态管理设计。它通过 HTML data 属性（如 data-class-change）绑定 DOM 元素的类名变更逻辑，无需手动调用 classList API，显著降低事件监听与样式切换耦合度。适用于渐进式增强、无框架 SPA 组件、可访问性驱动交互（如焦点/悬停状态同步）、CMS 内容嵌入场景，兼顾性能与语义化开发体验。
详细内容
## class-change.js 框架简介与定位
class-change.js 是一个极简、零依赖的前端微库，专注于以声明式方式驱动 DOM 元素的 CSS 类名变更。它不替代现代框架的响应式系统，而是作为轻量级增强层，将类名操作从命令式 JavaScript（如 `el.classList.add()`）解耦为基于 HTML 数据属性的声明式配置，提升可维护性与可测试性。适用于需最小体积、无构建流程、或需在遗留系统中快速注入交互能力的场景。
## 核心特性
- **声明式绑定**：通过 `data-class-change` 属性定义触发条件（如 `hover`, `focus`, `click`, `scroll`），无需编写事件监听器代码。
- **多态类名控制**：支持 `add`, `remove`, `toggle`, `replace` 四种基础操作，并可通过 `data-class-add`, `data-class-remove` 等属性精确指定目标类名。
- **上下文感知**：自动识别事件源（target）与目标元素（由 `data-target` 指定），支持跨元素联动（如点击按钮切换另一元素类名）。
- **生命周期钩子**：提供 `data-on-change` 属性执行自定义回调函数，便于集成分析、动画触发或状态同步。
- **无障碍友好**：原生支持 `:focus-visible`、`aria-expanded` 同步等语义化交互模式，符合 WCAG 推荐实践。
## 适用场景
- 静态网站或 JAMstack 项目中实现交互式 UI（折叠面板、主题切换、表单状态反馈）；
- CMS（如 WordPress、Contentful）输出的富文本内容内嵌交互，避免污染后端模板逻辑；
- 作为现有 jQuery 或 Vanilla JS 项目的渐进式重构工具，逐步替换手写 classList 操作；
- 教学示例与原型开发，直观演示 DOM 状态与 CSS 类的映射关系；
- 对打包体积敏感的嵌入式 Web 组件（如第三方小工具、广告 banner）。
## 快速入门
### 安装
直接通过 `<script>` 标签引入（推荐 CDN）：
```html
<script src="https://cdn.jsdelivr.net/npm/class-change@1.2.0/dist/class-change.min.js"></script>
```
或使用 npm（适用于有构建流程的项目）：
```bash
npm install class-change
```
然后在模块中导入：
```js
import 'class-change'; // 自动初始化
// 或显式调用：
// import { init } from 'class-change';
// init();
```
### 最小示例
```html
<!-- 点击按钮切换侧边栏可见性 -->
<button data-class-change="click"
data-class-toggle="hidden"
data-target="#sidebar">
切换菜单
</button>
<div id="sidebar" class="hidden">...</div>
```
> ✅ 初始化后，无需额外 JS —— 库会自动扫描并激活所有 `data-class-*` 属性。
## 生态与社区
- 项目托管于 GitHub（[jhildenbiddle/class-change](https://github.com/jhildenbiddle/class-change)），采用 MIT 协议，文档与示例均开源；
- 无官方 CLI 或插件生态，但因其零依赖设计，可无缝集成 Webpack/Vite 的 tree-shaking，或与 Alpine.js、HTMX 等轻量框架共存；
- 社区活跃度适中，主要通过 GitHub Issues 提供问题反馈与用例分享，作者持续维护核心功能稳定性；
- 不提供 TypeScript 类型定义（`.d.ts`）文件，但属性命名遵循标准 HTML data-* 规范，可安全用于 TS 项目。