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> ]