20 KiB
20 KiB
Pandora.js 完整 API 文档
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; /* 字体颜色 */
}
1.2 confirm - 自定义确认框
说明：重写原生 confirm，返回 Promise
使用方式：
confirm(config)
参数：
{
title: '标题', // 可选
content: '确认内容', // 可选
confirmText: '确认', // 可选，默认"确认"
cancelText: '取消', // 可选，默认"取消"
showConfirm: true, // 可选，是否显示确认按钮
showCancel: true // 可选，是否显示取消按钮
}
示例：
// 基础用法
confirm('确定要删除吗？').then(() => {
console.log('确认')
}).catch(() => {
console.log('取消')
})
// 完整配置
confirm({
title: '提示',
content: '是否继续操作？',
confirmText: '继续',
cancelText: '放弃'
}).then(() => {
// 确认回调
}).catch(() => {
// 取消回调
})
1.3 showLoading / hideLoading - 加载遮罩
使用方式：
showLoading(progress = null) // progress: 显示进度文字
hideLoading()
示例：
showLoading()
setTimeout(() => hideLoading(), 2000)
showLoading('加载中 50%...')
setTimeout(() => hideLoading(), 2000)
2. DOM 操作
2.1 选择器方法
说明：支持 CSS 选择器语法，类似 jQuery
示例：
const $ = Pandora
// 基础选择
$('.class') // 类选择器
$('#id') // ID 选择器
$('div') // 标签选择器
$('.class .child') // 层级选择器
// 链式操作
$('#box')
.find('.item')
.eq(0)
.addClass('active')
2.2 元素遍历与筛选
// 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 样式操作
// 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 内容操作
// 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 属性与类名操作
// 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 事件操作
// 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 请求
使用方式：
$('#').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)
}
})
示例：
// 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({
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 - 表单序列化
说明：将表单数据转换为对象
示例：
const formData = $('#form').serialize()
// { username: 'admin', password: '123456' }
4.2 setForm - 设置表单值
使用方式：
$('#form').setForm({
username: 'admin',
password: '123456',
gender: 'male' // radio
hobbies: ['reading'] // checkbox
})
5. 模板渲染
5.1 Mush - Mustache 模板渲染
使用方式：
$('#container').Mush({
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').setData({ name: '李四' })
5.2 全局数据管理
// setData - 设置全局数据
$('#box').setData({
userInfo: { name: '张三' },
config: { theme: 'dark' }
})
// getData - 获取全局数据
const userInfo = $('#box').getData('userInfo')
5.3 template - 模板加载
使用方式：
$('#container').template('home', document.body)
HTML 模板定义：
<template route="home" src="/templates/home.html"></template>
6. 路由 - Router
使用方式：
$('#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
使用方式：
$('#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 结构：
<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
使用方式：
$('#').AutoSize({
PageSize: 'device-width', // 固定尺寸
InitScale: 1, // 初始缩放
MinScale: 1, // 最小缩放
MaxScale: 1, // 最大缩放
Ratio: window.devicePixelRatio, // DPI缩放
Resize: true, // 窗口变化重新计算
ScaleFont: true // 缩放字体大小
})
9. 弹框 - Dialog
使用方式：
$('#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 结构：
<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 - 图片预加载
使用方式：
$('#container').ImgLoader({
lazy: true, // 渐进式
loading: (progress) => { // 加载进度
console.log(progress + '%')
},
callback: () => { // 加载完成
console.log('全部加载完成')
},
error: (err) => { // 加载错误
console.error(err)
}
})
10.2 ImgUpload - 图片上传
使用方式：
$('#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 结构：
<div id="upload">
<button>选择图片</button>
</div>
10.3 ImgTransit - 图片移动缩放
使用方式：
$('#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 结构：
<div id="container">
<img src="1.jpg" alt="image1">
<img src="2.jpg" alt="image2">
</div>
10.4 LazyLoad - 懒加载
使用方式：
$('#container').LazyLoad({
width: 100, // 缺省尺寸
height: 100,
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>
11. 微信 SDK - wxSDK
使用方式：
$('#').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
使用方式：
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
$('#box').pid // 获取当前实例的GUID
13.2 extend - 对象合并
const config = $('#box').extend({ a: 1 }, { b: 2 })
// { a: 1, b: 2 }
13.3 getParams - 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()
14. 全局配置
禁用原生重写
window.resetAlert = false // 禁用 alert 重写
window.resetConfirm = false // 禁用 confirm 重写
15. 最佳实践示例
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)
})
注意事项
- 浏览器兼容性：支持现代浏览器，需要 ES6 支持
- 依赖文件：需要
base64.js和icoConfig.json - Crypto 依赖：OSS 上传需要 Crypto 工具
- 微信 SDK：需要服务端签名支持
- 图片路径：确保图标路径正确
文档版本：1.0.0