Pandora/README.md

# Pandora.js 完整 API 文档

## 1. 基础工具函数

### 1.1 alert - 自定义提示框

**说明**：重写原生 alert，提供美观的提示效果

**使用方式**：
```javascript
alert(content, speed = 800)
```

**参数**：
- `content` (string): 提示内容
- `speed` (number, 可选): 自动消失时间，默认 800ms

**示例**：
```javascript
alert('操作成功！')
alert('加载中...', 2000)  // 2秒后消失
```

**CSS 变量自定义**：
```css
:root {
  --alertTheme: #fff;        /* 背景色 */
  --alertBg: transparent;    /* 遮罩色 */
  --alertFontSize: 1rem;     /* 字体大小 */
  --alertColor: #000;        /* 字体颜色 */
}
```

---

### 1.2 confirm - 自定义确认框

**说明**：重写原生 confirm，返回 Promise

**使用方式**：
```javascript
confirm(config)
```

**参数**：
```javascript
{
  title: '标题',              // 可选
  content: '确认内容',        // 可选
  confirmText: '确认',        // 可选，默认"确认"
  cancelText: '取消',         // 可选，默认"取消"
  showConfirm: true,          // 可选，是否显示确认按钮
  showCancel: true            // 可选，是否显示取消按钮
}
```

**示例**：
```javascript
// 基础用法
confirm('确定要删除吗？').then(() => {
  console.log('确认')
}).catch(() => {
  console.log('取消')
})

// 完整配置
confirm({
  title: '提示',
  content: '是否继续操作？',
  confirmText: '继续',
  cancelText: '放弃'
}).then(() => {
  // 确认回调
}).catch(() => {
  // 取消回调
})
```

---

### 1.3 showLoading / hideLoading - 加载遮罩

**使用方式**：
```javascript
showLoading(progress = null)  // progress: 显示进度文字
hideLoading()
```

**示例**：
```javascript
showLoading()
setTimeout(() => hideLoading(), 2000)

showLoading('加载中 50%...')
setTimeout(() => hideLoading(), 2000)
```

---

## 2. DOM 操作

### 2.1 选择器方法

**说明**：支持 CSS 选择器语法，类似 jQuery

**示例**：
```javascript
const $ = Pandora

// 基础选择
$('.class')        // 类选择器
$('#id')           // ID 选择器
$('div')           // 标签选择器
$('.class .child') // 层级选择器

// 链式操作
$('#box')
  .find('.item')
  .eq(0)
  .addClass('active')
```

---

### 2.2 元素遍历与筛选

```javascript
// eq(index) - 选择指定下标元素
$('.item').eq(0).text()

// child(name) - 选择子级元素
$('#box').child('.item')

// find(name) - 查找所有子级元素
$('#box').find('.item')

// parent() - 选择父级
$('.item').parent()

// siblings(name) - 选择同级元素
$('.item').siblings()

// prev() - 上一个同级元素
$('.item').prev()

// next() - 下一个同级元素
$('.item').next()

// first() - 第一个元素
$('.item').first()

// last() - 最后一个元素
$('.item').last()

// each(fn) - 遍历元素
$('.item').each((el, index) => {
  console.log(index, el.text())
})
```

---

### 2.3 样式操作

```javascript
// css(name) - 获取样式
const color = $('#box').css('color')

// css({key: value}) - 设置样式
$('#box').css({
  'color': 'red',
  'font-size': '14px'
})

// show(callback) - 显示
$('#box').show(() => console.log('显示完成'))

// hide(callback) - 隐藏
$('#box').hide(() => console.log('隐藏完成'))

// fadeIn(speed, callback) - 淡入
$('#box').fadeIn('fast')     // fast: 快速
$('#box').fadeIn('slow')     // slow: 慢速
$('#box').fadeIn(5)          // 自定义速度

// fadeOut(speed, callback) - 淡出
$('#box').fadeOut('fast')

// offset() - 获取位置信息
const rect = $('#box').offset()
// { x, y, width, height, top, left, right, bottom }

// width(width) - 获取/设置宽度
const w = $('#box').width()
$('#box').width('100px')

// height(height) - 获取/设置高度
const h = $('#box').height()
$('#box').height('100px')
```

---

### 2.4 内容操作

```javascript
// text(str) - 获取/设置文本
const txt = $('#box').text()
$('#box').text('新内容')

// html(content) - 获取/设置HTML
const html = $('#box').html()
$('#box').html('<div>新内容</div>')

// val(value) - 获取/设置表单值
const v = $('#input').val()
$('#input').val('新值')
$('#select').val('option1')

// append(target) - 追加内容
$('#box').append('<div>追加内容</div>')
$('#box').append(domElement)

// prepend(target) - 前置内容
$('#box').prepend('<div>前置内容</div>')

// empty() - 清空容器
$('#box').empty()

// remove() - 移除元素
$('#box').remove()
```

---

### 2.5 属性与类名操作

```javascript
// attr(name, value) - 获取/设置属性
const src = $('#img').attr('src')
$('#box').attr('data-id', '123')
$('#box').attr({ 'data-id': '123', 'data-name': 'test' })

// removeAttr(name) - 移除属性
$('#box').removeAttr('data-id')

// addClass(name) - 添加类名
$('#box').addClass('active')

// removeClass(name) - 移除类名
$('#box').removeClass('active')

// hasClass(name) - 检查类名
if ($('#box').hasClass('active')) {
  // ...
}
```

---

### 2.6 事件操作

```javascript
// bind(eventName, fn, options) - 绑定事件
$('#box').bind('click', function() {
  console.log('点击')
}, { capture: false, once: false, passive: false })

// unbind(eventName) - 解绑事件
$('#box').unbind('click')

// click(fn) - 点击事件
$('#box').click((el, index) => {
  console.log('点击元素', index)
})

// dblclick(fn) - 双击事件
$('#box').dblclick(() => console.log('双击'))

// trigger(eventName) - 主动触发事件
$('#box').trigger('click')

// focus() - 获取焦点
$('#input').focus()

// blur() - 失去焦点
$('#input').blur()

// taping(fn, cb) - 长按事件
$('#box').taping(
  (ele) => console.log('长按中'),
  (ele) => console.log('长按结束')
)
```

---

## 3. 网络请求

### 3.1 ajax - AJAX 请求

**使用方式**：
```javascript
$('#').ajax({
  url: '/api/data',           // 接口地址
  type: 'get',                // 请求类型：get/post
  async: false,               // 是否异步
  headers: {                  // 请求头
    'Content-type': 'application/x-www-form-urlencoded'
  },
  dataType: 'json',           // 发送数据类型：json/form
  responseType: 'json',       // 返回体类型
  data: { name: 'value' },    // 发送数据
  progress: (p) => {          // 加载进度
    console.log(p + '%')
  },
  success: (res) => {         // 成功回调
    console.log(res)
  },
  error: (err) => {           // 失败回调
    console.error(err)
  }
})
```

**示例**：
```javascript
// GET 请求
$('#').ajax({
  url: '/api/users',
  type: 'get',
  async: true,
  success: (res) => console.log(res)
})

// POST 请求
$('#').ajax({
  url: '/api/users',
  type: 'post',
  dataType: 'json',
  data: { name: '张三', age: 18 },
  success: (res) => console.log(res)
})

// FormData 上传
const formData = new FormData()
formData.append('file', fileInput.files[0])

$('#').ajax({
  url: '/api/upload',
  type: 'post',
  dataType: 'form',
  data: formData,
  progress: (p) => console.log(p + '%'),
  success: (res) => console.log(res)
})

// 取消请求
window.cancelAjax()
```

---

### 3.2 fetch - Fetch API 封装

**使用方式**：
```javascript
$('#').fetch({
  url: '/api/data',
  type: 'get',              // get/post
  headers: {
    'Content-type': 'application/x-www-form-urlencoded'
  },
  data: { key: 'value' },   // 可选
  returnData: (res) => {    // 返回数据格式化
    return res.json()
  }
})
```

**示例**：
```javascript
// GET 请求
$('#').fetch({
  url: '/api/data',
  returnData: (res) => res.json()
}).then(data => console.log(data))

// POST 请求
$('#').fetch({
  url: '/api/data',
  type: 'post',
  data: { name: 'value' },
  returnData: (res) => res.json()
}).then(data => console.log(data))
```

---

## 4. 表单操作

### 4.1 serialize - 表单序列化

**说明**：将表单数据转换为对象

**示例**：
```javascript
const formData = $('#form').serialize()
// { username: 'admin', password: '123456' }
```

---

### 4.2 setForm - 设置表单值

**使用方式**：
```javascript
$('#form').setForm({
  username: 'admin',
  password: '123456',
  gender: 'male'      // radio
  hobbies: ['reading'] // checkbox
})
```

---

## 5. 模板渲染

### 5.1 Mush - Mustache 模板渲染

**使用方式**：
```javascript
$('#container').Mush({
  data: {                // 渲染数据
    name: '张三',
    age: 18
  },
  Init: (data) => {     // 首次渲染完成
    console.log('初始渲染', data)
  },
  Update: (data) => {   // 每次更新完成
    console.log('数据更新', data)
  }
})
```

**HTML 模板**：
```html
<div id="container">
  <p>姓名：{{name}}</p>
  <p>年龄：{{age}}</p>
</div>
```

**动态更新**：
```javascript
// 修改数据会自动更新视图
$('#container').setData({ name: '李四' })
```

---

### 5.2 全局数据管理

```javascript
// setData - 设置全局数据
$('#box').setData({
  userInfo: { name: '张三' },
  config: { theme: 'dark' }
})

// getData - 获取全局数据
const userInfo = $('#box').getData('userInfo')
```

---

### 5.3 template - 模板加载

**使用方式**：
```javascript
$('#container').template('home', document.body)
```

**HTML 模板定义**：
```html
<template route="home" src="/templates/home.html"></template>
```

---

## 6. 路由 - Router

**使用方式**：
```javascript
$('#app').Router({
  routes: [
    {
      path: '/',
      component: '/pages/home.html',
      callback: (state) => console.log('首页', state)
    },
    {
      path: '/about',
      component: '/pages/about.html',
      callback: (state) => console.log('关于', state)
    }
  ]
})

// 跳转路由
$('#app').to('/about')
$('#app').to('/about?id=123')
```

---

## 7. 轮播图 - Switcher

**使用方式**：
```javascript
$('#slider').Switcher({
  Speed: 1,              // 过渡速度(秒)
  Curve: 'ease',         // 动画曲线
  Effect: 'slider',      // 切换效果：slider/fade
  Direction: 'horizontal', // 方向：horizontal/vertical
  Inertia: true,         // 惯性回弹
  Distance: 3,           // 滑动比例
  AutoSpeed: 3,          // 自动切换间隔(秒)，0不自动
  Pagination: true,      // 分页器
  Hover: true,           // 悬浮停止
  Scroll: true,          // 滚轮滚动
  InitPage: 0,           // 初始页码
  Loop: true,            // 循环
  onChange: (index) => console.log('切换到', index),
  AutoResize: true       // 窗口变化自动调整
})

// 控制方法
$('#slider').prev()      // 上一页
$('#slider').next()      // 下一页
$('#slider').direct(2)   // 跳转到指定页
$('#slider').disable()   // 禁用
$('#slider').enable()    // 启用
```

**HTML 结构**：
```html
<div id="slider">
  <div class="item" data-title="1">...</div>
  <div class="item" data-title="2">...</div>
  <div class="item" data-title="3">...</div>
</div>
```

---

## 8. 响应式 - AutoSize

**使用方式**：
```javascript
$('#').AutoSize({
  PageSize: 'device-width', // 固定尺寸
  InitScale: 1,             // 初始缩放
  MinScale: 1,              // 最小缩放
  MaxScale: 1,              // 最大缩放
  Ratio: window.devicePixelRatio, // DPI缩放
  Resize: true,             // 窗口变化重新计算
  ScaleFont: true           // 缩放字体大小
})
```

---

## 9. 弹框 - Dialog

**使用方式**：
```javascript
$('#dialog').Dialog({
  mask: true,               // 显示遮罩
  maskColor: 'rgba(0,0,0,.85)',
  maskOut: true,            // 点击遮罩退出
  Speed: 180,               // 过渡速度(毫秒)
  Curve: 'ease-out',        // 过渡曲线
  Direction: 'zoom',        // 进出方式：none/zoom/top/bottom
  In: () => console.log('进入'),
  Out: () => console.log('退出'),
  Confirm: {
    btn: '.confirm-btn',
    callback: ({ param, close }) => {
      console.log('确认', param)
      close()
    }
  },
  Cancel: {
    btn: '.cancel-btn',
    callback: ({ param, close }) => {
      console.log('取消', param)
      close()
    }
  }
})

// 打开弹框
$('#dialog').open({ data: '参数' })

// 关闭弹框
$('#dialog').close()
```

**HTML 结构**：
```html
<div id="dialog" style="display:none">
  <div class="content">弹框内容</div>
  <button class="confirm-btn">确认</button>
  <button class="cancel-btn">取消</button>
</div>
```

---

## 10. 图片处理

### 10.1 ImgLoader - 图片预加载

**使用方式**：
```javascript
$('#container').ImgLoader({
  lazy: true,               // 渐进式
  loading: (progress) => {  // 加载进度
    console.log(progress + '%')
  },
  callback: () => {         // 加载完成
    console.log('全部加载完成')
  },
  error: (err) => {         // 加载错误
    console.error(err)
  }
})
```

---

### 10.2 ImgUpload - 图片上传

**使用方式**：
```javascript
$('#upload').ImgUpload({
  apiUrl: '/api/upload',    // 接口地址
  Format: '*',              // 格式限制：jpg/png/gif/*
  type: 'default',          // 选择类型：default/camera
  Max: 3,                   // 最大数量
  Quality: 100,             // 压缩比例
  Clip: {                   // 尺寸裁切
    width: null,
    height: null
  },
  alwaysCover: false,       // 总是覆盖
  Events: {
    overMax: () => console.log('超过限制'),
    ready: () => console.log('开始上传'),
    progress: (p) => console.log(p + '%'),
    success: (data) => console.log('上传成功', data),
    fail: () => console.log('上传失败')
  },
  Uid: 'user_123'           // 唯一ID
})
```

**HTML 结构**：
```html
<div id="upload">
  <button>选择图片</button>
</div>
```

---

### 10.3 ImgTransit - 图片移动缩放

**使用方式**：
```javascript
$('#container').ImgTransit({
  icon: true,               // 显示控制图标
  iconSize: 30,             // 图标大小
  border: true,             // 显示边框
  Gesture: false,           // 多点触控
  padding: 10,              // 内边距
  scale: {
    enable: true,
    min: 80,
    max: 150,
    rate: 1
  },
  rotate: {
    enable: true,
    rate: 1
  },
  delete: true,             // 启用删除
  bounds: true,             // 边界限制
  outBounds: 0,             // 可超出范围
  callback: (data) => {     // 操作回调
    console.log(data.type, data.obj)
  }
})
```

**HTML 结构**：
```html
<div id="container">
  <img src="1.jpg" alt="image1">
  <img src="2.jpg" alt="image2">
</div>
```

---

### 10.4 LazyLoad - 懒加载

**使用方式**：
```javascript
$('#container').LazyLoad({
  width: 100,               // 缺省尺寸
  height: 100,
  icon: '/loader.svg'       // 缺省图标
})
```

**HTML 结构**：
```html
<div id="container">
  <img data-src="1.jpg" data-width="200" data-height="150">
  <img data-src="2.jpg" data-width="200" data-height="150">
</div>
```

---

## 11. 微信 SDK - wxSDK

**使用方式**：
```javascript
$('#').wxSDK({
  apiUrl: '/api/wechat/sign', // 获取签名接口
  sdk: 'https://res.wx.qq.com/open/js/jweixin-1.6.0.js',
  title: ['分享至朋友圈', '分享至好友'],
  desc: '万事皆虚，万物皆允',
  shareIcon: 'https://example.com/icon.jpg',
  shareLinks: window.location.href,
  debug: false,
  jsApiList: ['chooseImage', 'previewImage'],
  openTagList: ['wx-open-launch-app'],
  callback: {
    ready: () => console.log('分享就绪'),
    success: () => console.log('分享成功'),
    error: () => console.log('分享失败')
  }
})
```

---

## 12. OSS 上传 - ossUpload

**使用方式**：
```javascript
const uploader = $('#').ossUpload({
  AccessId: 'your-access-id',
  AccessKey: 'your-access-key',
  Endpoint: 'https://bucket.oss-cn-hangzhou.aliyuncs.com',
  maxSize: 2  // MB
})

// 上传文件
uploader.start({
  fileObj: file,
  fileName: 'image',
  dirName: 'images',
  headers: null,
  async: true,
  progress: (p) => console.log(p + '%')
}).then(res => {
  console.log('上传成功', res.url)
}).catch(err => {
  console.error('上传失败', err)
})
```

---

## 13. 工具方法

### 13.1 guid - 生成唯一ID

```javascript
$('#box').pid  // 获取当前实例的GUID
```

---

### 13.2 extend - 对象合并

```javascript
const config = $('#box').extend({ a: 1 }, { b: 2 })
// { a: 1, b: 2 }
```

---

### 13.3 getParams - URL参数解析

```javascript
const params = $('#box').getParams()
// URL: ?id=123&name=test
// 返回: { id: '123', name: 'test' }
```

---

### 13.4 Array - 数组工具

```javascript
// 随机打乱
const shuffled = $('#box').Array.Random()

// 判断重复
const hasRepeat = $('#box').Array.hasRepeat()

// 数组求和
const sum = $('#box').Array.Sum()
```

---

## 14. 全局配置

### 禁用原生重写

```javascript
window.resetAlert = false   // 禁用 alert 重写
window.resetConfirm = false // 禁用 confirm 重写
```

---

## 15. 最佳实践示例

### 15.1 完整的 CRUD 操作

```javascript
// 列表加载
function loadList() {
  showLoading()
  $('#').ajax({
    url: '/api/users',
    type: 'get',
    async: true,
    success: (res) => {
      renderList(res.data)
      hideLoading()
    },
    error: () => {
      alert('加载失败')
      hideLoading()
    }
  })
}

// 渲染列表
function renderList(data) {
  const html = data.map(item => `
    <tr>
      <td>${item.id}</td>
      <td>${item.name}</td>
      <td>
        <button onclick="editUser(${item.id})">编辑</button>
        <button onclick="deleteUser(${item.id})">删除</button>
      </td>
    </tr>
  `).join('')
  $('#list').html(html)
}

// 添加用户
function addUser() {
  const formData = $('#form').serialize()
  showLoading()
  $('#').ajax({
    url: '/api/users',
    type: 'post',
    data: formData,
    success: () => {
      alert('添加成功')
      hideLoading()
      loadList()
    }
  })
}

// 删除用户
function deleteUser(id) {
  confirm({
    title: '确认删除',
    content: '确定要删除该用户吗？'
  }).then(() => {
    showLoading()
    $('#').ajax({
      url: `/api/users/${id}`,
      type: 'delete',
      success: () => {
        alert('删除成功')
        hideLoading()
        loadList()
      }
    })
  })
}
```

---

### 15.2 图片上传预览

```javascript
$('#upload').ImgUpload({
  apiUrl: '/api/upload',
  Max: 5,
  Events: {
    ready: () => showLoading(),
    progress: (p) => showLoading(`上传中 ${p}%`),
    success: (data) => {
      hideLoading()
      $('#preview').append(`<img src="${data.src}">`)
    },
    fail: () => {
      hideLoading()
      alert('上传失败')
    }
  }
})
```

---

### 15.3 轮播图完整实现

```javascript
$('#slider').Switcher({
  Speed: 0.8,
  Effect: 'slider',
  AutoSpeed: 3,
  Pagination: true,
  Hover: true,
  Loop: true,
  onChange: (index) => {
    $('.dot').removeClass('active')
    $('.dot').eq(index).addClass('active')
  }
})

// 绑定分页点击
$('.dot').click((el, index) => {
  $('#slider').direct(index)
})
```

---

### 15.4 模板渲染动态数据

```javascript
$('#user-info').Mush({
  data: {
    name: '张三',
    age: 18,
    avatar: '/avatar.jpg'
  },
  Init: (data) => {
    console.log('用户信息加载完成', data)
  },
  Update: (data) => {
    console.log('用户信息已更新', data)
  }
})

// 更新数据
$('#user-info').setData({ name: '李四', age: 20 })
```

---

### 15.5 SPA 路由应用

```javascript
$('#app').Router({
  routes: [
    { path: '/', component: '/pages/home.html' },
    { path: '/user', component: '/pages/user.html' },
    { path: '/detail', component: '/pages/detail.html' }
  ]
})

// 页面跳转
$('.nav-item').click((el) => {
  const path = el.attr('data-path')
  $('#app').to(path)
})
```

---

## 注意事项

1. **浏览器兼容性**：支持现代浏览器，需要 ES6 支持
2. **依赖文件**：需要 `base64.js` 和 `icoConfig.json`
3. **Crypto 依赖**：OSS 上传需要 Crypto 工具
4. **微信 SDK**：需要服务端签名支持
5. **图片路径**：确保图标路径正确

---

*文档版本：1.0.0*