jQuery AJAX - ajax() メソッド

jQuery Ajax 参考書

例

AJAXでテキストをロードします：

jQueryコード：

$("document").ready(function(){
  $("#b01").click(function(){
  htmlobj=$.ajax({url:"/jquery/test1.txt",async:false});
  $("#myDiv").html(htmlobj.responseText);
  });
});

HTMLコード：

<div id="myDiv"><h2>Ajaxでこのテキストを変更</h2></div>
<button id="b01" type="button">コンテンツを変更</button>

実際に試してみてください

定義と使用法

ajax()メソッドはHTTPリクエストを通じてリモートデータをロードします。

これはjQueryのベースレベルのAJAX実装です。簡単で使いやすい高レベルの実装は$.get、$.postなどです。$.ajax()は生成したXMLHttpRequestオブジェクトを返します。ほとんどの場合、この関数を直接操作する必要はありませんが、より多くの柔軟性が必要な場合、不常用のオプションを操作する必要があります。

最もシンプルな場合、$.ajax()はパラメータなしで直接使用できます。

注意：すべてのオプションは$.ajaxSetup()関数を使用してグローバルに設定できます。

文法

jQuery.ajax([settings]
パラメータ 説明
settings

オプション。Ajaxリクエストを構成するキーワードの集合。

$.ajaxSetup()を使用して、任意のオプションのデフォルト値を設定できます。

パラメータ

options

タイプ：Object

オプション。AJAXリクエストの設定。すべてのオプションはオプションです。

async

タイプ：Boolean

デフォルト値: true。デフォルト設定では、すべてのリクエストが非同期リクエストです。同期リクエストを送信する必要がある場合は、このオプションをfalseに設定してください。

注意、同期リクエストはブラウザをロックし、ユーザーの他の操作はリクエストが完了するまで実行できません。

beforeSend(XHR)

タイプ：Function

リクエストを送信する前に、XMLHttpRequestオブジェクトを変更する関数（カスタムHTTPヘッダを追加するなど）を呼び出すことができます。

XMLHttpRequestオブジェクトがユニークなパラメータです。

これはAjaxイベントです。falseを返すと、このajaxリクエストをキャンセルできます。

キャッシュ

タイプ：Boolean

デフォルト値: true、dataTypeがscriptおよびjsonpの場合デフォルトでfalseです。falseに設定すると、このページはキャッシュされません。

jQuery 1.2の新機能。

complete(XHR, TS)

タイプ：Function

リクエストが完了した後に呼び出されるコールバック関数（リクエストが成功したかどうかにかかわらず呼び出されます）。

パラメータ：XMLHttpRequestオブジェクトとリクエストタイプを説明する文字列です。

これは Ajax イベントです。

contentType

タイプ：String

デフォルト値: "application/x-www-form-urlencoded"。サーバーに情報を送信する際の内容エンコードタイプです。

デフォルト値は大多数のケースに適しています。$.ajax()に明示的にcontent-typeを渡した場合、それは必ずサーバーに送信されます（データが送信されない場合でも）。

context

タイプ：Object

このオブジェクトはAjax関連のコールバック関数の上下文を設定するために使用されます。つまり、コールバック関数内のthisをこのオブジェクトに指すようにします（このパラメータを設定しない場合、thisはAJAXリクエストを呼び出す際に渡されたoptionsパラメータを指します）。例えば、DOM要素をcontextパラメータとして指定すると、successコールバック関数の上下文がこのDOM要素に設定されます。

こんな感じで：

$.ajax({ url: "test.html", context: document.body, success: function(){
        $(this).addClass("done");
      });
data

タイプ：String

サーバーに送信されるデータです。自動的にリクエスト文字列形式に変換されます。GETリクエストではURLの後ろに付加されます。processDataオプションの説明を確認して、この自動変換を無効にすることができます。Key/Value形式でなければなりません。配列の場合、jQueryは同じ名前で異なる値に対応します。例えば、{foo:["bar1", "bar2"]}は'&foo=bar1&foo=bar2'に変換されます。

dataFilter

タイプ：Function

Ajaxが返す原始データを事前処理する関数です。dataとtypeの2つのパラメータを提供します：dataはAjaxが返す原始データ、typeはjQuery.ajaxを呼び出す際に提供されたdataTypeパラメータです。関数が返す値はjQueryによってさらに処理されます。

dataType

タイプ：String

サーバーが返すデータのタイプを予測します。指定しない場合、jQueryはHTTPパケットMIME情報に基づいて自動的に判断します。例えば、XML MIMEタイプはXMLとして認識されます。1.4では、JSONはJavaScriptオブジェクトを生成し、scriptはこのスクリプトを実行します。その後、サーバーから返されるデータはこの値に基づいて解析され、コールバック関数に渡されます。利用可能な値:

  • "xml": XMLドキュメントを返す。jQueryで処理可能。
  • "html": 純テキストHTML情報を返す；含まれるscriptタグはDOMに挿入されたときに実行される。
  • "script": 純テキストJavaScriptコードを返す。結果は自動的にキャッシュされない。"cache"パラメータが設定されていない場合に限る。注意：リモートリクエスト（同じドメインではない場合）では、すべてのPOSTリクエストがGETリクエストに変換される（DOMのscriptタグを使用して読み込むためである）。
  • "json": JSONデータを返す。
  • "jsonp": JSONP形式。"myurl?callback=?"のようなJSONP形式で関数を呼び出す場合、jQueryは自動的に?を正しい関数名に置き換え、コールバック関数を実行する。
  • "text": 純テキスト文字列を返す
error

タイプ：Function

デフォルト値: 自動判断（xmlまたはhtml）。リクエストが失敗したときにこの関数を呼び出す。

以下の3つのパラメータを持つ：XMLHttpRequestオブジェクト、エラーメッセージ、（オプション）キャッチした例外オブジェクト。

エラーが発生した場合、エラーメッセージ（第2引数）はnull以外にも「timeout」、「error」、「notmodified」、「parsererror」の可能性がある。

これは Ajax イベントです。

global

タイプ：Boolean

グローバルAJAXイベントをトリガーするかどうか。デフォルト値: true。falseに設定すると、グローバルAJAXイベント（例えばajaxStartやajaxStop）はトリガーされない。

ifModified

タイプ：Boolean

サーバー側のデータが変更されたときに新しいデータを取得する。デフォルト値: false。HTTPパケットのLast-Modifiedヘッダ情報を使って判断。jQuery 1.4では、データが変更されていないかを確認するためにサーバーが指定した'etag'もチェックする。

jsonp

タイプ：String

JSONPリクエストでコールバック関数の名前を書き換える。この値は「callback=?」のようなGETまたはPOSTリクエストのURLパラメータの「callback」部分に代わりに使用される。例えば{jsonp:'onJsonPLoad'}は「onJsonPLoad=?」をサーバーに送信する。

jsonpCallback

タイプ：String

jsonp リクエストにコールバック関数名を指定します。この値は jQuery が自動的に生成するランダムな関数名に置き換わります。これは jQuery がユニークな関数名を生成し、リクエストの管理を容易にし、コールバック関数とエラーハンドリングを簡単にするためのものです。また、GET リクエストをブラウザがキャッシュするようにしたい場合にも使用できます。

password

タイプ：String

HTTP アクセス認証リクエストに応答するパスワード

processData

タイプ：Boolean

デフォルト値: true。デフォルトでは、data オプションを通じて渡されるデータがオブジェクト（技術的には文字列でない場合）であれば、デフォルトのコンテンツタイプ "application/x-www-form-urlencoded" に対応するクエリ文字列に変換されます。DOM ツリー情報や他の変換を望まない情報を送信する場合は false に設定してください。

scriptCharset

タイプ：String

dataType パラメータが "jsonp" または "script" で、type が "GET" の場合のみ、強制的に charset を変更します。通常、ローカルとリモートの内容エンコーディングが異なる場合に使用されます。

success

タイプ：Function

リクエスト成功後のコールバック関数。

パラメータ: サーバーから返され、dataType パラメータに基づいて処理されたデータ；状態を説明する文字列。

これは Ajax イベントです。

traditional

タイプ：Boolean

データをシリアライズする伝統的な方法を使用したい場合は true に設定してください。jQuery.param メソッドのツールカテゴリを参照してください。

timeout

タイプ：Number

リクエストのタイムアウト時間（ミリ秒）を設定します。この設定はグローバル設定をオーバーライドします。

type

タイプ：String

デフォルト値: "GET")。リクエスト方法 ("POST" または "GET")、デフォルトでは "GET" です。注意: PUT または DELETE などの他の HTTP リクエストメソッドも使用できますが、一部のブラウザのみがサポートしています。

url

タイプ：String

デフォルト値: 現在のページのアドレス。リクエストを送信するアドレスです。

username

タイプ：String

HTTP アクセス認証リクエストに応答するユーザー名を用います。

xhr

タイプ：Function

XMLHttpRequest オブジェクトを返す必要があります。デフォルトでは IE では ActiveXObject で、他の環境では XMLHttpRequest です。XMLHttpRequest オブジェクトを書き換えたり、拡張するために使用されます。このパラメータは jQuery 1.3以前では利用できません。

コールバック関数

$.ajax() で得たデータを処理するには、beforeSend、error、dataFilter、success、complete コールバック関数を使用する必要があります。

beforeSend

リクエストを送信する前に呼び出されます。XMLHttpRequest をパラメータとして渡します。

error

リクエストがエラーになったときに呼び出されます。XMLHttpRequest オブジェクト、エラータイプを説明する文字列、および例外オブジェクト（あれば）を渡します。

dataFilter

リクエストが成功した後に呼び出されます。返されたデータと "dataType" パラメータの値を渡し、新しいデータ（処理された可能性があります）を success コールバック関数に渡さなければなりません。

success

リクエストの後に呼び出されます。返されたデータと成功コードを含む文字列を渡します。

complete

リクエストが完了した後にこの関数を呼び出します。成功または失敗に関わらず、XMLHttpRequest オブジェクトと成功またはエラーコードを含む文字列を渡します。

データタイプ

$.ajax() 関数はサーバーが提供する情報に依存してデータを処理します。サーバーが返されるデータが XML と報告した場合、返される結果は通常の XML メソッドまたは jQuery のセレクタで遍历できます。他のタイプ、例えば HTML が見つかった場合、データはテキスト形式で扱われます。

dataType オプションを使用して、他の異なるデータ処理方法を指定できます。単なる XML だけでなく、html、json、jsonp、script、または text を指定できます。

text と xml タイプのデータは処理されません。データは単に XMLHttpRequest の responseText または responseHTML 属性が success コールバック関数に渡されます。

注意：ウェブサーバーが報告する MIME タイプは、選択した dataType と一致する必要があります。例えば、XMLの場合、サーバー側は text/xml または application/xml を宣言して一貫した結果を得ることができます。

HTML タイプが指定された場合、内嵌された JavaScript は HTML が文字列として返される前に実行されます。同様に、script タイプが指定された場合、サーバー側で生成された JavaScript が先に実行され、その後、スクリプトがテキストデータとして返されます。

json タイプが指定された場合、取得したデータを JavaScript オブジェクトとして解析し、構築したオブジェクトを結果として返します。この目的を実現するために、まず JSON.parse() を使用します。ブラウザがサポートしない場合、関数を使用して構築します。

JSON データは、JavaScript で簡単に構造化データを解析できる形式です。データファイルがリモートサーバー上に保存されている場合（ドメインが異なるため、クロスドメインからのデータ取得）、jsonp タイプを使用する必要があります。このタイプを使用すると、callback=? というクエリ文字列パラメータがリクエストの URL の後に追加されます。サーバーサイドは、有効な JSONP リクエストを完了するために、JSON データの前にコールバック関数名を追加する必要があります。デフォルトの callback に代わるコールバック関数のパラメータ名を指定するには、$.ajax() の jsonp パラメータを設定できます。

注意：JSONP は JSON フォーマットの拡張です。これは、サーバーサイドのコードがクエリ文字列パラメータを検出し処理する必要があります。

script や jsonp タイプが指定された場合、サーバーからデータを受信する際には、実際には <script> タグではなく XMLHttpRequest オブジェクトを使用します。この場合、$.ajax() は XMLHttpRequest オブジェクトを返さず、beforeSend などのイベントハンドラを渡しません。

データをサーバーに送信する

デフォルトでは、Ajax リクエストは GET メソッドを使用します。POST メソッドを使用する場合は、type パラメータの値を設定できます。このオプションは、data オプションの内容がサーバーにどのように送信されるかにも影響します。

data オプションは、例えば key1=value1&key2=value2 などのクエリ文字列を含むことができます。また、{key1: 'value1', key2: 'value2'} などのマッピングもできます。後者の形式を使用した場合、データは送信器でクエリ文字列に変換されます。この処理プロセスは、processData オプションを false に設定することで回避できます。XML オブジェクトをサーバーに送信する場合、この処理は適切ではありません。この場合、contentType オプションの値も変更し、デフォルトの application/x-www-form-urlencoded に代わる適切な MIME タイプを使用する必要があります。

高度なオプション

global オプションは、.ajaxSend や ajaxError などの応答登録されたコールバック関数をブロックするために使用されます。これはリクエストが非常に頻繁で短い場合などに非常に有用で、ajaxSend 内でこの機能を無効にすることができます。

サーバーが HTTP 認証が必要な場合、username と password オプションを通じてユーザー名とパスワードを設定できます。

Ajax リクエストは時間制限がありますので、エラーワーニングがキャッチされ处理后、ユーザーエクスペリエンスを向上させるために使用できます。タイムアウトのパラメータは通常デフォルト値をそのままにしておいたり、jQuery.ajaxSetup を通じてグローバルに設定することが多く、特定のリクエストに timeout オプションを再設定することは稀です。

デフォルトでは、リクエストは常に送信されますが、ブラウザがキャッシュからデータを取得することがあります。キャッシュの結果を使用しないようにするには、cache パラメータを false に設定します。データが前回のリクエストから変更されていない場合にエラーを報告するように設定するには、ifModified を true に設定します。

scriptCharset は、<script> タグのリクエストに特定の文字セットを設定し、script や jsonp などのデータに使用されます。スクリプトとページの文字セットが異なる場合に特に便利です。

Ajax の最初の文字は asynchronous の頭文字で、これはすべての操作が並行であり、完了の順序に前後関係がないことを意味します。$.ajax() の async パラメータは常に true に設定されていますが、これはリクエストが開始された後でも他のコードが実行できることを示しています。このオプションを false に設定することは強く推奨されません。これはすべてのリクエストが非同期でないことを意味し、ブラウザがロックされる原因となります。

$.ajax 関数は、作成した XMLHttpRequest オブジェクトを返します。通常 jQuery は内部で処理し、このオブジェクトを作成しますが、ユーザーは xhr オプションを通じて自分で作成した xhr オブジェクトを渡すこともできます。返されたオブジェクトは通常捨てられますが、リクエストを観察および操作するためのベースレベルのインターフェースを提供します。例えば、オブジェクト上の .abort() を呼び出すことで、リクエストが完了する前にリクエストを一時停止できます。

jQuery Ajax 参考書