$.ajax()

Ajaxリクエストを送信するオプションをキーと値のペアで指定します。 このオプションに初期値を設定したい場合は、 $.ajaxSetup()を使用します。

.ajax( url[, settings] ) 1.5追加

戻り値:jqXHR

引数説明
url Ajaxリクエストを送信するURLを指定します。
[settings] $.ajax(setting)と同じです。 この書き方はsettingsのurlを第1引数に指定する書き方です。

.ajax( [settings] ) 1.0追加

戻り値:jqXHR

引数 説明
[settings]

型:PlainObject

Ajaxリクエスト設定のためのキーと値のペアを設定します。 全ての設定は任意になります。 デフォルトでは$.ajaxSetup()を使用した設定が使用されます。

下記は、サーバにユーザー情報をPOST送信し、通信完了時にアラートダイアログを表示する例になります。

$.ajax({
  type: "POST",
  url: "some.php",
  data: { name: "John", location: "Boston" }
}).done(function( msg ) {
  alert( "データ保存: " + msg );
});

settings引数について

settings引数は下記のキーと値のペアにより設定します。

キー
accepts

型:PlainObject 初期値:DataTypeに依存

サーバーにどの種類のレスポンスを返して欲しいのかを伝える、リクエストヘッダー内に指定されるコンテンツタイプです。

async

型:Boolean 初期値:true

デフォルトでは、全てのリクエストは非同期です。(デフォルトでtrueのため) もし同期リクエストをする必要があれば、このオプションをfalseにします。 クロスドメイン、またはdataType: "jsonp"のリクエストは、同期操作はサポートされません。 同期リクエストは一時的にブラウザをロックし、リクエスト処理中は全てのアクションが無効になることに注意してください。

jQuery 1.8で、jqXHR($.Deferred)でのasync: falseの使用は非推奨になりました。 jqXHR.done()、または非推奨のjqXHR.success()のような、 jqXHRオブジェクトのメソッドに沿ったsuccess/error/completeのコールバックオプションを使用する必要があります。

beforeSend
(jqXHR, settings)

型:Function( jqXHR jqXHR, PlainObject settings )

送信される直前にjqXHR(jQuery1.4.xではXMLHTTPRequest)オブジェクトの変更が可能な、コールバック関数です。 これを使用してカスタマイズヘッダーの設定等を行います。 jqXHRとsettingsオブジェクトは引数として渡されます。 これは、Ajaxイベントで、 beforeSend関数からfalseが返されるとリクエストがキャンセルされます。

jQuery 1.5で、beforeSendオプションはリクエストのタイプに関係なく呼び出されるようになりました。

cache

型:Boolean
初期値:true、ただし、dataTypeが'script'または'jsonp'の場合は、false

falseを設定すると、ブラウザによってリクエストされたページを強制的にキャッシュしないようにします。

注意: cacheへのfalse設定は、HEADとGETリクエスト時のみ正しく動作します。 これは"_={timestamp}"をGETパラメーターに追加することで動作します。 このパラメーターは、GETによって既にリクエストされているURLへPOSTする際のIE8を除き(翻訳に自信なし)、 その他のタイプのリクエストでは不要です。

complete
(jqXHR, textStatus)

型:Function( jqXHR jqXHR, String textStatus )

リクエストが完了した際に呼び出される関数です。(success、errorのコールバック実行後) この関数は2つの引数を受け取ります。 1つ目はjqXHR(jQuery1.4.xではXMLHTTPRequest)オブジェクトで、 2つ目はtextStatusは、リクエストのステータスを分類するための文字列です。

  • "success"
  • "notmodified"
  • "error"
  • "timeout"
  • "abort"
  • "parsererror"

jQuery 1.5から、completeは関数の配列を受け取れるようになり、 各関数は順に呼び出されます。 これはAjaxイベントです。

contents
1.5追加

型:PlainObject

jQueryによる指定されたコンテンツタイプ毎のそのレスポンスのパース方法を決定する、 文字列/正規表現のオブジェクトのペアとなるオブジェクトです。

contentType

型:String 初期値:
'application/x-www-form-urlencoded; charset=UTF-8'

サーバーへデータが送信される際に、ここで指定されたコンテンツタイプが指定されます。 デフォルトは、"application/x-www-form-urlencoded; charset=UTF-8"で、 ほとんどのケースは、これで問題ありません。 もし明示的にcontent-typeを$.ajax()へ渡すと、常にそれがサーバーへ送信されます。(データが送信されない場合でも) W3CのXMLHttpRequestの仕様では、charsetは常にUTF-8であることが指示されており、 その他のcharsetをブラウザにエンコーディングを変更させることを強制しません。(翻訳に自信なし)

context

型:Object

ここに指定されたオブジェクトが、全てのAjax関連のコールバックのコンテキストにされます。 デフォルトでは、このコンテキストは呼び出し時に使用されるajaxの設定が反映されるオブジェクトになります。 ($.ajaxSettingsとマージされた設定が、$.ajaxに渡されます。) DOMを指定することで、関連するAjaxのコールバック関数全てでthisを指定した際にcontextに指定したDOMが参照されるようになります。 例として、contextとして指定されたDOM要素は、下記のようにリクエストの完了コールバック時のコンテキストになります。

$.ajax({
  url: "test.html",
  context: document.body
}).done(function() {
  $( this ).addClass( "done" );
});
converters
1.5追加

型:PlainObject
初期値:{"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML})

dataTypeオプション毎のコンバーターを含むオブジェクトです。 各コンバーターの値は、レスポンスの変換された値を返す関数です。 通信後の戻り値はこの関数によってそれぞれパース処理されます。

crossDomain
1.5追加

型:Boolean
初期値:同じドメインのリクエストならfalse、クロスドメインのリクエストならtrue

もし、(JSONPのような)同じドメイン上で強制的にクロスドメインリクエストを行いたい場合、 この値をtrueに設定します。 例えば、サーバサイドで別ドメインへリダイレクトされるような場合は、trueを指定します。

data

型:PlainObjectまたはString

サーバーへ送信するデータです。 もし文字列で無ければ、クエリー文字列に変換されます。 これはGETリクエストのURLに追加されます。 この自動的に行われるプロセスを防ぎたい場合は、processDataのオプションを参照してください。 オブジェクトは、キー/値のペアでなければいけません。 もし値が配列の場合、jQueryは従来の設定の、値をベースとした同じキーを使用した複数の値のシリアライズを行います。(詳細は後述)

dataFilter

型:Function( String data, String type ) => Object

XMLHttpRequestの生のレスポンスデータを扱うのに使用する関数を指定します。 これは、レスポンスをサニタイズするためのプレ・フィルタリング関数で、 サニタイズされたデーターが返されるべきです。 この関数は2つの引数を受け取り、1つ目はサーバーから返される名前のデータで、 2つ目は'dataType'の値になります。

dataType

型:String 初期値:xml,json,script,htmlからjQueryがMIME typeを元に判別

あなたが期待するサーバーから返されるデータの型を指定します。 もし指定されなければ、jQueryはレスポンスのMIME typeを元に推察することを試みます。 (XMLのMIME typeはXMLを生成し、1.4でJSONはJavaScriptオブジェクト、scriptはスクリプトの実行、 その他は文字列として返されるようになりました。) 利用可能な型(そして、successのコールバックへ第1引数として渡される結果)は、下記の通りです。

"xml"
jQueryを介して処理することが可能なXMLドキュメントが返されます。
"html"
プレーンテキストとしてのHTMLを返します。 含まれるscriptタグはDOMに挿入された際に評価されます。
"script"
JavaScriptとしてレスポンスを評価し、プレーンテキストとしてそれを返します。 cacheオプションがtrueに設定されなければ、 URLへクエリー文字列パラメーター"_=[TIMESTAMP]"の追加によるキャッシュの無効化が行われます。

注意:クロスドメイン間の送信ではPOST送信は自動的にGET送信に切り替わります。

"json"
JSONとしてレスポンスを評価し、JavaScriptオブジェクトが返されます。 このJSONデータは厳格な作法によってパースされるため、奇形と判断されたJSONは拒絶され、パースエラーがスローされます。 jQuery1.9からは、空のレスポンスも拒絶されるようになったため、 サーバーは代わりにnullまたは{}を返す必要があります。 正しいJSONのフォーマットについて、より詳しい情報を知りたければ、 json.orgを参照してください。
"jsonp"

JSONPを使用してJSONブロックを読み込みます。 コールバック関数を指定するために、URLの最後に"?callback=?"を追加します。 cacheオプションがtrueに設定されなければ、 URLへクエリー文字列パラメーター"_=[TIMESTAMP]"の追加によるキャッシュの無効化が行われます。

"?callback=?"の部分は、実際にはクエリー文字列で?callback=jQuery1234567890のようなコールバック関数名が指定され、 サーバー側で例えばPHPであれば、$_GET['callback'] . '(' . jsonデータ . ');'と処理することで、 JavaScriptのコールバック関数の実行が出力されます。 ランダムな関数名が割り当てられるのは、他のグローバルなJavaScriptの関数名とバッティングしない等の理由が考えられます。

"text"
プレーンなテキスト文字列です。
複数、空白区切りの値

jQuery1.5からは、jQueryはContent-Type内で受け取ったdataTypeを、あなたが必要とするものに変換出来るようになりました。 例えば、もしテキストのレスポンスをXMLとして取り扱いたい場合は、dataTypeに"text xml"を指定します。

また、"jsonp text xml"とすることで、JSONPリクエストをテキストとして受け取り、 jQueryにXMLとして解釈させることも可能です。(翻訳に自信なし) 同じように"jsonp xml"のような省略された文字列指定を行うと、最初にjsonpからxmlへの変換を試み、 それが失敗するとjsonpからtextへ変換し、次にtextからxmlに変換します。

error

型:Function( jqXHR jqXHR, String textStatus, String errorThrown )

リクエストが失敗すると呼び出される関数です。 この関数は、jqXHR(jQuery 1.4.xではXMLHttpRequest)オブジェクト、発生したエラーの型を示す文字列、 任意指定の例外オブジェクトの3つの引数を受け取ります。 第2引数に指定される可能のある値は、(nullの他に、)"timeout"、"error"、"abort"、"parsererror"です。 第3引数であるerrorThrownはHTTPエラーが発生した際に、"Not Found"や"Internal Server Error"のような、 HTTPステータスのテキスト部分を受け取ります。 jQuery1.5からは、errorの設定は関数の配列を受け取れるようになり、各関数は順に呼び出されます。

注意: このハンドラはクロスドメイン・スクリプトとクロスドメイン・JSONPリクエストに対しては呼び出されません。

これはAjaxイベントです。

global

型:Boolean 初期値:true

このリクエストがグローバルAjaxイベントハンドラをトリガするか否かを決定します。 デフォルトはtrueです。 falseに設定すると、ajaxStartajaxStopのようなグローバルのハンドラがトリガされることを防ぎます。 これは、様々なAjaxイベントを制御するのに使用することが可能です。

headers
1.5追加

型:PlainObject 初期値:{}

XMLHttpRequestを使用した通信に使用するリクエストに沿って送信する、 HTTPリクエストのヘッダーのキー/値のペアの追加オブジェクトを指定します。 X-Requested-With: XMLHttpRequestヘッダーは常に追加されますが、 このデフォルトの値をここで変更することが出来てしまいます。 このheadersの設定での値は、 beforeSend関数によって上書きすることも可能です。

ifModified

型:Boolean 初期値:false

trueに設定すると、レスポンスが最後のリクエストから変更されている場合のみ、リクエストを成功とみなします。 Last-Modifiedヘッダーを確認することで、それが行われます。 デフォルトの値はfalseで、ヘッダーの内容は無視されます。 jQuery 1.4で、変更されていないデータの確認のためにサーバによって指定される'etag'も確認するようになりました。(翻訳に自信無し)

isLocal
1.5.1追加

型:Boolean
初期値:(現在のローカルのプロトコルに依存)

jQueryがデフォルトでそのように判断しなかったとしても、 現在の環境を"ローカル"である(例えばファイルシステム)と認識することを可能とします。 file*-extensionwidgetのプロトコルがローカルであると認識されます。 もし、isLocal設定の変更が必要な場合、 $.ajaxSetup()メソッドでこれを行うことが推奨されています。

jsonp

型:String

jsonpリクエストのコールバック関数名を上書きするのに使用されます。 この値はURLのクエリー文字列部分'callback=?'の、'callback'の代わりとして使用されます。 そのため例えば{jsonp:'onJSONPLoad'}と指定すると、 クエリー文字列は'onJSONPLoad=?'としてサーバーへ渡されることになります。

jQuery 1.5からは、jsonpオプションをfalseに設定すると、jQueryがURLへ"?callback"文字列を追加することを、 また"=?"を変換する試みを止めさせることが出来るようになりました。 この場合、例えば{ jsonp: false, jsonpCallback: "callbackName" }のようにして、 jsonpCallback設定を明示的に指定する必要があります。

"?callback=?"の部分は、ここでfalseが指定されなければ、 実際にはURLクエリー文字列は?callback=jQuery1234567890のようになり、ここでコールバック関数名が指定され、 サーバー側で例えばPHPであれば、$_GET['callback'] . '(' . jsonデータ . ');'のようにしてコールバック関数が実行されます。 jQuery側では動的にjQuery1234567890という関数が作成されているものと思われます。

jsonpCallback

型:StringまたはFunction()

JSONPリクエストのためのコールバック関数名を指定します。 この値はjQueryによって自動的に生成されるランダムなコールバック関数名の代わりに使用されます。 ただし、リクエストの管理、コールバック関数の提供、エラーハンドリングが簡潔になることから、 通常はjQueryの自動生成に任せることが推奨されています。 GETリクエストでブラウザキャッシュを有効にしたい場合に、このコールバック名を指定したいというケースがあります。 jQuery1.5からは、この設定に関数も使用できるようになり、その場合はjsonpCallbackの値は、 この関数の戻り値が設定されます。

mimeType
1.5.1追加

型:String

XHRのMIME typeを上書きします。

password

型:String

HTTPアクセスの認証リクエストに応答するXMLHttpRequestに使用されるパスワードを指定します。

processData

型:Boolean 初期値:true

デフォルトでは、dataオプションにオブジェクトとして渡されるデータ(厳密に言えば、文字列以外のもの)は、 デフォルトのcontent-typeである"application/x-www-form-urlencoded"に合わせた形式でクエリー文字列へ変換されます。 もしDOMDocument、またはその他の形式のデータを送信したい場合は、このオプションをfalseに設定します。

scriptCharset

型:String

"script"通信での使用時での用途に限られます。 (例えば、"jsonp"、"script"のdataTypeでのクロスドメインへの"GET"リクエスト) scriptタグでのcharset属性の設定は、このリクエストでの指定が使用されます。 ローカルページ上で設定された文字コードと、リモートスクリプト上での文字コードが異なる場合に使用します。

{scriptCharset:"EUC-JP"}
statusCode
1.5追加

型:PlainObject 初期値:{}

HTTPコードの数値と、それに相当するコードが応答された際に呼び出される関数のオブジェクト(マップ)を指定します。 例えば、404を受け取った場合に、alertダイアログを表示したい場合は下記のように指定します。

$.ajax({
  statusCode: {
    404: function() {
      alert( "page not found" );
    }
  }
});

通信が成功した場合、successコールバックと同じ値を引数として受け取り、 同様に通信が失敗(300番台のリダイレクトも含む)した場合も、errorコールバックと同じ値を引数として受け取ります。

success

型:Function( PlainObject data, String textStatus, jqXHR jqXHR )

リクエストが成功した祭に呼び出される関数を指定します。 この関数は下記の3つの引数を受け取ります。

data
サーバが返すデータ(例えば、json値など)をdataTYpeに沿ってフォーマットされた値が格納されています。
textStatus
通信の結果により、「"success", "notmodified", "error", "timeout", "abort", "parsererror"」のいずれかが指定されます。
jqXHR
jqXHRオブジェクトです。(jQuery1.4.xまでは、XMLHttpRequestです。)

jQuery1.5からは、successの設定は関数の配列が受け取れるようになりました。 各関数は順に呼び出されます。

このsuccessは、Ajaxイベントです。

timeout

型:Number

リクエストのタイムアウト(ミリ秒)で設定します。 これは$.ajaxSetup()によって設定された、 グローバルなタイムアウトを上書きします。 タイムアウトのカウントは$.ajaxが呼び出しが行われた時点で開始され、 もし処理中にその他のリクエストがあり、ブラウザのコネクションが利用出来ないと、 送信が行われる前にリクエストがタイムアウトされることもあります。

jQuery 1.4.x、それ以下のバージョンでは、リクエストがタイムアウトするとXMLHttpRequestオブジェクトは不正(invalid)な状態になり、 オブジェクトのメンバへアクセスしようとすると、例外がスローされるかもしれません。

Firefox 3.0以上のみ、scriptとJSONPのリクエストはタイムアウトによるキャンセルが出来ず、 タイムアウト期限後でもスクリプトが実行されてしまいます。

traditional

型:Boolean

従来のパラメーターのシリアル化を使用したいのであれば、これをtrueに設定します。

type

型:String 初期値:'GET'

リクエストのタイプ("POST"または"GET")を指定します。

注意: PUTやDELETEのような、他のHTTPリクエストメソッドも、ここで指定することが可能ですが、 全てのブラウザでサポートされている保証がありません。

url

型:String 初期値:現在のページ

リクエストを送信するURLを指定します。

username

型:String

HTTPアクセスの認証リクエストに応答するXMLHttpRequestに使用されるユーザー名を指定します。

xhr

型:Function()
初期値:IEでこれが利用可能な場合はActiveXObject、それ以外はXMLHttpRequest

XMLHttpRequestオブジェクトが生成された際のコールバック関数を指定します。 デフォルトは、ActiveXObject(IE)が利用可能であればそれを、それ以外はXMLHttpRequestになります。 独自実装のXMLHttpRequestの上書きや、ファクトリーによる拡張が可能です。

xhrFields
1.5.1追加

型:PlainObject

ネイティブのXHRオブジェクト上に設定する、フィールド名/フィールド値のペアのオブジェクトを指定します。 例えば、下記のようにクロスドメインへのリクエストのために、 withCredentialsへtrueを指定することが可能です。

$.ajax({
   url: a_cross_domain_url,
   xhrFields: {
      withCredentials: true
   }
});

jQuery1.5までは、withCredentialsプロパティはネイティブのXHRに伝えられないため、 これを必要とするCORSリクエストは、このフラグを無視していました。 こういった理由から、このようなケースではjQuery 1.5.1以上を使用する事が推奨されています。

$.ajax()はjQueryによる全てのAjaxリクエスト処理の基盤となる関数です。 多くのケースで、この関数を直接呼び出す必要は無く、 $.get().load()のような、 代わりとなる高階層の扱い易い関数が用意されています。 あまり一般的ではないオプションが必要となるケースで、柔軟に対応出来る$.ajax()を使用します。

単に、$.ajax()関数は引数無しで呼び出される事が可能です。

$.ajax();

注意: デフォルトで、 設定(settings)には$.ajaxSetup()関数によるグローバルな設定が行われます。

この例ではオプションを使用せず、現在のページのコンテンツを読み込みますが、結果に対して何も行いません。 得られた結果を使用するには、コールバック関数のいずれかを実装する必要があります。

jqXHRオブジェクトについて

jQuery 1.5から$.ajax()によって返されるようになったjQuery XMLHttpRequest(jqXHR)は、 ブラウザネイティブのXMLHttpRequestオブジェクトのスーパーセットです。 例えば、これはgetResponseHeader()だけでなく、 responseTextresponseXMLプロパティも含みます。 XMLHttpRequestに無い何らかの通信メカニズムを行う際(例えば、JSONPリクエストのためのscriptタグ)に、 jqXHRオブジェクトは可能であれば、ネイティブのXHRの機能をシミュレートします。

jQuery 1.5.1では、jqXHRオブジェクトはoverrideMimeType()メソッドも含むようになりました。 (これはjQuery1.4.xで利用可能でしたが、jQuery1.5で一時的に取り除かれていました。) .overrideMimeType()メソッドは、例えばレスポンスのcontent-typeヘッダーを変更するために、 beforeSend()コールバック関数で使用されるかもしれません。

$.ajax({
  url: "http://fiddle.jshell.net/favicon.png",
  beforeSend: function( xhr ) {
    xhr.overrideMimeType( "text/plain; charset=x-user-defined" );
  }
})
  .done(function( data ) {
    if ( console && console.log ) {
      console.log( "Sample of data:", data.slice( 0, 100 ) );
    }
  });

jqXHRオブジェクトは、jQuery1.5でPromiseの全プロパティ、メソッド、振る舞いが与えられたPromiseインターフェース実装されて以降、 $.ajax()によって返されるようになりました。(詳細は、Deferredオブジェクト参照) これらのメソッドは、$.ajax()リクエストが終了した際に呼び出される、1つ以上の関数の引数を取得します。 これは、1つのリクエストで複数のコールバックを割り当てることを可能にし、 更にリクエストが完了している可能性がある後にでもコールバックを割り当てることが出来ます。 (もしリクエストが既に完了している場合、コールバックは即座に実行されます。) jqXHRオブジェクトに含まれる利用可能なPromiseメソッドは下記の通りです。

jqXHR.done(function( data, textStatus, jqXHR ) {});
successコールバックのオプションの代わりとなる仕組みで、 非推奨となった.success()メソッドは、 .done()メソッドに置き換えられました。 実装の詳細については、deferred.done()を参照してください。
jqXHR.fail(function( jqXHR, textStatus, errorThrown ) {});
errorコールバックオプションの代わりとなる仕組みで、 非推奨となった.error()メソッドは、 .fail()メソッドに置き換えられました。 実装の詳細については、deferred.fail()を参照してください。
jqXHR.always(function( data|jqXHR, textStatus, jqXHR|errorThrown ) {});

completeコールバックオプションの代わりとなる仕組みで、 非推奨となった.complete()メソッドは、 .always()メソッドに置き換えられました。

成功リクエストの応答であれば、関数の引数は.done()の場合と同じ、 data、textStatus、jqXHRオブジェクトになります。 失敗リクエストでの引数は、.fail()の場合と同じ、 jqXHRオブジェクト、textStatus、errorThrownになります。 実装の詳細については、deferred.always()を参照してください。

jqXHR.then(function( data, textStatus, jqXHR ) {}, function( jqXHR, textStatus, errorThrown ) {});
.done().fail()メソッドの機能を1つにし、 (jQuery1.8では)Promiseを基にした柔軟な扱いを可能とします。 実装の詳細については、deferred.then()を参照してください。

非推奨に関する注意: jqXHR.success()jqXHR.error()jqXHR.complete()コールバックは、 jQury1.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" );
  });

// その他の処理を実行します…。

// 上記のリクエストに、もう1つの完了時の関数を設定します。
jqxhr.always(function() {
  alert( "second complete" );
});

全てのコールバックでのthis参照は、 設定(settings)で$.ajaxに渡されたcontextオプションのオブジェクトになります。 もし、contextが指定されていなければ、thisはAjaxのsettings自体の参照となります。

XMLHttpRequestの後方互換のために、jqXHRオブジェクトは下記のプロパティとメソッドを公開します。

  • readyState
  • status
  • statusText
  • responseXMLと/またはresponseTextは、 それぞれのリクエストの応答のxmlと/またはtextに基づきます。
  • setRequestHeader(name, value)は、 新しい値を古いものに繋ぎ合わせるのではなく、 古い値を新しいものに置き換えるため、標準からは外れます。(翻訳に自信なし)
  • getAllResponseHeaders()
  • getResponseHeader()
  • statusCode()
  • abort()

onreadystatechangeのメカニズムは提供されませんが、 done、fail、alwaysとstatusCodeで考えられる必要事項を満たす事が出来るはずです。

コールバック関数キューについて

beforeSend、error、dataFilter、success、completeオプションが受け取る全てのコールバック関数は、 適切なタイミングで実行されます。

jQuery1.5ではfailとdoneが、jQuery1.6ではalwaysコールバックのフックが、 先入れ先出し管理のキューとなり、各フックのために1つ以上のコールバックが可能になりました。(翻訳に自信なし) これらの$.ajax()コールバックのフックのために、 内部的に実装されているDeferredオブジェクトのメソッドを参照してください。

$.ajax()によって提供されるコールバックのフックは、下記の通りです。

  1. beforeSendコールバックオプションは、 jqXHRオブジェクトとsettingsオブジェクトをパラメータとして受け取った際に実行されます。
  2. errorコールバックオプションは、リクエスト失敗時に実行されます。 これは、jqXHR、エラーのタイプを示す文字列、該当する例外オブジェクトを受け取ります。 組み込みエラーは、例外オブジェクトとして"abort"、"timeout"、"No Transport"の文字列を提供します。
  3. dataFilterコールバックオプションは、レスポンスデータの受け取りの成功直後に実行されます。 これはサーバーから返されるデータとdataTypeの値を受け取り、 successへ渡す(おそらく変更が行われた)データを返さなければいけません。
  4. successコールバックオプションは、リクエストが成功すると実行されます。 これはサーバーから返されたデータ、成功コードを含む文字列、jqXHRオブジェクトを受け取ります。
  5. Promiseコールバック - .done()、.fail()、.always()、.then()は、それぞれ登録された順に実行されます。
  6. completeコールバックオプションは、リクエスト完了時に成功か失敗かに関わらず実行されます。 これは成功またはエラーのコードを含む文字列だけでなく、jqXHRオブジェクトを受け取ります。

データタイプ(dataType)について

$.ajax()呼び出しへのレスポンスの異なるタイプが指定されている場合は、成功時の処理へ渡される前に、 異なる種類に変換するためのプリプロセスの処理が行われます。 プリプロセス処理のタイプは、デフォルトのレスポンスのContent-Typeに依存しますが、 dataTypeオプションを使用することでこれを明示的に設定することが可能です。 dataTypeオプションが提供されると、レスポンスのContent-Typeヘッダーは無視されます。

利用可能なデータのタイプは、texthtmlxmljsonjsonpscriptになります。

textまたはhtmlが指定された場合は、プリプロセスの処理は実行されません。 データは単にsucessのハンドラへ渡され、jqXHRオブジェクトのresponseTextを通して利用されます。

xmlが指定された場合は、successハンドラへ渡される前にjQuery.parseXMLを使用して、 XMLDocumentとしてレスポンスが解析されます。 XMLドキュメントは、jqXHRオブジェクトのresponseXMLプロパティを通して利用可能になります。

jsonが指定された場合は、successハンドラへ渡される前にjQuery.parseJSONを使用して、 オブジェクトとしてレスポンスが解析されます。 解析されたJSONオブジェクトは、jqXHRオブジェクトのresponseJSONプロパティを通して利用可能になります。

scriptが指定された場合、文字列としてsuccessハンドラへ渡される前に、 $.ajax()はサーバーから受け取ったJavaScriptを実行します。

jsonpが指定された場合、$.ajax()は(デフォルトで)自動的にURLへcallback=?のクエリー文字列パラメーターを追加します。 $.ajax()へ渡される設定(settings)のjsonpjsonpCallbackプロパティは、 それぞれクエリー文字列パラメーターの名前、JSONPコールバック関数の名前になります。 サーバーはJSONレスポンスをコールバック関数へ渡す適切なJavaScriptを返す必要があります。 $.ajax()は、レスポンスに含まれるJSONオブジェクトが$.ajax()のsuccessハンドラへ渡される前に、 返されたJavaScript(JSONPコールバック関数の呼び出し)を実行します。

JSONPの詳細については、Remote JSON - JSONPを参照してください。

サーバへのデータ送信について

デフォルトでは、AjaxリクエストはGETのHTTPメソッドを使用して送信されます。 もしPOSTメソッドが必要な場合は、typeオプションの設定の値によって指定することが可能です。 このオプションはdataオプションの中身がどのようにサーバーへ送信されるかにも影響します。 POSTデータは、W3CのXMLHTTPRequest標準に従い、常にUTF-8の文字セットを使用してサーバーへ運ばれます。

dataオプションは、key1=value1&key2=value2形式のクエリー文字列、 または{key1: 'value1', key2: 'value2'}形式のオブジェクトのどちらかを含む事が出来ます。 もし後者の形式を使用すると、 送信される直前にjQuery.param()を使用してクエリー文字列に変換されます。 この処理は、processDatafalseに設定することで回避することが可能です。 この処理は、XMLオブジェクトをサーバーへ送信したい場合には不適切かもしれません。 そういったケースでは、contentTypeオプションをapplication/x-www-form-urlencodedから、 より適切なMIME typeに変更してください。

高度なオプション

globalオプションは、 .ajaxSend().ajaxError()、 その他の同様のメソッドを使用して登録されたハンドラが、 リクエストがそれらをトリガする際に、発火することを妨げます。 これは例えば、ローディング・インディケーターが.ajaxSend()によって実装されており、 瞬間的且つ頻繁にリクエストが発生してインディケーターが繰り返し表示・非表示をしてしまう事を抑えたいようなケースで便利です。 クロスドメイン・スクリプトとJSONPリクエストでは、globalオプションは自動的にfalseに設定されます。 これらのメソッドの詳細については、後述します。

もし、レスポンス提供前にサーバーがHTTP認証を実行する場合、 ユーザー名とパスワードのペアをusernamepasswordオプションを通して送信することが可能です。

Ajaxリクエストは時間制限が掛けられるため、そのエラーをキャッチして、より良いユーザー体験を提供するために扱うことが可能です。 リクエストのタイムアウトは、特定のリクエストをtimeoutオプションを使用して上書きするよりも、デフォルトのままか、 $.ajaxSetup()を使用した、 グローバルなデフォルト設定が使用されることが一般的です。

デフォルトでは、ブラウザは常にリクエストを発行しますが、ブラウザがその結果のキャッシュを提供する事があるかもしれません。 このキャッシュされた結果の使用を避けたい場合は、cachefalseに設定します。 リクエストしたものが最後のリクエストから変更されていない際に、リクエストの失敗を報告させるには、 ifModifiedtrueに設定します。

scriptCharsetは、<script>タグで使用される文字コードを明示的に指定することを可能にします。 (scriptまたはjsonp) これはスクリプトとホストページの文字セットが異なる場合に便利です。

Ajaxの1文字目のAは"非同期(asynchronous)"を表すもので、 これはその処理は平行に行われ、それは完了することが保証されない事を意味します。 $.ajax()asyncオプションは、デフォルトではtrueに設定されており、 これはコードの実行がリクエスト後に続けられる事を示します。 このオプションをfalseに設定すること(すなわち非同期による呼び出しをしない)は、 ブラウザの反応が悪くなることがあるかもしれないため、推奨されません。

$.ajax()関数は、作成したXMLHttpRequestオブジェクトを返します。(翻訳に自信なし) 通常jQueryはこのオブジェクトを内部的に作りますが、 xhrオプションを使用して、これを作り出すカスタム関数を指定することが可能です。 ここで返されるオブジェクトは通常は破棄されますが、 監視用の低階層のインターフェースを提供し、そのリクエストを操作することが出来ます。 特に、オブジェクトの.abort()の呼び出しは、そのリクエストが完了する前に中断させることが可能です。

Ajaxの拡張

jQuery 1.5では、Ajax実装にプレフィルター(prefilter)、トランスポート(transport)、コンバーター(converter)が含まれ、 Ajaxを柔軟に扱えるような拡張が出来るようになりました。

コンバーターの使用

$.ajax()コンバーターは、データ(data)のタイプと他のデータ(data)のタイプのマッピングをサポートします。 ただし、カスタムデータのタイプを、よく知られているタイプ(例えば、json)にマッピングしたい場合は、 contentsオプションを使用して、そのレスポンスのContent-Typeと実際のデータのタイプが一致するものを追加しなければいけません。

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "mycustomtype json": function( result ) {
      // 何か行う
      return newresult;
    }
  }
});

レスポンスのContent-Typesとデータのタイプは、厳格に1対1で一致するものでは無いため、 これが必要になります。(そのために正規表現を使用)

サポートされたタイプ(例えば、text、json)から、カスタムデータのタイプに変換、または元に戻すには、 別にパスを通すコンバーターを使用します。

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "text mycustomtype": true,
    "mycustomtype json": function( result ) {
      // 何か行う
      return newresult;
    }
  }
});

こうすることで、textからmycustomtypeを通し、次にmycustomtypeからjsonに通すことが出来るようになります。

その他の注意事項

  • ブラウザによるセキュリティ制限により、ほとんどの"Ajax"リクエストは"同一生成元ポリシー"に準ずるため、 異なるドメイン、サブドメイン、ポートまたはプロトコルからのデータの取得は成功しません。
  • scriptとJSONPリクエストは、"同一生成元ポリシー"の制限を受けません。

サンプル

サーバへデータを保存し、完了した事をユーザーに通知します。

$.ajax({
  type: "POST",
  url: "some.php",
  data: { name: "John", location: "Boston" }
})
  .done(function( msg ) {
    alert( "Data Saved: " + msg );
  });

ページの最新状態を取得し、id="results"要素内に受け取ったHTMLを挿入します。

$.ajax({
  url: "test.html",
  cache: false
}).done(function( html ) {
  $("#results").append(html);

XMLデータを送信する際には、processDataのオプションをfalseに設定して jQueryが自動変換する事を防ぎます。

var xmlDocument = [create xml document];
var xmlRequest = $.ajax({
  url: "page.php",
  processData: false,
  data: xmlDocument
});

xmlRequest.done(handleResponse);

サーバーへデータとしてidを送信してサーバー上に保存し、 完了するとユーザーへ通知します。 もしリクエストが失敗すると、ユーザーへ警告(alert)します。

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"
});

 Back to top

© 2010 - 2016 STUDIO KINGDOM