jQuery 3.1 API中文文档

欢迎大家访问我的个人网站《刘江的博客和教程》：www.liujiangblog.com

主要分享Python 及Django教程以及相关的博客

jQuery 3.1 API中文文档

一、核心

1.1 核心函数

jQuery([selector,[context]])

接收一个包含 CSS 选择器的字符串，然后用这个字符串去匹配一组元素。
jQuery 的核心功能都是通过这个函数实现的。 jQuery中的一切都基于这个函数，或者说都是在以某种方式使用这个函数。这个函数最基本的用法就是向它传递一个表达式（通常由 CSS 选择器组成），然后根据这个表达式来查找所有匹配的元素。
默认情况下, 如果没有指定context参数，$()将在当前的 HTML document中查找 DOM 元素；如果指定了 context 参数，如一个 DOM 元素集或 jQuery 对象，那就会在这个 context 中查找。在jQuery1.3.2以后，其返回的元素顺序等同于在context中出现的先后顺序。

jQuery(html,[ownerDocument])

根据提供的原始 HTML 标记字符串，动态创建由 jQuery 对象包装的 DOM 元素。同时设置一系列的属性、事件等。

$("<div>", {
  "class": "test",
  text: "Click me!",
  click: function(){
    $(this).toggleClass("test");
  }
}).appendTo("body");

jQuery(callback)

$(document).ready()的简写。
允许你绑定一个在DOM文档载入完成后执行的函数，可以在一个页面中使用任意多个$(document).ready事件。

$(function(){
  // 文档就绪
});

jQuery.holdReady(hold)

暂停或恢复.ready() 事件的执行。

1.2 对象访问

#### each(callback) 循环元素并执行callback函数。函数中的this关键字都指向一个不同的DOM元素（每次都是一个不同的匹配元素）。如果你想得到 jQuery对象，可以使用 $(this) 函数。你可以使用 'return' 来提前跳出 each() 循环。

HTML 代码:

<button>Change colors</button>
<span></span> 
<div></div> 
<div></div>
<div></div> 
<div></div>
<div id="stop">Stop here</div> 
<div></div>
<div></div>
<div></div>

jQuery 代码:

$("button").click(function () { 
$("div").each(function (index, domEle) { 
  // domEle == this 
  $(domEle).css("backgroundColor", "yellow");  
  if ($(this).is("#stop")) { 
  $("span").text("Stopped at div index #" + index); 
  return false; 
  } 
});
});

size（）和length

Query 对象中元素的个数。
与 length 将返回相同的值。

selector

返回你用什么选择器来找元素的。可以与context一起使用，用于精确检测选择器查询情况。

context

返回传给jQuery()的原始的DOM节点内容，即jQuery()的第二个参数。如果没有指定，那么context指向当前的文档(document)。

get()

取得其中一个匹配的元素。 num表示取得第几个匹配的元素。从0开始，返回的是DOM对象，类似的有eq(index),不过eq(index)返回的是jQuery对象。

index([selector|element])

搜索匹配的元素，并返回相应元素的索引值，从0开始计数。

1.3 数据缓存

#### data([key],[value]) 在元素上存放或读取数据,返回jQuery对象。

removeData([name|list])

在元素上移除存放的数据，与 data([key], [value]) 函数作用相反

1.4 队列控制

#### queue(element,[queueName]) 显示或操作在匹配元素上执行的函数队列

dequeue([queueName])

从队列最前端移除一个队列函数，并执行他。队列名默认为fx

clearQueue([queueName])

清空对象上尚未执行的所有队列
如果不带参数，则默认清空的是动画队列。这跟 stop(true)类似，但 stop(true)只能清空动画队列，而这个可以清空所有通过 .queue() 创建的队列。

1.5 插件机制

####jQuery.fn.extend(object) 扩展 jQuery 元素集来提供新的方法（通常用来制作插件）。

jQuery.fn.extend({
  check: function() {
    return this.each(function() { this.checked = true; });
  },
  uncheck: function() {
    return this.each(function() { this.checked = false; });
  }
});

定义了两个用户自定义的函数check和uncheck。调用方式：

$("input[type=checkbox]").check();
$("input[type=radio]").uncheck();

jQuery.extend(object)

扩展jQuery对象本身。用来在jQuery命名空间上增加新函数。

jQuery.extend({
  min: function(a, b) { return a < b ? a : b; },
  max: function(a, b) { return a > b ? a : b; }
});

调用方式：

jQuery.min(2,3); // => 2
jQuery.max(4,5); // => 5

1.6 多库共存

#### jQuery.noConflict([extreme]) 运行这个函数将变量`$`的控制权让渡给第一个实现它的那个库。这有助于确保jQuery不会与其他库的`$`对象发生冲突。在运行这个函数后，就只能使用jQuery变量访问jQuery对象。例如，在要用到$("div p")的地方，就必须换成jQuery("div p")。 '''注意:'''这个函数必须在你导入jQuery文件之后，并且在导入另一个导致冲突的库'''之前'''使用。当然也应当在其他冲突的库被使用之前，除非jQuery是最后一个导入的。

二、选择器

选择器的符号：

符号	用途
#	id
.	类
*	所有
，	组合
空格	祖孙
>	父子
+	紧随
~	兄弟
：	筛选
[]	属性

2.1 基本选择器

#### #id 根据给定的ID匹配一个元素。

使用任何的元字符（如!"#$%&'()*+,./:;<=>?@[]^{|}~）作为名称的文本部分， 它必须被两个反斜杠转义：\。

element

根据给定的元素标签名匹配所有元素

.class

根据给定的css类名匹配元素。
一个元素可以有多个类，只要有一个符合就能被匹配到。且不会被重复搜索。

*

匹配所有元素
多用于结合上下文来搜索。

selector1,selector2,selectorN

所谓的组合选择器，其实就是多个选择器写在一起了。

2.2 层级选择器

#### ancestor descendant 在给定的祖先元素下匹配所有的后代元素。 #### parent > child 在给定的父元素下匹配所有的子元素

prev + next

匹配所有紧接在 prev 元素后的 next 元素。必须紧跟，不能有间隔，不能跨层级。而且是第一个元素！prev可能会找到很多个，但每个prev后最多只能匹配一个next。

prev ~ siblings

匹配 prev 元素之后的所有同辈元素。

2.3 基本筛选器

用法：$("selector:xxx")

:first 第一个
:not(selector)取反
:even偶数
:odd奇数
:eq(index)索引
:gt(index)大于索引
:lt(index)小于索引
:lang(language)语言
:last最后一个
:header标题
:animated动画
:focus焦点元素
:root文档根元素
:target目标元素

2.4 内容

:contains(text)包含文本
:empty空元素
:has(selector)包含指定元素
:parent包含子元素或文本

2.5 可见性

:hidden不可见的元素
:visible可见的元素

2.6 属性

[attribute]包含指定属性的元素
[attribute=value]属性等于值
[attribute!=value]不等于值
[attribute^=value]以值开头
[attribute$=value]以值结尾
[attribute*=value]值中包含
[selector1][selector2][selectorN]组合属性筛选器

2.7 子元素

:first-child为每个父元素匹配第一个子元素
:last-child为每个父元素匹配最后一个子元素
:first-of-type忘了它！
:last-of-type忘了它！
:nth-child匹配其父元素下的第N个子或奇偶元素
:nth-last-child(n|even|odd|formula)选择所有他们父元素的第n个子元素。
:nth-last-of-type(n|even|odd|formula)选择所有他们的父级元素的第n个子元素
:nth-of-type(n|even|odd|formula)选择同属于一个父元素之下，并且标签名相同的子元素中的第n个。
:only-child如果某个元素是父元素中唯一的子元素，那将会被匹配
:only-of-type选择所有没有兄弟元素，且具有相同的元素名称的元素。

2.8 表单

:input匹配所有 input, textarea, select 和 button 元素
:text匹配所有的单行文本框
:password匹配所有密码框
:radio匹配所有单选按钮
:checkbox匹配所有复选框
:submit匹配所有提交按钮
:image匹配所有图像域
:reset匹配所有重置按钮
:button匹配所有按钮
:file匹配所有文件域

2.9 表单对象属性

:enabled匹配所有可用元素
:disabled匹配所有不可用元素
:checked匹配所有选中的被选中元素(复选框、单选框等）
:selected匹配所有选中的option元素

2.10 混淆选择器

$.escapeSelector(selector)
通常被用在类选择器或者ID选择器中包含一些CSS特殊字符的时候，这个方法基本上与CSS中CSS.escape()方法类似，唯一的区别是jquery中的这个方法支持所有浏览器。

三、AJAX

3.1 ajax请求

### 3.2 ajax事件
### 3.3 其它

四、属性

4.1 属性

#### attr(name|properties|key,value|fn) 设置或返回被选元素的属性值。

removeAttr(name)

匹配的元素中删除一个属性

prop(name|properties|key,value|fn)

获取在匹配的元素集中的第一个元素的属性值。与attr的唯一区别是它更适合checkbox的checked属性的设置，true或者false。而不是attr中的checked。

removeProp(name)

删除由.prop()方法设置的属性集

4.2 CSS类

#### addClass(class|fn) 为每个匹配的元素添加指定的类名。

removeClass([class|fn])

从所有匹配的元素中删除全部或者指定的类。

toggleClass(class|fn[,sw])

如果存在（不存在）就删除（添加）一个类。

4.3 HTML/text/val

* html([val|fn]) 取得第一个匹配元素的html内容。 * text([val|fn]) 取得所有匹配元素的内容。结果是由所有匹配元素包含的文本内容组合起来的文本。 * val([val|fn|arr]) 获得匹配元素的当前值。

五、CSS

5.1 CSS样式

#### css(name|pro|[,val|fn]) 访问或修改匹配元素的样式属性。

jQuery.cssHooks

直接向 jQuery 中添加钩子，用于覆盖设置或获取特定 CSS 属性时的方法，目的是为了标准化 CSS 属性名或创建自定义属性。

5.2 位置

#### offset([coordinates]) 获取匹配元素在当前视口的相对偏移。返回的对象包含两个整型属性：top 和 left，以像素计。此方法只对可见元素有效。

position()

获取匹配元素相对父元素的偏移。
返回的对象包含两个整型属性：top 和 left。为精确计算结果，请在补白、边框和填充属性上使用像素单位。此方法只对可见元素有效。

scrollTop([val])

获取匹配元素相对滚动条顶部的偏移。此方法对可见和隐藏元素均有效。

scrollLeft([val])

获取匹配元素相对滚动条左侧的偏移。此方法对可见和隐藏元素均有效。

5.3 尺寸

#### height([val|fn]) 取得匹配元素当前计算的高度值（px）。 #### width([val|fn]) 取得第一个匹配元素当前计算的宽度值（px）。

innerHeight()

获取第一个匹配元素内部区域高度（包括补白、不包括边框）。

innerWidth()

获取第一个匹配元素内部区域宽度（包括补白、不包括边框）。

outerHeight([options])

获取第一个匹配元素外部高度（默认包括补白和边框）。

outerWidth([options])

获取第一个匹配元素外部宽度（默认包括补白和边框）。

六、文档处理

6.1 内部插入

#### append(content|fn) 向每个匹配的元素内部最后面追加内容。

appendTo(content)

把所有匹配的元素追加到另一个指定的元素元素集合中。

prepend(content)

向每个匹配的元素内部前置内容。

prependTo(content)

把所有匹配的元素前置到另一个、指定的元素元素集合中。

6.2 外部插入

#### after(content|fn) 在每个匹配的元素之后插入内容。也就是外部紧跟着的位置。 #### before(content|fn) 在每个匹配的元素之前插入内容。 #### insertAfter(content) 把所有匹配的元素插入到另一个、指定的元素集合的后面。after方法的颠倒操作。 #### insertBefore(content) 把所有匹配的元素插入到另一个、指定的元素集合的前面。before的颠倒操作。

6.3 包裹

6.4 替换

#### replaceWith(content|fn) 将所有匹配的元素替换成指定的HTML或DOM元素。 #### replaceAll(selector) 用匹配的元素替换掉所有 selector匹配到的元素。上面的颠倒操作。

6.5 删除

#### empty() 删除匹配的元素集合中所有的子节点。会留下元素标签。 #### remove([expr]) 从DOM中删除所有匹配的元素。什么都不留下。 #### detach([expr]) 从DOM中删除所有匹配的元素。与remove()不同的是，所有绑定的事件、附加的数据等都会保留下来。

6.6 复制

#### clone([Even[,deepEven]]) 克隆匹配的DOM元素并且选中这些克隆的副本。在想把DOM文档中元素的副本添加到其他位置时这个函数非常有用。

七、筛选

7.1 过滤

#### eq(index|-index) 获取当前链式操作中第N个jQuery对象，返回jQuery对象，当参数大于等于0时为正向选取，比如0代表第一个，1代表第二个。当参数为负数时为反向选取，比如-1为倒数第一个。 #### first() 获取第一个元素 #### last() 获取最后个元素 #### hasClass(class) 检查当前的元素是否含有某个特定的类，如果有，则返回true。其实就是 is("." + class)。 #### filter(expr|obj|ele|fn) 筛选出与指定表达式匹配的元素集合。这个方法用于缩小匹配的范围。用逗号分隔多个表达式 #### is(expr|obj|ele|fn) 根据选择器、DOM元素或 jQuery 对象来检测匹配元素集合，如果其中至少有一个元素符合这个给定的表达式就返回true。 #### map(callback) 将一组元素转换成其他数组（不论是否是元素数组）可以用这个函数来建立一个列表，不论是值、属性还是CSS样式，或者其他特别形式。 #### has(expr|ele) 保留包含特定后代的元素，去掉那些不含有指定后代的元素。 #### not(expr|ele|fn) 将与指定表达式匹配的元素挑除出去 #### slice(start, [end]) 选取一个匹配的子集。切片！

7.2 查找

#### children([expr]) 取得一个包含匹配的元素集合中每一个元素的所有子元素的元素集合。

closest(expr|object|element)

从元素本身开始，逐级向上级元素匹配，并返回最先匹配的元素。

find(expr|obj|ele)

搜索所有与指定表达式匹配的元素。这个函数是找出正在处理的元素的后代元素的好方法。

next([expr])

取得一个包含匹配的元素集合中每一个元素紧邻的后面同辈元素的元素集合。

nextAll([expr])

查找当前元素之后所有的同辈元素。

nextUntil([exp|ele][,fil])

查找当前元素之后所有的同辈元素，直到遇到匹配的那个元素为止。

offsetParent()

返回第一个匹配元素用于定位的父节点。

parent([expr])

取得一个包含着所有匹配元素的唯一父元素的元素集合。

parents([expr])

取得一个包含着所有匹配元素的祖先元素的元素集合（不包含根元素）。

parentsUntil([expr|element][,filter])

查找当前元素的所有的父辈元素，直到遇到匹配的那个元素为止。

prev([expr])

取得一个包含匹配的元素集合中每一个元素紧邻的前一个同辈元素的元素集合。

prevAll([expr])

查找当前元素之前所有的同辈元素

prevUntil([exp|ele][,fil])

查找当前元素之前所有的同辈元素，直到遇到匹配的那个元素为止。

siblings([expr])

取得一个包含匹配的元素集合中每一个元素的所有唯一同辈元素的元素集合。

7.3 串联

#### add(expr|ele|html|obj[,con]) 把与表达式匹配的元素添加到jQuery对象中。这是往已经选出来的元素集合中手动添加元素的方法。 #### addBack() 添加堆栈中元素集合到当前集合，一个选择性的过滤选择器。 #### contents() 查找匹配元素内部所有的子节点（包括文本节点）。如果元素是一个iframe，则查找文档内容。 #### end() 回到最近的一个"破坏性"操作之前。即，将匹配的元素列表变为前一次的状态。

八、事件

8.1 页面载入

#### ready(fn) 当DOM载入就绪可以查询及操纵时绑定一个要执行的函数。这是事件模块中最重要的一个函数，因为它可以极大地提高web应用程序的响应速度。简单地说，这个方法纯粹是对向window.load注册事件的替代方法。通过使用这个方法，可以在DOM载入就绪能够读取并操纵时立即调用你所绑定的函数，而99.99%的JavaScript函数都需要在那一刻执行。有一个参数－－对jQuery函数的引用－－会传递到这个ready事件处理函数中。可以给这个参数任意起一个名字，并因此可以不再担心命名冲突而放心地使用$别名。请确保在 ` `元素的onload事件中没有注册函数，否则不会触发+$(document).ready()事件。可以在同一个页面中无限次地使用$(document).ready()事件。其中注册的函数会按照（代码中的）先后顺序依次执行。

jQuery 代码:

$(document).ready(function(){
  // 在这里写你的代码...
});

或者使用 $(document).ready() 的简写，同时内部的 jQuery 代码依然使用 $ 作为别名，而不管全局的 $ 为何。

$(function($) {
  // 你可以在这里继续使用$作为别名...
});

8.2 事件处理

#### on(events,[selector],[data],fn) 在选择元素上绑定一个或多个事件的事件处理函数。 on()方法绑定事件处理程序到当前选定的jQuery对象中的元素。它是jquery所有绑定事件的底层方法。 #### off(events,[selector],[fn]) 在选择元素上移除一个或多个事件的事件处理函数。 off() 方法移除用.on()绑定的事件处理程序。 #### bind(type,[data],fn) 为每个匹配元素的特定事件绑定事件处理函数。 jQuery 3.0中已弃用此方法，请用 on()代替。 #### unbind(type,[data|fn]]) bind()的反向操作，从每一个匹配的元素中删除绑定的事件。 jQuery 3.0中已弃用此方法，请用 off()代替。 #### one(type,[data],fn) 为每一个匹配元素的特定事件（像click）绑定一个一次性的事件处理函数。 #### trigger(type,[data]) 在每一个匹配的元素上触发某类事件。 #### triggerHandler(type, [data]) 触发指定的事件类型上所有绑定的处理函数。但不会执行浏览器默认动作，也不会产生事件冒泡。

8.3 事件委派

live(type, [data], fn)已经废弃
die(type, [fn])已经废弃
delegate(selector,[type],[data],fn)在jQuery 3.0中弃用此方法，请用 on()代替。
委派事件，让后加入的元素自动具有同类的事件触发功能
undelegate([selector,[type],fn])在jQuery 3.0中已弃用此方法，请用 off()代替。
解除委派事件。

8.4 事件切换

#### hover([over,]out) 一个模仿悬停事件（鼠标移动到一个对象上面及移出这个对象）的方法。这是一个自定义的方法，它为频繁使用的任务提供了一种“保持在其中”的状态。over:鼠标移到元素上要触发的函数。out:鼠标移出元素要触发的函数。

toggle([speed],[easing],[fn])

用于绑定两个或多个事件处理器函数，以响应被选元素的轮流的 click 事件。

8.5 事件

blur([[data],fn])失去焦点
change([[data],fn])元素值发生改变
click([[data],fn])点击
dblclick([[data],fn])双击
error([[data],fn])错误
focus([[data],fn])获取焦点
focusin([data],fn)可以在父元素上检测子元素获取焦点的情况
focusout([data],fn)可以在父元素上检测子元素失去焦点的情况
keydown([[data],fn])按下某个键
keypress([[data],fn])每插入一个字符，就会发生该事件
keyup([[data],fn])按键弹起
mousedown([[data],fn])鼠标按下
mouseup([[data],fn])鼠标松开
mouseenter([[data],fn])鼠标穿过被选元素
mouseleave([[data],fn])鼠标离开被选元素
mousemove([[data],fn])鼠标在被选元素或它的子元素中移动，其.clientX 和 .clientY 属性代表鼠标的坐标
mouseout([[data],fn])鼠标离开被选元素或它的子元素
mouseover([[data],fn])鼠标指针位于元素上方时
resize([[data],fn])窗口大小被调整
scroll([[data],fn])滚动指定的元素
select([[data],fn])被选择
submit([[data],fn])提交表单
unload([[data],fn])离开页面

示例
描述:在服务器端记录JavaScript错误日志:
jQuery 代码:

$(window).error(function(msg, url, line){
  jQuery.post("js_error_log.php", { msg: msg, url: url, line: line });
});

描述:隐藏JavaScript错误:
jQuery 代码:

$(window).error(function(){
  return true;
});

描述:给你IE的用户隐藏无效的图像:
jQuery 代码:

$("img").error(function(){
  $(this).hide();
});

描述:在页面内对键盘按键做出回应，可以使用如下代码:
jQuery 代码:

$(window).keydown(function(event){
  switch(event.keyCode) {
    // ...
    // 不同的按键可以做不同的事情
    // 不同的浏览器的keycode不同
    // 更多详细信息:     http://unixpapa.com/js/key.html
    // 常用keyCode： 空格 32   Enter 13   ESC 27 CTRL 17
  }
});

描述:获得鼠标指针在页面中的位置：
jQuery 代码:

$(document).mousemove(function(e){
  $("span").text(e.pageX + ", " + e.pageY);
});

描述:如果你要阻止表单提交:
jQuery 代码:

$("form").submit( function () {
  return false;
} );

九、动画效果

9.1 基本

#### show([speed,[easing],[fn]]) 显示隐藏的匹配元素。 speed:三种预定速度之一的字符串("slow","normal",or"fast")或表示动画时长的毫秒数值(如：1000) fn:在动画完成时执行的函数，每个元素执行一次。 easing:(Optional) 用来指定切换效果，默认是"swing"，可用参数"linear"

hide([speed,[easing],[fn]])

隐藏显示的元素。
speed:三种预定速度之一的字符串("slow","normal",or"fast")或表示动画时长的毫秒数值(如：1000)
fn:在动画完成时执行的函数，每个元素执行一次。
easing:(Optional) 用来指定切换效果，默认是"swing"，可用参数"linear"

toggle([speed],[easing],[fn])

用于绑定两个或多个事件处理器函数，以响应被选元素的轮流的 click 事件。
其实就是在显示和隐藏两种状态之间进行切换。

9.2 滑动

#### slideDown([speed],[easing],[fn]) 以滑动方式显示隐藏的元素。参数同样。

slideUp([speed,[easing],[fn]])

以滑动方式隐藏元素。参数同样。

slideToggle([speed],[easing],[fn])

在显示和隐藏两种状态之间进行滑动切换。

9.3 淡入淡出

#### fadeIn([speed],[easing],[fn]) 通过不透明度的变化来实现所有匹配元素的淡入效果，并在动画完成后可选地触发一个回调函数。这个是显示出来，不是藏起来，下一个才是。

fadeOut([speed],[easing],[fn])

淡出，藏起来！

fadeTo([[speed],opacity,[easing],[fn]])

把所有匹配元素的不透明度以渐进方式调整到指定的不透明度，并在动画完成后可选地触发一个回调函数。opacity:一个0至1之间表示透明度的数字。
这个就是指定显示到多少透明度了！

fadeToggle([speed,[easing],[fn]])

淡入淡出的切换。

9.4 自定义

#### animate(params,[speed],[easing],[fn]) 用于创建自定义动画的函数。这个函数的关键在于指定动画形式及结果样式属性对象。这个对象中每个属性都表示一个可以变化的样式属性（如“height”、“top”或“opacity”）。注意：所有指定的属性必须用骆驼形式，比如用marginLeft代替margin-left. 而每个属性的值表示这个样式属性到多少时动画结束。如果是一个数值，样式属性就会从当前的值渐变到指定的值。如果使用的是“hide”、“show”或“toggle”这样的字符串值，则会为该属性调用默认的动画形式。

白话说就是，指定某个样式作为最终状态，元素会自动平滑的从当前样式过渡到指定的样式。

描述:在600毫秒内切换段落的高度和透明度

jQuery 代码:
$("p").animate({
   height: 'toggle', opacity: 'toggle'
 }, "slow");

在一个动画中同时应用三种类型的效果

$("#go").click(function(){
  $("#block").animate({ 
     "90%",
    height: "100%", 
    fontSize: "10em", 
    borderWidth: 10
  }, 1000 );
});

stop([clearQueue],[jumpToEnd])

停止所有在指定元素上正在运行的动画。
如果队列中有等待执行的动画(并且clearQueue没有设为true)，他们将被马上执行

delay(duration,[queueName])

设置一个延时来推迟执行队列中之后的项目。

$('#foo').slideUp(300).delay(800).fadeIn(400);

finish( [queue ] )

停止当前正在运行的动画，删除所有排队的动画，并完成匹配元素所有的动画。

9.5 设置

#### jQuery.fx.off 关闭页面上所有的动画。把这个属性设置为true可以立即关闭所有动画(所有效果会立即执行完毕)。当把这个属性设成false之后，可以重新开启所有动画。

  jQuery.fx.off = true;    //关闭 动画

jQuery.fx.interval

设置动画的显示帧速。

jQuery.fx.interval = 100;//100毫秒