jquery jQuery の load()

2013年11月22日

jQuery の load() の基本的な使い方に関するメモ。

基本的な使い方

Ajax 利用時の制限

  • 文字コードは、原則として「UTF-8 」を使用。(他の文字コードを使うと文字化けする)
  • Ajax ではセキュリティ上の理由から、HTML と同一ドメイン上にあるファイルしか取得できない。

ページにテキスト(ファイル)を挿入する

load() は引数に読み込むファイルを指定すると、セレクタで指定した要素内のテキストを書き換える。

書式
$(セレクタ).load(テキストファイル名)

ボタンをクリックすると p 要素の内容を「foo.txt 」の内容で書き換える例

$("button").click(function(){
      $("p").load("foo.txt");
    })

外部の HTML を表示する

load() に単純に HTML ファイルを指定すると HTML ファイルの冒頭から末尾(DOCTYPE から </html>)を取り込んでしまう。 HTML の場合、 ファイル名の後ろに セレクタを追加することで、読み込む場所を絞り込める。

//foo.html の #bar の中の p 要素を div 要素に読み込む

$("div").load("../../foo.html #bar p");

load()

サーバーから(html)コンテンツを取得して DOM に挿入する。

  • 指定の URL(jQuery セレクタを指定可能)に向けて、Ajax 要求の発行を開始する。
  • 要求が完了して DOM の書き換えが終了したとき呼び出されるコールバック関数を指定できる。
  • マッチした要素全ての内容が、応答テキスト(取得したデータ)で置き換えられる。

書式

load(url, parameters, callback)

パラメータと戻り値

url (String)
要求を送信するサーバ側リソース(読む込むデータ)のURL。
オプションとして jQuery セレクタを使える 。
parameters (String|Object|Array) 
オプション。
リクエストと一緒に送信するデータ(要求のパラメータとして渡すべきデータ)を指定。
データ型は、文字列、 オブジェクト、オブジェクトの配列のいずれか。
文字列はそのままクエリ文字列として使用される。
オブジェクトは、プロパティがシリアライズされ、 適切にエンコードされたパラメータとして要求に渡される。
オブジェクトの配列は、その nameプロパティと valueプロパティで、名前と値のペアを 指定。
オブジェクトまたは配列で指定した場合、要求には POST メソッドが使用される。
省略した場合と、文字列で指定した場合は、GET メソッドが使われる。
callback (Function) 
オプション。
応答データ(取得したデータ)がロードされた後に呼び出されるコールバック関数。
この関数に渡されるパラメータは、
・response:応答テキスト(取得したデータ)、
・status:ステータス文字列(success、 error、notmodified、timeout、parsererror)、
・xhr:XMLHttpRequest インスタンス。
この関数はマッチしている各要素それぞれで呼び出され、ターゲットの要素集合(それぞれの DOM 要素)が関数のコンテクスト(this)になる。
$('#some_id').load('xyz.html div#id', function(response, status, xhr) {  
  処理      
});
戻り値
ラップ集合

GET 要求でパラメータを渡す場合、URL ににクエリ文字列として含めることができるが、文字列を正しくフォーマットし、要求パラメータの名前と値を URI エンコーディングしておく必要がある。これには JavaScript の encodeURICompnent()メソッドや、jQuery の $.param() ユーティリティ関数が利用できる。

セレクタを指定するには、URLの後に、1個のスペースに続けてセレクタを書く。例えば、応答要素(取得するデータ)にフィルタをかけて div インスタンスだけを注入したい場合は、次のように書く。

$('.injectMe').load('en/schedule.html div');

サンプル

以下の様な HTML で、リストの a 要素をクリックすると、指定した URL の「div#toBeLoaded」を「div#main」に読み込む場合。

<div id="main"> 
<!-- ここに読み込む -->
</div><!-- end of #main -->

<div id="side">
<ul id="activity">
  <li><a href="schedule.html" >ツアー2013</a></li>
  <li><a href="archives/schedule_2012.html" >ツアー2012</a></li>
  <li><a href="archives/schedule_2011.html" >ツアー2011</a></li>
  <li><a href="archives/schedule_2010.html" >ツアー2010</a></li>
</ul>
</div><!--end of #side-->

読み込み先の HTML の例(archives/schedule_2012.html)

<div id="main" class="shcedulejp">  
<div id="toBeLoaded"> 
 <h2>ツアー2012</h2>
 ・・・省略・・・
 </div><!--end of #toBeLoaded-->
</div><!--end of #main-->

jQuery

jQuery(function($){
  $('#activity li a').click(function() {
    var href = $(this).attr('href');
    $('#main').load(href + ' #toBeLoaded');
    return false;
  });  
});

読み込み先の URL を変数 href に格納。
「ツアー2012」のリンクをクリックした場合は以下が実行される。

$(‘#main’).load(‘archives/schedule_2012.html #toBeLoaded’);

以下は読み込み先の URL を変数には格納せず直接指定。また読み込んだ要素は一旦非表示にしてその後「fadeIn()」で表示する例。

jQuery(function($){
  $('#activity li a').click(function() {
    $('#main').load($(this).attr('href')+ ' #toBeLoaded').css('display','none').fadeIn('slow');
    return false;
  });  
});

もしロードした部分に別のファイルで定義した関数などがある場合、その関数の定義されているファイル(または関数自体)をロードしないとその関数は機能しないので、コールバック関数で $.getScript() を使って読み込むともできる。

$('.someClass').load('div.someDiv',function(){
  //$.getScript でスクリプトを読み込む
  $.getScript('../../js/someScript.js');
});

または、その関数を「on」を使って定義できれば、再度読み込まなくてもすむ。

「on」を使えば後から追加した要素に対してもイベントを設定可能。

$(document).on('click', 'a.someClass', function() {
    処理を記述    
  });

$.getScript()

$.getScript(url,callback)
urlパラメータで指定されたスクリプトを取得する。これには指定のサーバへのGET要求を使う。オプションとして成功時にコールバックを 呼び出す。

パラメータ

url (String)
取得するスクリプトのURL。このURLは、ページと同じドメインに制限されない。
callback (Function)
オプションのコールバック関数。
スクリプトのリソースがロードされ、評価された後に呼び出される。
パラメータはロードされたテキストと、テキストステータスメッセージ(成功すれば”success”)。
戻り値
スクリプトの取得に使用したXMLHttpRequestインスタンス。

 
この関数は、jQueryに組み込まれている Ajax 機構を使ってスクリプトファイルをロードしている。

$.param()

form 要素やオブジェクトの値を、URLクエリ文字列の形式でシリアライズする。

$.param(params,traditional)
渡された情報を、要求を送信するクエリ文字列として使うのに適した文字列にシリアライズする。渡される値は、フォーム要素の配列、 jQuery のラップ集合、JavaScript オブジェクトのいずれか。クエリ文字列は適切に整形され、文字列に含まれる個々の名前と値は 適切に URI エンコーディングされる。

パラメータ

params (Array|jQuery|Object)
 クエリ文字列にシリアライズするパラメータ。要素の配列か、jQuery のラップ集合が渡されたら、それに含まれるフォーム要素によって表現される名前と値のペアがクエリ文字列に追加される。JavaScript オブジェクトが渡されたら、そのプロパティがパラメータの名前と値になる。
traditional (Boolean)
オプションのフラグ。jQuery1.4よりも前に使われていたのと同じアルゴリズムを強制的に使ってシリアライズ する。この影響を受けるのは、一般にオブジェクトをネストしたソースオブジェクトのみ。もし省略されたら、デフォルトの falseになる。
戻り値
整形されたクエリ文字列。

 

var string = $.param({
      'foo': 'it&s=value',
      'bar': '!@#$%^&*()_+='
});

//string は foo=it%26s%3Dvalue&bar=!%40%23%24%25%5E%26*()_%2B%3D

& のクエリ文字は「%26」

var string = $.param({
      'foo': '&'
});

//string は foo=%26

XML データを取得・加工して表示する

テキストファイルや HTML ファイルは、読み込んだ内容をそのまま表示すればよいが、XML ファイルは取得した内容を加工しないと HTML としてブラウザに 表示できない。 XML の取得・加工には $.ajax() というユーティリティ関数が使える。

XML の取得・加工のための $.ajax() ユーティリティ関数の書式

$.ajax({
      url: '取得する XML ファイル',
      dataType: 'xml',
      //データの取得に成功したときに実行するコールバック
      success : function(data) {  
         //取得したファイルに対する処理  
         //data: 取得した XML の内容
      }
    })

$.ajax()

$.ajax(url,options)
渡されたオプションを使ってAjax要求を開始する。オプションは、要求発行とコールバック通知を制御する。

パラメータ

url (String)
要求のURL。
options (Object)
プロパティによって処理のパラメータを定義するオブジェクト。
戻り値
XHRインスタンス
$.ajax()ユーティリティ関数のオプションの一部
名前 説明
type (String)使用するHTTPメソッド。通常はPOSTまたはGET。省略時のデフォルトはGET。
data (String|Object|Array)要求に渡すクエリパラメータの役割を果たす値を定義する。もしGET要求なら、このデータはクエリ文字列として渡される。POSTなら、データは要求本文として渡される。どちらの場合も、値のエンコーディングは$.ajax()ユーティリティ関数によって処理される。このパラメータは、(クエリ文字列または要求本文として使われる)文字列か、(プロパティがシリアライズされる)オブジェクトか、(name及びvalueプロパティが名前と値のペアを指定する)オブジェクトの配列。
dataType (String)応答によって返されると期待されるデータの型を識別するキーワード。この値は、そのデータがコールバック関数(複数可)に渡される前に、どのような前処理を行うべきかを決定する。

  • xml : 応答テキストはXML文書として解析され、その結果であるXML DOMがコールバックに渡される
  • html : 応答テキストは前処理なしでコールバック関数に渡される。返されたHTML断片に<script>ブロックが含まれたいたら、それらは評価される。
  • json : 応答テキストはJSON文字列として評価され、その結果のオブジェクトがコールバックに渡される。
  • jsonp : jsonと同様だが、(リモートサーバーがサポートしていれば)リモートスクリプティングを許可する。
  • script : 応答テキストはコールバックに渡される。コールバックが呼び出される前に、応答はJavaScriptステートメント(複数でもよい)として評価される。
  • text : 応答テキストはプレーンテキストとみなされる。

このプロパティが省略された場合応答テキストは、前処理も評価もされず、
そのままコールバックに渡される。jQuery1.5以降では、スペースで区切られた複数の値を指定可能。

cache (Boolean)もしfalseなら、応答がブラウザによってキャッシュされないようにする。デフォルトは true(但しdataTypeがscriptまたはjsonpの場合を除く)
context (Element)この要求に関連するすべてのコールバックにコンテクストとしてして設定する要素を指定する。
timeout (Number)Ajax要求のタイムアウトをミリ秒単位で設定する。もし要求が完了する前にタイムアウトしたら、その要求は中止され、(もし定義されていたら)エラーコールバックが呼び出される。
contentType (String)要求で指定するコンテントタイプ。もし省略したら、デフォルトは、application/x-www-form-urlencodedとなる。これは、フォーム送信でデフォルトとして使われるものと同じ。
success (Function)要求への応答が成功のステータスコードを示したときに呼び出される関数。その応答本文が、この関数への第1パラメータとして渡され、dataTypeプロパティの指定に従って評価される。第2パラメータはステータス値を含む文字列で、この場合は常に”success”。第3パラメータは、XHR(jQuery1.5からはjqXHR)インスタンスへの参照を提供する。jQuery1.5以降は、順番に実行される複数の successコールバックを配列で渡すことが可能。次項の error、completeも同様。
error (Function)要求への応答がエラーのステータスコードを示したときに呼び出される関数。これには3つの引数が渡される:XHR(jQuery1.5からはjqXHR)インスタンス、ステータス値を含む文字列(”error”, “timeout”, “notmodified”, “parseerror”のどれか)、及びオプションの例外オブジェクト。
complete (Function)要求の完了時に呼び出される関数。これには2つの引数が渡される。XHR(jQuery1.5からはjqXHR)インスタンスと(success、errorなどの)ステータスメッセージ文字列。もし errorや successのコールバックも同時に指定されていたら、それらが呼び出されたあとに、このコールバックが呼び出される。
beforeSend (Function)要求を発行する前に呼び出される関数。この関数には、XHR(jQuery1.5からはjqXHR)インスタンスが渡され、カスタムヘッダの設定など要求の前処理を実行できる。このハンドラから falseを返したら要求はキャンセルされる。
async (Boolean) falseが指定されたら、同期要求として送信される。デフォルトは非同期要求。
processData (Boolean)もし falseに設定されたら、渡されたデータをURLエンコーディングされたフォーマットに変換する処理を行わない。デフォルトでは、データはapplication/x-www-form-urlencodedタイプの要求で使うのに適したフォーマットにURLエンコーディングされる。
dataFilter (Function)応答データのフィルタリングのために呼び出される関数。この関数には、受け取ったままの応答データと datatType値が渡される。この関数は「サニタイズ」したデータを返すことが求められる。
ifModified (Boolean)もし trueなら、前回の要求と比べて応答内容が変化した場合のみ要求を成功と認める。この判定は、Last-Modifiedヘッダによる。省略したら、ヘッダのチェックは行わない(デフォルトは false)。
username (String)HTTPのアクセス認証要求に対して使用するユーザー名を指定する。
password (String)HTTPのアクセス認証要求に対して使用するパスワードを指定する。
scriptCharset (String)リモートコンテントとローカルコンテントで文字列集合が異なる場合、script及び jsonpタイプの要求で使用する文字列を指定する。

$.ajaxSetup() / Ajax リクエストのデフォルト設定

$.ajaxSetup()は、スクリプト処理のどの段階でも呼び出すことができ、以後の$.ajax()呼び出しのすべてで使用されるデフォルトを設定することが可能。設定後は、オーバーライドしない限り、それらの値が使用される。

$.ajaxSetup(options)
渡されたオプションプロパティ集合を今後の $.ajax() 呼び出しにおけるデフォルトとして設定する。
options (Object)
デフォルトの Ajaxオプション集合を定義するプロパティを持つオブジェクトのインスタンス。これらは $.ajax() のオプションと同じ。但し、成功、エラー、完了のためのコールバック関数を設定してはならない。
戻り値
なし

$.ajaxSetup()が設定するデフォルトは、load() メソッドには適用されない。また、$.get()や $.post()のようなユーティリティ関数の HTTPメソッドが、これらのデフォルトでオーバーライドされるわけではない。

Ajax要求( load()メソッドではなくユーティリティ関数)使用するデフォルト値を設定するには、ヘッダの<script>要素に置く最初のステートメントに次のように書くことが可能。

$.ajaxSetUp({
  type: 'POST',
  timeout: 5000,
  dataType: 'html'
});

これによって、今後のAjax呼び出し(load()は除く)では、これらのデフォルトが使われるようになる。ただし、使用する Ajaxユーティリティ関数に渡すプロパティによって、明示的にオーバーライドすることが可能。