.ready()

類別：事件 > 文件載入

.ready( handler )傳回：jQuery

說明：指定一個在 DOM 完全載入時執行的函式。

.ready() 方法提供一種方式，可以在頁面的文件物件模型 (DOM) 安全地進行操作時立即執行 JavaScript 程式碼。這通常是執行在使用者檢視或與頁面互動之前所需的任務的適當時機，例如新增事件處理常式和初始化外掛程式。當透過連續呼叫此方法新增多個函式時，它們會在 DOM 準備好的順序執行。從 jQuery 3.0 開始，jQuery 確保一個處理常式中發生的例外情況不會阻止隨後新增的處理常式執行。

大多數瀏覽器提供類似的功能，以 DOMContentLoaded 事件的形式提供。然而，jQuery 的 .ready() 方法在一個重要且有用的方面有所不同：如果 DOM 準備好，瀏覽器在程式碼呼叫 .ready( handler ) 之前觸發 DOMContentLoaded，函式 handler 仍會執行。相反地，事件觸發後新增的 DOMContentLoaded 事件監聽器永遠不會執行。

瀏覽器也會在 window 物件上提供 load 事件。當此事件觸發時，表示頁面上所有資源都已載入，包括影像。此事件可以使用 $( window ).on( "load", handler ) 在 jQuery 中監控。在程式碼仰賴已載入資源的情況下（例如，需要影像的尺寸），應將程式碼置於 load 事件的處理常式中。

請注意，儘管 DOM 總是在頁面完全載入之前就準備好，但在 .ready() 處理常式執行的程式碼中附加 load 事件監聽器通常並不安全。例如，程式碼可以在頁面載入後很長一段時間使用 $.getScript() 等方法動態載入。儘管由 .ready() 新增的處理常式將永遠在動態載入的程式碼中執行，但 window 的 load 事件已發生，而那些監聽器將永遠不會執行。

jQuery 提供多種方法來附加一個函式，該函式將在 DOM 準備好時執行。所有下列語法都相同

  • $( handler )
  • $( document ).ready( handler )
  • $( "document" ).ready( handler )
  • $( "img" ).ready( handler )
  • $().ready( handler )

從 jQuery 3.0 開始，只建議使用第一個語法；其他語法仍然有效，但已不建議使用。這是因為選取對 .ready() 方法的行為沒有影響，這會降低效率，並可能導致對方法行為的錯誤假設。例如，第三個語法使用 "document"，它不會選取任何內容。第四個語法會等待文件準備好，但暗示（不正確）它會等待影像準備好。

還有 $(document).on( "ready", handler )，自 jQuery 1.8 棄用，並於 jQuery 3.0 中移除。請注意，如果在附加此事件之前 DOM 已準備就緒，則處理常式不會執行。

.ready() 方法通常與匿名函數搭配使用

1
2
3
 
$( document ).ready(function() {
  // Handler for .ready() called.
});

這等同於建議的呼叫方式

1
2
3
 
$(function() {
  // Handler for .ready() called.
});

別名 jQuery 物件

當使用 $.noConflict() 來避免命名空間衝突時，$ 捷徑將不再可用。不過，.ready() 處理常式會傳遞一個參照給呼叫方法的 jQuery 物件。這允許處理常式使用 jQuery 物件，例如作為 $，而不知道它的別名

1
2
3
4
 
jq2 = jQuery.noConflict();
jq2(function( $ ) {
  // Code using $ as usual goes here; the actual jQuery object is jq2
});

範例

在 DOM 載入時顯示訊息。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>ready demo</title>
  <style>
  p {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
  <script>
 
  $(function() {
    $( "p" ).text( "The DOM is now loaded and can be manipulated." );
  });
 
  </script>
 
</head>
<body>
 
<p>Not loaded yet.</p>
 
 
</body>
</html>

示範