jQuery逆引きリファレンス
一般的なAjax通信を実装するには？（$.ajax）
非同期通信の動作をより細かく制御したい場面で使える$.ajaxメソッドの構文と利用可能なパラメーター群の概要を紹介。簡単なサンプルで使い方を説明する。
jQueryでAjax通信の基本的な機能を担うのは、$.ajaxメソッドです。本連載では、すでにload、$.get、$.post、$.getJSONなどのメソッドを紹介してきましたが、これらのメソッドも内部的には$.ajaxメソッドを利用しています。つまり、load、$.get、$.post、$.getJSONといったメソッドは、「$.ajaxメソッドの簡易構文」といえます。
一般的には、それで賄えるならば簡易構文を優先して利用すれば十分です。しかし、非同期通信の動作をより細かく制御したいという状況では、$.ajaxメソッドを、という使い分けになることでしょう*1。
$.ajaxメソッドの構文は、以下の通りです。
［構文］$.ajaxメソッド
$.ajax(url [,settings])
- url： アクセス先のパス
- settings： 通信時の設定パラメーター（「パラメーター名: 値」のハッシュ）
- *1 ただし、jQuery 1.12／2.2以降では、
$.get／$.postメソッドにも第2引数としてsettings（設定パラメーター）を渡せるようになりました。
引数settingsで利用可能なパラメーターには、以下のようなものがあります。
| 分類 | パラメーター名 | 概要 |
|---|---|---|
| 基本 | type | 通信に利用するHTTPメソッド（デフォルトはGET） |
| dataType | 応答データの種類（text、html、xml、json、jsonp、script） | |
| data | 送信するデータ（「キー名: 値」のハッシュ形式） | |
| headers | リクエスト時に送信するヘッダー（「ヘッダー名: 値」のハッシュ形式） | |
| コールバック | beforeSend | リクエスト送信前に実行されるコールバック関数 |
| converters | dataTypeオプション単位のコンバーター（「dataType値: コンバーター」のハッシュ形式）。デフォルトは「{"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML}」 |
|
| dataFilter | レスポンスデータを処理するためのコールバック関数 | |
| 設定 | accepts | 期待する応答のデータ型 |
| cache | 通信結果をキャッシュするか。デフォルトはtrue（ただし、dataType="script"/"jsonp"の場合はfalse） |
|
| contentType | リクエスト時に利用するContent-Typeヘッダー（デフォルトはapplication/x-www-form-urlencoded; charset=UTF-8） | |
| context | コールバック関数のコンテキスト | |
| crossDomain | クロスドメインのリクエストか | |
| global | $.ajaxXxxxxイベントを処理するか（デフォルトはtrue） |
|
| ifModified | trueの場合、応答に変更がある場合にだけ成功ステータスを返す（デフォルトはfalse） | |
| jsonp | JSONPリクエストのコールバック関数名 | |
| processData | dataパラメーターの内容をクエリ情報に変換するか（デフォルトはtrue） |
|
| scriptCharset | スクリプトを読み込む際に利用する文字コード（例："UTF-8"など）（dataType=が"script"や"jsonp"などの場合のみ使用できる） |
|
| timeout | タイムアウト時間 | |
| xhrFields | ネイティブなXMLHttpRequestオブジェクトに設定するフィールド値（「フィールド名: 値」のハッシュ形式） |
|
| 認証 | username | 認証時に利用するユーザー名 |
| password | 認証時に利用するパスワード |
以下では、$.ajaxメソッドの基本的な例として、別稿「TIPS：HTTP GET／POSTで非同期通信を実施するには？」のサンプルを、$.ajaxメソッドを使って書き換えてみましょう。
|
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>jQuery TIPS</title>
</head>
<body>
<form>
<div>
<label for="keyword">キーワード：</label>
<input id="keyword" type="text" size="20" />
<input id="search" type="button" value="検索" />
</div>
<ul id="result" class="ajax"></ul>
</form>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.1/jquery.min.js"></script>
<script>
$(function() {
// ［検索］ボタンクリックで検索開始
$('#search').click(function() {
// .phpファイルへのアクセス
$.ajax('get.php',
{
type: 'get',
data: { query: $('#keyword').val() },
dataType: 'xml'
}
)
// 検索成功時にはページに結果を反映
.done(function(data) {
// 結果リストをクリア
$('#result').empty();
// <Question>要素（個々の質問情報）を順番に処理
$('Question', data).each(function() {
// <Url>（詳細ページ）、<Content>（質問本文）を基にリンクリストを生成
$('#result').append(
$('<li></li>').append(
$('<a></a>')
.attr({
href: $('Url', this).text(),
target: '_blank'
})
.text($('Content', this).text().substring(0, 255) + '...')
)
);
});
})
// 検索失敗時には、その旨をダイアログ表示
.fail(function() {
window.alert('正しい結果を得られませんでした。');
});
});
});
</script>
</body>
</html>
|
※このコードを試す際には、キーワード入力後にEnterキーではなく［検索］ボタンクリックをする必要があるので注意すること。
コードの詳細な解説については別稿を参照いただくとして、本稿で注目すべきは太字の箇所です。この例では、
HTTP GET（
typeパラメーター）でget.phpに対して、「query=テキストボックスの入力値」（dataパラメーター）というクエリ情報を渡すこと、
戻り値としてxml文書を期待すること（dataTypeパラメーター）
を指定して、Ajax通信を実施しています。成功／失敗時の処理にdone／failメソッドを利用する点は$.getメソッドと変わりありません。
本稿では、まずは基本的なパラメーターだけを利用しましたが、その他のパラメーターについても、後日別稿で個別に解説していく予定です。
API：jQuery.ajax() カテゴリ：Ajax > Low-Level Interface（低レベルインターフェース）
※以下では、本稿の前後を合わせて5回分（第57回～第61回）のみ表示しています。
連載の全タイトルを参照するには、［この記事の連載 INDEX］を参照してください。
57. 既存の要素をコピーするには？ ― cloneメソッド
既存の要素をjQueryオブジェクトとして複製する方法を説明。オブジェクトはappendToなどの挿入系メソッドを使ってHTMLソース内に要素として追加したりできる。
59. 【現在、表示中】≫ 一般的なAjax通信を実装するには？（$.ajax）
非同期通信の動作をより細かく制御したい場面で使える$.ajaxメソッドの構文と利用可能なパラメーター群の概要を紹介。簡単なサンプルで使い方を説明する。
60. 非同期通信のキャッシュを無効化するには？（$.ajax［cache］）
Ajax通信の結果をキャッシュするか否かを制御できる「$.ajaxメソッドのcacheパラメーター」の基本的な使い方を説明する。
61. Ajax通信の前に処理を実行するには？（$.ajax［beforeSend］）
Ajax通信を送信する前に任意の処理を実行できるようになる「$.ajaxメソッドのbeforeSendパラメーター」の基本的な使い方を説明する。
