1. 概述

KuoqiJS 是一个轻量级前端 JavaScript 框架，通过 $Q() 函数作为核心入口，支持链式调用。

<script src="https://js.kuoqps.com/assets/kq.1.14/kq.1.14.js"></script>

• 全局别名：$Q 和 kuoqiJs 等价
• 选择器返回 KuoqiDom 对象（类数组，带 length），支持链式调用
• 如果 $ 未被占用，也会设置 $ = $Q

2. DOM 选择器

基本用法

$Q(selector [, context])   // 从 context 内查找
$Q(domElement)             // 包装原生 DOM
$Q(nodeList)               // 包装 NodeList
$Q(htmlString)             // 创建 DOM 元素
$Q(function)               // ready 简写 (同 $Q(document).ready(fn))
$Q(kuoqiDom)               // 返回自身

标准 CSS 选择器均支持（标签、类、ID、属性选择器、后代/子代/相邻选择器）。

扩展伪类

伪类	说明
:first	第一个匹配元素
:last	最后一个匹配元素
:eq(n)	第 n 个元素（0-indexed）
:neq(n)	非第 n 个元素
:gt(n)	索引大于 n
:lt(n)	索引小于 n
:even	偶数索引元素
:odd	奇数索引元素
:notEmpty	非空元素（有子节点或文本）
:hidden	隐藏元素（display:none 或 type=hidden）
:visible	可见元素
:animated	正在执行动画的元素
:contains(text)	包含指定文本的元素
:has(selector)	包含匹配选择器的后代元素
:header	h1-h6 标题元素
:input	input/select/textarea/button
:checkbox / :radio	类型过滤
:checked / :selected / :disabled / :focus / :empty	状态过滤
:file / :image / :password / :submit / :text / :button	input type 过滤
:parent	有子节点的元素
:first-child / :last-child / :nth-child(n) / :only-child	子元素位置

3. DOM 遍历

$Q(selector).each(function(index, element) { ... })
$Q(selector).find(subSelector)       // 查找后代
$Q(selector).children([selector])    // 直接子元素
$Q(selector).parent()                // 父元素
$Q(selector).parents([selector])     // 所有祖先
$Q(selector).siblings([selector])    // 兄弟元素
$Q(selector).next([selector])        // 下一个兄弟
$Q(selector).prev([selector])        // 上一个兄弟
$Q(selector).closest(selector)       // 最近的匹配祖先
$Q(selector).filter(selector)        // 过滤
$Q(selector).not(selector)           // 排除
$Q(selector).is(selector)            // 布尔判断
$Q(selector).has(selector)           // 包含判断
$Q(selector).index([element])        // 获取索引
$Q(selector).eq(index)               // 第 n 个元素
$Q(selector).first()                 // 第一个
$Q(selector).last()                  // 最后一个
$Q(selector).slice(start, end)       // 切片
$Q(selector).map(callback)           // 映射

4. DOM 内容与属性

内容操作

$Q(el).html()              // 获取 innerHTML
$Q(el).html(content)       // 设置 innerHTML（链式）
$Q(el).text()              // 获取 textContent
$Q(el).text(content)       // 设置 textContent（链式）
$Q(el).val()               // 获取表单 value
$Q(el).val(value)          // 设置表单 value（链式）
$Q(el).append(content)     // 末尾追加（HTML 或 DOM 或 KuoqiDom）
$Q(el).prepend(content)    // 开头插入
$Q(el).before(content)     // 之前插入
$Q(el).after(content)      // 之后插入
$Q(el).remove()            // 移除自身
$Q(el).empty()             // 清空子节点
$Q(el).clone([deep])       // 克隆（默认 true 深克隆）
$Q(el).replaceWith(content)// 替换自身
$Q(el).unwrap()            // 移除父元素
$Q(el).wrap(html)          // 用 HTML 包裹
$Q(el).wrapInner(html)     // 包裹内部

属性操作

$Q(el).attr(name)              // 获取属性
$Q(el).attr(name, value)       // 设置属性（链式）
$Q(el).attr({ key: val })      // 批量设置
$Q(el).removeAttr(name)        // 移除属性
$Q(el).prop(name)              // 获取属性（checked/selected 等）
$Q(el).prop(name, value)       // 设置属性
$Q(el).removeProp(name)        // 移除属性
$Q(el).data(name)              // 获取 data-* 属性
$Q(el).data(name, value)       // 设置 data-* 属性

CSS / 样式

$Q(el).css(name)               // 获取计算样式
$Q(el).css(name, value)        // 设置样式（链式）
$Q(el).css({ key: val })       // 批量设置
$Q(el).width()                 // 宽度
$Q(el).height()                // 高度
$Q(el).innerWidth()            // width + padding
$Q(el).innerHeight()           // height + padding
$Q(el).outerWidth([margin])    // width + padding + border (+ margin)
$Q(el).outerHeight([margin])   // 同上
$Q(el).offset()                // { top, left } 相对于 document
$Q(el).position()              // { top, left } 相对于 offsetParent
$Q(el).scrollLeft([value])     // 滚动条左偏移
$Q(el).scrollTop([value])      // 滚动条上偏移
$Q(el).offsetParent()          // 定位父元素

类操作

$Q(el).hasClass(className)     // 布尔判断
$Q(el).addClass(className)     // 添加类（链式）
$Q(el).removeClass(className)  // 移除类（链式）
$Q(el).toggleClass(className)  // 切换类（链式）

5. 事件系统

核心事件方法

$Q(el).on(types, selector, data, fn)       // 绑定事件
$Q(el).off(types, selector, fn)            // 移除事件
$Q(el).trigger(type, data)                 // 触发事件
$Q(el).one(type, fn)                       // 单次绑定
$Q(el).hover(fnIn, fnOut)                  // mouseenter + mouseleave

on() 参数说明：

• types：事件类型字符串（支持空格分隔的多个事件，如 "click mouseenter"）
• selector：可选，事件委托的子元素选择器
• data：可选，传递给事件处理函数的额外数据（通过 e.data 访问）
• fn：处理函数，接收 event 参数

快捷方法

$Q(el).click(fn)        $Q(el).dblclick(fn)
$Q(el).mousedown(fn)    $Q(el).mouseup(fn)
$Q(el).mousemove(fn)    $Q(el).mouseenter(fn)
$Q(el).mouseleave(fn)   $Q(el).mouseover(fn)
$Q(el).mouseout(fn)
$Q(el).keydown(fn)      $Q(el).keyup(fn)
$Q(el).keypress(fn)
$Q(el).focus(fn)        $Q(el).blur(fn)
$Q(el).change(fn)       $Q(el).submit(fn)
$Q(el).scroll(fn)       $Q(el).resize(fn)
$Q(el).load(fn)         $Q(el).unload(fn)
$Q(el).select(fn)       $Q(el).error(fn)
$Q(el).contextmenu(fn)  $Q(el).input(fn)
$Q(el).focusin(fn)      $Q(el).focusout(fn)

文档就绪

$Q(function() { ... })              // DOMContentLoaded 简写
$Q(document).ready(function() { })  // DOMContentLoaded
$Q(window).loaded(function() { })   // window.onload

自定义事件

$Q(el).eventCustom(type, fn)        // 绑定自定义事件
$Q(el).evt(type, fn)                // evt 系统（拖拽、缩放等）
$Q(el).trigger('customevent', data) // 触发自定义事件

事件对象属性

e.target       // 实际触发事件的元素
e.currentTarget// 绑定事件的元素
e.delegateTarget// 委托的元素
e.data         // on() 传入的额外数据
e.which        // 键码/鼠标按钮
e.pageX/Y      // 鼠标位置
e.clientX/Y    // 视口位置
e.offsetX/Y    // 相对元素位置
e.keyCode      // 按键代码
e.ctrlKey / e.shiftKey / e.altKey / e.metaKey
e.preventDefault()   // 阻止默认行为
e.stopPropagation()  // 阻止冒泡
e.stopImmediatePropagation() // 阻止冒泡并阻止后续同元素同类型事件

6. AJAX

核心请求

$Q.ajax(options)

选项	说明
url	请求地址
type	请求方法（GET/POST/PUT/DELETE），默认 GET
data	发送数据（对象或字符串）
dataType	预期返回类型（json/text/html/xml/script/jsonp）
async	是否异步，默认 true
timeout	超时时间（毫秒）
cache	是否缓存，默认 true
headers	自定义请求头
contentType	请求 Content-Type，默认 application/x-www-form-urlencoded
processData	是否处理 data 为查询字符串，默认 true
beforeSend(xhr)	发送前回调，返回 false 取消请求
success(data, status, xhr)	成功回调
error(xhr, status, error)	失败回调
complete(xhr, status)	完成回调（成功/失败均执行）
xhr	自定义 XMLHttpRequest 工厂函数

快捷方法

$Q.get(url, data, success, dataType)
$Q.post(url, data, success, dataType)
$Q.getJSON(url, data, success)     // dataType = 'json'
$Q.getScript(url, success)          // dataType = 'script'

表单异步提交

$Q.ajaxSubmit(formElement [, options])
$Q.ajaxConts(url, target)           // 加载 URL 内容到 target 元素

7. Canvas 绘图

var ctx = $Q.canvas(element)

绘图方法

ctx.line(x1, y1, x2, y2, color, width)
ctx.circle(x, y, radius, color, fill)
ctx.rect(x, y, w, h, color, fill)
ctx.polygon(points, color, fill)          // points: [[x1,y1],[x2,y2],...]
ctx.gear(x, y, r, teeth, color, fill)     // 齿轮
ctx.text(text, x, y, color, size, align)  // align: 'left'/'center'/'right'
ctx.image(img, x, y, w, h)
ctx.clear([x, y, w, h])                   // 清除区域

样式与渐变

ctx.gradient(x1, y1, x2, y2, colors)      // colors: [{offset:0,color:'#000'},...]
ctx.fill(color)
ctx.stroke(color, width)
ctx.setGlobalAlpha(alpha)                  // 透明度 0-1
ctx.setLineDash(segments)                  // 虚线 [5,5]
ctx.rotate(angle)                          // 旋转（弧度）
ctx.scale(x, y)                            // 缩放
ctx.translate(x, y)                        // 平移
ctx.save()                                 // 保存状态
ctx.restore()                              // 恢复状态

路径

ctx.beginPath()
ctx.moveTo(x, y)
ctx.lineTo(x, y)
ctx.arc(x, y, r, startAngle, endAngle, anticlockwise)
ctx.bezier(cp1x, cp1y, cp2x, cp2y, x, y)  // 贝塞尔曲线
ctx.quadratic(cpx, cpy, x, y)             // 二次贝塞尔
ctx.closePath()
ctx.strokePath(color, width)
ctx.fillPath(color)

H5 动画引擎

var anim = new $Q.h5()
anim.animate(fn)                 // 每帧执行
anim.timer(fn, interval)         // 定时器
anim.run()                       // 开始
anim.stop()                      // 停止
anim.pause()                     // 暂停
anim.resume()                    // 恢复
anim.remove()                    // 移除

8. 图表

折线图

var chart = new $Q.broken(element, {
    data: [
        { name: '系列1', data: [10, 20, 30] },
        { name: '系列2', data: [15, 25, 35] }
    ],
    xAxis: ['一月','二月','三月'],
    colors: ['#ff6b6b', '#4ecdc4'],
    bg: '#f5f5f5',
    lineWidth: 2,
    dot: true,                    // 显示数据点
    area: false,                  // 面积图
    smooth: true,                 // 平滑曲线
    legend: 'top',                // 图例位置
    grid: true                    // 网格线
})
chart.render()
chart.update(data)               // 更新数据
chart.destroy()                  // 销毁

饼图

var pie = new $Q.chartPie(element, {
    data: [
        { name: '分类A', value: 30 },
        { name: '分类B', value: 50 },
        { name: '分类C', value: 20 }
    ],
    colors: ['#ff6b6b', '#4ecdc4', '#ffe66d'],
    radius: 100,                  // 半径
    innerRadius: 0,               // 内半径（>0 为环形图）
    animate: true,                // 动画效果
    legend: 'right',
    label: true                   // 显示标签
})
pie.render()
pie.update(data)
pie.destroy()

9. 动画

CSS 动画

$Q(el).animate(properties, duration, easing, callback)
$Q(el).animate(properties, options)

参数	说明
properties	CSS 属性对象 { opacity: 0.5, width: '200px', height: '+=50' }
duration	持续时间（毫秒），默认 400
easing	缓动函数：swing（默认）/ linear / ease-in / ease-out / cubic-bezier(n,n,n,n)
callback	完成回调

// options 对象
{
    duration: 400,
    easing: 'swing',
    complete: fn,
    step: function(now, tween) {},   // 每帧回调
    queue: true,                     // 是否加入队列
    specialEasing: { opacity: 'linear' }
}

3D 动画

$Q(el).animate3D(options)

旋转动画

$Q(el).animateRotate(angle, duration, callback)

动画控制

$Q(el).animateStop([clearQueue])      // 停止动画
$Q(el).animatePause()                 // 暂停动画
$Q(el).animateResume()                // 恢复动画
$Q(el).animateFinish()                // 立即完成
$Q(el).animateDelay(duration)         // 延迟开始
$Q(el).animateQueue(name)             // 管理动画队列

10. 工具函数

对象操作

$Q.opts(defaults, options)           // 合并选项（类似 $.extend）
$Q.extend(target, ...sources)        // 深度合并
$Q.type(obj)                         // 类型判断
$Q.isArray(obj)
$Q.isFunction(obj)
$Q.isPlainObject(obj)
$Q.isEmptyObject(obj)
$Q.isNumeric(val)
$Q.isWindow(obj)
$Q.inArray(value, array)             // 返回索引，-1 表示不存在
$Q.each(obj, callback)               // 遍历对象或数组
$Q.map(obj, callback)                // 映射
$Q.grep(array, callback)             // 过滤
$Q.unique(array)                     // 去重
$Q.merge(arr1, arr2)                 // 合并数组
$Q.makeArray(obj)                    // 转换为数组
$Q.trim(str)                         // 去除前后空格

字符串工具

$Q.strTohump(str)                    // a-b-c → aBC（短横线转驼峰）
$Q.strTolower(str)                   // aBC → a-b-c（驼峰转短横线）
$Q.strToUppercase(str)               // 转大写（含下划线转驼峰）
$Q.jsonEncode(obj)                   // JSON.stringify()
$Q.jsonDecode(str)                   // JSON.parse()
$Q.base64Encode(str)
$Q.base64Decode(str)
$Q.md5(str)                          // MD5 哈希
$Q.encodeURI(str)
$Q.decodeURI(str)
$Q.parseUrl(url)                     // 解析 URL 各组成部分
$Q.param(obj)                        // 对象转查询字符串

数字 / 唯一标识

$Q.random(min, max)                  // 随机整数
$Q.randomString(length)              // 随机字符串
$Q.createID([prefix])                // 创建唯一 ID（格式: prefix_xxxxxxxx）

验证

$Q.validata.phone(val)               // 手机号验证
$Q.validata.email(val)               // 邮箱验证
$Q.validata.idCard(val)              // 身份证验证
$Q.validata.url(val)                 // URL 验证
$Q.validata.number(val)              // 数字验证
$Q.validata.range(val, min, max)     // 数值范围
$Q.validata.length(val, min, max)    // 字符串长度
$Q.validata.required(val)            // 非空
$Q.validata.regex(val, pattern)      // 正则验证

日期

$Q.date(format, timestamp)           // 格式化日期
// format 占位符：YYYY / YY / MM / DD / hh / mm / ss
$Q.date.diff(d1, d2, unit)           // 日期差（unit: 'day'/'hour'/'minute'）
$Q.date.add(date, amount, unit)      // 日期加减
$Q.date.startOf(date, unit)          // 开始时间（'month' → 当月1日）
$Q.date.endOf(date, unit)            // 结束时间
$Q.date.formatRelative(timestamp)    // 相对时间（"3 分钟前"）

平台检测

$Q.isMobile()                        // 移动端
$Q.isWX()                            // 微信内置浏览器
$Q.isIE()                            // Internet Explorer
$Q.isEdge()                          // Microsoft Edge
$Q.isFirefox()                       // Firefox
$Q.isChrome()                        // Chrome
$Q.isSafari()                        // Safari
$Q.isAndroid()                       // Android
$Q.isIOS()                           // iOS
$Q.isTablet()                        // 平板
$Q.isWeibo()                         // 微博客户端
$Q.isQQ()                            // QQ 内置浏览器
$Q.isAlipay()                        // 支付宝客户端
$Q.browser()                         // 返回浏览器信息对象
$Q.os()                              // 返回操作系统信息

剪贴板

$Q.clipBoard(text)                   // 复制到剪贴板，返回 Promise

Cookie / Storage

$Q.cookie(name)                      // 获取 cookie
$Q.cookie(name, value, options)      // 设置 cookie
$Q.removeCookie(name)                // 删除 cookie

$Q.localStorage.set(key, value)
$Q.localStorage.get(key)
$Q.localStorage.remove(key)
$Q.localStorage.clear()

$Q.sessionStorage.set(key, value)
$Q.sessionStorage.get(key)
$Q.sessionStorage.remove(key)
$Q.sessionStorage.clear()

其他

$Q.guid()                            // 生成 GUID
$Q.now()                             // 当前时间戳
$Q.contains(parent, child)           // 是否包含
$Q.parseHTML(html)                   // HTML 字符串解析为 DOM
$Q.proxy(fn, context)                // 绑定函数上下文
$Q.noConflict()                      // 释放 $ 控制权
$Q.support                           // 浏览器特性检测对象

11. 文件处理

文件选择

$Q.file(options)                     // 弹出文件选择对话框

• options.multiple: 多文件
• options.accept: 文件类型过滤
• options.success(files): 选择成功回调

FileReader 封装

$Q.file.readAsDataURL(file, callback)    // 读取为 data:URL
$Q.file.readAsText(file, callback)       // 读取为文本
$Q.file.readAsArrayBuffer(file, callback, progress)

文件上传（带切片）

new $Q.Uploader({
    url: '/upload',
    files: fileInput,
    data: { type: 'avatar' },
    multiple: true,
    accept: 'image/*',
    maxSize: 10 * 1024 * 1024,       // 最大文件大小
    chunkSize: 1024 * 1024,           // 切片大小（1MB）
    autoUpload: true,                 // 选择后自动上传
    success: function(res, file) {},
    error: function(err, file) {},
    progress: function(e, file) {     // 单文件进度
        var pct = Math.round(e.loaded / e.total * 100)
    },
    allprogress: function(pct) {},    // 总进度
    complete: function() {},          // 全部完成
    beforeSend: function(file) {}     // 上传前回调
}).send()

12. 流程控制

Flow（异步迭代器）

$Q.flow(tasks, callback)
// tasks: 函数数组，每个函数接收 next 回调
$Q.flow([
    function(next) {
        $Q.get('/api/step1', function(data) { next(null, data) })
    },
    function(next) {
        $Q.get('/api/step2', function(data) { next(null, data) })
    }
], function(err, results) {
    // 所有任务完成
})

Loop（循环控制）

new $Q.Loop(function(i) {
    // i 为当前索引
    if (i >= 10) return false  // 停止循环
})

13. 插件系统

插件位于 assets/kq.1.14/plugin/ 目录，通过 $Q.plugin 或扩展 $Q 对象使用。

插件	文件	说明
slide	plugin/slide.js	轮播图/幻灯片
wheel	plugin/wheel.js	滚轮选择器
weixin	plugin/weixin.js	微信 JS-SDK 封装
editor	plugin/editor.js	富文本编辑器
datetime	plugin/datetime.js	日期时间选择器
html5	plugin/html5.js	HTML5 功能支持
browser	plugin/browser.js	浏览器兼容工具

扩展 KuoqiJS

// 扩展 $Q 静态方法
$Q.extend($Q, {
    myPlugin: function() { ... }
})

// 扩展 KuoqiDom 原型（所有 $Q() 对象可用）
$Q.extend($Q.KuoqiDom.prototype, {
    myMethod: function() { return this }
})

14. 常见模式

表单异步提交 + data-ajax 属性

<form data-ajax data-ajax-success="handleSuccess" data-ajax-before="handleBefore">
    <input name="email" type="email" required>
    <button type="submit">提交</button>
</form>

data-ajax 自动绑定表单，支持回调属性：

• data-ajax-success：成功回调函数名
• data-ajax-error：失败回调函数名
• data-ajax-before：发送前回调函数名
• data-ajax-complete：完成回调函数名

拖拽（evt 系统）

$Q(el).evt('drag', function(e) {
    // e.dx, e.dy 为偏移量
    // e.x, e.y 为当前位置
})
$Q(el).evt('resize', function(e) { /* 缩放处理 */ })

文件上传进度

var uploader = new $Q.Uploader({
    url: '/api/upload',
    files: '#fileInput',
    multiple: true,
    success: function(res) { console.log('上传成功:', res.url) },
    progress: function(e) {
        var pct = Math.round(e.loaded / e.total * 100)
        $Q('#progress').css('width', pct + '%').text(pct + '%')
    },
    allprogress: function(pct) {
        $Q('#totalProgress').css('width', pct + '%')
    }
})
uploader.send()

链式调用惯例

$Q('#container')
    .addClass('active')
    .css({ width: '200px', height: '100px' })
    .on('click', function() { ... })
    .html('<span>内容</span>')
    .animate({ opacity: 1 }, 300)

// 选择器链式细化
$Q('.list').find('.item.active').eq(0).addClass('highlight')

15. 注意事项

1. 选择器上下文：$Q(selector, context) 等同于 $Q(context).find(selector)
2. 动画队列：默认动画按队列依次执行，设置 queue: false 可同时执行
3. ajax 的 dataType：指定 'json' 会自动解析响应；'script' 会执行返回的脚本
4. Uploader 切片：当 chunkSize > 0 时启用切片上传，支持断点续传
5. Canvas 坐标：所有绘图方法坐标均为 Canvas 内部坐标系
6. AJAX complete 回调不可靠：$Q.ajax 的 complete 回调可能在某些情况下不被触发。需要清理/收尾的逻辑应同时放在 success 和 error 回调中。

// 错误：complete 可能不触发
$Q.ajax({
    success: function() { /* ... */ },
    error: function() { /* ... */ },
    complete: function() { running--; next(); }  // 危险
})

// 正确：在 success 和 error 中分别处理
$Q.ajax({
    success: function() { running--; next(); },
    error: function() { running--; next(); }
})