jQuery.ajax()のまとめ: 小粋空間

ナビゲーションをスキップする

Top ＞ JavaScript ＞ jQuery ＞ jQuery.ajax()のまとめ

jQuery.ajax()のまとめ

Posted at October 2,2012 12:55 AM
Tag：[Ajax, jQuery]

jQuery.ajax()について逆引きリファレンスっぽくまとめてみました。

まとめた理由は、ネットで「jQuery.ajax」や「jQuery.ajax サンプル」などで調べても、いい感じの内容がなかなかヒットしないことと、よくヒットするサイトの情報が古かったりする（1.4で止まっているとか）ためです。

ということで、~~2012年10月現在~~2014年10月現在の「jQuery.ajax()」などをざっと調べて作ってみました。

初心者向けの内容です。すべてのオプションは網羅できていません。とりあえずサンプルコードがほしい方は１５項をご覧ください。

若番から必要と思われるものを順番に並べているつもりですが、後半は適当です。また、各項のサンプルはなんとなく積み上げていく感じにしています。

調べている間にも3つくらい新しい発見（といっても古い情報ですが…）があり、jQueryが日々進化していることを感じました。

勉強がてらの記事なので間違いがありましたらどこかでつぶやいてください。

１．基本

全体に共通する基本的な事項です。

まず、「:」の右辺に記述する文字が文字列の場合、クォーテーションまたはダブルクォーテーションで括ってください。数値・変数・真偽値は括らなくても大丈夫です。左辺は括る必要はありません。

$.ajax({
    url: 'hoge.html', // 文字列
    ...

var url = 'hoge.html';
$.ajax({
    url: url, // 変数
    ...

$.ajax({
    timeout: 10000, // 数値
    ...

$.ajax({
    async: true, // 真偽値
    ...

また、後述する各オプションの末尾にカンマを付け忘れないよう、気をつけましょう（一番最後のオプションの末尾のカンマは不要）。

２．HTTPのリクエストメソッドを指定するには？

HTTPのリクエストメソッド（POST/GET）を指定するには「type」オプションを指定します。デフォルトは「GET」です。

POSTの場合

$.ajax({
    type: 'POST',
    ...

GETの場合

$.ajax({
    type: 'GET',
    ...

３．送信先URLを指定するには？

送信先URLは「url」オプションに設定します。

$.ajax({
    type: 'POST',
    url: 'http://user-domain/hoge.php',
    ...

４．クエリーパラメータを指定するには？

「data」オプションに設定します。

$.ajax({
    type: 'GET',
    url: 'http://user-domain/hoge.php',
    data: {
        id: 1,
        mode: 'hoge',
        type: 'entry'
    },
    ...

GETメソッドであれば次のようなリクエストになると思います。

http://user-domain/hoge.php?id=1&mode=hoge&type=entry

５．受信データタイプの指定は？

受信データタイプは「dataType」オプションに設定します。デフォルトは自動推測ですが、レスポンスを期待通り受信あるいは処理できない場合は設定してみましょう。

プレーンテキストを受信する場合

$.ajax({
    type: 'POST',
    url: 'http://user-domain/hoge.txt',
    dataType: 'text',
    ...

HTMLデータを受信する場合

$.ajax({
    type: 'POST',
    url: 'http://user-domain/hoge.html',
    dataType: 'html',
    ...

XMLデータを受信する場合

$.ajax({
    type: 'POST',
    url: 'http://user-domain/hoge.xml',
    dataType: 'xml',
    ...

JavaScriptデータを受信する場合

$.ajax({
    type: 'POST',
    url: 'http://user-domain/hoge.js',
    dataType: 'script',
    ...

JSONデータを受信する場合

$.ajax({
    type: 'POST',
    url: 'http://user-domain/hoge.json',
    dataType: 'json',
    ...

JSONの場合、jQuery.getJSON()を使ってもOKです。

JSONPを受信する場合

$.ajax({
    type: 'POST',
    url: 'http://user-domain/hoge.php',
    dataType: 'jsonp',
    ...

JSONPの場合、URLに「callback=?」という特殊なクエリーが自動的に付与されます。「?」の部分は任意の文字列を設定してサーバにコールバック関数名として送信します。

サーバ側ではこの「callback=?」の部分を読み取り、jsonpのコールバック関数名として返却値に設定する必要があります。通信が成功すれば「success」オプションで受信できます。

コールバック関数のキー名を指定したい場合は、「jsonp」オプションにコールバック関数のキーを設定します。

$.ajax({
    type: 'POST',
    url: 'http://user-domain/hoge.php',
    dataType: 'jsonp',
    jsonp: 'jsoncallback',
    ...
});

コールバック関数名は「jsonpCallback」オプションで設定可能です。

$.ajax({
    type: 'POST',
    url: 'http://user-domain/hoge.php',
    dataType: 'jsonp',
    jsonp: 'jsoncallback',
    jsonpCallback: 'foo',
    ...
});

クロスドメインの場合は、さらに「crossDomain」オプションを付与します。「true」を設定すればクロスドメイン通信が可能です。

$.ajax({
    type: 'POST',
    url: 'http://user-domain/hoge.php',
    dataType: 'jsonp',
    jsonp: 'jsoncallback',
    jsonpCallback: 'foo',
    crossDomain: true,
    ...
});

1.5以降では複数のデータ型を指定できるようです。

    dataType: 'text xml',

６．キャッシュされたデータを受信したくないのですが？

「cache」オプションを設定します。デフォルトは「true」で、「false」を設定すればキャッシュされなくなるようです。

$.ajax({
    type: 'POST',
    url: 'http://user-domain/hoge.php',
    data: {
        id: 1,
        mode: 'hoge',
        type: 'entry'
    },
    dataType: 'html',
    cache: false,
    ...

７．結果の受信は？

注：「success」「complete」「error」オプションは旧バージョンのため、記載を削除しました。

「done」「fail」「always」で受信できます。

「done」オプションは通信が成功したとき、「always」オプションは通信が完了したとき、「fail」オプションは通信に失敗したときに起動されます。

$.ajax({
    url: 'http://user-domain/hoge.php',
    type: 'POST',
    data: {
        id: 1,
        mode: 'hoge',
        type: 'entry'
    },
    dataType: 'html'
})
.done(function( data, textStatus, jqXHR ) {
        // ...
})
.fail(function( jqXHR, textStatus, errorThrown ) {
        // ...
})
.always(function( jqXHR, textStatus ) {
        // ...
});

「done」オプションで起動される関数の引数は3つですが、最初のdataのみでも大丈夫かと思います。textStatusはリクエストの状態（「success」など）を返却します。

.done(function( data ) {
    $('#foo").html( data );
})

パラメータdataには、「dataType:」で指定したデータが設定されています。設定したdataTypeと受信したデータ型が一致していないと、正常に処理できない可能性があります。

failの引数は3つで、順にjqXHRオブジェクト、エラー内容、補足的な例外オブジェクトを受け取ります。第2引数には "timeout", "error", "notmodified", "parsererror"などが返ります。

話がちょっとそれますが、「jqXHR」は1.5から返却されるようになったオブジェクトで、1.4.xまでの「XMLHttpRequest」と違い、Promiseインターフェースというものを備えていて、これによりdoneやfailによるコールバック登録が行えるようになっています。

８．「done」と「always」の違いは？

「done」は通信に成功した場合のみ起動されます。「always」は「fail」を含め、処理が完了した場合に必ず起動されます。

Javaが分かる人は「try/catch/finally」と対応させれば理解が容易になると思います。

９．送信前に処理を行いたいが？

「beforeSend」オプションを設定します。

$.ajax({
    url: 'http://user-domain/hoge.php',
    type: 'POST',
    beforeSend: function ( jqXHR, settings ) {
        // ...
    }
})
.done(function( data, textStatus, jqXHR ) {
    // ...
}),
...

第2パラメータの「settings」は、jQuery.ajax()の設定オプションを参照できます。

    beforeSend: function ( jqXHR, settings ) {
        alert( setting.type ); // 'POST'
        alert( setting.url );  // 'http://user-domain/hoge.php'
    }

１０．同期で通信したいが？

「async」オプションを設定します。「false」を設定すれば、jQuery.ajax()の後方の処理が待ち合わせされます。

下の例では「success」または「error」の処理が終わってからalertが実行されます。非同期の場合は（多分）alertが先に実行されます。

$.ajax({
    async: false,
    url: 'http://user-domain/hoge.php',
    type: 'POST'
})
.done(function( data, textStatus, jqXHR ) {
    // ...
})
.fail(function( jqXHR, textStatus, errorThrown ) {
    // ...
});
alert("OK");

なお「false」を設定しても「beforeSend」が一番早く実行されます。

注：jQuery 1.8以降は「async: false」の記述は非推奨となっており、「you must use the complete/success/error callbacks」と書かれています。

１１．ステータスコードで処理を振り分けたいが？

「statusCode」オプションを利用します。

$.ajax({
    async: false,
    url: 'http://user-domain/hoge.php',
    type: 'POST',
    statusCode: {
        200: function(){
            console.log("200");
        }, 
        404: function(){
            console.log("404");
        }
    }
});

レスポンスデータも受け取れます。

    statusCode: {
        200: function( data ){
            console.log( data );
        },

１２．最後のリクエスト以降で変更があったことを判定したいが？

「ifModified」オプションを利用します。「true」を設定すれば、Last-Modifiedヘッダをチェックします。

$.ajax({
    async: false,
    url: 'http://user-domain/hoge.php',
    type: 'POST',
    ifModified: true,
    ...

１３．HTTP認証が必要だが？

「username」オプションと「password」オプションを設定します。

$.ajax({
    async: false,
    url: 'http://user-domain/hoge.php',
    type: 'POST',
    username: 'foo',
    password: 'bar',
    ...

１４．タイムアウトさせたいが？

「timeout」オプションを設定します。単位はmsです。

$.ajax({
    async: false,
    url: 'http://user-domain/hoge.php',
    type: 'POST',
    timeout: 10000,
    ...

１５．すぐに使えるサンプルは？

POSTデータで「http://user-domain/hoge.php」を起動するサンプルをいくつか作ってみました。返却値はHTMLで受け取ります。

$.ajax({
    url: 'http://user-domain/hoge.php',
    type: 'POST',
    data: {
        id: 1,
        mode: 'hoge',
        type: 'entry'
    },
    dataType: 'html'
})
.done(function( data ) {
        // ...
})
.fail(function( data ) {
        // ...
})
.always(function( data ) {
        // ...
});

それぞれのコールバックを分割することもできます。変数jqxhrのスコープに気をつけてください。

var jqxhr = $.ajax({
    url: 'http://user-domain/hoge.php',
    type: 'POST',
    data: {
        id: 1,
        mode: 'hoge',
        type: 'entry'
    },
    dataType: 'html'
});
jqxhr.done(function( data ) {
    // ...
});
jqxhr.fail(function( data ) {
    // ...
});
jqxhr.always(function( data ) {
    // ...
});

１６．参考サイト

主な参考サイトは以下です。ありがとうございました。

2014.10.22
1.8以前のsuccess/error/completeの記述を削除しました。

Posted by yujiro このページの先頭に戻る

小粋空間 - a cheap joke and a play on words site