yuantao/Pandora
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity
Files
3292f6c71d29c39102fb96cebc7efe9438d17006
Pandora/README.md

30 KiB
Raw Blame History

Pandora.js 完整 API 文档

📖 简介

Pandora.js 是一款专为新手优化的 JavaScript 插件，提供前端开发中常用的功能模块，API 设计简洁，支持链式调用。

核心特性

  • 轻量级：零依赖，开箱即用
  • 链式调用：大多数方法支持链式写法
  • 原生 JS：基于原生 JavaScript 实现，兼容性好
  • 功能丰富：涵盖 DOM 操作、网络请求、组件交互等

快速开始

<!-- 引入 Pandora.js -->
<script src="Pandora.js"></script>

<!-- 依赖文件 -->
<script src="src/base64.js"></script>

1️⃣ 基础工具函数

1.1 alert - 自定义提示框

功能说明：

  • 提供美观的自定义提示框，替代原生 alert
  • 支持自定义显示时间和主题样式
  • 支持点击遮罩立即关闭
  • 具有平滑的淡入淡出动画效果

使用方式：

alert(content, speed = 800)

参数说明：

  • content (string): 提示内容
  • speed (number, 可选): 自动消失时间（毫秒），默认 800ms

示例：

// 基础用法
alert('操作成功！')

// 自定义显示时间
alert('加载中...', 2000)  // 2秒后消失

CSS 变量自定义：

:root {
  --alertTheme: #fff;        /* 背景色 */
  --alertBg: transparent;    /* 遮罩色 */
  --alertFontSize: 1rem;     /* 字体大小 */
  --alertColor: #000;        /* 字体颜色 */
}

全局配置：

// 禁用 alert 重写
window.resetAlert = false

1.2 confirm - 自定义确认框

功能说明：

  • 提供美观的自定义确认框，替代原生 confirm
  • 返回 Promise 对象，支持异步回调
  • 支持自定义按钮文本、标题和内容
  • 支持显示/隐藏确认和取消按钮
  • 支持主题样式自定义

使用方式：

confirm(config)

参数说明：

{
  title: '标题',              // 可选
  content: '确认内容',        // 可选
  confirmText: '确认',        // 可选，默认"确认"
  cancelText: '取消',         // 可选，默认"取消"
  showConfirm: true,          // 可选，是否显示确认按钮
  showCancel: true,           // 可选，是否显示取消按钮
  success() {},               // 可选，确认回调
  fail() {}                   // 可选，取消回调
}

示例：

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

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

// 仅显示确认按钮
confirm({
  content: '操作完成',
  showCancel: false
}).then(() => {
  console.log('已确认')
})

CSS 变量自定义：

:root {
  --confirmTheme: #fff;          /* 背景色 */
  --confirmBg: transparent;      /* 遮罩色 */
  --confirmFontSize: 1rem;       /* 字体大小 */
  --confirmColor: #636363;       /* 字体颜色 */
  --confirmBtnBg: #fafafa;       /* 按钮背景 */
  --confirmBtnColor: #636363;    /* 按钮文字颜色 */
  --confirmBtnBorder: #f1f1f1;   /* 按钮边框颜色 */
}

全局配置：

// 禁用 confirm 重写
window.resetConfirm = false

1.3 showLoading / hideLoading - 加载遮罩

功能说明：

  • 显示全屏加载遮罩层
  • 支持显示进度文字或数字
  • 使用 SVG 加载动画图标
  • 可随时调用 hideLoading 关闭遮罩

使用方式：

showLoading(progress = null)
hideLoading()

参数说明：

  • progress (string | number, 可选): 显示进度文字或百分比

示例：

// 基础用法
showLoading()
setTimeout(() => hideLoading(), 2000)

// 显示进度
showLoading('加载中 50%...')
setTimeout(() => {
  showLoading('加载中 80%...')
  setTimeout(() => hideLoading(), 1000)
}, 1000)

// 显示数字进度
showLoading(25)  // 显示 25%

2️⃣ DOM 操作

2.1 选择器方法

功能说明：

  • 支持 CSS 选择器语法选择 DOM 元素
  • 返回 Pandora 实例，支持链式调用
  • 支持类选择器、ID 选择器、标签选择器等
  • 支持层级选择器

使用方式：

const $ = Pandora

示例：

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

// 链式操作
$('#box')
  .find('.item')
  .eq(0)
  .addClass('active')
  .css({ color: 'red' })

2.2 元素遍历与筛选

功能说明：

  • 支持通过索引选择指定元素
  • 支持选择父级、子级、同级元素
  • 支持遍历元素集合
  • 返回新的 Pandora 实例，支持链式调用

示例：

// eq(index) - 选择指定下标元素
$('.item').eq(0).text()
$('.item').eq(2).css('color', 'red')

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

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

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

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

// 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 样式操作

功能说明：

  • 支持获取和设置元素样式
  • 支持获取元素位置和尺寸信息
  • 支持显示/隐藏元素
  • 支持淡入淡出动画效果

示例：

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

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

// 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')
$('#box').width('50%')

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

2.4 内容操作

功能说明：

  • 支持获取和设置元素的文本内容
  • 支持获取和设置元素的 HTML 内容
  • 支持获取和设置表单元素的值
  • 支持在元素内部追加或前置内容

示例：

// 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 属性与类名操作

功能说明：

  • 支持获取和设置元素属性
  • 支持移除元素属性
  • 支持添加和移除 CSS 类名
  • 支持检查元素是否包含指定类名

示例：

// 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')
$('#box').addClass('active hidden')

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

// hasClass(name) - 检查类名
if ($('#box').hasClass('active')) {
  console.log('包含 active 类')
}

2.6 事件操作

功能说明：

  • 支持绑定和解绑事件
  • 支持点击、双击、长按等快捷事件
  • 支持主动触发事件
  • 支持焦点获取和失去

示例：

// 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 请求

功能说明：

  • 支持 GET 和 POST 请求
  • 支持同步和异步请求
  • 支持自定义请求头
  • 支持上传进度监听
  • 支持取消请求

使用方式：

$('#').ajax(config)

参数说明：

{
  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)
  }
}

示例：

// 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 封装

功能说明：

  • 基于 Fetch API 的简洁封装
  • 支持 GET 和 POST 请求
  • 支持自定义返回数据格式化
  • 返回 Promise 对象

使用方式：

$('#').fetch(config)

参数说明：

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

示例：

// 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 - 表单序列化

功能说明：

  • 自动遍历表单内所有带 name 属性的元素
  • 自动处理 input、select、radio、checkbox 等不同类型
  • 返回键值对对象，便于发送到服务器

示例：

const formData = $('#form').serialize()
// { username: 'admin', password: '123456', gender: 'male' }

4.2 setForm - 设置表单值

功能说明：

  • 根据对象键名自动匹配表单元素的 name 属性
  • 自动处理 input、select、radio、checkbox 等不同类型
  • 快速填充表单数据

使用方式：

$('#form').setForm(obj)

示例：

$('#form').setForm({
  username: 'admin',
  password: '123456',
  gender: 'male',      // radio
  hobbies: ['reading'] // checkbox
})

5️⃣ 模板渲染

5.1 Mush - Mustache 模板渲染

功能说明：

  • 支持 {{变量}} 格式的模板语法
  • 支持数据响应式，数据变化自动更新视图
  • 提供生命周期回调（Init、Update）
  • 简化前端数据绑定操作

使用方式：

$('#container').Mush(config)

参数说明：

{
  data: {                // 渲染数据
    name: '张三',
    age: 18
  },
  Init: (data) => {     // 首次渲染完成
    console.log('初始渲染', data)
  },
  Update: (data) => {   // 每次更新完成
    console.log('数据更新', data)
  }
}

示例：

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

// 初始化渲染
$('#container').Mush({
  data: {
    name: '张三',
    age: 18
  },
  Init: (data) => {
    console.log('初始渲染', data)
  },
  Update: (data) => {
    console.log('数据更新', data)
  }
})

// 动态更新（会自动更新视图）
$('#container').setData({ name: '李四' })

5.2 全局数据管理

功能说明：

  • 提供全局数据存储机制
  • 支持设置和获取全局数据
  • 配合 Mush 模板实现数据共享

示例：

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

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

5.3 template - 模板加载

功能说明：

  • 从 <template> 标签加载 HTML 模板
  • 支持从远程 URL 加载模板
  • 自动加载关联的 CSS 和 JS 文件
  • 简化页面组件化管理

使用方式：

$('#container').template(route, container)

示例：

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

// 加载模板
$('#container').template('home', document.body)

6️⃣ 路由 - Router

功能说明：

  • 基于 History API 实现单页应用路由
  • 支持路由参数传递
  • 自动处理 <a> 标签点击事件
  • 支持路由回调函数

使用方式：

$('#app').Router(config)

参数说明：

{
  routes: [
    {
      path: '/',
      component: '/pages/home.html',
      callback: (state) => console.log('首页', state)
    }
  ]
}

示例：

// 初始化路由
$('#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')

// 带参数跳转
$('#app').to('/detail?pid=123&name=test')

7️⃣ 轮播图 - Switcher

功能说明：

  • 支持滑动和淡入淡出两种切换效果
  • 支持触摸手势和鼠标滚轮控制
  • 支持自动播放和循环模式
  • 支持分页器和悬浮暂停

使用方式：

$('#slider').Switcher(config)

参数说明：

{
  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').Switcher({
  Speed: 1,
  Curve: 'ease',
  Effect: 'slider',
  Direction: 'horizontal',
  AutoSpeed: 3,
  Pagination: true,
  Hover: true,
  Loop: true,
  onChange: (index) => {
    console.log('切换到', index)
  }
})

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

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

功能说明：

  • 自动计算并设置 <meta name="viewport">
  • 根据屏幕尺寸设置根元素字体大小
  • 支持窗口变化时重新计算

使用方式：

$('#').AutoSize(config)

参数说明：

{
  PageSize: 'device-width', // 固定尺寸
  InitScale: 1,             // 初始缩放
  MinScale: 1,              // 最小缩放
  MaxScale: 1,              // 最大缩放
  Ratio: window.devicePixelRatio, // DPI缩放
  Resize: true,             // 窗口变化重新计算
  ScaleFont: true           // 缩放字体大小
}

示例：

$('#').AutoSize({
  PageSize: 'device-width',
  Ratio: window.devicePixelRatio,
  Resize: true,
  ScaleFont: true
})

9️⃣ 弹框 - Dialog

功能说明：

  • 创建遮罩层和弹框元素
  • 支持多种进出动画效果（无、缩放、从上/下方进入）
  • 支持点击遮罩关闭
  • 支持确认和取消按钮回调

使用方式：

$('#dialog').Dialog(config)

参数说明：

{
  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').Dialog({
  mask: true,
  maskOut: true,
  Direction: 'zoom',
  Confirm: {
    btn: '.confirm-btn',
    callback: ({ close }) => {
      console.log('确认')
      close()
    }
  },
  Cancel: {
    btn: '.cancel-btn',
    callback: ({ close }) => {
      console.log('取消')
      close()
    }
  }
})

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

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

HTML 结构：

<div id="dialog" style="display:none">
  <div class="content">弹框内容</div>
  <button class="confirm-btn">确认</button>
  <button class="cancel-btn">取消</button>
</div>

🔟 图片处理

10.1 ImgLoader - 图片预加载

功能说明：

  • 自动解析 HTML 获取所有图片地址
  • 使用 Promise.all 批量加载图片
  • 支持 CSS 背景图加载
  • 支持容器内和全局两种模式

使用方式：

$('#container').ImgLoader(config)

参数说明：

{
  lazy: true,               // 渐进式
  loading: (progress) => {  // 加载进度
    console.log(progress + '%')
  },
  callback: () => {         // 加载完成
    console.log('全部加载完成')
  },
  error: (err) => {         // 加载错误
    console.error(err)
  }
}

示例：

// 容器内图片预加载
$('#container').ImgLoader({
  lazy: true,
  loading: (progress) => {
    showLoading(`加载中 ${progress}%`)
  },
  callback: () => {
    hideLoading()
  },
  error: (err) => {
    alert('加载失败')
  }
})

// 全局图片预加载
$().ImgLoader({
  lazy: false,
  loading: (progress) => console.log(progress + '%'),
  callback: () => console.log('加载完成')
})

10.2 ImgUpload - 图片上传

功能说明：

  • 使用 FormData 上传文件
  • 支持图片压缩和尺寸裁切
  • 支持拖拽上传
  • 支持多文件上传

使用方式：

$('#upload').ImgUpload(config)

参数说明：

{
  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
}

示例：

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

HTML 结构：

<div id="upload">
  <button>选择图片</button>
</div>

10.3 ImgTransit - 图片移动缩放

功能说明：

  • 支持图片移动、缩放、旋转操作
  • 支持多点触控手势
  • 支持边界限制
  • 提供控制图标和边框显示

使用方式：

$('#container').ImgTransit(config)

参数说明：

{
  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)
  }
}

示例：

$('#container').ImgTransit({
  icon: true,
  scale: { enable: true, min: 50, max: 200 },
  rotate: { enable: true },
  delete: true,
  bounds: true,
  callback: (data) => {
    console.log('操作类型:', data.type)
  }
})

HTML 结构：

<div id="container">
  <img src="1.jpg" alt="image1">
  <img src="2.jpg" alt="image2">
</div>

10.4 LazyLoad - 懒加载

功能说明：

  • 监听滚动事件检测元素位置
  • 当图片进入视口时延迟加载
  • 支持自定义缺省尺寸和图标

使用方式：

$('#container').LazyLoad(config)

参数说明：

{
  width: 100,               // 缺省尺寸
  height: 100,
  icon: '/loader.svg'       // 缺省图标
}

示例：

$('#container').LazyLoad({
  width: 200,
  height: 150,
  icon: '/loader.svg'
})

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>

1️⃣1️⃣ 微信 SDK - wxSDK

功能说明：

  • 动态加载微信 JS-SDK
  • 配置微信分享参数
  • 支持服务端签名

使用方式：

$('#').wxSDK(config)

参数说明：

{
  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('分享失败')
  }
}

示例：

$('#').wxSDK({
  apiUrl: '/api/wechat/sign',
  title: ['分享标题', '分享标题'],
  desc: '分享描述',
  shareIcon: 'https://example.com/icon.jpg',
  shareLinks: window.location.href,
  debug: false,
  jsApiList: ['chooseImage', 'previewImage'],
  callback: {
    ready: () => console.log('分享就绪'),
    success: () => console.log('分享成功'),
    error: () => console.log('分享失败')
  }
})

1️⃣2️⃣ OSS 上传 - ossUpload

功能说明：

  • 使用阿里云 OSS 客户端签名上传
  • 支持文件大小限制
  • 支持上传进度监听

使用方式：

const uploader = $('#').ossUpload(config)
uploader.start(options)

参数说明：

{
  AccessId: 'your-access-id',
  AccessKey: 'your-access-key',
  Endpoint: 'https://bucket.oss-cn-hangzhou.aliyuncs.com',
  maxSize: 2  // MB
}

// start 参数
{
  fileObj: file,
  fileName: 'image',
  dirName: 'images',
  headers: null,
  async: true,
  progress: (p) => console.log(p + '%')
}

示例：

const uploader = $('#').ossUpload({
  AccessId: 'your-access-id',
  AccessKey: 'your-access-key',
  Endpoint: 'https://bucket.oss-cn-hangzhou.aliyuncs.com',
  maxSize: 2
})

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

1️⃣3️⃣ 工具方法

13.1 guid - 生成唯一ID

功能说明：

  • 生成 UUID 格式的唯一标识符
  • 每个实例自动分配唯一 ID

示例：

$('#box').pid  // 获取当前实例的GUID
// 例如: PandoraEX_3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b

13.2 extend - 对象合并

功能说明：

  • 将默认配置与用户配置合并
  • 实现配置对象的扩展

示例：

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

13.3 getParams - URL参数解析

功能说明：

  • 解析 URL 查询字符串
  • 返回键值对对象

示例：

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

13.4 Array - 数组工具

功能说明：

  • 提供数组随机打乱、判断重复、求和等常用操作

示例：

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

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

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

1️⃣4️⃣ 全局配置

禁用原生重写

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

1️⃣5️⃣ 最佳实践示例

15.1 完整的 CRUD 操作

// 列表加载
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 图片上传预览

$('#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 轮播图完整实现

$('#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 模板渲染动态数据

$('#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 路由应用

$('#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. 图片路径：确保图标路径正确

📄 许可证

详见 LICENSE 文件

文档版本：2.0.0