快捷方法:jQuery.getJSON()

(PS:這篇文章是官網 1.9版 API文件的非專業翻譯+個人意見,並且重新排版過)

快捷方法:jQuery.getJSON()

使用Get HTTP請求從伺服端載入JSON編碼的資料。

語法:

jQuery.getJSON( url [, data ] [, success( data, textStatus, jqXHR ) ] )
//version added: 1.0
  • url
    Type: String
    一個包含著請求要送達的URL的字串。
  • data
    Type: PlainObject
    會伴隨著請求送到伺服端的plain物件,或是字串。
  • success( data, textStatus, jqXHR )
    Type: Function()
    一個回呼函式,當請求成功時會被執行
這個快捷Ajax函式相同於:
$.ajax({
dataType: "json",
url: url,
data: data,
success: success
});

發送到服務器的資料會被當成一個查詢字符串附加到URL中。假如data參數的值是一個plain物件,會被轉成url編碼的字串,然後才再附加到URL中。

大部分在實作上會指定一個一個success處理函式:

$.getJSON( "ajax/test.json", function( data ) {
var items = [];
$.each( data, function( key, val ) {
items.push( "<li id='" + key + "'>" + val + "</li>" );
});
 
$( "<ul/>", {
"class": "my-new-list",
html: items.join( "" )
}).appendTo( "body" );
});

當然,這個例子中,依賴於JSON文件的結構:

{
"one": "Singular sensation",
"two": "Beady little eyes",
"three": "Little birds pitch by my doorstep"
}

這個例子遍歷了請求傳回的資料,使用這樣的結構建立了一個非順序的列表並且附加到body中

請求傳回的資料會被傳遞到請求成功時會呼叫的回呼函式。該請求傳回的資料一般都是藉由JSON結構所定義的Javascript物件或是陣列,並由使用$.parseJSON()方法解析。回呼函式也會被傳遞回應的本文狀態。

(維克:ajax所取得的原始資料應該要是符合JSON規格的字串,經過$.parseJSON()方法後解析成為物件後,才傳給回呼函式使用。JSON是一種輕量級的傳遞格式,他是物件實字與字陣列實字的組合,下面是一個JSON字串的例子:{"key":"value","key2":[1,2,3] } )

從jQuery1.5開始,success回呼函式接受一個 "jqXHR" object(在jQuery1.4中,她接受的是XMLHttpRequest物件)。然而,因為JSONP與跨網域GET請求並不使用XHR。在那些案例中,傳遞到sucess回呼函式的jqXHR與textStatus狀態會是未定義undefined。

(維克:在語法中有提到:success(data, textStatus, jqXHR),其中sucess的三個參數就是上面講到的三個傳入值)

重要:從jQuery1.4開始,假使JSON檔案包含一個語法錯誤,請求會默默地失敗。基於這個理由,應該避免頻繁的手動編輯JSON資料。JSON是一個資料交換格式,擁有著比Javascript物件文字語法更為嚴謹的規則。例如,所有在JSON中表示的字串,不論是屬性或是值都必須由雙引號所包覆。更細節的JSON格式請參考http://json.org/.。

JSONP

假如URL包含了字串"callback=?"(或是相似的,由伺服端API所定義的),這個請求被視為JSONP格式。請參考$.ajax()中的 JSONP資料型態討論以取得更多的細節。

jqXHR 物件

從jQuery1.5開始,所有的jQuery的Ajax方法返回XMLHttpRequest物件的一個超集。由$.get()傳回的  jQuery XHR物件,或者稱之為 "jqXHR",實作了Promise介面。讓它擁有了Promise介面的的屬性,方法,以及行為。(參考Deferred object以取得更多訊息)。jqXHR.done() (代表成功時), jqXHR.fail() (代表錯誤時), 以及jqXHR.always() (代表完成時,不論結果是成功或是失敗)方法接受一個函式參數,當請求終結時,該函式會被呼叫。關於這個函數接收的參數的詳細信息,請參考 $.ajax() 文件的 jqXHR Object 章節。

(維克:所謂的介面,就是定義了一些屬性,方法,以及行為的規範。實現了某個介面的意思是,他實現的介面所定義的屬性,方法,以及行為。譬如說上例。Promise介面定義了done()方法。而jqXHR物件實現了Promise介面,所以jqXHR會有一個done()方法==>jqXHR.done()  )

Promise介面也允許jQuery的Ajax方法,包含了$.get()可以在單一個請求中去串鍊多個.done(), .fail(), 以及.always()回呼函式。甚至可以在要求可能完成後指派這些回呼。假使請求已經完成,回呼會立即發發出。

// Assign handlers immediately after making the request,
// and remember the jqxhr object for this request
var jqxhr = $.getJSON( "example.json", function() {
  console.log( "success" );
})
  .done(function() {
    console.log( "second success" );
  })
  .fail(function() {
    console.log( "error" );
  })
  .always(function() {
    console.log( "complete" );
  });
 
// Perform other work here ...
 
// Set another completion function for the request above
jqxhr.complete(function() {
  console.log( "second complete" );
});

棄用通知:

在jQuery 1.5 中的jqXHR.success(), jqXHR.error(), 與jqXHR.complete()回呼函式,從jQuery 1.8版開始將會被棄用。為了讓你的程式碼準備好移除這些函式,使用jqXHR.done(), jqXHR.fail(), andjqXHR.always()來作為代替。

其他注意事項:

  • 由於瀏覽器的安全限制,大部分的"Ajax"請求都受到同源政策(same origin policy)的規範。不同網域,子網域或是協定的請求無法成功取得資料。
  • Script與JSONP請求不受同源政策影響。

範例:

範例:從Flickr JSONP API載入雷尼爾山最近的四張圖片。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery.getJSON demo</title>
  <style>
  img {
    height: 100px;
    float: left;
  }
  </style>
  <script src="http://code.jquery.com/jquery-1.9.1.js"></script>
</head>
<body>
 
<div id="images"></div>
 
<script>
(function() {
  var flickerAPI = "http://api.flickr.com/services/feeds/photos_public.gne?jsoncallback=?";
  $.getJSON( flickerAPI, {
    tags: "mount rainier",
    tagmode: "any",
    format: "json"
  })
    .done(function( data ) {
      $.each( data.items, function( i, item ) {
        $( "<img>" ).attr( "src", item.media.m ).appendTo( "#images" );
        if ( i === 3 ) {
          return false;
        }
      });
    });
})();
</script>
 
</body>
</html>

範例:從test.js載入JSON資料並且從傳回的資料中存取一個名稱。

$.getJSON( "test.js", function( json ) {
  console.log( "JSON Data: " + json.users[ 3 ].name );
 });

範例:從test.js載入JSON資料,傳遞而外的資料,並且從傳回的資料中存取一個名稱。假如錯誤產生,記錄一個錯誤訊息。

$.getJSON( "test.js", { name: "John", time: "2pm" } )
  .done(function( json ) {
    console.log( "JSON Data: " + json.users[ 3 ].name )
  })
  .fail(function( jqxhr, textStatus, error ) {
    var err = textStatus + ", " + error;
    console.log( "Request Failed: " + err );
});
 
 

  按個讚!~支持本站!~

FB推薦載入中