jQuery.ajax()
jQuery.ajax( url [, settings] ) Returns: jqXHR
説明: 非同期 HTTP（Ajax）リクエストを実行します。
-
version added: 1.5 jQuery.ajax( url [, settings] )
urlリクエストが送信されるURLを含む文字列。
settingsAjaxリクエストを構成するキー/値ペアのセット。全ての settings はオプションです。 デフォルトのオプションは、$.ajaxSetup() で設定することができます。 全設定の完全なリストについては、以下の jQuery.ajax( settings ) を参照してください。
-
version added: 1.0 jQuery.ajax( settings )
settingsAjaxリクエストを構成するキー/値ペアのセット。全ての settings はオプションです。 デフォルトのオプションは、$.ajaxSetup() で設定することができます。
$.ajax() 関数は、jQueryによって送信されるリクエストのすべて基礎となります。
$.get() および .load() のような高レベルでより使いやすい
関数が使用できるので、多くの場合、直接この関数を呼ぶことは不要です。しかし、さほど一般的ではないオプションが必要な場合、
$.ajax()はより柔軟に使用することができます。
最も簡単な例として、$.ajax() 関数を引数なしで呼出します:
$.ajax();
注: デフォルトの設定は、$.ajaxSetup() 関数を使用して
グローバルに設定することができます。
この例は、どのオプションも使用しないで、現在のページのコンテンツをロードしますが、結果を何もしません。 結果を使用するには、コールバック関数を1つ実装することができます。
jqXHR オブジェクト
jQuery 1.5 の $.ajax() により返された jQuery XMLHttpRequest（jqXHR）オブジェクトは、
ブラウザのネイティブ XMLHttpRequest オブジェクトのスーパーセットです。
例えば、それには、getResponseHeader() メソッドだけでなく responseText と responseXML
プロパティが含まれています。
転送メカニズムがXMLHttpRequest以外（例えば、JSONPリクエストのスクリプトタグ）である場合、jqXHR オブジェクトは、
可能であればネイティブ XHR 機能をシミュレートします。
jQueryの1.5.1 時点で、jqXHR オブジェクトには、overrideMimeType() メソッドも
含まれています（それは、jQuery 1.4.x で使用可能でしたが、一時的にjQuery 1.5 で削除されていました）。
.overrideMimeType() メソッドは、例えば content-type ヘッダの応答を変更するために、
beforeSend() コールバック関数で使用することができます:
$.ajax({
url: 'http://fiddle.jshell.net/favicon.png',
beforeSend: function( xhr ) {
xhr.overrideMimeType( 'text/plain; charset=x-user-defined' );
},
success: function( data ) {
if (console && console.log){
console.log( 'Sample of data:', data.slice(0,100) );
}
}
});
jQuery 1.5 では、$.ajax() によって返される jqXHR オブジェクトは、Promiseインターフェースを実装し、
Promiseのすべてのプロパティ、メソッド、および動作を与えます（詳細についてはDeferredオブジェクトを参照してください）。
$$.ajax() で使用するコールバック名による利便性と一貫性のために、jqXHR も .error()、
.success()、.complete() メソッドを提供します。
これらのメソッドは、$.ajax() リクエストが終了するときに呼出される関数を引数に取ります。
関数は、対応して名付けられた $.ajax() コールバックと同じ引数を受け取ります。
これは、1回のリクエストに複数のコールバックを割当てを可能にし、リクエストが完了した後にコールバックを割り当てることさえ可能にします。（リクエストが既に完了している場合、コールバックがすぐに実行解雇されています。）
廃止のお知らせ:
jqXHR.success()、jqXHR.error()、jqXHR.complete()コールバックは、jQuery 1.8 で廃止される予定です。最終的な削除に向けたコードの準備のためには、代りにjqXHR.done()、jqXHR.fail()、jqXHR.always()を使用してください。
// リクエスト直後にハンドラを割り当て、
// このリクエストの jqxhr オブジェクトを記憶する
var jqxhr = $.ajax( "example.php" )
.done(function() { alert("success"); })
.fail(function() { alert("error"); })
.always(function() { alert("complete"); });
// ここで他の作業を実行する ...
// 上記リクエストを完成させるのために別の関数を設定する
jqxhr.always(function() { alert("second complete"); });
XMLHttpRequest との下位互換性のために、jqXHR オブジェクトは、
次のプロパティとメソッドを公開しています:
-
readyState -
status -
statusText - 基本的なリクエストへ xmlおよび(または)テキストで応答する時、
responseXMLおよび(または) responseText - 古い値に新しい値に連結するのではなく、古い値を新しい値で置換することで標準を変更する
setRequestHeader(name, value) -
getAllResponseHeaders() -
getResponseHeader() -
abort()
しかしながら、success、error、complete、statusCodeは、考えられる必要条件をすべてカバーするので、onreadystatechangeメカニズムは提供されません。
コールバック関数のキュー
beforeSend、error、dataFilter、success、complete オプション
すべては、適切な時点で呼出すコールバック関数を受け入れます。
jQuery 1.5 では、error (fail)、success (done)、complete (jQuery 1.6 では、always)コールバック・フックは、先入先出法で管理されるキューです。
（フック（Hook）は、プログラム中の特定の箇所に、利用者が独自の処理を追加できるようにする仕組みである。また、フックを利用して独自の処理を追加することを「フックする」という。-- wikipedia から）。
これは、各フックに複数のコールバックを割り当てできることを意味します。$.ajax() コールバック・フックが内部的
に実装されている繰延オブジェクトのメソッドを参照してください。
全コールバック内の this 参照は、設定の中で$ $.ajax に渡された context オプション
のオブジェクトです; もし context を指定をしなければ、this は、Ajax 設定自体への参照です。
JSONP や、クロスドメイン GET リクエストのようないくつかのタイプでは、XHR を使用しないでください; それらの場合、
コールバックに渡す XMLHttpRequest と textStatus パラメーターは未定義になります。
ここに $.ajax() で提供されるコールバック・フックがあります:
-
beforeSendコールバックが呼出されます;jqXHRオブジェクトとパラメータとしてsettingsマップを受信します。 -
errorコールバックは、リクエストが失敗した場合に登録順に呼出されます。適用可能な場合、jqXHR、エラー・タイプの種類を示す文字列、および例外オブジェクトを受信します。いくつかの組込みのエラーは、例外オブジェクトとして文字列を提供します: "abort", "timeout", "No Transport"。 -
dataFilterコールバックは、応答データを正常に受信した場合、直ぐに呼び出されます。 それは、戻されたデータとdataTypeの値を受信して、successに渡す（おそらく変更）データを返す必要があります。 -
successコールバックは、リクエストが成功した場合に登録順に呼出されます。それらは、戻されたデータ、 success コードを含む文字列、およびjqXHRオブジェクトを受信します。 -
completeコールバックは、リクエストが成功・失敗にかかわらず完了した場合に、登録順に起動されます。 それらはjqXHRオブジェクトと、成功またはエラーのコードを含む文字列も受信します。
例えば、戻された HTML を利用するために、success ハンドラを実装することができます:
$.ajax({
url: 'ajax/test.html',
success: function(data) {
$('.result').html(data);
alert('Load was performed.');
}
});
Data タイプ
$.ajax() 関数は、取得するデータに対する情報を提供するサーバに依存します。サーバが、XMLとしてデータを返したと
報告した場合、結果は通常のXMLメソッドまたはjQueryのセレクタを使用してトラバースすることができます。
別のタイプ、上記例ではHTMLとして検出された場合、データはテキストとして取り扱われます。
別なデータ処理は、dataType オプションを使用するこで達成ができます。プレーン xml に加えて、
dataType は、html、json、jsonp、script、text
にすることができます。
text と xml タイプは、未処理のデータを返します。単に、データはそれぞれ、
jqXHR オブジェクトの responseText または responseXML プロパティのいずれかを通して、
成功したハンドラに渡されます。
注: Webサーバから報告されたMIMEタイプが、選択した dataType と一致していることを確認する必要があります。特に、XMLは、一貫性のある結果を得るためには text/xml または dataType としてサーバにより
宣言されていなければなりません。
html が指定された場合は、HTMLが文字列として返される前に、取得したデータに埋め込まれた全てのJavaScriptは実行されます。
Similarly, script will execute the JavaScript that is pulled back from the server, then return nothing.（同様に、スクリプトは、サーバから引き戻されているJavaScriptが実行され、その後何も返さない。）
json タイプは、JavaScript オブジェクトとして、取り出されたデータ・ファイルをパースし、
結果データとして、構成されたオブジェクトを戻します。
これを行うために、ブラウザがサポートしている場合、jQuery.parseJSON() を使用します; それ以外の場合は、
Function コンストラクタを使用します。
不正な形式のJSONデータは、パースエラーがスローされます（詳細については json.org を参照してください）。
JSONデータは、簡潔でJavaScriptをパースするために、簡単な方法で構造化データを通信するために便利です。フェッチしたデータファイルがリモートサーバー上に存在する場合は、代わりにJSONPの種類を指定します。
JSONデータは、簡潔でJavaScriptがパースし易い方法で構造化データを通信するのに便利です
取出すデータファイルがリモートサーバ上に存在する場合は、代わりに jsonp タイプを指定します。
jsonp タイプは、クエリ文字列パラメータ callback=? を URL に付加します。
サーバが妥当なJSONPレスポンスを作るために、コールバック名をJSONデータの前に付加する必要があります。
$.ajax() に、jsonp オプションを使用して callback 以外のパラメータ名を指定できます。
注: JSONP は、JSON形式の拡張で、クエリ文字列パラメータを検出して処理するためのサーバ・サイド・コードを必要とします。その詳細については、original post detailing its use に記載されています。
データをリモートサーバから取得する時（これは、script または jsonp データ・タイプを使用してのみ可能です）、error のコールバック、およびグローバルイベントが発生することはありません。
サーバへのデータ送信
デフォルトで、Ajaxリクエストは、GET HTTPメソッドを使用して送信されます。 POSTメソッドが必要な場合は、type オプションの値を設定することによって、このメソッドを指定することができます。このオプションは、data オプションのコンテンツをサーバに送信する方法に影響を与えます。 POSTデータは、常にW3C XMLHTTPRequest標準によって、UTF-8文字セットを使用してサーバへ送信されます。
data オプションは、クエリ文字列形式 key1=value1&key2=value2 か、マップ形式
{key1: 'value1', key2: 'value2'} のいずれかを指定することができます。
後者の形式が使用されている場合、データは、送信前に jQuery.param()
を使用してクエリ文字列に変換されます。この処理は、 processData に false を
設定することで回避できます。XMLオブジェクトをサーバに送信したい場合は、処理は不適当かもしれません; この場合には、
application/x-www-form-urlencoded から、適切な MIME タイプへ contentType オプションを変更してください。
高度なオプション
global オプションは、.ajaxSend()、.ajaxError()
、及びこのリクエストがそれらをトリガする時に始動する同じ様なメソッドを使って登録された処理を防ぎます。
これは、例えば、リクエストが頻繁に行われてかつ短い場合、.ajaxSend()
により実装されるローディングインジケータを消去するのに便利です。クロスドメインスクリプトとJSONPリクエストにより、
グローバルオプションは自動的に false に設定されます。詳細については、以下のこれらのメソッドの説明を参照してください。
サーバがレスポンスを返する前に HTT P認証を実行する場合、ユーザ名とパスワードのペアは、username と
password オプションを使用して送信することができます。
Ajaxリクエストは、時間制限されるので、優れたユーザ・エクスペリエンスを提供するため、エラーのキャッチと処理を行うことができます。
リクエストのタイムアウトは、通常デフォルトのままか、timeout オプションで特定のリクエストために
オーバーライドするよりは、$.ajaxSetup() を使用してグローバル・デフォルト
として設定します。
デフォルトでは、リクエストが常に発っせられてますが、ブラウザはキャッシュから結果を提供することができます。
キャッシュされた結果の使用を禁止するには、cache を false に設定します。
アセットが最後のリクエスト以降に変更されていない場合、リクエストは失敗を報告する原因になるために、
ifModified に true を設定します。
scriptCharset は、<script> タグを使用する（すなわち、script
または jsonpタイプ）リクエストのために、文字セットを明示的に指定することを可能にします。
これは、スクリプトとホスト·ページの文字セットが異なっている場合に便利です。
Ajaxの最初の文字 "asynchronous（非同期）" は、操作が並行して行われ、完了の順序は保証されていないことを意味しています。
$.ajax() デフォルトへ、async オプションを true にすると、リクエストした後も
コード実行が続くことを示します。
このオプションを false (非同期ではなくなる) に設定すると、ブラウザが応答しなくなる原因となりますので、強く推奨しません。
$.ajax() 関数は、作られた XMLHttpRequest オブジェクトを返します。
通常、jQueryは内部でこのオブジェクトの作成をしますが、それを製造するためのカスタムの関数は、xhr オプションを使用して指定できます。返されたオブジェクトは、一般的に破棄することができますが、リクエストを観察し、操作するための低レベルのインタフェースを提供します。
特に、完了する前にオブジェクトの .abort() を呼出すことで、リクエストを停止させます。
現在、.getResponseHeader('Content-Type') は空でない文字列を返しますが、
.getAllResponseHeaders() が空の文字列を返すという Firefox のバグのため、Firefox での jQuery による
JSON CORS レスポンスを自動的にデコードすることはサポートされていません。
次のように jQuery.ajaxSettings.xhr をオーバーライドすることで、これを回避することができます:
var _super = jQuery.ajaxSettings.xhr;
jQuery.ajaxSettings.xhr = function () {
var xhr = _super(),
getAllResponseHeaders = xhr.getAllResponseHeaders;
xhr.getAllResponseHeaders = function () {
if ( getAllResponseHeaders() ) {
return getAllResponseHeaders();
}
var allHeaders = "";
$( ["Cache-Control", "Content-Language", "Content-Type",
"Expires", "Last-Modified", "Pragma"] ).each(function (i, header_name) {
if ( xhr.getResponseHeader( header_name ) ) {
allHeaders += header_name + ": " + xhr.getResponseHeader( header_name ) + "\n";
}
return allHeaders;
});
};
return xhr;
};
Ajaxの拡張
jQuery 1.5 でのjQueryのAjax実装には、大きな柔軟性を持った Ajax の拡張を可能にするため、 prefilter、converter、transport が含まれています。これらの高度な機能の詳細については、 拡張 Ajax のページを参照してください。
補注:
- ブラウザのセキュリティ制限のため、ほとんどの "Ajax" リクエストは 同一生成元ポリシーに 従います; リクエストは、別なドメイン、サブドメイン、またはプロトコルから正常にデータを取得することはできません。
- Script と JSONP のリクエストは、同一生成元ポリシー制約の対象にはなりません。
例:
例:サーバにデータを保存し、完了後はユーザに通知します。
$.ajax({
type: "POST",
url: "some.php",
data: "name=John&location=Boston",
}).done(function( msg ) {
alert( "Data Saved: " + msg );
});
例:HTMLページの最新版を取得します（キャッシュを無効にする）。
$.ajax({
url: "test.html",
cache: false,
success: function(html){
$("#results").append(html);
}
});
例:XMLドキュメントをデータとしてサーバへ送信します。 ProcessData オプションに false を設定することで、文字列へデータの自動変換が防止されます。
var xmlDocument = [create xml document];
var xmlRequest = $.ajax({
url: "page.php",
processData: false,
data: xmlDocument
});
xmlRequest.done(handleResponse);
例:データとして id をサーバに送信して、サーバへあるデータを保存して、完了した時にはユーザ へ通知します。リクエストが失敗した場合は、ユーザに警告を出します。
var menuId = $("ul.nav").first().attr("id");
var request = $.ajax({
url: "script.php",
type: "POST",
data: {id : menuId},
dataType: "html"
});
request.done(function(msg) {
$("#log").html( msg );
});
request.fail(function(jqXHR, textStatus) {
alert( "Request failed: " + textStatus );
});
例:JavaScript ファイルをロードして実行します。
$.ajax({
type: "GET",
url: "test.js",
dataType: "script"
});