いろんなところで役に立ちそうなPreloadJSをさわって使い方をまとめてみた

* version 0.3.0を使用 *

何ができるか

PreloadJSを使うと"ファイルの読み込みが終わってから何かする"という方法に一貫性を持たせることができるようになります。
利用シーンとしてはアニメーションの開始前に必要なファイルを確実に読み込ませたいとか色々考えられそうです。

• 使い方
• 画像の読み込みが完了してから処理を行う
• loadFile()の記述方法いろいろ
• loadManifestで複数ファイルを一括で登録する
• completeイベント
• itemのもつプロパティ
• ファイルの種類を判定して処理を行う
• 登録したアイテムをqueueから削除する

使い方

PreloadJSのサイトからダウンロードします。*執筆時点の最新は0.3.0*
http://www.createjs.com/#!/PreloadJS

APIドキュメント

http://www.createjs.com/Docs/PreloadJS/modules/PreloadJS.html

PreloadJSの読み込み

<script src="./preloadjs-0.3.0.min.js"></script>

使用例

ex) 画像の読み込みが完了してから処理を行う(単一ファイル編)

  <script>
  function init(){
   var queue = new createjs.LoadQueue(true); // PreloadJSのインスタンス作成(ファイルの取得にXHRを使わずにtagによる読み込みを行う場合は引数にfalseを設定する)
   queue.loadFile("./image01.jpg",true); // 読み込みたいファイルのURL・パスを登録する。複数行記述することで複数のファイルを登録できる
   queue.addEventListener('fileload',handleFileLoad); // fileloadイベントに任意のfunctionを割り当てる

   function handleFileLoad(event){ // fileloadイベントに登録したfunction。fileloadイベント発生時に呼ばれる
    document.body.appendChild(event.result); // event.resultでfileloadの結果が得られる
   }
  }
  window.onload = function(){
   init();
  }
  </script>

loadFile()の記述方法いろいろ

loadFile()の記述は単純なURL・パスの登録以外にidを割り当てる方法があります。idを割り当てるとidを指定した参照が行えます。
これは複数ファイルを読み込んだときに役に立ちます。
*idを設定する場合の記述はJSON形式で行うのと、ファイルのURL・パスは"src"プロパティにセットする必要があります。

   queue.loadFile("./image01.jpg");
   queue.loadFile( { "src" : "./image02.jpg" } );
   queue.loadFile( { "src" : "./image03.jpg" , "id" : "image03" } );
   /* 
    *idを指定しなかった場合のプロパティは以下のように自動的に値がセットされます。*
    image01.jpg: src="./image01.jpg" , id="./image01.jpg"
    image02.jpg: id="./image02.jpg"
   */

loadFile()の第2引数(true/false)

loadFile()の第2引数でqueueにあるファイルを登録と同時に読み込むかどうかを決めることができます。
読み込みを開始させたくない場合はfalseを指定します。
任意のタイミングで読み込みを開始したい場合、load()を実行します。

    queue.loadFile("./image01.jpg",false);
    queue.loadFile( { "src" : "./image02.jpg" , "id" : "image02" } ,false);
    queue.load(); /* 読み込みは登録した順に行われる */

trueを指定した場合と、第2引数を省略した場合はFileの登録と同時に読み込みが開始されます。
このとき注意したいのは、複数行でloadFile()を行なっている場合、いずれかの行でtrueが指定された時点でqueueの中の全てのファイルを読み込む点です。

loadManifestで複数ファイルを一括で登録する

loadFile()を複数行書くのはめんどくさい。そんなときはloadManifest()を使います。
loadManifest()への登録は配列で行います。

   var manifest = [
    {"src":"./image1.jpg","id":"file1"},
    {"src":"./image2.jpg","id":"file2"},
    {"src":"./image3.jpg","id":"file3"}
   ];
   var queue = new createjs.LoadQueue(true);
   queue.loadManifest(manifest,true); /* 第2引数はloadFile()と同じ */

completeイベント

queueに登録した全てのファイルの読み込みが終わってから処理したい場合は"complete"イベントに登録したfunctionで行います。
この場合fileloadイベントとは違い、queue.getResult('idかsrcを指定')でファイルを取得します。

  function init(){
   var queue = new createjs.LoadQueue(true);
   var manifest = [
    {"src":"./image1.jpeg","id":"file1"},
    {"src":"./image2.jpeg","id":"file2"},
    {"src":"./image3.jpeg","id":"file3"}
   ];
   queue.loadManifest(manifest,false);
   queue.load();
   queue.addEventListener('complete',handleComplete);

   function handleComplete(event){
    var image = queue.getResult(manifest[2].id); // ex) manifestの2番目のファイルのidを指定して結果を得る
    document.body.appendChild(image);

    /*
    var target = event.target;
     target.loaded; // true/false
     target.useXHR; // true/false
     target.progress // 1(?)
    */
   }
  }

itemのもつプロパティ

fileloadイベントに登録したfunctionにはオブジェクトが渡され、そのオブジェクトには読み込んだ結果と、そのファイルの拡張子や種類などを示すプロパティがセットされています。
渡されるオブジェクトの名前をeventとした場合、event.itemになります。

   function handleFileLoad(event){   // fileloadイベントに登録したfunction
      var item = event.item;   // loadしたファイルの情報をもつitem
      var type = item.type;  // 'image'や'javascript'や'css'などファイルの種類
      var ext  = item.ext;  // 拡張子　('jpg'などドットを含まない拡張子)
      var id   = item.id;   // loadFile()登録時に指定したid
      var src  = item.src;  // loadFile()登録時に指定したURL・パス
      var tag  = item.tag;  //　読み込んだファイルを扱えるtag名 (画像なら'img' CSSなら'style' JSなら'script' )
   }

ファイルの種類を判定して処理を行う

ファイルの種類に応じた処理を行いたい場合はitem.typeと、createjs.LoadQueueの持っているプロパティを比較します。

・用意されているプロパティ

   createjs.LoadQueue.CSS   // "css"
   createjs.LoadQueue.IMAGE  // "image"
   createjs.LoadQueue.JAVASCRIPT // "javascript"
   createjs.LoadQueue.JSON   // "json"
   createjs.LoadQueue.SOUND  // "sound"
   createjs.LoadQueue.SVG   // "svg"
   createjs.LoadQueue.TEXT   // "text"
   createjs.LoadQueue.XML   // "xml"

処理の例

   var queue = new createjs.LoadQueue(true);
   var manifest = [
    {"src":"./image1.jpeg","id":"file1"},
    {"src":"./style.css"  ,"id":"file2"},
    {"src":"./script.js"  ,"id":"file3"}
   ];
   queue.loadManifest(manifest,true);

   queue.addEventListener('fileload',handleFileLoad);

   function handleFileLoad(event){
    var item = event.item;    
    var type = item.type;

    if(type === createjs.LoadQueue.IMAGE){
           document.body.appendChild(event.result);
       }
   }

登録したアイテムをqueueから削除する

queueに登録したファイルを削除するにはremove()かremoveAll()を使います。

   /* remove()で一つのファイルをqueueから削除する */
   queue.loadFile({"id":"image1","src":"./image.jpg"});
   queue.remove("image1");   // idかsrcを指定して削除する
   queue.remove("./image.jpg");

   /* removeAll()で全てのファイルをqueueから削除する */
  var manifest = [
   {"src":"./image1.jpeg","id":"file1"},
   {"src":"./style.css"  ,"id":"file2"},
   {"src":"./script.js"  ,"id":"file3"}
  ];
  queue.loadManifest(manifest,true);
  queue.removeAll();    // 0.3.0ではバグがありremoveAll()を実行するとエラーが出ます。
  

removeAll()は0.3.0ではバグのため動きません。-> http://community.createjs.com/discussions/preloadjs/123-removeall
次のバージョンを待つか、github/PreloadJSにあるソースからbuildを行えばremoveAll()が使えます。
*もしくはminifyされたpreloadjs-0.3.0.min.jsを開いて22行目のthis.initialize(this.useXHR)をthis.init(this.useXHR)にすれば動きます。

しめ

基本的な使い方はこんな感じでしょうか。
あとはドキュメントを読むといろいろとメソッドが用意されているので使い込みたい人はドキュメントとCreateJS Supportを参照してみてください。

PreloadJS以外にもSoundJS/EaselJS/TweenJSなど、CreateJSが今後フロントエンドでは主流となると個人的には思っています。いまのうちにさわっておくと色々と捗りそうです。