jQuery.ajax(settings)
version 1.0 以降
解説
HTTPリクエストを使用してデータを取得します。
このメソッドは、ajax の最も低レベルな実装です。
より使いやすく具体化された実装には、jQuery.get(url, [data], [handler], [dataType])、jQuery.post(url, [data], [handler], [dataType])などがあります。
但し、このメソッドほど多くの機能は提供しませんので(例えば、エラーコールバック関数などは指定できません)、場合によって使い分けてください。
(もちろん、ajaxError(handler) 等のグローバルAjaxイベントを使えば、共通処理におけるハンドリングは可能です。)
このメソッドは XMLHttpRequest を返します。ほとんど使用することはありませんが、必要であれば、手動でリクエストを中止したりすることができます。
引数
- options : リクエストのパラメータ。キーと値のハッシュ。
キー |
型 |
初期値 |
説明 |
async |
Boolean |
true |
非同期通信かどうかを指定します。非同期通信の場合は true、同期通信の場合は falseを設定します。
(同期通信の場合、通信中はブラウザがロックされ、すべての操作を受け付けなくなります。場合によって使い分けてください。)
|
beforeSend |
Function |
なし |
リクエストが送信される前に実行するコールバック関数を指定します。
引数にXMLHttpRequestオブジェクトが渡されますので、ヘッダをカスタマイズしたい場合などに使うことができます。
このコールバック関数が false を返すと、リクエストを中止します。
function (XMLHttpRequest) {
}
|
cache |
Boolean |
true dataType=="script"の場合はfalse |
キャッシュを使用するかどうかを指定します。
キャッシュを有効にすると、リクエストに現在の時刻を使ったパラメータを付与します。
これにより,リクエスト毎に必ず異なった送信クエリが生成されるため、キャッシュされなくなります。
|
complete |
Function |
なし |
通信が終了したときに実行するコールバック関数を指定します。
(success、errorのコールバック関数が実行された後に呼び出されます。)
引数にXMLHttpRequestオブジェクトと、リクエスト結果を表す文字列が渡されます。
リクエスト結果 | 説明 |
success | 成功 |
error | 失敗 |
notmodified | 更新されていない |
timeout | タイムアウト |
parsererror | データパースエラー |
function (XMLHttpRequest, status) {
if (status == "success") {
} else if (status == "error") {
} else if (status == "notmodified") {
} else if (status == "timeout") {
} else if (status == "parsererror") {
}
}
|
contentType |
String |
"application/x-www-form-urlencoded" |
送信データのコンテンツタイプを指定します。
|
context
|
Object |
なし |
コールバック関数の context(this) を指定します。
$.ajax({
url: urlString,
context: document.getElementById("#contextID"),
success: function(data, status, xhr) {
$("selector", this).append(data);
}
});
|
data |
Object, String |
null |
サーバに送信するデータを指定します。
文字列でない場合は、自動的に application/x-www-form-urlencoded 形式 にシリアライズします。
(この自動変換を行いたくない場合は、processDataオプションにfalseを指定してください。)
オブジェクトを指定する場合、キーと値のペア(ハッシュ)を指定してください。
値が配列の場合は、同じキー名でシリアライズします。
例){key:["value1", "value2"]} => &key=value1&key=value2
|
dataFilter |
Function |
なし |
サーバから受信したデータをフィルタリングします。success コールバック関数に返す前に、データの無害化などを行うことができます。
dataFilter には、応答データと、応答データの形式 が渡されます。
function (data, type) {
data;
type;
...
return data;
}
|
dataType |
String |
なし(自動判断) |
期待するサーバの応答データの形式を指定します。指定された形式に従い、応答データを評価します。
指定しない場合は、応答データのMIMEタイプから自動的に判断します。
dataType | successコールバック関数の第1引数に渡されるデータ |
xml | jQueryで処理可能なXMLドキュメントです。 |
html | HTMLテキストです。scriptタグは評価されます。 |
script | 応答データをJavaScriptとして評価します。cacheオプションが指定されない限りキャッシュされません。 |
json | 応答データをJSONとして評価した、JavaScriptオブジェクトです。 |
jsonp | JSONPを使用し、応答データを指定したコールバック関数によってJSONとして評価した、JavaScriptオブジェクトです。 |
text | プレーンテキストです。 |
|
error |
Function |
なし |
通信が失敗したときに実行するコールバック関数を指定します。
引数にXMLHttpRequestオブジェクトと、リクエスト結果を表す文字列、例外オブジェクトが渡されます。
function (XMLHttpRequest, status, errorThrown) {
XMLHttpRequest;
status;
errorThrown;
}
|
global |
Boolean |
true |
グローバルAjaxイベントを実行するかどうかを指定します。falseを指定すると実行しません。
グローバルAjaxイベント一覧
|
ifModified |
Boolean |
false |
データが更新されていた場合のみにデータを送信してもらうかどうかを指定します。
("If-Modified-Since"ヘッダを設定します。)
|
jsonp |
String |
なし (内部的に"callback"になる) |
JSONPリクエストで使用するコールバック関数のパラメータ名を設定します。
何も指定をしないと、"callback"になります。
|
jsonpCallback |
String |
"jsonp" + エポック秒文字列 |
JSONPリクエストで使用するコールバック関数名を設定します。
何も指定をしないと、"jsonp" + エポック秒文字列になります。
|
password |
String |
null |
認証が必要なHTTPリクエストを送信する場合のパスワードを指定します。
|
processData |
Boolean |
true |
dataオプションに指定したオブジェクトを、application/x-www-form-urlencoded 形式にシリアライズするかどうかを指定します。
もし、そのままの形式で送信したい場合はfalse を指定してください。
|
scriptCharset |
String |
なし |
dataTypeオプションが "script"の場合や、内部的にscriptタグを生成して通信する場合(jsonp等)の、script読み込み時の文字コードを指定します。
|
success |
Function |
なし |
通信が成功したときに実行するコールバック関数を指定します。
引数にdataTypeオプションに応じて評価された応答データ、リクエスト結果を表す文字列、XMLHttpRequest が渡されます。
function (data, status, xhr) {
data;
status;
xhr;
}
|
timeout |
Number |
0 |
タイムアウトの時間をミリ秒で指定します。 |
traditional |
Boolean |
なし (内部的に false と同等) |
true を指定すると、1.3 以前の古い形式でパラメータをシリアライズします。
詳細は、jQuery.param(obj, [traditional]) を参照してください。
|
type |
String |
"GET" |
"POST" もしくは "GET" を指定します。
("PUT", "DELETE"も指定することができますが、すべてのブラウザに対応していません。)
|
url |
String |
現在のページのURL(location.href) |
リクエスト先のURLを指定します。
|
username |
String |
null |
認証が必要なHTTPリクエストを送信する場合のユーザ名を指定します。
|
xhr |
Function |
なし |
XMLHttpRequest オブジェクトを生成する関数を指定します。
例えば IE で Msxml2.XMLHTTP.6.0 を XMLHttpRequest として利用したい場合は、次のようにします。
function () {
try {
return new ActiveXObject("Msxml2.XMLHTTP.6.0");
} catch(e){}
try {
return new ActiveXObject("Microsoft.XMLHTTP");
} catch(e){}
return new XMLHttpRequest();
}
|
戻り値
例
例1:Youtubeから検索結果をJSONPで取得し、表示します。
$.ajax({
url: "http://gdata.youtube.com/feeds/api/videos",
data: {
"vq": "テスト",
"max-results": 5,
"alt": "json-in-script"
},
dataType: "jsonp",
cache: true,
success: function(data, status, xhr) {
$("#test_result").append("----- Youtube検索結果 -----");
$.each(data.feed.entry, function(i, item){
var group = item.media$group;
$("<div/>")
.append($("<img/>").attr("src", group.media$thumbnail[0].url))
.append("<br/>")
.append(item.title.$t)
.click(function(){window.open(group.media$player[0].url, null)})
.appendTo("#test_result");
});
}
});
Etag のサポート
version 1.4 以降 では、Etag パラメータを判別するようになりました。
ifModified オプションが true の場合、レスポンスヘッダに Etag パラメータが存在した場合は、If-None-Match パラメータを送信します。
|
- jQuery API 1.4.4 日本語リファレンス
- Core
- Selectors
- Attributes
- Traversing
- Manipulation
- CSS
- Events
- Effects
- Ajax
- jQuery.ajax(settings)
- ajaxComplete(handler)
- ajaxError(handler)
- ajaxSend(handler)
- jQuery.ajaxSetup(options)
- ajaxStart(handler)
- ajaxStop(handler)
- ajaxSuccess(handler)
- jQuery.get(url, [data], [handler], [dataType])
- jQuery.getJSON(url, [data], [handler])
- jQuery.getScript(url, [handler])
- load(url, [data], [handler])
- jQuery.param(obj, [traditional])
- jQuery.post(url, [data], [handler], [dataType])
- serialize()
- serializeArray()
- Utilities
- jQuery UI API 1.8.4 日本語リファレンス
- jQueryと他のライブラリを同時に使用する方法
|