# xjs

一个**“最小可用、可直接用 `<script>` 引入”**的现代化前端工具库，面向 **网站 / H5 / App WebView** 的轻量组件集成场景。

核心设计理念是 **"All in One Selector"** —— 一个全局函数 `animal` (可别名为 `$`) 既是选择器，也是功能入口。

## ✨ 核心特性

1.  **极简集成**: 零构建工具依赖，直接引入即可使用。
2.  **统一入口**: 使用 `animal('.selector')` 统一管理动画与交互。
3.  **高性能**: 优先使用 WAAPI (Web Animations API) 运行在合成线程。
4.  **模块化**: 包含 **Animal** (动画) 和 **Layer** (弹窗) 两个核心能力。

---

## 📦 安装与引入

```html
<!-- 1. 引入动画引擎 (导出全局变量 animal) -->
<script src="animal.js"></script>

<!-- 2. 引入弹窗组件 (导出全局变量 Layer) -->
<script src="layer.js"></script>
```

---

## 🚀 快速上手

为了获得最佳体验，建议将 `animal` 赋值给 `$` (或其他你喜欢的简写)。

```javascript
// 建立简写别名
const $ = animal;
```

### 1. 基础动画 (`.animate`)

```javascript
$('.box').animate({
  x: 200,             // 自动处理 transform
  scale: 1.5,
  opacity: 0.5,
  backgroundColor: '#f00', 
  duration: 800,
  easing: 'ease-out'
}).then(() => {
  console.log('Animation done');
});
```

### 2. 弹窗交互 (`.layer`)

直接在选择器上绑定点击弹窗事件。

```javascript
// 点击按钮触发弹窗
$('.btn-delete').layer({
  title: '确定删除?',
  text: '此操作不可恢复',
  icon: 'warning',
  showCancelButton: true
});
```

### 3. SVG 描边 (`.draw`)

```javascript
$('path').draw({ 
  duration: 1500,
  easing: 'ease-in-out'
});
```

---

## 📚 详细功能

### Animal: 动画引擎

#### 物理弹簧 (Spring)
无需配置复杂的贝塞尔曲线，使用物理参数即可。

```javascript
$('.card').animate({
  y: [100, 0],
  easing: { stiffness: 200, damping: 10 }
});
```

#### 视口触发 (InView)
元素进入屏幕可视区域时自动播放。

```javascript
$('.fade-up').inViewAnimate({
  y: [50, 0],
  opacity: [0, 1],
  duration: 600
}, { once: true });
```

#### 滚动驱动 (Scroll)
将动画进度绑定到页面滚动条。

```javascript
const controls = $('.progress').animate({ 
  width: ['0%', '100%'], 
  autoplay: false 
});

// 使用静态方法 $.scroll 绑定
$.scroll(controls);
```

#### 时间轴 (Timeline)
编排串行复杂的动画序列。

```javascript
const tl = $.timeline();

tl.add('.box-1', { x: 100 })
  .add('.box-2', { x: 100 }, '-=200') // 提前 200ms
  .play();
```

---

### Layer: 弹出层

虽然推荐使用 `$('.el').layer(...)` 绑定事件，但你也完全可以通过全局对象手动调用。

#### 基础弹窗 (直接调用 $.layer)
```javascript
$.layer({
  title: 'Hello World',
  text: 'This is a message from $.layer()'
});
```

#### Confirm 确认流程
```javascript
$.layer({
  title: '提交表单?',
  showCancelButton: true
}).then((res) => {
  if (res.isConfirmed) {
    $.layer({ title: '提交成功!', icon: 'success' });
  }
});
```

#### 弹窗内容支持 DOM/HTML
```javascript
// 传入 DOM 元素
$.layer({
  title: 'Custom Content',
  content: document.querySelector('#my-template')
});

// 或者传入 HTML 字符串
$.layer({
  html: '<strong>Bold Text</strong><br>New line'
});
```

#### 配置参数表
| 参数名 | 说明 |
| :--- | :--- |
| `title` | 标题 |
| `text` | 正文 (纯文本) |
| `html` | 正文 (HTML 字符串) |
| `content` | 正文 (DOM 元素或 CSS 选择器) |
| `icon` | `success` / `error` / `warning` |
| `showCancelButton` | 是否显示取消按钮 (默认 false) |
| `confirmButtonText` | 确认按钮文字 (默认 OK) |
| `cancelButtonText` | 取消按钮文字 (默认 Cancel) |

---

## 🛠️ API 速查表

| 调用方式 | 描述 |
| :--- | :--- |
| **`$(selector)`** | **核心选择器**，返回 Selection 对象 |
| `Selection.animate(params)` | 执行动画 |
| `Selection.draw(params)` | SVG 描边动画 |
| `Selection.layer(options)` | 绑定点击弹窗 |
| `Selection.inViewAnimate(...)` | 进入视口触发动画 |
| **`$.spring(config)`** | 创建物理缓动函数 |
| **`$.timeline()`** | 创建时间轴 |
| **`$.scroll(controls)`** | 绑定滚动驱动 |
| **`$.layer(options)`** | **直接弹出窗口 (别名 $.fire)** |