jQuery.find()

注意

jQuery 选择器引擎首先尝试通过原生的 querySelectorAll 运行传入的选择器（并进行一些修改），因此当前浏览器原生支持的选择器通常可以直接使用。但是，如果浏览器无法识别该选择器，jQuery 将自行执行整个选择过程。某些较新的选择器可能不适用于这种 jQuery 选择方式。

选择器 (Selectors)

CSS 3

jQuery 几乎支持所有 CSS 3 选择器，包括转义选择器 (.foo\+bar)、Unicode 选择器，并且返回的结果按文档顺序排列。唯一的例外是那些需要额外的 DOM 事件监听器来跟踪元素状态的选择器。

因此，以下伪选择器不受支持：

• :hover
• :active
• :visited, :link

注意：在版本 1.9 之前，这些 CSS3 伪选择器是不受支持的

• :target
• :root
• :nth-last-child
• :nth-of-type, :nth-last-of-type, :first-of-type, :last-of-type, :only-of-type
• :lang()

其他选择器和约定

变更

• :not() 中的完整选择器列表；例如 :not(a.b), :not(div > p), :not(div, p)
• 嵌套伪选择器；例如 :not(:has(div:first-child))

新增

• [NAME!=VALUE]：NAME 属性与指定值不匹配的元素。等同于 :not([NAME=VALUE])。
• :contains(TEXT)：textContent 包含 'TEXT' 文本的元素。区分大小写。
• :header：标题元素 (h1, h2, h3, h4, h5, h6)。
• :parent：至少有一个子节点（文本或元素）的元素。
• :selected：当前被选中的 (option) 元素

表单选择器新增

注意：在这种情况下，input、button、select 和 textarea 都被视为输入元素。

• :input：输入元素
• :button：是 button 或 type 为 "button" 的输入元素
• :checkbox, :file, :image, :password, :radio, :reset, :submit, :text：具有指定 type 的输入元素

位置选择器新增

在这种情况下，“位置”指的是元素在选择后集合中的位置，基于文档顺序。例如，div:first 将返回包含页面上第一个 div 的数组，而 div:first em 将定位页面上第一个 div 并选择其中的所有 em 元素。

注意：位置索引从零开始。

• :first/:last：第一个/最后一个匹配元素
• :even/:odd：偶数/奇数位置的元素
• :eq/:nth：第 n 个元素；例如 :eq(5) 找到第 6 个元素
• :lt/:gt：位置高于/低于指定位置的元素

API

jQuery Selection API 由 3 部分组成

• 公共 API，供用户交互。
• 扩展 API，用于修改选择器引擎。
• 内部 API，供 jQuery 内部使用。

公共 API

jQuery.find( String selector[, DOMNode context[, Array results]] )

查找元素的主要函数。如果可用，使用 querySelectorAll。

返回 (Array)：所有匹配选择器的元素

参数

selector：CSS 选择器

context：用作查找元素的上下文的元素、文档或文档片段。默认为 document。注意：在版本 2.1 之前，文档片段在这里是无效的。

results：一个数组或类数组对象，jQuery 会将结果附加到其中。例如，jQuery 传入一个 jQuery 集合。一个“类数组对象”是一个具有非负数值 length 属性和 push 方法的对象。

jQuery.find.matchesSelector( DOMElement element, String selector )

如果可用，使用原生的 matchesSelector

返回(Boolean)：给定元素是否匹配选择器

参数

element：jQuery 将用其测试选择器的 DOMElement

selector：CSS 选择器

jQuery.find.matches( String selector, Array<DOMElement> elements )

返回(Array)：数组中匹配给定选择器的元素

参数

selector：CSS 选择器

elements：用于根据指定选择器进行过滤的 DOMElement 数组

扩展 API

jQuery.expr.match.NAME = RegExp

这包含用于将选择器解析为不同部分的正则表达式，用于查找和过滤。每个正则表达式的名称应与 jQuery.expr.find 和 jQuery.expr.filter 对象中指定的名称相对应。

查找

为了添加新的查找函数

• 必须向 match 对象添加一个正则表达式。
• 必须定义一个函数到 find。
• 必须将 "|" + NAME 追加到 jQuery.expr.order 正则表达式中。

jQuery.expr.find.NAME = function( match, context, isXML ) {}

一种用于在页面上查找某些元素的方法。指定的函数对每个选择器最多调用一次。

• match 是将指定的正则表达式与选择器匹配后返回的结果数组。
• context 是将从中进行选择的 DOMElement 或 DOMDocument。
• isXML 是一个布尔值，指示函数当前是否在 XML 文档中运行。

筛选 (Filtering)

为了添加新的过滤语句

• 必须向 match 对象添加一个正则表达式。
• 必须向 filter 对象添加一个函数。
• 可以选择向 preFilter 对象添加一个函数。

jQuery.expr.preFilter.NAME = function( match ) {}

一个可选的预过滤函数，允许根据相应的正则表达式过滤匹配数组，它将返回一个新的匹配数组。这个匹配数组最终将作为参数传递并扁平化到相应的过滤函数中。这旨在清理过滤函数中发生的一些重复处理。

jQuery.expr.filter.NAME: function( element, match[1][, match[2], match[3], ...] ) {}

注意： match[0] 在传递给过滤器之前将被删除，不得使用。

过滤器方法的参数是元素和与此过滤器对应的正则表达式的捕获（如上所示，从索引 1 开始）。返回结果必须是布尔值：如果元素匹配选择器，则为 true，否则为 false。

属性 (Attributes)

jQuery.expr.attrHandle.LOWERCASE_NAME = function( elem, casePreservedName, isXML ) {}

处理需要特殊处理的属性（例如 href，它存在跨浏览器问题）。返回结果必须是该属性的实际字符串值。

伪选择器 (pseudos)

jQuery.expr.pseudos.NAME = function( elem ) {}

选择器引擎最常见的扩展：添加新的伪选择器。此函数的返回结果必须是布尔值：如果元素匹配选择器，则为 true，否则为 false。

例如，这定义了一个简单的 :fixed 伪选择器

var $test = jQuery( document );
jQuery.expr.pseudos.fixed = function( elem ) {
  $test[ 0 ] = elem;
  return $test.css( "position" ) === "fixed";
};

jQuery.expr.createPseudo( function )

只有当自定义伪选择器接受参数时才需要 createPseudo。

注意：在 jQuery 1.8 及更早版本中，用于创建带参数的自定义伪选择器的 API 是有缺陷的。在 jQuery 1.8.1+ 中，API 向后兼容。无论如何，强烈建议使用 createPseudo。

现在解析器编译一个包含其他函数的单个函数，带参数的自定义伪选择器变得更加清晰。

例如，在 jQuery 内部，:not( <sub-selector> ) 伪选择器的实现与以下内容非常相似

jQuery.expr.pseudos.not =
  jQuery.expr.createPseudo( function( subSelector ) {
    var matcher = jQuery.find.compile( subSelector );
    return function( elem ) {
      return !matcher( elem );
    };
  } );

jQuery.expr.setFilters.LOWERCASE_NAME = function( elements, argument, not ) {}

这些过滤器在选择器的前一部分已经返回结果后运行。setFilters 是通过匹配 jQuery.expr.match.POS 找到的。在适用情况下，argument 预计是一个整数。not 参数是一个布尔值，指示结果是否应该反转（如 div:not(:first) 中所示）。

例如，:first setFilter 的代码类似于

var first = function( elements, argument, not ) {
  // No argument for first
  return not ? elements.slice( 1 ) : [ elements[ 0 ] ];
};
jQuery.expr.setFilters.first = first;

扩展 jQuery 选择引擎很容易 — 甚至包括 jQuery 的 POS 选择器。例如，将 :first 重命名为 :uno

jQuery.expr.match.POS = new RegExp( oldPOS.source.replace( "first", "uno" ), "gi" );
jQuery.expr.setFilters.uno = jQuery.expr.setFilters.first;
delete jQuery.expr.setFilters.first;
jQuery.find( "div:uno" ); // ==> [ <div> ]

内部 API

注意：功能应通过公共 API 和扩展 API 访问。虽然内部 API 专门用于内部用途，但为了应对边缘情况，它已被暴露。

jQuery.expr.cacheLength

jQuery 内部缓存编译的选择器函数和标记化对象。这些缓存的长度默认为 50，但可以通过将其分配给此属性来设置为任何正整数。

jQuery.find.compile( selector )

此方法编译一个选择器函数并将其缓存以供以后使用。例如，在插件初始化期间调用 jQuery.find.compile( ".myWidget:myPseudo" ) 将加快匹配元素的首次选择。

返回(Function)：用于过滤可能匹配元素集的已编译函数

参数

selector：CSS 选择器