库介绍
"未来之窗昭和仙君cyberwin_fairyalliance_webquery"(简称$cq库)是一款轻量级JavaScript查询库,支持DOM元素选择、样式操作、事件绑定、表单处理、AJAX请求等功能,同时提供了中文友好的方法命名,兼容多种浏览器,可满足前端日常开发中的常见交互需求。
- 简洁易用的API设计,更轻量
- 支持中文命名的方法,符合中文开发者习惯
- 丰富的DOM操作和事件处理能力
- 强大的表单验证和数据序列化功能
- 完整的AJAX请求支持,包括GET、POST等方法
- 模板引擎语法简洁,能快速结合数据生成动态 HTML,兼具防 XSS、支持逻辑处理和灵活配置,且衔接 DOM 高效渲染
- 数据一键渲染:图片,表单,赋值,文本,复选
- 兼容主流浏览器,包括IE等旧版本浏览器
核心选择器
1. 基础选择器
通过$cq()
或$zh()
函数创建查询实例,支持ID、类、标签选择器。
选择器类型 | 语法 | 说明 |
---|---|---|
ID选择器 | $cq("#元素ID") |
通过元素ID选择单个元素 |
类选择器 | $cq(".元素类名") |
通过元素类名选择多个元素 |
标签选择器 | $cq("标签名") |
通过HTML标签名选择多个元素 |
2. 选择器方法
方法 | 功能 | 示例 |
---|---|---|
eq(n) |
选择匹配元素集合中的第n个元素(n从0开始) | $cq(".通用输入").eq(0).val() |
find(selector) |
在当前匹配元素的子元素中查找符合选择器的元素 | $cq("#form_common").find("input") |
not(selector) |
排除匹配元素中符合选择器的元素 | $cq("input").not(":disabled") |
DOM操作方法
1. 内容操作
方法 | 功能 | 示例 |
---|---|---|
val([value]) |
无参数时获取元素值(适用于input、select等),有参数时设置元素值 |
获取值: 设置值: |
text([value]) |
无参数时获取元素文本内容,有参数时设置元素文本内容 |
获取文本: 设置文本: |
html([value]) |
无参数时获取元素HTML内容,有参数时设置元素HTML内容 |
获取HTML: 设置HTML: |
2. 样式操作
方法 | 功能 | 示例 |
---|---|---|
css(attr, [value]) |
无value时获取元素CSS属性值,有value时设置元素CSS属性 |
获取样式: 设置样式: |
3. 显示隐藏
方法 | 功能 | 示例 |
---|---|---|
show() |
显示匹配的元素(设置display: block) | $cq("#modal").show() |
hide() |
隐藏匹配的元素(设置display: none) | $cq("#modal").hide() |
4. DOM操作方法-2025-08-30
方法 | 功能 | 示例 |
---|---|---|
append(html) |
向匹配元素内部的末尾添加HTML内容 |
批量添加: |
prepend(html) |
向匹配元素内部的开头添加HTML内容 |
添加多个元素: |
insertBefore(html) |
在匹配元素的前面(同级位置)插入HTML内容 |
插入提示信息: |
insertAfter(html) |
在匹配元素的后面(同级位置)插入HTML内容 |
插入辅助内容: |
5. tagName属性
作用: 获取匹配元素集合中第一个元素的标签名
语法: $cq(selector).tagName
返回值
字符串,返回第一个匹配元素的标签名(大写形式,与原生DOM保持一致),若没有匹配元素则返回空字符串。
示例
// HTML: <input type="text" id="username" />
var tag = $cq("#username").tagName;
console.log(tag); // 输出: "INPUT"
6. tagNames属性
作用: 获取所有匹配元素的标签名列表
语法: $cq(selector).tagNames
返回值
数组,包含所有匹配元素的标签名(大写形式),每个元素对应一个匹配元素的标签名。
示例
// HTML:
// <input type="text" class="form-control" />
// <select class="form-control"></select>
// <div class="form-control"></div>
var tags = $cq(".form-control").tagNames;
console.log(tags); // 输出: ["INPUT", "SELECT", "DIV"]
属性与数据操作
1. 元素属性操作
方法 | 功能 | 示例 |
---|---|---|
attr(name, [value]) |
无value时获取元素属性值,有value时设置元素属性;value为null时移除属性 |
获取属性: 设置属性: 移除属性: |
removeAttr(name) |
移除元素指定属性 | $cq("input").removeAttr("readonly") |
2. 数据属性操作(data-*)
方法 | 功能 | 示例 |
---|---|---|
data(key, [value]) |
无参数时获取所有data-*属性集合;1个参数时获取指定key的data值;2个参数时设置data值(自动处理data-前缀) |
获取所有data: 获取指定data: 设置data: |
3. 扩展属性访问器
为$cq库扩展了常用的元素属性访问器,用于快速获取元素的标准属性值。
id
获取匹配元素集合中第一个元素的id属性值
// 语法
$cq(selector).id
name
获取匹配元素集合中第一个元素的name属性值
// 语法
$cq(selector).name
className
获取匹配元素集合中第一个元素的class属性值
// 语法
$cq(selector).className
src
获取匹配元素集合中第一个元素的src属性值(适用于img、script等)
// 语法
$cq(selector).src
href
获取匹配元素集合中第一个元素的href属性值(适用于a等)
// 语法
$cq(selector).href
tagName
获取匹配元素集合中第一个元素的标签名
// 语法
$cq(selector).tagName
tagNames
获取所有匹配元素的标签名列表
// 语法
$cq(selector).tagNames
属性示例
HTML结构
<img id="user-avatar" class="avatar" src="/images/avatar.jpg" />
<a id="home-link" name="nav-link" href="/home">首页</a>
JavaScript代码
// 获取图片元素属性
console.log($cq("#user-avatar").id); // 输出: "user-avatar"
console.log($cq("#user-avatar").className); // 输出: "avatar"
console.log($cq("#user-avatar").src); // 输出: "/images/avatar.jpg"
console.log($cq("#user-avatar").tagName); // 输出: "IMG"
// 获取链接元素属性
console.log($cq("#home-link").name); // 输出: "nav-link"
console.log($cq("#home-link").href); // 输出: "/home"
console.log($cq("#home-link").tagName); // 输出: "A"
通用属性操作方法:prop()
方法名: prop
作用: 通用的属性/特性获取和设置方法,支持获取单个属性值或为多个元素设置属性值
方法语法
// 获取属性值
$cq(selector).prop(name)
// 设置属性值
$cq(selector).prop(name, value)
参数说明
参数名 | 类型 | 是否必需 | 说明 |
---|---|---|---|
name | String | 是 | 要获取或设置的属性名称 |
value | 任意类型 | 否 | 要设置的属性值,省略时为获取属性操作 |
返回值
- 获取属性时:返回第一个匹配元素的属性值,无匹配元素返回空字符串
- 设置属性时:返回当前$cq对象,支持链式调用
使用示例
HTML结构
<input type="checkbox" id="agree" name="terms" />
<input type="text" class="form-control" />
<input type="text" class="form-control" />
JavaScript代码
// 获取属性值
console.log($cq("#agree").prop("type")); // 输出: "checkbox"
console.log($cq("#agree").prop("name")); // 输出: "terms"
console.log($cq("#agree").prop("checked")); // 输出: false
// 设置属性值
// 为复选框设置checked属性
$cq("#agree").prop("checked", true);
// 为多个元素设置属性
$cq(".form-control")
.prop("disabled", true)
.prop("placeholder", "请输入内容"); // 支持链式调用
// 验证结果
console.log($cq("#agree").prop("checked")); // 输出: true
console.log($cq(".form-control:first").prop("disabled")); // 输出: true
实现代码
// 通用属性/特性获取设置方法
cyberwin_query.prototype.prop = function(name, value) {
// 无匹配元素时返回空
if (this.elements.length === 0) {
return value === undefined ? '' : this;
}
// 仅获取属性值
if (value === undefined) {
return this.elements[0][name] !== undefined ? this.elements[0][name] : '';
}
// 设置属性值
this.elements.forEach(el => {
el[name] = value;
});
return this; // 支持链式调用
};
事件绑定
方法 | 功能 | 示例 |
---|---|---|
click(fn) |
为匹配元素绑定点击事件 |
|
each(fn) |
遍历匹配元素集合,为每个元素执行回调函数(回调参数:索引i、当前元素) |
|
事件处理方法:事件()
本文档介绍$cq库中用于事件绑定的核心方法事件()
,该方法提供了灵活的事件处理机制,支持多种事件类型和绑定方式。
1. 方法概述
方法名: 事件
作用: 为匹配的DOM元素绑定一个或多个事件处理函数,支持链式调用
方法语法
// 单个事件绑定
$cq(selector).事件(eventName, handler)
// 多个事件批量绑定
$cq(selector).事件({
eventName1: handler1,
eventName2: handler2,
...
})
参数说明
参数名 | 类型 | 是否必需 | 说明 |
---|---|---|---|
eventName | String | 是(单个事件时) | 事件名称,如"click"、"focus"等 |
handler | Function | 是(单个事件时) | 事件处理函数,当事件触发时执行 |
events | Object | 是(批量绑定时) | 键值对形式的事件配置,键为事件名,值为对应的处理函数 |
返回值
返回当前$cq对象实例,支持链式调用(如:$cq("input").事件("focus", fn).事件("blur", fn2)
)
实现代码
cyberwin_query.prototype.事件 = function(events, handler) {
// 处理对象形式的事件配置 { event1: handler1, event2: handler2 }
if (typeof events === 'object' && typeof handler === 'undefined') {
Object.keys(events).forEach(eventName => {
this.事件(eventName, events[eventName]);
});
return this;
}
// 确保事件名和处理器有效
if (typeof events !== 'string' || typeof handler !== 'function') {
console.error('事件名必须为字符串且处理器必须为函数');
return this;
}
// 为所有匹配元素绑定事件
this.elements.forEach(element => {
// 使用已有的myAddEvent函数绑定事件
未来之窗_附加事件(element, events, function(e) {
// 绑定this为当前元素,传递事件对象
handler.call(element, e || window.event);
});
});
return this; // 支持链式调用
};
2. 常用事件类型及示例
以下是Web开发中常用的事件类型及使用示例,适用于表单元素、输入框等交互组件:
元素获得焦点时触发
元素失去焦点时触发
元素值发生变化时触发
元素值改变并失去焦点时触发
按下键盘按键时触发
搜索框触发搜索时触发
完整示例:表单输入框事件处理
HTML结构
<form id="user-form">
<div>
<label>用户名:</label>
<input type="text" id="username" name="username" placeholder="请输入用户名">
</div>
<div>
<label>搜索:</label>
<input type="search" id="search-input" placeholder="搜索内容">
</div>
<div>
<label>爱好:</label>
<select id="hobby">
<option value="">请选择</option>
<option value="reading">阅读</option>
<option value="sports">运动</option>
</select>
</div>
</form>
JavaScript代码
// 用户名输入框事件处理
$cq("#username")
// 获得焦点事件
.事件("focus", function() {
// 聚焦时添加高亮样式
this.style.border = "2px solid #165DFF";
this.style.backgroundColor = "#f0f7ff";
})
// 失去焦点事件
.事件("blur", function() {
// 失焦时恢复样式
this.style.border = "1px solid #ccc";
this.style.backgroundColor = "";
// 验证输入内容
if (this.value.length < 3) {
alert("用户名长度不能少于3个字符");
}
})
// 输入事件(实时监测)
.事件("input", function(e) {
console.log("正在输入:", this.value);
// 限制输入长度为10
if (this.value.length > 10) {
this.value = this.value.substring(0, 10);
}
})
// 键盘按下事件
.事件("keydown", function(e) {
// 禁止输入空格
if (e.keyCode === 32) {
e.preventDefault(); // 阻止默认行为
alert("用户名不能包含空格");
}
});
// 搜索框事件处理
$cq("#search-input")
// 搜索事件(回车或搜索按钮)
.事件("search", function() {
if (this.value.trim()) {
console.log("搜索内容:", this.value);
// 执行搜索逻辑
// searchAction(this.value);
} else {
alert("请输入搜索内容");
}
});
// 下拉选择框事件处理
$cq("#hobby")
// 选项改变事件
.事件("change", function() {
console.log("选择了:", this.value);
if (this.value) {
alert("您选择的爱好是:" + this.options[this.selectedIndex].text);
}
});
// 批量绑定事件示例
$cq("input, select")
.事件({
"focus": function() {
console.log("元素获得焦点:", this.id);
},
"blur": function() {
console.log("元素失去焦点:", this.id);
}
});
示例说明
- focus/blur:用于处理输入框获取和失去焦点时的样式变化和验证逻辑
- input:实时监测输入框内容变化,可用于实时验证或输入限制
- keydown:捕获键盘输入,可用于禁止特定字符输入或快捷键处理
- search:专门用于搜索框,在用户执行搜索操作时触发
- change:适用于下拉框、复选框等,在值改变并确认后触发
- 批量绑定方式可简化多事件绑定代码,提高开发效率
3. 事件处理函数中的this和事件对象
this指向
在事件处理函数中,this
指向当前触发事件的DOM元素,方便直接操作元素:
$cq("input").事件("focus", function() {
// this指向当前获得焦点的input元素
this.style.outline = "none";
this.style.boxShadow = "0 0 3px #165DFF";
});
事件对象(e)
事件处理函数接收一个事件对象参数,包含事件相关信息(如触发元素、按键代码等):
$cq("input").事件("keydown", function(e) {
// 标准化事件对象(兼容IE)
e = e || window.event;
console.log("按键代码:", e.keyCode);
console.log("是否按下Ctrl键:", e.ctrlKey);
// 阻止事件默认行为(如禁止回车提交表单)
if (e.keyCode === 13) {
e.preventDefault();
}
});
4. 实际应用场景
场景1:表单验证 - 结合focus、blur和input事件实现实时表单验证:
$cq("#email")
.事件("blur", function() {
var email = this.value;
if (email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
alert("请输入有效的邮箱地址");
this.focus(); // 聚焦回输入框
}
})
.事件("input", function() {
// 实时显示验证状态
var isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(this.value);
this.style.borderColor = isValid ? "green" : "red";
});
场景2:搜索框自动完成 - 结合input和keydown事件实现搜索提示:
$cq("#search")
.事件("input", function() {
// 输入间隔大于300ms才发送请求,避免频繁请求
clearTimeout(this.searchTimer);
var value = this.value;
this.searchTimer = setTimeout(function() {
if (value.length >= 2) {
// 发送搜索建议请求
// getSearchSuggestions(value);
console.log("获取搜索建议:", value);
}
}, 300);
})
.事件("keydown", function(e) {
// 按下上下键选择建议项
if (e.keyCode === 38 || e.keyCode === 40) {
e.preventDefault();
// navigateSuggestions(e.keyCode === 38 ? "up" : "down");
}
});