jQuery.ajax()の戻り値
jQuery.ajax()の戻り値はjqXHRオブジェクトである。
jqXHRオブジェクトに対してdoneメソッドとfailメソッドを使用して
サーバが返すデータ等を見ることができる。
done()メソッドの引数は成功時のコールバック関数であり、通常はデータが渡される。
一方、fail()メソッドの引数は失敗時のコールバック関数であり、通常はエラー情報が渡される。
jQuery.ajax([settings])のsettingsはAjaxリクエストを設定することができる。このsettingは省略可能な設定項目である。
jqXHR.done()
jqXHR.done(function(data, textStatus, jqXHR) {});は「An alternative construct to the success callback option」(success callback optionの代替構成)とjQuery公式webサイトに載っている。
つまり、jqXHR.done(function( data, textStatus, jqXHR){});はsettingsの設定項目successと同じくAjaxリクエストの成功時の処理を書くことできる。
settingsの設定項目successに設定する関数の引数(data, textStatus, jqXHR)とjqXHR.done(function(data, textStatus, jqXHR){});のコールバック関数の引数は同じということを意味する。
success
Type: Function(Anything data, String textStatus, jqXHR jqXHR)
settingsの設定項目succeessにリクエストに成功した場合に呼び出される関数を設定できる。
次のように設定する。
$.ajax({
url: "example.com",
success: function(data, textStatus, jqXHR) {
// 成功時の処理
}
})
jqXHR.fail()
jqXHR.fail(function( jqXHR, textStatus, errorThrown ) {});は「An alternative construct to the error callback option」(error callback optionの代替構成)とjQuery公式webサイトに載っている。
つまり、jqXHR.fail(function(data, textStatus, jqXHR) {});はsettingsの設定項目errorと同じくAjaxリクエストの失敗時の処理を書くことできる。
settingsの設定項目errorに設定する関数の引数(jqXHR, textStatus, errorThrown)とjqXHR.fail(function( jqXHR, textStatus, errorThrown){});のコールバック関数の引数は同じということを意味する。
error
Type: Function( jqXHR jqXHR, String textStatus, String errorThrown)
settingsの設定項目errorにリクエストに失敗した場合に呼び出される関数を設定できる。
次のように設定する。
$.ajax({
url: "example.com",
error: function(jqXHR, textStatus, errorThrown) {
// 失敗時の処理
}
})
jqXHR.done(function(data, textStatus, jqXHR){});
doneメソッドに渡すコールバック関数の3つの引数について
data
サーバが返すデータ(test.txtの中身)が
dataTYpeに沿ってフォーマットされた値が格納されている。
textStatus
通信結果が文字列「success」で返ってくる。
備考
doneは正常終了した場合に実行されるので文字列「success」しか返らないはず。私は「success」が出る時しか確認していない。
jqXHR
jqXHRオブジェクト
jqXHR.fail(function(jqXHR, textStatus, errorThrown){});
failメソッドに渡すコールバック関数の3つの引数について
jqXHR
jqXHRオブジェクト
textStatus
通信結果が文字列「timeout」、「error」、「abort」、「parsererror」で返ってくる。
備考
jQuery公式webサイトのsettingの「error」を見ると「Possible values for the second argument (besides null) are “timeout”, “error”, “abort”, and “parsererror”. 《第2引数でとりうる値(NULL以外)は、「timeout」、「error」、「abort」、「parsererror」である。》」
とあったが、通信結果が「null」の場合もあるのか？私は文字列「error」が格納される時しか確認していない。
errorThrown
HTTPエラーが発生すると、「Not Found」や「Internal Server Error」などの HTTPステータスのテキスト部分を受け取る。
(HTTP/2 では代わりに空の文字列になる場合があります)
備考
jQuery公式webサイトを見ると
error
Type: Function( jqXHR jqXHR, String textStatus, String errorThrown)
The function receives three arguments:The jqXHR (in jQuery 1.4.x, XMLHttpRequest) object, a string describing the type of error that occurred and an optional exception object, if one occurred.
《この関数は3つの引数を受け取ります。jqXHRオブジェクト(jQuery 1.4.xではXMLHttpRequestオブジェクト)、発生したエラーの種類を示す文字列、およびオプションの例外オブジェクト(存在する場合)。》
“if one occurred”は「オプションの例外オブジェクトが発生した場合」という意味である。つまり、例外オブジェクトが存在するかどうかに応じて、3番目の引数が渡されるかどうかが変わる。
「String errorThrown(文字列errorThrown)」と書いてあるが、「an optional exception object(オプションの例外オブジェクト)」とも書いてあり、矛盾しているように思える。
私はerrorThrownに文字列「Not Found」が格納される時だけ確認した。
errorThrownがオブジェクトの場合がありえるのか？
jqXHR
jqXHRオブジェクト
The jQuery XMLHttpRequest (jqXHR) object returned by $.ajax() as of jQuery 1.5 is a superset of the browser’s native XMLHttpRequest object.
(jQuery1.5以降の $.ajax() が返す jQuery XMLHttpRequest (jqXHR) オブジェクトは、ブラウザのネイティブ XMLHttpRequest オブジェクトのスーパーセットです。)
とjQuery公式webサイトに書いてある。
ここでjQuery公式webサイトで言いたいことは、jQuery.ajax()メソッドを使用して行われるAjaxリクエストの結果として返されるjqXHRオブジェクトは、ブラウザのネイティブXMLHttpRequestオブジェクトを拡張したものであり、機能のスーパーセットとなる。
XMLHttpRequestオブジェクトのスーパーセット(上位集合)がjqXHRオブジェクトである。
The jqXHR objects returned by $.ajax() as of jQuery 1.5 implement the Promise interface, giving them all the properties, methods, and behavior of a Promise (see Deferred object for more information).
(jQuery 1.5以降の$.ajax()が返すjqXHRオブジェクトは、Promiseインターフェースを実装しており、Promiseのすべてのプロパティ、メソッド、動作を提供します（詳細は「Deferredオブジェクト」を参照）。)
とjQuery公式webサイトに書いてある。
このPromiseインターフェースがいまいち理解できていないから勉強する必要がるな。
「Promiseインターフェースが実装」という言い方するのか？
doneメソッドとfailメソッドを使った例を次に示す。
$.ajax({
type: 'POST',
url: 'test.txt',
dataType: 'text'
}).done(function(data, textStatus, jqXHR) {
console.log(data);
console.log(textStatus);
console.log(jqXHR);
}).fail(function(jqXHR, textStatus, errorThrown){
console.error("jqXHR.status = " + jqXHR.status + ",textStatus = " + textStatus + ",errorThrown = " + errorThrown);
});
参考
jQuery.ajax() | jQuery API Documentation ExternalLink
JavaScriptがちょっとわかる人向けの、Ajaxの話。 – Qiita ExternalLink
$.ajax() | jQuery 1.9 日本語リファレンス | js STUDIO (studio-kingdom.com) ExternalLink