Ajax風にファイルをアップロードするjQueryプラグイン「Uploadify」の使い方

Ajax風（？）なファイルのアップローダーは多々あります。その中でも、この「Uploadify」はかなり使いやすそうです。

画面遷移なしでファイルをアップロードできるのはもちろんのこと、アップロードの進行状況も見られたり、複数ファイルのアップロードにも対応していたりと、非常に良い感じです。また、アップロード完了後やファイルの選択後の振るまい、重複ファイルのチェックなど、色々とオプションの設定が出来るのも嬉しいです。

jQuery のプラグインということもあり、敷居も低い気がします。

まずは試してみる

まずは、「uploadify - a multiple file upload plugin for jquery」からファイルをダウンロードします。

解凍したフォルダの中の「example」フォルダをサーバーにアップロードします。

これで準備完了ですので、exampleフォルダ内のindex.phpにアクセスしてみます。

「BROWSE」ボタンが表示されているはずですので、このボタンをクリックしてファイルを選択しましょう。複数のファイルを選択すれば、まとめてアップロードすることもできます。選択すると自動的にファイルがアップロードされます。

exampleフォルダ内の「uploads」フォルダにアップロードされていれば設置成功です！

もし、アップロードがうまくできていなかったら、exampleフォルダ内の「uploads」フォルダのパーミッションを書き込み出来るようにしてみると良いかもしれません。

使い方

Uploadifyの良さを体感したところで、使い方をもう少し詳しく見てみます。

ファイルを読み込む

まずは、Uploadify を設置したいファイルで以下の CSS と JavaScript を読み込みます。

uploadify.css
jquery-1.3.2.min.js
swfobject.js
jquery.uploadify.v2.1.0.min.js

仮に、exampleフォルダをドメインルートにアップロードしたとすると、読み込むソースは次のようになります。

<link href="/example/css/uploadify.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="/example/scripts/jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="/example/scripts/swfobject.js"></script>
<script type="text/javascript" src="/example/scripts/jquery.uploadify.v2.1.0.min.js"></script>

なお、Uploadify を設置するファイルは、同梱されているサンプルファイルは PHP（index.php）になっていますが、HTMLファイルでも問題ないと思います。

HTMLを用意する

次に、Uploadifyのファイル選択ボタンとアップロードの進行を表示するボックスを設置します。

<div id="fileQueue"></div>
<input type="file" name="uploadify" id="uploadify" />

div#fileQueue が、アップロードの進行を表示するボックスで、input#uploadify:file が Uploadify を適用させるボタン（ファイル選択フォーム）です。

最後に、上記でファイルを読み込んだ後に、以下のようなコードを書いて、Uploadify をそのボタンに適用させます。

<script type="text/javascript">
jQuery(function($) {
 // #uploadifyはUploadifyを使うinput:fileのID
 $("#uploadify").uploadify({
 
 // uploadify.swfのパス
 'uploader' : '/example/scripts/uploadify.swf',
 
 // uploadify.phpのパス
 'script' : '/example/scripts/uploadify.php',
 
 // 進行表示ボックスに表示されるキャンセルアイコン
 'cancelImg' : '/example/cancel.png',
 
 // ファイルをアップロードするフォルダのパス（注意あり。後述）
 'folder' : '/example/uploads',
 
 // 進行表示ボックスのID（今はdiv#fileQueueなので）
 'queueID' : 'fileQueue',
 
 // ファイルを選択すると同時にアップロードする場合はtrue
 'auto' : true,
 
 // 複数ファイルのアップロードを有効にする場合はtrue
 'multi' : true
 });
});
</script>

オプション設定

Uploadifyは、jQueryプラグインなのでオプション設定も簡単です。オプションについては、「JQuery File Upload Plugin Script - Documentation - Uploadify」に丁寧なドキュメントが用意されているので、そちらもご覧ください（英語です）。

なお、オプションは以下のように指定して、最後の行末はカンマは不要な点に注意しましょう。

'uploader': '/example/scripts/uploadify.swf',
'script' : '/example/scripts/uploadify.php',
（省略）
'auto' : ture,
'multi' : true

checkScript

Uploadifyに同梱されている「check.php」のパスを書けば、フォルダに同名のファイルが既に存在しているかをアップロード時にチェックしてくれます。既に存在する場合は上書きしていいか聞かれます。

folder

ファイルをアップロードするフォルダです。末尾に「 / 」は付けません。

ドキュメントを読むと、「 / 」で始まる絶対パスか「http://」で始まるURLで指定すると良いような感じで書いてありますが、前記の checkScript を使用する場合は、絶対パスなどの指定だとちょっと不具合が生じます。

jquery.uploadify.v2.1.0.js を見ると、148行目に以下のような記述があります。

postData.folder = pagePath + folder;

これは、checkScript に POST リクエストを送る値として使われています。

また、58〜61行目には以下の記述があります。

var pagePath = location.pathname;
pagePath = pagePath.split('/');
pagePath.pop();
pagePath = pagePath.join('/') + '/';

つまり、checkScript には、folder で指定した値の先頭にファイルのパスを付加した状態で folder が送られることになります。

したがって、checkScript を使用する場合は、絶対パスなどの指定よりも、Uploadify を適用する HTML ファイルからの相対パスで指定するか、先ほどの148行目を以下のようにカスタマイズする必要があります。

if (folder.match(/^\//) || folder.match(/^http/)) {
	postData.folder = folder;					
} else {
	postData.folder = pagePath + folder;					
}

queueID

アップロードの進行状況を表示するボックスのIDです。このボックスの中に、「uploadifyEXBHDI」のように「uploadify＋ランダムの６文字」という一意のIDが振られたdivが生成され、そこにそれぞれのアップロードの進行状況が表示されます。

queueSizeLimit

一度にアップロードできるファイルの数です。デフォルトは 999 になっています。

multi

true にすると、複数ファイルをまとめてアップロードすることができます。

auto

true にするとファイルを選択すれば自動的にアップロードが始まります。これをtrueにしない場合は、次のようなアップロードボタンを設置する必要があります。

<a href="javascript:jQuery('#uploadify').uploadifyUpload()">Upload</a>

fileDesc

次のfileExtでアップロードできるファイルタイプを指定したときに、ブラウザのダイアログボックスの下に表示されるテキストを指定するみたいです。Macだと、どこのことなのか分かりませんでしたが、これを指定しておかないと、次のfileExtが有効になりませんでした。

fileExt

'*.ext1;*.ext2;*.ext3'というフォーマットで、アップロードできるファイルの拡張子を指定します。

sizeLimit

アップロードできるファイルサイズの上限を指定します。単位はbyteです。例えば上限を500KBにする場合は、'500000'と指定します。

buttonText

Flashのアップロードボタンに表示されるテキストです。デフォルトは'BROWSE'です。僕は'Select files'なんかがいいかな。

buttonImg

任意の画像へのパスを指定して、アップロードボタンの画像を変更できます。

width

ボタンの横幅を指定します。デフォルトは110です。

height

ボタンの高さを指定します。デフォルトは30です。

cancelImg

進行状況を表示するボックスの右上にあるキャンセルボタンの画像ファイルを指定します。

onInit

ここに設定した関数が、jquery.uploadify.v2.1.0.jsが読み込まれたときに最初に呼ばれます。ここで true を返せば uploadify が適用され、false を返せば uploadify は適用されません。

（例）
'onInit': function(){
 return confirm('Uploadifyを使いたいですか？');
},

onSelect

ここに設定した関数が、アップロードするファイルを選択した後（各ファイルごと）に呼ばれます。その関数で false を返すと、アップロードの進行状況は表示されなくなります。

この関数には、次の３つの引数が渡されます。

event: イベントが起こったオブジェクトです。
queueID: 選択されたファイルに与えられた一意のIDです。
fileObj: 選択されたファイルの詳細情報が入ったオブジェクトです。詳細情報は以下のようにして取得します。
- fileObj.name - ファイル名
- fileObj.size - ファイルサイズ
- fileObj.creationDate - ファイルを作成した日時
- fileObj.modificationDate - ファイルを最後に編集した日時
- fileObj.type - ファイルの拡張子です。なぜかうまく取得できません...

なお、creationDate と modificationDate は日時に関するオブジェクトとなっているので、さらに以下のプロパティ（？）でそれぞれの値が取得できます。

month
monthUTC
minutesUTC
hours
milliseconds
hoursUTC
dateUTC
fullYearUTC
day
time
secondsUTC
date
minutes
fullYear
millisecondsUTC
dayUTC
timezoneOffset
seconds

onSelectOnce

上の onSelect で設定した関数は、各ファイルごとに呼ばれます。つまり、３つのファイルを選択したら３回呼ばれます。

それに対して、この onSelectOnce は、ファイル選択に対して１回だけ呼ばれます。つまり、１つのファイルを選択しても３つのファイルを選択しても１回だけ呼ばれます。

呼ばれるタイミングは、onSelect が終わってから呼ばれるようです。

この関数には、次の２つの引数が渡されます。

event: イベントが起こったオブジェクトです。
data: 今回のファイル選択に関する詳細情報が入ったオブジェクトです。詳細情報は以下のようにして取得します。
- data.fileCount - 選択したファイル数（queueの中にあるもの。進行表示ボックスの中にある総数）
- data.filesSelected - 選択したファイル数（fileCount との違いは後述）
- data.filesReplaced - 置き換えたファイル数
- data.allBytesTotal - 選択したファイルサイズの合計（queueの中にあるもの。進行表示ボックスの中にあるファイルサイズの総数。単位はbyte）

これらのうち、fileCount や filesSelected などは、違いがちょっと分かりにくいので、以下の例で確認してください。なお、「auto: true」している場合は関係ないと思います。

（例）

まず、image01.png、image02.png、image03.png を選択します。それぞれの値は以下の通りです。

allBytesTotal
 11669
fileCount
 3
filesSelected
 3
filesReplaced
 0

続いて、アップロードしないまま image02.png、image03.png、image04.png をアップロードします。image02.png、image03.png は変更で、最終的にアップロードされるのは、image01〜image04 の４ファイルですね。

allBytesTotal
 15404
fileCount
 4（最終的にアップロードするファイル数ですね）
filesSelected
 1（選択した３ファイルのうち今回新たに選択したのは１ファイルですね）
filesReplaced
 2（選択した３ファイルのうち２ファイルは変更ですね）

いかがでしょうか。

onCancel

アップロードするファイルをキャンセルしたときに、ここに設定した関数が呼ばれます。その関数で false を返すとキャンセルを取りやめることができます（ただし、僕の環境では false を返したときに Actionscript のエラーっぽい状況になって、その後何も反応しなくなっちゃいました）。

この関数には、次の４つの引数が渡されます。

event: イベントオブジェクト
queueID: キャンセルされたファイルの一意のID
fileObj: キャンセルされたファイルの詳細情報が入ったオブジェクトです。詳細情報は onSelect と同様に name, size, creationDate, modificationDate, type 取得できます。
data: 今回の削除に関する情報が入ったオブジェクト
- data.fileCount - キャンセルした後の、残りのファイルの総数です。
- data.allBytesTotal - キャンセルした後の、残りのファイルサイズの総数です。

onClearQueue

uploadifyClearQueue() が呼ばれたときにこの関数が呼ばれます。ここで false を返すと uploadifyClearQueue() を止めることができますが、どうもその後に不具合がでたりしました。

ドキュメントによると、この関数には次の２つの引数が渡されるようですが、２つめの data は確認できていません。

event: イベントオブジェクト
data: An object containing details about the file queue.
- data.fileCount - The number of files remaining in the upload queue
- data.allBytesTotal - The number of bytes remaining in the upload queue

onQueueFull

queueSizeLimit で指定した一度にアップロードできる数をこえると、ここで設定した関数が呼ばれます。デフォルトの関数は、「The queue is full. The max size is 設定した数.」とアラートがでるようになっていますが、ここで指定した関数で false を返せば、そのアラートは表示されません。よって、次のように日本語で表示させるという手もありますね。

（例）
'onQueueFull' : function(event, queueSizeLimit) {
 alert('一度にアップロードできるファイルは' + queueSizeLimit + 'です。');
 return false;
},

この関数には次の２つの引数が渡されます。

event: イベントオブジェクト
queueSizeLimit: 最大ファイル数

onErrorChanged

アップロード中にエラーが発生したときに、ここで設定された関数が呼ばれます。デフォルトでは、それぞれのファイルのアップロード状況を示すボックスにエラーメッセージが表示されるそうです。

この関数には、次の４つの引数が渡されます。

event: イベントオブジェクト
queueID: エラーがあったファイルのID
fileObj: エラーがあったファイルの詳細情報が入ったオブジェクトです。詳細情報は onSelect のときと同様にして取得できます。
errorObj: エラーの詳細情報が入ったオブジェクトです。
- errorObj.type - 'HTTP'か'IO'か'Security'か。
- errorObj.info - エラーメッセージ

onOpen

Flashファイルによって、アップロードするためにファイルが開かれる度に呼ばれる関数を定義します。デフォルト関数はありません。

この関数には、次の３つに引数が渡されます。

event: イベントオブジェクト
queueID: アップロードするファイルのID
fileObj: ファイルの詳細情報が入ったオブジェクトです。詳細情報は onSelect のときと同様にして取得できます。

onProgress

アップロードの進行状況を表示する際に呼ばれる関数を定義します。デフォルト関数では、ボックスに進行状況を表すバーが表示されますが、ここで定義した関数で false を返せば、デフォルト関数は呼ばれなくなります。

この関数には、次の４つの引数が渡されます。

event: イベントオブジェクト
queueID: 進行状況を表示するボックスのID
fileObj: ファイルの詳細情報が入ったオブジェクトです。詳細情報は onSelect のときと同様にして取得できます。
data: 進行状況に関する詳細情報が格納されたオブジェクト
- percentage - アップロードが何パーセント終わっているか
- bytesLoaded - 今アップロードしているファイルについてどれくらいのサイズがアップロードされたか
- allBytesLoaded - 全ファイルでどれくらいのサイズがアップロードされたか
- speed - アップロードのスピード。単位は、KB/s

onComplete

１つのファイルのアップロードが完了すると、ここで定義した関数が呼ばれます。デフォルト関数で、アップロードの進行状況を表示するボックスが削除されます。ここで設定した関数で false を返すとデフォルトの関数は呼ばれません。

この関数には、次の４つの引数が渡されます。

event: イベントオブジェクト
queueID: アップロードが完了したファイルのID
fileObj: ファイルの詳細情報が入ったオブジェクト。詳細情報は onSelect のときと同様にして取得できます。
response: サーバーから送られてくるレスポンスデータ。アップロードに成功すると 1 が返ってくるのだと思います。
data: アップロード予定のファイルに関するオブジェクト
- data.fileCount - アップロードする予定の残りのファイル数です。
- data.speed - アップロードのスピードです。単位は KB/s。

onAllComplete

上記の onComplete が、１つのファイルが終わるたびに呼ばれるのに対して、onAllComplete はすべてのファイルのアップロードが終わったときに１度だけ呼ばれます。デフォルトの関数はありません。

この関数には、２つの引数が渡されます。

event: イベントオブジェクト
data: 今回のアップロードプロセスに関する情報がはいったオブジェクト
- data.filesUploaded - アップロードされたファイル数
- data.errors - アップロード中にエラーになった数
- data.allBytesLoaded - アップロードしたファイルの合計サイズ（単位はbyte）
- data.speed - アップロードのスピード

onCheck

checkScript と併用して使い、サーバー上で同名のファイルが見つかったときに、ここで定義した関数が呼ばれます。デフォルトの関数では、上書きして良いか聞かれます。

ここで定義した関数で false を返すとデフォルトの関数は呼ばれませんが、その場合、cancelFileUpload というアップロードをキャンセルする関数も呼ばれなくなってしまうので、少し注意が必要です。

ちなみに、デフォルトの関数では、上書きして良いかどうかは英語で聞かれるので、日本語にするには、jquery.uploadify.v2.1.0.js の 157行目の以下の部分を日本語にカスタマイズする必要があります。

var replaceFile = confirm("Do you want to replace the file " + data[key] + "?");

この関数には、５つの引数が渡されます。

event: イベントオブジェクト
checkScript: チェックするスクリプト（check.php）ファイルのパス
fileQueue: 重複しているファイルの「IDとファイル名」、「folderとfolderの値」がセットになったオブジェクト
folder: アップロードしようとしたフォルダのパス
single: queue からアップロードされているファイルが１つの場合は true となるようです。未確認です。

ファイルのパーミッションがらみの注意点

Uploadify でアップロードしたファイルについて、FTPソフトではそのファイルの存在を確認できるのにブラウザでは閲覧できない、という状況に遭遇するかもしれません。

これは uploadify.php（というかPHP？）の仕様なのか、サーバーの仕様なのか、詳しいことは分かりませんが、uploadify.php のアップロードの仕方だと、アップロードしたファイルのパーミッションが「600」などになり、ブラウザではファイルにアクセスできないことが原因です。

このような場合は、uploadify.php の 40行目あたりに次の１行がありますが、

move_uploaded_file($tempFile,$targetFile);

その後ろに、次の１行を挿入すれば大丈夫だと思います。最後の「0666」がパーミッションです。適宜変更してください。

chmod($targetFile, 0666);

以上です。がんばって詳しく書いてみました。いかがでしょうか。

まずは試してみる

使い方

ファイルを読み込む

HTMLを用意する

オプション設定

checkScript

folder

queueID

queueSizeLimit

multi

auto

fileDesc

fileExt

sizeLimit

buttonText

buttonImg

width

height

cancelImg

onInit

onSelect

onSelectOnce

onCancel

onClearQueue

onQueueFull

onErrorChanged

onOpen

onProgress

onComplete

onAllComplete

onCheck

関連する関数

uploadifySettings

uploadifyUpload

uploadifyCancel

uploadifyClearQueue

ファイルのパーミッションがらみの注意点

「JavaScript」カテゴリの記事一覧