jQuery()

分類：核心
根據傳遞的引數在 DOM 中找到或透過傳遞 HTML 字串建立的相符元素集合。

內容

jQuery( selector [, context ] )傳回：jQuery

說明：接受包含 CSS 選擇器的字串，然後用來比對一組元素。

在上面列出的第一個公式中，jQuery() — 也可寫成 $() — 會在 DOM 中搜尋任何與提供的選取器相符的元素，並建立一個新的 jQuery 物件來參照這些元素

1
 
$( "div.foo" );

如果沒有元素與提供的選取器相符，新的 jQuery 物件會是「空的」；也就是說，它不包含任何元素，且 .length 屬性為 0。

選取器內容

預設情況下，選取器會從文件根目錄開始在 DOM 中執行搜尋。不過，可以透過使用 $() 函式的第二個選用參數，為搜尋提供替代內容。例如，要在事件處理常式中執行搜尋，可以像這樣限制搜尋

1
2
3
 
$( "div.foo" ).on( "click", function() {
  $( "span", this ).addClass( "bar" );
});

當 span 選擇器的搜尋限制在 this 的內容中時，只有被按下的元素內的 span 會取得額外的類別。

在內部，選擇器內容是使用 .find() 方法實作的，所以 $( "span", this ) 等於 $( this ).find( "span" )。

使用 DOM 元素

這個函式的第二和第三個公式使用一個或多個已經用其他方式選取的 DOM 元素建立一個 jQuery 物件。jQuery 物件是由陣列元素建立的，順序和它們在陣列中出現的順序相同；與大多數其他多元素 jQuery 操作不同，元素不會依 DOM 順序排序。元素會照原本的樣子從陣列中複製，如果它們已經是 jQuery 集合，也不會解開。

請注意，雖然你可以用這種方式將文字節點和註解節點傳遞到 jQuery 集合中，但大多數操作都不支援它們。有支援的幾個操作會在它們的 API 文件頁面上有明確註解。

單一 DOM 元素建構的常見用途是在透過關鍵字 this 傳遞到回呼函式的元素上呼叫 jQuery 方法

1
2
3
 
$( "div.foo" ).on( "click", function() {
  $( this ).slideUp();
});

這個範例會讓元素在被按一下時以滑動動畫隱藏。因為處理常式在 this 關鍵字中接收被按下的項目為一個裸露的 DOM 元素，所以必須在對它套用 jQuery 方法之前將元素傳遞給 $() 函式。

從 Ajax 呼叫傳回的 XML 資料可以傳遞給 $() 函式，這樣就可以使用 .find() 和其他 DOM 遍歷方法擷取 XML 結構的個別元素。

1
2
3
 
$.post( "url.xml", function( data ) {
  var $child = $( data ).find( "child" );
});

複製 jQuery 物件

當一個 jQuery 物件傳遞給 $() 函式時，將會建立該物件的複製。這個新的 jQuery 物件會參考與最初物件相同的 DOM 元素。

傳回一個空的集合

呼叫 jQuery() 方法且沒有參數會傳回一個空的 jQuery 集合（.length 屬性為 0）。類似地，如果傳入的參數為 null、undefined、一個空的陣列（[]）或一個空的字串（""），則集合不會包含任何元素。

使用一般物件

目前，唯一支援在以 jQuery 包裝的純 JavaScript 物件上執行的操作為：.data()、.prop()、.on()、.off()、.trigger() 和 .triggerHandler()。在一般物件上使用 .data()（或任何需要 .data() 的方法）將會在物件上產生一個新的屬性，稱為 jQuery{randomNumber}（例如 jQuery123456789）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
// Define a plain object
var foo = { foo: "bar", hello: "world" };
 
// Pass it to the jQuery function
var $foo = $( foo );
 
// Test accessing property values
var test1 = $foo.prop( "foo" ); // bar
 
// Test setting property values
$foo.prop( "foo", "foobar" );
var test2 = $foo.prop( "foo" ); // foobar
 
// Test using .data() as summarized above
$foo.data( "keyName", "someValue" );
console.log( $foo ); // will now contain a jQuery{randomNumber} property
 
// Test binding an event name and triggering
$foo.on( "eventName", function () {
  console.log( "eventName was called" );
});
 
$foo.trigger( "eventName" ); // Logs "eventName was called"

如果使用 .trigger( "eventName" )，它會在物件上搜尋一個 "eventName" 屬性，並嘗試在執行任何附加的 jQuery 處理常式後執行它。它不會檢查該屬性是否為函式。為避免這種行為，應改用 .triggerHandler( "eventName" )。

1
 
$foo.triggerHandler( "eventName" ); // Also logs "eventName was called"

範例

找出所有為 div 元素子項目的 p 元素，並套用一個框線。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery demo</title>
  <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
</head>
<body>
 
<p>one</p>
<div><p>two</p></div>
<p>three</p>
 
<script>
$( "div > p" ).css( "border", "1px solid gray" );
</script>
 
</body>
</html>

示範

找出文件中第一個表單中的所有 radio 類型的輸入。

1
 
$( "input:radio", document.forms[ 0 ] );

從 Ajax 回應中找出 XML 文件中的所有 div 元素。

1
 
$( "div", xml.responseXML );

將頁面的背景顏色設定為黑色。

1
 
$( document.body ).css( "background", "black" );

隱藏表單中的所有輸入元素。

1
 
$( myForm.elements ).hide();

jQuery( html [, ownerDocument ] )傳回： jQuery

說明： 從提供的原始 HTML 字串中動態建立 DOM 元素。

建立新元素

如果將字串傳遞為 $() 的參數，jQuery 會檢查字串是否看起來像 HTML（例如，它以 <tag ... > 開頭）。如果不是，則會將字串解釋為選擇器表達式，如上所述。但如果字串看起來像 HTML 片段，jQuery 會嘗試根據 HTML 所述建立新的 DOM 元素。然後會建立一個 jQuery 物件並傳回，該物件會參考這些元素。您可以在這個物件上執行任何常見的 jQuery 方法

1
 
$( "<p id='test'>My <em>new</em> text</p>" ).appendTo( "body" );

若要明確將字串解析為 HTML，請使用 $.parseHTML() 方法。

預設情況下，元素會建立一個 .ownerDocument，與載入 jQuery 函式庫的文件相符。要注入到不同文件的元素應使用該文件建立，例如 $("<p>hello iframe</p>", $("#myiframe").prop("contentWindow").document)。

如果 HTML 比上述範例中沒有屬性的單一標籤更複雜，則實際建立元素會由瀏覽器的 .innerHTML 機制處理。在大多數情況下，jQuery 會建立一個新的 <div> 元素，並將元素的 innerHTML 屬性設定為傳入的 HTML 片段。當參數有一個單一標籤（具有可選的關閉標籤或快速關閉）— $( "<img />" ) 或 $( "<img>" )、$( "<a></a>" ) 或 $( "<a>" ) — jQuery 會使用原生 JavaScript .createElement() 函式建立元素。

當傳入複雜的 HTML 時，有些瀏覽器可能無法產生與提供的 HTML 來源完全相同的 DOM。如前所述，jQuery 使用瀏覽器的 .innerHTML 屬性來解析傳入的 HTML 並將其插入目前的文檔中。在此過程中，有些瀏覽器會過濾掉某些元素，例如 <html>、<title> 或 <head> 元素。因此，插入的元素可能無法代表傳入的原始字串。

不過，過濾並不限於這些標籤。例如，第 8 版之前的 Internet Explorer 還會將連結上的所有 href 屬性轉換為絕對 URL，而第 9 版之前的 Internet Explorer 則無法正確處理 HTML5 元素，除非另外新增一個 相容性層。

為確保跨平台相容性，程式碼片段必須格式良好。可以包含其他元素的標籤應與關閉標籤配對

1
 
$( "<a href='https://jquery.com'></a>" );

無法包含元素的標籤可以快速關閉或不關閉

1
2
 
$( "<img>" );
$( "<input>" );

將 HTML 傳遞給 jQuery() 時，請注意文字節點不會被視為 DOM 元素。除了少數方法（例如 .content()）之外，它們通常會被忽略或移除。例如

1
2
 
var el = $( "<br>2<br>3" ); // returns [<br>, "2", <br>]
el = $( "<br>2<br>3 >" ); // returns [<br>, "2", <br>, "3 &gt;"]

這種行為是預期的。從 jQuery 1.9.0 開始（除非使用 jQuery Migrate 外掛程式），jQuery() 要求 HTML 字串以 < 開頭（亦即文字節點不能出現在 HTML 字串的前面）。

從 jQuery 1.4 開始，jQuery() 的第二個引數可以接受一個純粹物件，其中包含可以傳遞給 .attr() 方法的屬性超集。

重要：如果傳遞了第二個參數，第一個參數中的 HTML 字串必須表示一個沒有屬性的簡單元素。自 jQuery 1.4 起，任何 事件類型 都可以傳遞，並且可以呼叫以下 jQuery 方法：val、css、html、text、data、width、height 或 offset。

自 jQuery 1.8 起，任何 jQuery 執行個體方法（jQuery.fn 的方法）都可以用作傳遞給第二個參數的物件的屬性

1
2
3
4
5
6
7
8
 
$( "<div></div>", {
  "class": "my-div",
  on: {
    touchstart: function( event ) {
      // Do something
    }
  }
}).appendTo( "body" );

物件中的名稱 "class" 必須加上引號，因為它是 JavaScript 保留字，而 "className" 無法使用，因為它指的是 DOM 屬性，而不是屬性。

雖然第二個參數很方便，但它的靈活性可能會導致意外後果（例如 $( "<input>", {size: "4"} ) 呼叫 .size() 方法，而不是設定 size 屬性）。因此，先前的程式碼區塊可以改寫成

1
2
3
4
5
6
7
8
 
$( "<div></div>" )
  .addClass( "my-div" )
  .on({
    touchstart: function( event ) {
      // Do something
    }
  })
    .appendTo( "body" );

範例

動態建立一個 div 元素（及其所有內容），並將其附加到 body 元素。在內部，會建立一個元素，並將其 innerHTML 屬性設定為指定的標記。

1
 
$( "<div><p>Hello</p></div>" ).appendTo( "body" )

建立一些 DOM 元素。

1
2
3
4
5
6
7
8
 
$( "<div/>", {
  "class": "test",
  text: "Click me!",
  click: function() {
    $( this ).toggleClass( "test" );
  }
})
  .appendTo( "body" );

jQuery( callback )傳回：jQuery

說明：繫結一個函式，以便在 DOM 完成載入時執行。

此函數的行為就像 $( document ).ready()，在於它應該用於包裝頁面上其他依賴於 DOM 準備就緒的 $() 操作。雖然此函數在技術上是可以鏈接的，但實際上並不需要鏈接到它。

範例

當 DOM 準備好使用時執行函數。

1
2
3
 
$(function() {
  // Document is ready
});

同時使用 $(document).ready() 的捷徑和參數，使用 $ 別名編寫安全無虞的 jQuery 程式碼，而不依賴於全域別名。

1
2
3
 
jQuery(function( $ ) {
  // Your code using failsafe $ alias here...
});