xjs

xjs

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

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

项目贡献/扩展开发的规范与流程请看：Guide.md

✨ 核心特性

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

---

📦 安装与引入

<!-- 开发/测试（推荐）：xjs.js 会自动加载 animal.js + layer.js -->
<script src="xjs.js"></script>

引入后会得到这些全局变量：

• xjs（推荐统一使用，也是一个 selector 函数）
• animal（兼容别名，等同于 xjs）
• Layer

如果你确实想全局占用 $（可能与 jQuery 冲突），在引入前设置：

<script>window.XJS_GLOBAL_DOLLAR = true;</script>
<script src="xjs.js"></script>

生产构建（合并为单文件）

开发阶段请只修改 animal.js / layer.js（不要手改合并产物）。

运行下面命令会把两个源文件合并输出到 dist/xjs.js：

go run main.go build

你也可以指定输出路径：

go run main.go build xjs.bundle.js

---

🚀 快速上手

示例中统一直接使用 xjs(...)，不再额外定义 $ 等别名（避免与其他库冲突，也更清晰）。

1. 基础动画 (.animate)

xjs('.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)

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

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

3. SVG 描边 (.draw)

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

---

📚 详细功能

Animal: 动画引擎

物理弹簧 (Spring)

无需配置复杂的贝塞尔曲线，使用物理参数即可。

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

视口触发 (InView)

元素进入屏幕可视区域时自动播放。

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

滚动驱动 (Scroll)

将动画进度绑定到页面滚动条。

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

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

时间轴 (Timeline)

编排串行复杂的动画序列。

const tl = xjs.timeline();

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

---

Layer: 弹出层

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

基础弹窗 (直接调用 xjs.layer)

xjs.layer({
  title: 'Hello World',
  text: 'This is a message from xjs.layer()'
});

Confirm 确认流程

xjs.layer({
  title: '提交表单?',
  showCancelButton: true
}).then((res) => {
  if (res.isConfirmed) {
    xjs.layer({ title: '提交成功!', icon: 'success' });
  }
});

弹窗内容支持 DOM/HTML

// 传入 DOM 元素
xjs.layer({
  title: 'Custom Content',
  content: document.querySelector('#my-template')
});

// 或者传入 HTML 字符串
xjs.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 速查表

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