ホーム  >  Ajax / JavaScript / jQuery

jQuery 「Ajax」Ajaxの設定パラメータ

Ajaxでは、Webサーバとの通信を、さまざまな設定でコントロールします。jQueryのAjax機能で設定・参照が可能な各種パラメータは次のとおりです。

目次
  1. accepts（既定値：データ型による）
  2. always
  3. async（既定値：true）
  4. beforeSend（jqXHRオブジェクト,既定値オブジェクト）メソッド
  5. cache（既定値：trueただし’script’と’jsonp’データ型ではfalse）
  6. contents
  7. contentType（既定値：’application/x-www-form-urlencoded;charset=UTF-8’）
  8. context
  9. converters（既定値：{“*text”}window.String,”text html”:true,”textjson”:jQuery.parseJSON,”text xml”:jQuery.parseXML}）
  10. crossDomain（既定値：同一ドメインのリクエストはfalse、クロスドメインのリクエストはtrue）
  11. data
  12. dataFilter(data,type)関数
  13. dataType（既定値：自動判別（xml,json,script,html））
  14. done
  15. global（既定値：true）
  16. headers
  17. isLocal
  18. jsonp
  19. jsonpCallback
  20. method（既定値：GET）
  21. mimeType
  22. password
  23. processData（既定値：true）
  24. scriptAttrs
  25. scriptCharset
  26. statusCode
  27. timeout
  28. traditional
  29. type（既定値：’GET’）
  30. url（既定値：現在のページ）
  31. username
  32. xhr関数
  33. xhrFields

accepts（既定値：データ型による）

返り値としてどのような型を受け入れるかをWebサーバに伝えるために、データ型名とMIMEタイプのkey/valueペアをオブジェクトとして指定します。ここで指定するデータ型は、後述するconvertersパラメータにも定義しておく必要があります。

always

リクエスト成功、失敗にかかわらず実行される処理です。jQuery1.8からcomplete関数が非推奨となり、jQuery3.0で廃止されました。代わりにjQuery1.5から追加されたalways関数を使用する必要があります。

async（既定値：true）

非同期通信スィッチです。このスィッチがtrueの場合、Webサーバとの通信は非同期で行われます。同期通信を行う場合はfalseを指定する必要があり、その際は通信が完了するまでブラウザの操作はできなくなります。また、クロスドメインのリクエストと「jsonp」データ型のリクエストは同期通信をサポートしません。jQuery1.8以降では、.success()、.error()、.complete()の各メソッドは、それぞれ.done()、.fail()、.always()に置き換えるか、$.Deferredを用いた書き方に変更することになりました。

beforeSend（jqXHRオブジェクト,既定値オブジェクト）メソッド

jQuery1.5から、$.ajax()は従来のXMLHTTPRequestオブジェクトを拡張した「jqXHR」オブジェクトを返すようになりました。beforeSend()はサーバにリクエストを送信する前に実行されるメソッドですが、このメソッドの引数もjqXHRオブジェクトに変更されています。このメソッドの戻り値としてfalseを返すと、リクエストの送信はキャンセルされます。

$.ajax({
  url: "test.html";
  type: 'get',
  beforeSend: function(){
    var date = new Date();
    if(date.getDay() === 0){
      //日曜日に実行した場合はログを出力して処理を行わない
      console.log('日曜日は定休日です。');
      return false;
    }
  }
}).then(function(){
  console.log('処理完了');
});

cache（既定値：trueただし’script’と’jsonp’データ型ではfalse）

通信結果をキャッシュするかどうかのスィッチです。既定値はtrueですが、データタイプがscriptまたはjsonpの場合はfalseにセットされます。なお、falseが正しく効くのは、HEADとGETリクエストの場合だけです。

contents

レスポンスデータの形式がここで指定した形式（正規表現）と一致した場合、以後その形式としてデータを処理します。

$.ajax({
  url: "target.csv";
  contents:{"csv": /csv/}
}).then(function(response){
 //response内のデータはCSVデータとして処理されます。
});

contentType（既定値：’application/x-www-form-urlencoded;charset=UTF-8’）

サーバーへのデータ送信時にcontent-typeヘッダとして使用するMIMEタイプの値です。

context

Ajax関連のコールバックが対象とする、ドキュメントの「範囲」を指定します。例えば、次の例では、リクエスト成功時のコールバック内で、$(this)がdocument.bodyを支援すことになります。

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

converters（既定値：{“*text”}window.String,”text html”:true,”textjson”:jQuery.parseJSON,”text xml”:jQuery.parseXML}）

dataType関数で指定したタイプに対する独自パーサが定義できます。これによりデフォルトで処理できないMIMEタイプデータを受け取った場合でも、独自のパーサを作成した上で処理を行い、結果をdoneメソッドに渡せます。

$.ajax({
  url: "test.json";
  dataType: "json customConversion",
  converters:{
    console.log("do custom conversion.");
    //ここで独自のパーサを構築し処理を行う
    converted_data = …
    return converted_data;
  }
}).then(function(response){
 //パースしたデータを元に処理を行う
 console.log(response);
});

crossDomain（既定値：同一ドメインのリクエストはfalse、クロスドメインのリクエストはtrue）

同じドメイン上で他のドメインへリダイレクトを行いたい時などに強制的にクロスドメインリクエストを行いたい場合はtrueに設定します。

$.ajax({
  crossDomein: true
});

data

サーバに送信するデータを、オブジェクトまたは文字列（QUERY_STRING）で指定します。

dataFilter(data,type)関数

サーバから返されるデータを処理するフィルタ関数。データ中のメタ文字を除去したり、HTMLタグを文字実体参照に変換したりといった操作を行うのに便利です。

dataType（既定値：自動判別（xml,json,script,html））

サーバから返されるデータの形式を指定します。指定がない場合、jQueryは結果から自動判別を試みます。有効なデータタイプは次のとおりです。

  • “xml”・・・XMLドキュメント
  • “html”・・・HTMLドキュメント
  • “script”・・・JavaScript
  • “json”・・・JSON（JavaScript Object Notation）フォーマットのデータ
  • “jsonp”・・・jsonp(JSON with padding)フォーマットのデータ
  • “text”・・・テキスト

上記以外の場合、独自のパーサを組み込むことで対応が可能です（converters関数参照）。

※jQuery1.5から半角スペースで区切ることによってそれぞれの変換処理の順番を指定できるようになりました。例えば”text xml”と指定した場合は、レスポンスデータがテキストの場合、XMLデータとして処理を行います。また、”jsonp text xml”の場合、JSONPデータをまずテキストデータとして取得し、XMLデータとして処理を行います。この時に”jsonp xml”と指定した場合、まずJSONPデータをXMLデータへ変換し、もし失敗した場合はテキストデータとして中間処理を行った上で再度XMLデータとして処理を行います。

done

リクエスト成功時に実行されるコールバック関数です。

※jQuery1.8からsuccess関数が非推奨となり、jQuery3.0で廃止されました。代わりにv1.5で追加されたdone関数を使用する必要があります。例えばcontext関数にて記載した例は次のように記述することもできます。

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

global（既定値：true）

Ajaxグローバルイベントを実行するかどうかのスィッチです。ajaxStartイベントやajaxStopイベントに対してイベントハンドラを実行させたくない場合はfalseに設定します。

headers

追加で送信したいヘッダをオブジェクトとして渡します。ヘッダの値はbeforeSend()メソッドで上書きすることもできます。

$.ajax({
  headers: {
    "X-Sample-Header": "test"
  }
});

isLocal

処理を強制的に「ローカル」と認識させるためのスィッチです。デフォルトでは、プロトコルが「file」「*-extension」「widget」のいずれかのときはローカルとして扱われますが、これを変更したい場合は$.ajaxSetup()でisLocalの値を変更します。

jsonp

jsonpリクエストのコールバック名が「callback」ではない場合に、別のコールバック名を指定します。例えば、{jsonp:’onJsonPLoad’}と指定すると、サーバへのリクエストに’onJsonPLoad=?’が付加されます。

jsonpCallback

jsonpリクエストのコールバック関数名を指定します。

method（既定値：GET）

「POST」「GET」「PUT」など、HTTPリクエストに利用されるメソッドを指定します。

mimeType

XHR MIMEタイプを変更する際に指定します。

password

HTTP通信で認証が必要な場合にパスワードを指定します。

processData（既定値：true）

dataに指定した、サーバへ送信データを、QUERY_STRINGに変換するかどうかのスィッチです。

scriptAttrs

「script」または「jsonp」のリクエストの際に追加のアトリビュートをオブジェクトとして定義します。例えば、Content Security Policy（CSP）の要求を満たすために「nonce」「integrity」「crossorigin」といったアトリビュートを設定する際に利用します。

scriptCharset

dataTypeがjsonpまたはscriptの場合に、ブラウザ上のページとサーバ側のキャラクタセットが異なる場合に指定します。scriptの場合には、scriptAttrsでcharsetを指定することでも代替できます。

statusCode

HTTPステータスコードに応じた処理を記述できます。例えば次の例では、404（NotFound）のときにアラートダイアログを表示します。

$.ajax({
  statusCode: {
    404: function(){
      alert( "ページがみつかりません" );
    }
  }
});

timeout

サーバとの通信のタイムアウト時間をミリ秒単位で指定します。

traditional

古い変換方式でパラメータ変換したい場合はtrueを指定します。

type（既定値：’GET’）

methodの別名で、jQuery1.9.0以前のバージョンとの互換性のために残っています。

url（既定値：現在のページ）

リクエスト送信先のURLです。

username

HTTP通信で認証が必要な場合に、ユーザ名を指定します。

xhr関数

jqXHRオブジェクトが作成されたときに実行されるコールバック関数です。

xhrFields

XHRオブジェクトに設定するパラメータをオブジェクトとして渡します。

$.ajax({
  xhrFields: {
   withCredentials: true
  }
});

カテゴリー:Ajax​JavaScript​jQuery