jQuery入門

トップ > jQuery > Ajax

Ajax(Shorthand Methods)

obj.load(url[, data][, complete(data, textStatus, xhr)]) (1.0)

url で指定したリソースを Ajaxで読み込み、obj に流し込みます。

$("#result").load("test.php");

url には、URL に続いて、セレクタを指定することも可能です。この場合、対象の URI から、指定したセレクタにマッチした要素のみを取り出します。

$("#result").load("test.php #section2");

data にはフォームデータを指定します。引数を文字列で渡した場合は GET メソッド、オブジェクト形式で渡した場合は POST メソッドで HTTP通信を行います。

$("#result").load("test.php", "t1=AAA&t2=BBB&t3=CCC");             // GET method
$("#result").load("test.php", { t1:"AAA", t2:"BBB", t3:"CCC" });   // POST method

complete には、Ajax通信完了時のコールバック関数を指定します。data には取得した文字列、textStatus には success, error などの状態文字列、xhr には XMLHttpRequest オブジェクトが渡されます。xhr.status は HTTP のステータスコード、xhr.statusText にはその意味が格納されています。

$("#result").load("test.php", function(data, status, xhr) {
    $("#log").append("status = " + status + "<br>");                   // error
    $("#log").append("xhr.status = " + xhr.status + "<br>");           // 404
    $("#log").append("xhr.statusText = " + xhr.statusText + "<br>");   // Not Found
});
$.get(url[, data][, success(data, textStatus, xhr)][, dataType]) (1.0)

load() と類似の動作を行いますが、obj への流し込みを行わないこと、data の指定方式に関わらず GET メソッドを用いることなどが異なります。パラメータの詳細は load() を参照してください。

$.get("test.php", function(data, status, xhr) {
    if (status == "success") {
        $("#result").html(data);
    }
});

get() メソッドは、jqXHR オブジェクトを返します。これに対して下記の様なコールバック関数を指定することができます。

$.get("test.php", function(data, status, xhr) { $("#result").html(data); })
    .done(function(data, status, jqxhr) { $("#log").append("Done<br>"); })
    .fail(function(jqxhr, status, error) { $("#log").append("Failed<br>"); });
$.post(url[, data][, success(data, textStatus, xhr)][, dataType]) (1.0)

$.get() と類似の動作を行いますが、data の指定方式に関わらず POST メソッドを用いる点が異なります。

$.post("test.php", { t1:"AAA", t2:"BBB" }, function(data, status, xhr) {
    if (status == "success") {
        $("#result").html(data);
    }
});
$.getJSON(url[, data][, success(data, textStatus, xhr)]) (1.XXX)

$.get() と類似の動作を行いますが、data を JSON の値として受け取る点が異なります。

$.getJSON("test.php", { t1:"AAA", t2:"BBB" }, function(data, status, xhr) {
    $.each(data, function(key, val)) {
        $("#log").append("Data: " + key + " = " + val + "<br>");
    });
});
$.getScript(url[, success(script, textStatus, xhr)]) (1.0)

$.get() と類似の動作を行いますが、JavaScript ファイルを読み込み、実行する点が異なります。

$.getScript("test.js", function(script, status, xhr) {
    if (status == "error") {
        alert("Script loading error!");
    }
});

Ajax(Low-Level Interface)

$.ajax([options]) (1.0)
$.ajax(url[, options]) (1.5)

Ajax を用いて url を非同期に読み込みます。$.ajax() は jqXHR オブジェクトを返却します。このオブジェクトの done() メソッドでコールバック関数を指定することでデータを受け取ります。失敗した場合のコールバック関数は fail() メソッドで指定します。status には、"success", "notmodified", "error", "timeout", "abort", "parseerror" のいずれかの文字が設定されています。

$.ajax({
    url: "test.php",
    type: "POST",
    timeout: 10000
}).done(function(data, status, xhr) {
    $("#result").html(data);
}).fail(function(xhr, status, error) {
    $("#log").append("xhr.status = " + xhr.status + "<br>");          // 例: 404
    $("#log").append("xhr.statusText = " + xhr.statusText + "<br>");  // 例: Not Found
    $("#log").append("status = " + status + "<br>");                  // 例: error
    $("#log").append("error = " + error + "<br>");                    // 例: Not Found
});

options には、下記のパラメータを指定することができます。$.ajaxSetup() を用いてあらかじめ設定しておくこともできます。

種別 名前 説明
基本 url リソースの URL を指定します。
(例: url: "../common/getdata.php") (1.0)
type HTTP メソッドの種別を "GET" か "POST" で指定します。
(例: type: "POST") (1.0)
data サーバに送信するフォームデータを指定します。
(例1: data: { id:"tanaka", pw:"qWeRtY" })
(例2: data: "id=tanaka&pw=qWeRtY") (1.0)
timeout はタイムアウト値(ミリ秒)を指定します。
(例: timeout: 10000) (1.0)
結果取得 success 通信が成功した時に呼ばれるコールバック関数を指定します。詳細は後述。 (1.0)
error 通信が失敗した時に呼ばれるコールバック関数を指定します。詳細は後述。 (1.0)
complete 成功・失敗に関わらず通信が完了した時に呼ばれるコールバック関数を指定します。詳細は後述。 (1.0)
送信データ処理 mimeType リクエストの MIMEタイプを指定します。
(例: mimeType: "application/json") (1.5.1)
contentType リクエストの Content-Type を指定します。規定値は、送信データが存在する場合は "application/x-www-form-urlencoded; charset=UTF-8" です。送信データが存在しない場合、通常は Content-Type は付加されませんが、contentType を指定した場合は強制的に付与されます。
(例: contentType: "application/json; charset=UTF-8") (1.0)
processData data で指定した送信データをパーサで処理するか否かを true / false で指定します。規定値は true で、自動的に "application/x-www-form-urlencoded" 形式に変換されますが、false を指定することで、DOMDocument や 非変換データを無変換で送信することができます。
(例: processData: false) (1.0)
traditional true を指定すると、1階層分の変換のみを行う古い形式のパラメータ変換を行います。
(例: traditional: true) (1.0)
headers 追加の HTTPヘッダ情報をヘッダ名と値のマップで記述します。
(例: headers: { "X-Oroginal-Header" : "data..." }) (1.5)
beforeSend リクエスト送信前に呼び出されるコールバック関数を指定します。コールバック関数が false を返却した場合、リクエストは中断されます。
(例: beforeSend: function(xhr, options) { ... }) (1.0)
認証 username Basic認証を用いる際のユーザ名を指定します。
(例: username: "tanaka") (1.0)
password Basic認証を用いる際のパスワードを指定します。
(例: password: "qWeR+tYu") (1.0)
受信データ処理 dataType データの受信形式を "text", "html", "xml", "script", "json", "jsonp" のいずれかで指定します。省略時はレスポンスの MIMEタイプなどから jQuery が自動的に判断します。
(例: dataType: "json") (1.0)
accepts dataType で指定したタイプに対して、HTTP の Accept: ヘッダで送信する MIMEタイプを指定します。
(例: accepts: { text: "text/plain", json: "application/json" }) (1.0)
contents データタイプと、レスポンスの Content-Type の正規表現とのマッピングを記述します。例えば例の場合、レスポンスの Content-Type が text/x-yaml の場合、正規表現 /yaml/ にマッチし、そのデータタイプは yaml であるとみなされます。
(例: contents: { "yaml": /yaml/, "csv":/csv/ }) (1.5)
converters contents で判別したデータタイプに対するパーサ関数を指定します。これにより、未知の MIME タイプのデータでも、独自パーサで敵セスに変換した後に done() メソッドに渡すことが可能となります。
(例: converters: { "* yaml": function(data) { ...; return convertedData; } }) (1.5)
dataFilter json や xml などのパーサで解釈される前の生のレスポンスデータを参照・更新するコールバック関数を指定します。
(例: dataFilter: function(data, type) { ... }) (1.0)
cache キャッシュを利用するか否かを true / false で指定します。規定値は通常 true ですが、dataType が json や jsonp の場合は false となります。cache が false の場合、If-Modified-Since や If-None-Match などのヘッダ送信が抑制され、また、URL の末尾に ?_=タイムスタンプ を付加することで毎回異なる URL がリクエストされるようになります。
(例: cache: false) (1.0)
ifModified true を指定すると、リクエストヘッダに If-Modified-Since ヘッダが含まれ、レスポンスが 304 Not Modified の場合に、success: や done() とならず、error: や fail() にエラー番号 304が返却されます。これにより、リソースが、すでに受信炭のデータか否かを見分けることができます。ただし、レスポンスヘッダに Last-Modified ヘッダが含まれない場合はうまく機能しないようです。
(例: ifModified: true) (1.0)
statusCode レスポンスの HTTP ステータスに応じたコールバック関数を指定します。
(例: statusCode: { 404: function() { alert("Not Found!!"); } }) (1.5)
スクリプト呼び出し scriptCharset type が "GET" で、dataType が "script" または "jsonp" の場合に、読み込んだスクリプトの文字コードを指定します。
(例: scriptCharset: "UTF-8") (1.0)
jsonp (未稿) (1.0)
jsonCallback (未稿) (1.0)
その他 async false を指定すると Ajax が同期的に実行され、Ajax 処理が完了するまで次の処理を実行しません。
(例: async: false) (1.0)
context done() などのコールバック関数で $(this) として参照されるオブジェクトを指定します。
(例: context: document.body) (1.0)
global .ajaxStart() などのグローバル Ajaxイベントを実行するか否かを true / false で指定します。規定値は true です。
(例: global: false) (1.0)
isLocal 処理をローカルのものとして扱うか否かを true / false で指定します。通常、プロトコルが file, *-extension, widget の時のみローカルと認識されますが、isLocal を true にすることでそれ以外の場合でもローカルと見なして扱います。設定する場合は、$.ajaxSetup() で設定します。
(例: isLocal: true) (1.5.1)
crossDomain 同じドメイン上で JSONP の様なクロスドメイン要求を強制的に使用したい場合に true を指定します。例えば、他ドメインへのサーバサイドリダイレクションなどで利用されます。規定値は、同ドメインの場合は false、クロスドメインの場合は true です。
(例: crossDomain: true) (1.5)
xhr XMLHttpRequest オブジェクトを生成するためのコールバック関数を指定します。規定値では、IE の場合は ActiveXObject()、その他のブラウザでは XMLHttpRequest() が使用されます。
(例: xhr: MyXMLHttpRequest) (1.0)
xhrFields XHR オブジェクトに追加で設定する key-value マップを指定します。
(例: xhrFields: { withCredentials: true }) (1.5.1)

jQuery 1.0 では、結果やエラーを受け取るコールバック関数を下記の様に記述していました。

$.ajax({
    url: "test.php",
    success: function(data, status, xhr) {
        // 通信成功時の処理
    },
    error: function(xhr, status, error) {
        // 通信失敗時の処理
    },
    complete: function(xhr, status) {
        // 通信完了時の処理
    },

jQuery 1.5 では、下記の様に変更されましたが、この記法は jQuery 1.8 で非推奨となりました。

$.ajax({
    url: "test.php"
}).success(function(data, status, xhr) {
    // 通信成功時の処理
}).error(function(xhr, status, error) {
    // 通信失敗時の処理
}).complete(function(xhr, status) {
    // 通信完了時の処理
});

jQuery 1.8 以降では下記の様に記述します。always() の引数は、status が "success" の場合は always(data, status, xhr) となりますが、"success" 以外の場合は always(xhr, status, error) となるので注意が必要です。

$.ajax({
    url: "test.php"
}).done(function(data, status, xhr) {
    // 通信成功時の処理
}).fail(function(xhr, status, error) {
    // 通信失敗時の処理
}).always(function(arg1, status, arg2) {
    // 通信完了時の処理
});

もしくは、then() を用いて下記の様に記述します。

$.ajax({
    url: "test.php"
}).then(
    function(data, status, xhr) {
        // 通信成功時の処理
    },
    function(xhr, status, error) {
        // 通信失敗時の処理
    }
);
obj.ajaxSetup(options) (1.1)

$.ajax() を呼び出す際の options の値をあらかじめ設定しておきます。

$.ajaxSetup({
    timeout: 10000,
    type: "POST"
});
$.ajax({
    url: "../getdata.php",
    data: { "id": 345 },
}).done(function(data) { ... });
obj.ajaxPrefilter([dataTypes], handler(options, origOptions, xhr)) (1.5)

$.ajax() が呼ばれる際に毎回実行されるフィルタ関数を設定します。options には $.ajaxSetup() や $.ajax() で設定されたオプションや規定値のオプションが含まれます。origOptions には $.ajax() で設定したオプションのみが含まれます。

$.ajaxPrefilter(function(options, origOptions, xhr) {
    for (var key in options) {
        $("pre#log").append(key + "=" + options[key] + "\n");
    }
});

dataTypes を指定した場合、指定したデータタイプの場合のみ、フィルタ関数が呼ばれます。

$.ajaxPrefilter("json script", function(options, origOptions, xhr) {
    :
});
obj.ajaxPrefilter(dataType, handler(options, origOptions, xhr)) (1.5)

$.ajax() が内部で呼び出す送信関数(send())、中断関数(abort())を置き換えます。$.ajaxPrefilter() や converter などよりも、より高度な処理の変更を行いたい場合に実装します。

$.ajaxTransport("text", function(options, origOptions, xhr) {
    return {
        send: function(headers, completeCallback) {
            // 送信処理
        },
        abort: function() {
            // 中断処理
        }
    };
});

Ajax(Global Ajax Event Handlers)

obj.ajaxStart(handler()) (1.0)
obj.ajaxSend(handler(event, xhr, options)) (1.0)
obj.ajaxSuccess(handler(event, xhr, options)) (1.0)
obj.ajaxError(handler(event, xhr, options, error)) (1.0)
obj.ajaxComplete(handler(event, xhr, options)) (1.0)
obj.ajaxStop(handler()) (1.0)

Ajax処理開始時(Start)、送信開始時(Send)、通信成功時(Success)、通信失敗時(Error)、通信完了時(Complete)、Ajax処理停止時(Stop)にグローバルに呼び出されるイベントハンドラを指定します。

$(document).ajaxStart(function() {
    $("#log").append("==== Start\n");
});
$(documentg).ajaxSend(function(e, xhr, options, error) {
    $("#log").append("==== Send\n");
});
$(documentg).ajaxSuccess(function(e, xhr, options) {
    $("#log").append("==== Success\n");
});
$(documentg).ajaxError(function(e, xhr, options) {
    $("#log").append("==== Error\n");
});
$(documentg).ajaxComplete(function(e, xhr, options) {
    $("#log").append("==== Complete\n");
});
$(documentg).ajaxStop(function() {
    $("#log").append("==== Stop\n");
});

Ajax(Helper Functions)

obj.serialize() (1.0)

フォームデータを単一の文字列にシリアライズします。フォームに入力された値を Ajax でサーバに引き渡す際などに有用です。

var str = $("form#form1").serialize();

例えば、下記のフォームに対して上記のスクリプトを実行したとします。

<form id="form1">
    <input type="text" name="t1" value="AAA">
    <input type="text" name="t2" value="BBB">
    <input type="text" name="t3" value="CCC">
</form>

serialize() の戻り値 str は下記の文字列が設定されます。

t1=AAA&t2=BBB&t3=CCC
obj.serializeArray() (1.2)

フォームデータを名前と値の配列で取得します。

var data = $("form#form1").serializeArray();

例えば、上記の serialize() のサンプルにあるフォームに対して serializeArray() を実行すると、下記の構造の配列が返されます。

[
    { name: "t1", value: "AAA" },
    { name: "t2", value: "BBB" },
    { name: "t3", value: "CCC" }
]
◆ $.param(obj) (1.2)
◆ $.param(obj, traditional) (1.4)

URLクエリや Ajax通信のために、オブジェクトをシリアライズ化します。

var obj = {
    a: "AAA",
    b: {
       c: "CCC"
    },
    d: [ "DD1", "DD2" ]
};

str1 = $.param(obj);                       a=AAA&b%5Bc%5D=CCC&d%5B%5D=DD1&d%5B%5D=DD2
str2 = decodeURIComponent($.param(obj));   a=AAA&b[c]=CCC&d[]=DD1&d[]=DD2

Copyright (C) 2013 杜甫々
初版:2013年2月3日
http://www.tohoho-web.com/js/jquery/ajax.htm