jQuery 命令速查表 - jQuery 常用 API 与 DOM 操作大全

这套速查给还在维护老旧代码库、或需要给既有站点打补丁的前端开发者，覆盖每个 jQuery 文件里都出现的 API：选择器、读写 DOM 内容与属性、切类名、事件绑定与委托、Ajax 简写，以及基础动画。与一条条堆 jQuery API 不同，这里按"取元素→改内容→绑事件→发请求"一类交互动作来分组。读完应能把选择器链式接上 DOM 编辑、在动态列表上用事件委托保持性能，并一行 Ajax 代替整页刷新。

编程语言·共 45 条命令·最后更新 2026-07-21

典型使用场景

面向正在维护存量前端页面的开发者：jQuery 大量存在于没有构建工具的老项目、模板生成的后台系统和 WordPress 主题里，绕不开但也不值得为它引入新的框架。本表把维护期真正高频的几类操作集中起来：元素查找与遍历的正确区分（children 取直接子级、find 查所有后代）、类名与属性/数据/值的读写取舍、事件委托在动态插入节点场景下的必要性、Ajax 的全局头部注入与 Promise 化调用，以及动画效果的选用。最后一组易错点覆盖了 $.html() 误用丢事件、:eq 索引含义被误解、:first 只匹配一个元素这些反复踩的细节。

选择器 10

$("div")

标签选择器

$(".class")

类选择器

$("#id")

ID 选择器

$("div.class")

组合选择器

$("div > p")

子元素选择器

$("div p")

后代选择器

$(":input")

所有表单元素

$(":checkbox")

所有复选框

$("div:first")

第一个 div

$("li:eq(2)")

索引为 2 的 li

DOM 操作与遍历 14

$("#box").children("li")

取匹配元素的直接子元素中满足选择器的部分

$("#box").find("li")

向下查找所有后代中匹配的元素

$("#box").hasClass("active")

判断元素是否带有指定类，返回布尔值

$("#box").data("key")

读取元素上存的 data-key 数据

$("#box").html()

取匹配元素的首个 innerHTML，替换时把旧子节点整体替换

$("#box").html("内容")

把元素内部 HTML 整体替换为给定片段，重渲染简单视图常用

$("#box").text()

取合并后的纯文本内容，写文字内容用它避免 HTML 转义问题

$("#box").val()

取表单控件当前值，读 input/select 的值最常用

$("#box").attr("data-id")

取元素的 data-id 属性值，读自定义属性和固有属性通用

$("#box").attr("data-id", "123")

为元素设置 data-id 属性，动态挂数据给事件回调读取

$("#box").addClass("active")

为元素追加类名，常用于切换选中/高亮状态

$("#box").removeClass("active")

移除指定类名，没有该类时无副作用

$("#box").toggleClass("active")

有该类就移除、没有就添加，做开关样式最省事

$("<div>").appendTo("body")

创建新元素并插到 body 末尾，动态添加 DOM 的常用写法

事件绑定 8

$("#btn").click(fn)

点击事件

$("#btn").on("click", fn)

绑定事件（推荐）

$("#btn").off("click")

解绑事件

$(document).on("click", ".btn", fn)

事件委托

$("input").change(fn)

值改变事件

$("form").submit(fn)

表单提交事件

$(document).ready(fn)

DOM 加载完成

$(fn)

简写：DOM 加载完成

Ajax 请求 5

$.get("/api/data", fn)

GET 请求

$.post("/api/data", { key: "value" }, fn)

POST 请求

$.getJSON("/api/data", fn)

获取 JSON

$.ajax({ url, method, data, success })

完整 Ajax 调用

$.ajaxSetup({ headers: { "X-Token": token } })

全局设置请求头

动画与效果 8

$("#box").show()

显示

$("#box").hide()

隐藏

$("#box").toggle()

切换显示

$("#box").fadeIn()

淡入

$("#box").fadeOut()

淡出

$("#box").slideDown()

下滑显示

$("#box").slideUp()

上滑隐藏

$("#box").animate({ left: "200px" }, 500)

自定义动画

参数矩阵

参数	作用	示例
`$("div")`	标签选择器，取全部 div	`$("div")`
`$(".class")`	类选择器，取带该类名的元素	`$(".item")`
`$("#id")`	ID 选择器	`$("#box")`
`$("div > p")`	子元素选择器，只匹配直接子级 p	`$("div > p")`
`$("div p")`	后代选择器，匹配任意层级后代 p	`$("div p")`
`$(":input")`	匹配所有表单元素	`$(":input")`
`$(":checkbox")`	匹配所有复选框	`$(":checkbox")`
`$("div:first")`	只匹配匹配集中的第一个 div	`$("div:first")`
`$("li:eq(2)")`	匹配索引为 2 的元素（索引从 0 开始）	`$("li:eq(2)")`
`.children(sel)`	取直接子元素中满足选择器的部分	`$("#box").children("li")`
`.find(sel)`	向下查找所有后代中的匹配元素	`$("#box").find("li")`
`.hasClass(name)`	判断是否带指定类名，返回布尔值	`$("#box").hasClass("active")`
`.data("key")`	读取元素上存的 data-key 数据	`$("#box").data("key")`
`.attr("data-id")`	读/写 HTML 属性	`$("#box").attr("data-id", "123")`
`.html() / .html(str)`	整体读写 innerHTML，替换会重建子节点	`$("#box").html("<p>内容</p>")`
`.text()`	读写纯文本，不做 HTML 转义	`$("#box").text()`
`.val()`	读写表单控件当前值	`$("#box").val()`
`.addClass/.removeClass/.toggleClass`	类名的增/删/切换	`$("#box").toggleClass("active")`
`$("<div>").appendTo("body")`	创建新元素并插入指定位置	`$("<div>").appendTo("body")`
`.on(event, sel, fn)`	事件委托，匹配后代冒泡上来的事件	`$(document).on("click", ".btn", fn)`
`.off(event)`	解绑事件	`$("#btn").off("click")`
`$(document).ready(fn)`	DOM 加载完成后执行	`$(document).ready(fn)`
`$.get / $.post / $.getJSON`	GET、POST、取 JSON 的快捷请求	`$.get("/api/data", fn)`
`$.ajax({ url, method, data, success })`	完整 Ajax 调用，可指定方法与数据	`$.ajax({ url, method, data, success })`
`$.ajaxSetup({ headers })`	全局设置所有 Ajax 请求头	`$.ajaxSetup({ headers: { "X-Token": token } })`
`.show/.hide/.toggle`	显示、隐藏、切换可见性	`$("#box").toggle()`
`.fadeIn/.fadeOut`	淡入淡出	`$("#box").fadeOut()`
`.slideDown/.slideUp`	下滑显示、上滑隐藏	`$("#box").slideDown()`
`.animate(props, ms)`	自定义属性动画	`$("#box").animate({ left: "200px" }, 500)`

易错点与避坑指南

现象用 .html() 局部刷新容器后，容器内部元素上绑定的点击事件全部失效。

原因.html() 是整体替换 innerHTML，旧子节点被销毁，绑定在其上的事件处理器随之丢失。

处置改用事件委托把处理器挂到稳定的父元素上：$(document).on("click", ".btn", fn)，让它对新插入的节点同样生效。

现象$("li:eq(2)") 取到的不是预期的第三个元素。

原因:eq() 的索引从 0 开始，:eq(2) 是第三个；但若选择器前还带了标签过滤，索引是相对过滤后的集合而不是全体节点。

处置用 .eq(2) 明确在已筛选集合上取第三项，或用 .slice(0, 3) 取前三个，避免 :first/:eq 语义混淆。

现象$("div:first") 期望选中所有容器里各有一个首个 div，结果只拿到一个元素。

原因:first 是位置伪类，在整个匹配集合里只取第一个；需要「每个父级内的第一个」应该用 :first-child 或 .eq(0) 分组处理。

处置改用 CSS 结构选择器 $("div > :first-child")，或对每个容器单独用 .children().first()。

现象页面上有多个同名 id，用 $("#box") 只能操作其中一个，样式怎么改都不生效。

原因id 在 HTML 中必须全局唯一，重复 id 属于非法结构，jQuery 的 ID 选择器走 getElementById 只返回第一个。

处置把重复 id 换成 class，用 $(".box").eq(n) 精确定位，或用 $(".box").filter(":nth-of-type(n)") 定位。

现象把用户输入直接拼进 .html() 后页面出现脚本标签被执行。

原因.html() 解析并执行 HTML 内容，未过滤的输入会形成 XSS 注入点。

处置插入纯文本一律用 .text()；确需插 HTML 时先过滤再拼，不要把请求参数直接交给 .html()。

现象多个 Ajax 请求同时发出，后返回的旧请求把新数据覆盖了，界面出现回跳。

原因并发请求没有做时序控制，响应到达顺序不保证与发出顺序一致。

处置在 $.ajax 的 success 回调里判断当前页码/关键字是否仍与发起时一致，不一致就丢弃该响应；或对搜索框输入做防抖处理。

现象依赖 should 风格的断言式写法在值为 null 时报「Cannot read property should of null」。

原因直接对 null 或 undefined 取属性时 JS 会先抛错，断言根本没机会执行。

处置改用 expect 风格：expect(value).to.not.be.null，断言在参数求值前就能安全地处理空值。

排障路径

1确认选择器到底匹配了几个元素
console.log($("li:eq(2)").length)
输出 1 说明选择器命中了单个元素；若期望多个，先打印 $('.selector').length 确认基础集合大小。
2确认事件处理器是否真的挂上了
console.log($("#btn").data("events"))
输出 undefined 说明没有绑定任何事件，优先检查选择器是否命中目标元素。
3检查某元素上是否残留重复绑定
$("#btn").off("click").on("click", fn)
先 off 再 on 消除重复绑定；输出行为正常即说明原问题是同一事件被绑了多遍。
4给所有 Ajax 请求统一加上鉴权头
$.ajaxSetup({ headers: { "X-Token": token } })
在发起任何请求前执行一次，服务端收到的每个请求都会带上该头。
5观察实际发出的请求与响应
$.ajax({ url: "/api/data", method: "GET", success: console.log })
success 里打印响应体可确认是服务端返回问题还是前端解析问题。
6确认读写的是值还是文本
console.log($("#box").val(), $("#box").text())
表单控件用 .val()，纯文本节点用 .text()；两个都打印可快速判断该用哪个。

命令示例

事件委托处理动态插入的列表项

$(document).ready(function () {
  $(document).on("click", ".row .del", function (e) {
    e.preventDefault()
    $(this).closest(".row").remove()
  })

  $("#box").html('<div class="row"><span class="del">x</span></div>')
})

直接给 .del 绑定事件时，后续 html() 重建的节点不会带上处理器，点击静默失效。委托到 document 上只绑一次，新增节点照样响应。

全局注入 Token 头，再用 $.post 提交表单数据

$.ajaxSetup({ headers: { "X-Token": token } })

$("form").submit(function (e) {
  e.preventDefault()
  $.post("/api/data", { key: "value" }, function (res) {
    $("#box").text("saved: " + res.id)
  })
})

ajaxSetup 把鉴权头集中到一处，避免每个请求手写 headers。回调里用 text() 而不是 html()，接口回传的内容不会被当作标记解析。

toggleClass 切换状态，attr 挂数据给回调读

$("#box").attr("data-id", "123")
$("#box").toggleClass("active")

$("#box").on("click", function () {
  var id = $(this).data("id")
  $.getJSON("/api/item/" + id, function (data) {
    $(this).text(data.title)
  }.bind(this))
})

data("id") 读的是 jQuery 缓存的 data-* 值，与 attr("data-id") 写入的值同源但读取路径不同：HTML5 之外动态加的属性只有走 attr 才能保证一致。

链式选择：容器内定位 + 属性判断

if ($("#box").hasClass("active")) {
  $("#box").find("li:eq(2)").addClass("current")
}
$("#box").children("li:first").text("首项")

find 把查找范围锁在容器内，避免全文档的 li 被误选；hasClass 先做一次判断可以省掉后续整段 DOM 遍历。

常见坑与注意事项

$(selector) 是全局搜索：写 $("li:eq(2)") 选中的是整页第 3 个 li，而不是某个容器内的第 3 个，结果随页面其它模块增减而漂移；应写 $("#box").find("li").eq(2)。
.html("内容") 会整体替换子节点，原来绑定在子元素上的事件处理器一并消失；列表重渲染后点击没反应，根因通常在这里而不是事件代码。
.click()、.change()、.submit() 等快捷方法在 jQuery 3.x 已废弃，3.5 起会在控制台打出弃用警告，团队统一升级 3.x 时应全部换成 .on(...)。
把接口返回或用户输入直接拼进 .html() 等于开放 XSS，服务端数据被篡改一次即可在所有用户页面执行脚本；纯文本一律用 .text()。
$.getJSON 的回调只在成功时触发，失败默认被静默忽略：接口 500 时页面既不报错也不更新，用 $.ajax({ error }) 或 .fail 补上失败分支。
循环里反复写 $(".item").length 或 $(".item").eq(i) 会每次重新查询整个文档，长列表下直接拖垮主线程；先把集合缓存成变量再用 .each 遍历。

提示

事件委托 $(parent).on("click", ".child", fn) 适合动态添加的元素场景。
jQuery 3.x 已移除 $.ajax() 的 success/error 回调，推荐用 Promise。
新项目建议用原生 DOM API 或 Vue/React，jQuery 主要用于维护老项目。

常见问题

children() 和 find() 到底差在哪？

差别是查找深度：children("li") 只取匹配元素的直接子元素中满足选择器的那部分，一层，不往下；find("li") 向下遍历所有后代，任意深度都算。比如结构是 div#box > ul > li > a 时，$("#box").children("li") 拿不到（li 不是 box 的直接子级），而 $("#box").find("li") 可以拿到。所以做「直接子项」如菜单的二级层级时用 children，做「范围内任意匹配」如表格内所有链接时用 find。相邻还有 $(":checkbox")、$(":input") 这类表单伪选择器可配合 filter 收窄。

html()、text()、val()、attr()、data() 读值时怎么选？

按「取哪种值」分。html() 读的是首个匹配元素的 innerHTML，要写富文本片段时用它替换，$("#box").html("内容") 会把旧子节点整体换掉。text() 取合并后的纯文本，写文字用它可避免 HTML 转义问题。val() 专取表单控件当前值，读 input/select 最常用。attr("data-id") 读的是 HTML 属性（写与固有属性都适用），$("#box").attr("data-id", "123") 动态挂数据给事件回调读；而 data("key") 读的是元素上存的 data-key 数据，jQuery 首次读取会缓存进内部，之后直接改 attribute 不会同步，需 .removeData() 清缓存。

列表由 AJAX 动态生成，为什么事件绑了没反应？

因为直接绑在元素上时，绑定那一刻元素还不存在。两种解法：一是把事件交给一个稳定存在的祖先，用事件委托 $(document).on("click", ".btn", fn)，选择器 ".btn" 作为第二参数，事件冒泡到 document 时才做匹配，之后新插入的 .btn 同样生效；二是先用 $(document).ready(fn) 或简写 $(fn) 等 DOM 加载完成再绑定，但这对后续动态插入的元素依然无效。解绑用 $("#btn").off("click")，重复绑定前先 off 可以避免一次点击触发多次回调。表单相关事件用 $("input").change(fn) 和 $("form").submit(fn)。

jQuery 3.x 里的 $.ajax 该怎么写才不被弃用警告？

3.x 已经移除 $.ajax() 的 success / error 回调写法，改用 Promise：$.get("/api/data", fn) 传回调的简写形式还可用，但 $.post("/api/data", { key: "value" }, fn)、$.getJSON("/api/data", fn) 同样是回调式，想要 then/catch 就必须用 $.ajax({ url, method, data, success }) 的完整调用并读取返回的 jqXHR。请求头可以全局设一次：$.ajaxSetup({ headers: { "X-Token": token } })，之后所有请求自动带上，无需每处重复写 headers。选型上，GET 和取 JSON 用简写最省事，需要链式 then/catch、精细控制 method 或复用配置时才用 $.ajax。

show/hide、fadeIn/slideUp 和 animate 到底怎么选？

按「要不要过渡效果」分。show() / hide() / toggle() 是瞬间切换显示状态，适合不需要动画的显隐逻辑（下拉菜单展开、模态框）。要过渡就用 fadeIn() / fadeOut() 淡入淡出，或 slideDown() / slideUp() 纵向展开收起——后者做手风琴、展开详情一类的布局变化最自然，因为高度变化不会生硬。要完全自定义则用 animate({ left: "200px" }, 500)，第二个参数是毫秒时长，可传属性对象实现补间。类名状态切换则交给 addClass("active") / removeClass("active") / toggleClass("active")，后者适合做开关样式。

官方参考来源

下方为命令对应的官方权威文档，供你核对最新用法与深入查阅。

官方文档

由巧匠维护

公开更新于 2026年7月21日，内容持续校对官方文档。

联系我们

命令或描述有误？提交反馈、商务合作或产品建议都可发送邮件给我们。

联系我们

典型使用场景

选择器 10

DOM 操作与遍历 14

事件绑定 8

Ajax 请求 5

动画与效果 8

参数矩阵

易错点与避坑指南

排障路径

命令示例

事件委托处理动态插入的列表项

全局注入 Token 头，再用 $.post 提交表单数据

toggleClass 切换状态，attr 挂数据给回调读

链式选择：容器内定位 + 属性判断

常见坑与注意事项

提示

常见问题

相关速查表

分享

官方参考来源

由 巧匠 维护

联系我们

由巧匠维护