jQuery 学习九(筛选)

    ●  eq(index)

/**
 * 获取第 N 个元素。
 *
 * @index(Integer) 元素在 jQuery 对象中的索引
 * @return Object
 * @owner jQuery Object
 */
function eq(index);

// 例子：获取匹配的第二个元素。
<p> This is just a test.</p>
<p> So is this</p>

$("p").eq(1) ->  [ <p> So is this</p> ]

    ●  filter(expr)

/**
 * 筛选出与指定表达式匹配的元素集合。
 * 这个方法用于缩小匹配的范围。用逗号分隔多个表达式。
 *
 * @expr(Expression) 过滤表达式
 * @return Object
 * @owner jQuery Object
 */
function filter(expr);

// 例子一：保留带有 select 类的元素。
<p>Hello</p>
<p>Hello Again</p>
<p class="selected">And Again</p>
<p> So is this</p>

$("p").filter(".selected") ->  [ <p class="selected">And Again</p> ]

// 例子二：保留第一个以及带有 select 类的元素。
<p>Hello</p>
<p>Hello Again</p>
<p class="selected">And Again</p>

$("p").filter(".selected, :first") -> [ <p>Hello</p>, <p class="selected">And Again</p> ]

    ●  filter(fn)

/**
 * 筛选出与指定函数返回值匹配的元素集合。
 * 这个函数内部将对每个对象计算一次(正如 "$.each")。
 * 如果调用的函数返回 false 则这个元素被删除，否则就会保留。
 *
 * @fn(Function) 传递进 filter 的函数
 * @return Object
 * @owner jQuery Object
 */
function filter(fn);

// 例子：保留子元素中不含有 ol 的元素。
<p>
  <ol>
    <li>Hello</li>
  </ol>
</p>
<p>How are you?</p> 

$("p").filter(function(index) {
  return $("ol", this).length == 0;
});  ->  [ <p>How are you?</p> ]

    ●  hasClass(class)

/**
 * 检查当前的元素是否含有某个特定的类，如果有，则返回 true。
 * 这其实就是 is("." + class)。
 *
 * @class(String) 用于匹配的类名
 * @return boolean
 * @owner jQuery Object
 */
function hasClass(class);

// 例子：给包含有某个类的元素进行一个动画。
<div class="protected"></div>
<div></div>

$("div").click(function() {
  if ( $(this).hasClass("protected") )
    $(this)
      .animate({ left: -10 })
      .animate({ left: 10 })
      .animate({ left: -10 })
      .animate({ left: 10 })
      .animate({ left: 0 });
});

    ●  is(expr)

/**
 * 用一个表达式来检查当前选择的元素集合，如果其中至少有一个元素符合这个给定的表达式就返回 true。
 * 如果没有元素符合，或者表达式无效，都返回 false。filter 内部实际也是在调用这个函数，所以，filter()
 * 函数原有的规则在这里也适用。
 *
 * @expr(String) 用于筛选的表达式
 * @return boolean
 * @owner jQuery Object
 */
function is(expr);

// 例子：由于 input 元素的父元素是一个表单元素，所以返回 true。
<form>
  <input type="checkbox" />
</form>

$("input[type='checkbox']").parent().is("form") = true

    ●  map(callback)

/**
 * 将一组元素转换成其他数组(不论是否是元素数组)。
 * 你可以用这个函数来建立一个列表，不论是值、属性还是 CSS 样式，或者其他特别形式。这都可以用
 * $.map() 来方便的建立。
 *
 * @callback(Function) 给每个元素执行的函数
 * @return jQuery Object
 * @owner jQuery Object
 */
function map(callback);

// 例子：把 form 中的每个 input 元素的值建立一个列表。
<form>
  <input type="text" name="name" value="John"/>
  <input type="text" name="password" value="password"/>
  <input type="text" name="url" value="http://ejohn.org/"/>
</form>

/**
 * callback 里的 this 代表的是 DOM 元素，$(this) 则把 DOM 对象转换为 jQuery 对象。
 * map 函数返回的是 jQuery Object
 */
var result = $(function() {
  $("input").map(function() {
    return $(this).val();
  });
}); -> 
result[0] = "John"
result[1] = "password"
result[2] = "http://ejohn.org/"

    ●  not(expr)

/**
 * 删除与指定表达式匹配的元素。
 *
 * @expr(String, DOMElement, Array<DOMElement>) 一个表达式、一个元素或者一组元素
 * @return jQuery Object
 * @owner jQuery Object
 */
function not(expr);

// 例子：从 p 元素中删除 id 为 "selected" 的元素。
<p>Hello</p>
<p id="selected">Hello Again</p>

$("p").not( $("#selected")[0] ) -> [ <p>Hello</p> ]

    ●  slice(start, [end])

/**
 * 选取一个匹配的子集。
 *
 * @start(Integer) 开始选取子集的位置。第一个元素是 0.如果是负数，则可以从集合的尾部开始选起。
 * @end(Integer) (可选) 结束选取自己的位置，如果不指定，则就是本身的结尾。
 * @return jQuery Object
 * @owner jQuery Object
 */
function slice(start, [end]);

// 例子一：选择第一个 p 元素。
<p>Hello</p>
<p>cruel</p>
<p>World</p>

$("p").slice(0, 1).wrapInner("<b></b>") -> [ <p><b>Hello</b></p> ]

// 例子二：选择前两个 p 元素。
<p>Hello</p>
<p>cruel</p>
<p>World</p>

$("p").slice(0, 2).wrapInner("<b></b>") -> [ <p><b>Hello</b></p>,<p><b>cruel</b></p> ]

// 例子三：只选取第二个 p 元素。
<p>Hello</p>
<p>cruel</p>
<p>World</p>

$("p").slice(1, 2).wrapInner("<b></b>") -> [ <p><b>cruel</b></p> ]

// 例子四：只选取第二和第三个 p 元素。
<p>Hello</p>
<p>cruel</p>
<p>World</p>

$("p").slice(1).wrapInner("<b></b>") -> [ <p><b>cruel</b></p>, <p><b>World</b></p> ]

// 例子五：选取第最后一个 p 元素。
<p>Hello</p>
<p>cruel</p>
<p>World</p>

$("p").slice(-1).wrapInner("<b></b>") -> [ <p><b>World</b></p> ]

    ●  add(expr)

/**
 * 把与表达式匹配的元素添加到 jQuery 对象中。这个函数可以用于连接分别与两个表达式匹配的元素结果集。
 *
 * @expr(String, DOMElement, Array<DOMElement>) 用于匹配元素并添加的表达式字符串，或者用于动态生成
 *                                              的 HTML 代码，如果是一个字符串数组则返回多个元素
 * @return jQuery Object
 * @owner jQuery Object
 */
function add(expr);

// 例子一：添加一个新元素到一组匹配的元素中，并且这个新元素能匹配给定的表达式。
<p>Hello</p>
<span>Hello Again</span>

$("p").add("span") -> [ <p>Hello</p>, <span>Hello Again</span> ]

// 例子二：动态生成一个元素并添加至匹配的元素中。
<p>Hello</p>

$("p").add("<span>Again</span>") -> [ <p>Hello</p>, <span>Hello Again</span> ]

// 例子三：为匹配的元素添加一个或者多个元素。
<p>Hello</p>
<p><span id="a">Hello Again</span></p>

$("p").add(document.getElementById("a")) -> 
[ <p>Hello</p>, <p><span id="a">Hello Again</span></p>, <span id="a">Hello Again</span> ]

    ●  children([expr])

/**
 * 取得一个包含匹配的元素集合中每一个元素的所有子元素的元素集合。可以通过可选的表达式来过滤所匹配的
 * 子元素。注意：parents() 将查找所有祖辈元素，而 children() 只考虑子元素而不考虑所有后代元素。
 *
 * @expr(String) (可选) 用以过滤子元素的表达式
 * @return jQuery Object
 * @owner jQuery Object
 */
function children([expr]);

// 例子一：查找 DIV 中的每个子元素。
<p>Hello</p>
<div><span>Hello Again</span></div>
<p>And Again</p>

$("div").children() -> [ <span>Hello Again</span> ]

// 例子二：在每个 div 中查找 .selected 的类。
<div>
  <span>Hello</span>
  <p class="selected">Hello Again</p>
  <p>And Again</p>
</div>

$("div").children(".selected") ->  <p class="selected">Hello Again</p> ]

    ●  contents()

/**
 * 查找匹配元素内部所有的子节点(包括文本节点)。如果元素是一个 iframe，则查找文档内容。
 *
 * @return jQuery Object
 * @owner jQuery Object
 */
function contents();

// 例子一：查找所有文本节点并加粗。
<p>Hello <a href="http://ejohn.org/">John</a>, how are you doing?</p>

$("p").contents().not("[nodeType=1]").wrap("<b/>") -> 
<p><b>Hello</b> <a href="http://ejohn.org/">John</a>, <b>how are you doing?</b></p>

// 例子二：往一个空框架中加些内容。
<iframe src="/index-blank.html" width="300" height="100"></iframe>

$("iframe").contents().find("body").append("I'm in an iframe!")

    ●  find(expr)

/**
 * 搜索所有与指定表达式匹配的元素。这个函数是找出正在处理的元素的后代元素的好方法。
 * 所有搜索都依靠 jQuery 表达式来完成。这个表达式可以使用 CSS1-3 的选择器语法来写。
 *
 * @expr(String) 用于查找的表达式
 * @return jQuery Object
 * @owner jQuery Object
 */
function find(expr);

// 例子：从所有的段落开始，进一步搜索下面的 span 元素。与 $("p span") 相同。
<p><span>Hello</span>, how are you?</p>

$("p").find("span") -> [ <span>Hello</span> ]

    ●  next([expr])

/**
 * 取得一个包含匹配的元素集合中每一个元素紧邻的后面同辈元素的元素集合。
 * 这个函数只返回后面那个紧邻的同辈元素，而不是后面所有的同辈元素(可以使用nextAll)。
 * 可以用一个可选的表达式进行筛选。
 *
 * @expr(String) (可选) 用于筛选的表达式
 * @return jQuery Object
 * @owner jQuery Object
 */
function next([expr]);

// 例子一：找到每个段落的后面紧邻的同辈元素。
<p>Hello</p>
<p>Hello Again</p>
<div><span>And Again</span></div>

$("p").next() -> [ <p>Hello Again</p>, <div><span>And Again</span></div> ]

// 例子二：找到每个段落的后面紧邻的同辈元素中类名为 selected 的元素。
<p>Hello</p>
<p class="selected">Hello Again</p>
<div><span>And Again</span></div>

$("p").next(".selected") -> [ <p class="selected">Hello Again</p> ]

    ●  nextAll([expr])

/**
 * 查找当前元素之后所有的同辈元素。可以用表达式进行过滤。
 *
 * @expr(String) (可选) 用于筛选的表达式
 * @return jQuery Object
 * @owner jQuery Object
 */
function nextAll([expr]);

// 例子：给第一个div之后的所有元素加个类。
<div></div>
<div></div>
<div></div>
<div></div>

$("div:first").nextAll().addClass("after") -> 
    [ <div class="after"></div>, <div class="after"></div>, <div class="after"></div> ]

    ●  parent([expr])

/**
 * 取得一个包含着所有匹配元素的唯一父元素的元素集合。你可以使用可选的表达式来筛选。
 *
 * @expr(String) (可选) 用于筛选的表达式
 * @return jQuery Object
 * @owner jQuery Object
 */
function parent([expr]);

// 例子一：查找每个段落的父元素。
<div>
  <p>Hello</p>
  <p>Hello</p>
</div>

$("p").parent() -> [ <div><p>Hello</p><p>Hello</p></div>]

// 例子二：查找段落的父元素中每个类名为 selected 的父元素。
<div>
  <p>Hello</p>
</div>
<div class="selected">
  <p>Hello Again</p>
</div>

$("p").parent(".selected") -> [ <div class="selected"><p>Hello Again</p></div> ]

    ●  parents([expr])

/**
 * 取得一个包含着所有匹配元素的祖先元素的元素集合。可以通过一个可选的表达式进行筛选。
 *
 * @expr(String) (可选) 用于筛选祖先元素的表达式
 * @return jQuery Object
 * @owner jQuery Object
 */
function parents([expr]);

// 例子一：找到每个 span 元素的所有祖先元素。
<html>
  <body>
    <div>
      <p>
        <span>Hello</span>
      </p>
      <span>Hello Again</span>
    </div>
  </body>
</html>

$("span").parents()

// 例子二：找到每个 span 的所有是 p 元素的祖先元素。
<html>
  <body>
    <div>
      <p>
        <span>Hello</span>
      </p>
      <span>Hello Again</span>
    </div>
  </body>
</html>

$("span").parents("p")

    ●  prev([expr])

/**
 * 取得一个包含匹配的元素集合中每一个元素紧邻的前一个同辈元素的元素集合。
 * 可以用一个可选的表达式进行筛选。只有紧邻的同辈元素会被匹配到，而不是前面所有的同辈元素。
 *
 * @expr(String) (可选) 用于筛选前一个同辈元素的表达式
 * @return jQuery Object
 * @owner jQuery Object
 */
function prev([expr]);

// 例子一：找到每个段落紧邻的前一个同辈元素。
<p>Hello</p>
<div>
  <span>Hello Again</span>
</div>
<p>And Again</p>

$("p").prev() -> [ <div><span>Hello Again</span></div> ]

// 例子二：找到每个段落紧邻的前一个同辈元素中类名为 selected 的元素，
<div>
  <span>Hello</span>、
</div>
<p class="selected">Hello Again</p>
<p>And Again</p>

$("p").prev(".selected") -> [ <p class="selected">Hello Again</p> ]

    ●  prevAll([expr])

/**
 * 查找当前元素之前所有的同辈元素，可以用表达式渐进行过滤。
 *
 * @expr(String) (可选) 用于过滤的表达式
 * @return jQuery Object
 * @owner jQuery Object
 */
function prevAll([expr]);

// 例子：给最后一个之前的所有 div 加上一个类。
<div></div>
<div></div>
<div></div>
<div></div>

$("div:last").prevAll().addClass("before") -> 
    [ <div class="before"></div>, <div class="before"></div>, <div class="before"></div> ]

    ●  siblings([expr])

/**
 * 取得一个包含匹配的元素集合中每一个元素的所有唯一同辈元素的元素集合。可以用可选的表达式进行筛选。
 *
 * @expr(String) (可选) 用于筛选同辈元素的表达式
 * @return jQuery Object
 * @owner jQuery Object
 */
function siblings([expr]);

// 例子一：找到每个 div 的所有同辈元素。
<p>Hello</p>
<div>
  <span>Hello Again</span>
</div>
<p>And Again</p>

$("div").siblings() -> [ <p>Hello</p>, <p>And Again</p> ]

// 例子二：找到每个 div 的所有同辈元素中带有类名为 selected 的元素。
<div>
  <span>Hello</span>
</div>
<p class="selected">Hello Again</p>
<p>And Again</p>

$("div").siblings(".selected") -> [ <p class="selected">Hello Again</p> ]

    ●  andSelf()

/**
 * 加入先前所选的加入当前元素中。对于筛选或查找后的元素，要加入先前所选元素时将会很有用。
 *
 * @return jQuery Object
 * @owner jQuery Object
 */
function andSelf();

// 例子：选取所有 div 以及内部的 p，并加上 border 类。
<div>
  <p>First Paragraph</p>
  <p>Second Paragraph</p>
</div>

$("div").find("p").andSelf().addClass("border") -> 
<div class="border"><p class="border">First Paragraph</p><p class="border">Second Paragraph</p></div>

    ●  end()

/**
 * 回到最近的一个 "破坏性" 操作之前。即，将匹配的元素列表变为前一次的状态。
 * 如果之前没有破坏性操作，则返回一个空集。所谓的 "破坏性" 就是指任何改变所匹配的 jQuery 元素的操作。
 * 这包括在 Traversing 中任何返回一个 jQuery 对象的函数：
 * 'add', 'andSelf', 'children', 'filter', 'find', 'map', 'next', 'nextAll', 'not', 
 * 'parent', 'parents', 'prev', 'prevAll', 'siblings' and 'slice'。
 * 另外再加上 Manipulation 中的 'clone'。
 *
 * @return jQuery Object
 * @owner jQuery Object
 */
function end();

// 选取所有的 p 元素，查找并选取 span 子元素，然后再回过来选取 p 元素。
<p>
  <span>Hello</span>,how are you?
</p>

$("p").find("span").end() -> [ <p><span>Hello</span> how are you?</p> ]