jQuery日本語リファレンス

HTTP通信でページを読み込みます。

この関数はjQueryにおけるAJAX通信の基本部分で、実際には$.getや$.postといった関数を使った方が、容易に実装できます。
但し、これらの抽象化された関数は実装の容易さと引き換えに、エラー時のコールバックなどの複雑な機能を失っています。そのような処理を実装したい場合は、やはり基幹であるこの関数を用いる必要があります。

$.ajax関数は、戻り値として XMLHttpRequestオブジェクトを返します。殆どの場合、このオブジェクトを直接操作することは無いと思われますが、例えば投げてしまったリクエストを中断する場合など、必要であれば利用して下さい。

この関数は引数をひとつだけとりますが、実際にはハッシュで、キーと値の組み合わせにより多くのオプションを受け取ります。
以下にその一覧を載せますので、参考にして下さい。

async / boolean

非同期通信フラグ。初期値ではtrue（非同期通信）で、リクエストが投げられてから応答があるまで、ユーザエージェントは非同期に処理を続行します。falseに設定（同期通信）した場合、通信に応答があるまでブラウザはロックされ、操作を受け付けなくなることに注意してください。

beforeSend / function

AJAXによりリクエストが送信される前に呼ばれるAjax Eventです。戻り値にfalseを設定すれば、AJAX送信をキャンセルすることができます。

function(XMLHttpRequest){
  this; // AJAX送信に設定したオプションを示すオブジェクト
}

cache / boolean

jQuery 1.2より。初期値は通常はtrueですが、dataTypeがscriptの場合にはfalseになります。通信結果をキャッシュしたくない場合には、falseを設定してください。

complete / function

AJAX通信完了時に呼ばれる関数です。successやerrorが呼ばれた後に呼び出されるAjax Eventです。

function(XMLHttpRequest, textStatus){
  this; // AJAX送信に設定したオプションを示すオブジェクト
}

contentType / string

サーバにデータを送信する際に用いるcontent-typeヘッダの値です。初期値は"application/x-www-form-urlencoded"で、殆どの場合はこの設定のままで問題ないはずです。

data / object, string

サーバに送信する値。オブジェクトが指定された場合、クエリー文字列に変換されてGETリクエストとして付加されます。この変換処理については、後述するprocessDataを参照して下さい。オブジェクトはキーと値の組み合わせである必要がありますが、もし値が配列だった場合、jQueryは同じキーを持つ複数の値にシリアライズします。例えば {foo: ["bar1", "bar2"]} のように指定された場合、 &foo=bar1&foo=bar2 のように組み立てられます。

dataFilter / function

基本レベルでのXMLHttpRequestによる戻りデータをフィルタリングします。サーバからの戻り値をサニタイズする場合などに有用です。関数は第1引数に生データを、第2引数にdataTypeの値を受け取ります。フィルタをかけた値を戻り値として返して下さい。

function(data, type){
  // フィルタ処理
  // 最後に、サニタイズ後のデータを返す
  return data;
}

dataType / string

サーバから返されるデータの型を指定します。省略した場合は、jQueryがMIMEタイプなどを見ながら自動的に判別します。指定可能な値は、次のようなものです。

• "xml": XMLドキュメント
• "html": HTMLをテキストデータとして。ここにscriptタグが含まれた場合、処理は実行されます。
• "script": JavaScriptコードをテキストデータとして。cacheオプションに特に指定が無ければ、キャッシュは自動的に無効になります。リモートドメインに対するリクエストの場合、POSTはGETに変換されます。
• "json": JSON形式のデータとして評価し、JavaScriptのオブジェクトに変換します。
• "jsonp": JSONPとしてリクエストを呼び、callbackパラメータで指定した関数に呼び戻された値をJSONデータとして処理します。(jQuery 1.2より追加)
• "text": 通常の文字列。

dataTypeを指定する際は、幾つかの注すべき点があります。後述の注意1,2も参照して下さい。

error / function

通信に失敗した際に呼び出されるAjax Eventです。引数は3つで、順にXMLHttpRequestオブジェクト、エラー内容、補足的な例外オブジェクトを受け取ります。第2引数には "timeout", "error", "notmodified", "parsererror"などが返ります。

function(XMLHttpRequest, textStatus, errorThrown){
  // 通常はここでtextStatusやerrorThrownの値を見て処理を切り分けるか、
  // 単純に通信に失敗した際の処理を記述します。
  this; // thisは他のコールバック関数同様にAJAX通信時のオプションを示します。
}

global / boolean

Ajax EventsのGlobal Eventsを実行するかどうかを指定します。通常はtrueですが、特別な通信でfalseにすることも出来ます。詳しくはAjax Eventsを参照して下さい。

ifModified / boolean

サーバからの応答にあるLast-Modifiedヘッダを見て、前回の通信から変更がある場合のみ成功ステータスを返します。

jsonp / string

jsonpリクエストを行う際に、callbackではないパラメータであれば指定します。例えば {jsonp: 'onJsonPLoad'} と指定すれば、実際のリクエストには onJsonPLoad=[関数名] が付与されます。

password / string

認証が必要なHTTP通信時に、パスワードを指定します。

processData / boolean

dataに指定したオブジェクトをクエリ文字列に変換するかどうかを設定します。初期値はtrueで、自動的に "application/x-www-form-urlencoded" 形式に変換します。DOMDocumentそのものなど、他の形式でデータを送るために自動変換を行いたくない場合はfalseを指定します。

scriptCharset / string

スクリプトを読み込む際のキャラセットを指定します。dataTypeが"jsonp"もしくは"script"で、実行されるページと呼び出しているサーバ側のキャラセットが異なる場合のみ指定する必要があります。

success / function

AJAX通信が成功した場合に呼び出されるAjax Eventです。戻ってきたデータとdataTypeに指定した値の2つの引数を受け取ります。

function(data, dataType){
  // dataの値を用いて、通信成功時の処理を記述します。
  this; // thisはAJAX送信時に設定したオプションです
}

timeout / number

タイムアウト時間をミリ秒で設定します。$.ajaxSetupで指定した値を、通信に応じて個別に上書きすることができます。

type / string

"POST"か"GET"を指定して、HTTP通信の種類を設定します。初期値は"GET"です。RESTfulに"PUT"や"DELETE"を指定することもできますが、全てのブラウザが対応しているわけではないので注意が必要です。

url / string

リクエストを送信する先のURLです。省略時は呼び出し元のページに送信します。

username / string

認証が必要なHTTP通信時に、ユーザ名を指定します。

xhr / function

XMLHttpRequestオブジェクトが作成された際に呼び出されるコールバック関数です。この関数は、例えばIEではXMLHttpRequestではなくActiveXObjectが作られた際に呼ばれます。もし、サイト特有のXMLHttpRequestオブジェクトの拡張やインスタンス管理のファクトリーを持っている場合には、この関数で生成物を上書きすることが出来ます。jQuery1.2.6以前では利用できません。

※注意1
dataTypeオプションを用いる場合、サーバからの応答が正しいMIMEタイプを返すことを確認して下さい。
もしMIMEタイプと指定されたdataTypeに不整合がある場合、予期しない問題を引き起こす場合があります。
詳しくはSpecifying the Data Type for AJAX Requests (英語)を参照して下さい。

※注意2
dataTypeに"script"を指定して他のドメインへの送信を行う場合、POSTを指定してもリクエストはGETに自動的に変換されます。

jQuery 1.2からは、異なったドメインからもJSONPを用いてJSONデータを取得できるオプションが付きました。JSONPを提供するサーバが "url?callback=function" のような形でリクエストを受け付ける場合には、jQueryは自動的にfunctionを指定してJSONデータを受け取ります。
また、パラメータが callback ではない場合、jsonpオプションにパラメータ名を指定することで同様に処理できます。

$.ajax({
  type: "GET",
  url: "test.js",
  dataType: "script"
});

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

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

var html = $.ajax({
  url: "some.php",
  async: false
 }).responseText;

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