SWFUploadflashとjsを組み合わせて作られたファイルアップロードプラグインで、その機能は非常に強力です。以前プロジェクトで何度か使ったことがありますが、設定パラメータが多すぎて、使った後は使い方を忘れてしまい、次に使う時にはまた公式サイトでドキュメントを見なければならず、本当に面倒です。そこで思い切ってその使い方を記録しておくことにしました。英語が苦手な人にも参照しやすく、人にも自分にも有益で、一度やってしまえば永久的に解決します。
SWFUploadの特徴
- 1、flashでアップロードを行い、ページはリフレッシュされず、Flashボタンのスタイルもカスタマイズできます;
- 2、ブラウザ側でアップロードするファイルを制限できます;
- 3、一度に複数ファイルのアップロードが可能ですが、アップロードキューがあり、キュー内のファイルは1つずつアップロードされます。サーバー側でのファイル受信は通常のフォームアップロードと同じです;
- 4、開発者が使用できる豊富なイベントインターフェースを提供します;
SWFUploadのファイルアップロードの流れ：
- 1、対応するjsファイルを読み込む
- 2、SWFUploadオブジェクトをインスタンス化し、設定パラメータオブジェクトを渡して各方面の設定を行います。
- 3、SWFUploadが提供するFlashボタンをクリックすると、ファイル選択ウィンドウがポップアップし、アップロードするファイルを選択します；
- 4、ファイル選択が完了すると、条件に合致するファイルがアップロードキューに追加されます；
- 5、startUploadメソッドを呼び出して、キュー内のファイルのアップロードを開始します；
- 6、ファイルアップロード処理中に対応するイベントが発生します。開発者はこれらのイベントを利用してUIの更新、エラー処理、プロンプト表示などを行います。
SWFUploadは3つの部分で構成されています：SWFUpload.js、swfupload.swf、初期化設定パラメータおよび各種イベント処理関数。そのため、まずページにSWFUpload.jsを読み込みます。
<script src='SWFUpload.js.html'></script>
次にSWFUploadオブジェクトをインスタンス化します：
var swfu;
window.onload = function () {
var settings_object = {//定义参数配置对象
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload.swf",
file_post_name : "Filedata",
post_params : {
"post_param_name_1" : "post_param_value_1",
"post_param_name_2" : "post_param_value_2",
"post_param_name_n" : "post_param_value_n"
},
use_query_string : false,
requeue_on_error : false,
http_success : [201, 202],
assume_success_timeout : 0,
file_types : "*.jpg;*.gif",
file_types_description: "Web Image Files",
file_size_limit : "1024",
file_upload_limit : 10,
file_queue_limit : 2,
debug : false,
prevent_swf_caching : false,
preserve_relative_urls : false,
button_placeholder_id : "element_id",
button_image_url : "http://www.swfupload.org/button_sprite.png",
button_width : 61,
button_height : 22,
button_text : "<b>Click</b> <span class="redText">here</span>",
button_text_style : ".redText { color: #FF0000; }",
button_text_left_padding : 3,
button_text_top_padding : 2,
button_action : SWFUpload.BUTTON_ACTION.SELECT_FILES,
button_disabled : false,
button_cursor : SWFUpload.CURSOR.HAND,
button_window_mode : SWFUpload.WINDOW_MODE.TRANSPARENT,
swfupload_loaded_handler : swfupload_loaded_function,
file_dialog_start_handler : file_dialog_start_function,
file_queued_handler : file_queued_function,
file_queue_error_handler : file_queue_error_function,
file_dialog_complete_handler : file_dialog_complete_function,
upload_start_handler : upload_start_function,
upload_progress_handler : upload_progress_function,
upload_error_handler : upload_error_function,
upload_success_handler : upload_success_function,
upload_complete_handler : upload_complete_function,
debug_handler : debug_function,
};
swfu = new SWFUpload(settings_object);//实例化一个SWFUpload，传入参数配置对象
};
/*定义各种事件监听函数*/
function swfupload_loaded_function(){}
function file_dialog_start_function(){}
...等等
swfuploadアップロード機能を実装するのはとても簡単で、swfuploadオブジェクトをインスタンス化するだけです。しかし、煩雑なのは、インスタンス化時に使用するパラメータ設定オブジェクトと、各種イベントの発生タイミングや提供されるパラメータです。そこで重要ポイントです。以下のいくつかの表に、開発で使用するものを列挙しました。すでにかなり多いですが、これはswfuploadのすべてではなく、私が列挙したのは一般的によく使うものだけです。完全なドキュメントを確認するには、swfupload公式サイトを参照してください。
swfupload設定パラメータオブジェクトの一般的なプロパティと説明
| 属性 | 类型 | 默认值 | 描述 |
| upload_url | String | アップロードファイルを処理するサーバー側ページのurlアドレス。絶対アドレスでも相対アドレスでも構いません。相対アドレスの場合は、現在のコードがあるドキュメントのアドレスが基準になります。 | |
| preserve_relative_urls | Boolean | false | falseの場合、SWFUploadはswfupload.swfで使用される相対アドレスを絶対アドレスに変換し、より良い互換性を実現します。 |
| file_post_name | String | Filedata | 通常のファイルフィールドでファイルをアップロードするときのname属性に相当します。サーバー側の受信ページはこの名前でアップロードされたファイルを取得します。 |
| post_params | Object（直接リテラル） | オブジェクトリテラルです。中のキー/値ペアは各ファイルと一緒にアップロードされます。ファイルアップロード時に何らかの情報を付加したい場合に便利です。 | |
| use_query_string | Boolean | false | falseの場合、post_params属性で定義されたパラメータはpost方式でアップロードされます。trueの場合、get方式でアップロードされます（つまり、パラメータはクエリ文字列の形式でurlの後ろに付加されます）。 |
| file_types | String | この属性はアップロードを許可するファイルタイプを指定します。複数のタイプがある場合はセミコロンで区切ります。例：*.jpg;*.png。すべてのタイプを許可する場合は*.*を使用します。 | |
| file_types_description | String | ファイル選択ウィンドウに表示されるファイルタイプの説明を指定します。ヒントや説明の役割を果たします。 | |
| file_size_limit | String | アップロードするファイルの最大サイズを指定します。単位を付けることができ、有効な単位はB、KB、MB、GBです。単位を省略した場合はKBとみなされます。この属性が0の場合は、ファイルサイズが制限されないことを意味します。 | |
| file_upload_limit | Number | アップロードできるファイルの最大数を指定します。アップロードに成功したファイル数がこの最大値に達すると、それ以上ファイルをアップロードできなくなり、アップロードキューにファイルを追加することもできなくなります。この属性を0に設定すると、ファイルのアップロード数が制限されないことを意味します。 | |
| file_queue_limit | Number | ファイルアップロードキューに同時に保存できるファイルの最大数を指定します。この数を超えた場合、キュー内のファイルのアップロードが成功するか、アップロードエラーになるか、アップロードがキャンセルされた後にのみ、同数の他のファイルを追加できます。file_upload_limitの値または残りのアップロード可能なファイル数がfile_queue_limitより小さい場合は、その小さい方の値が適用されます。 | |
| flash_url | String | swfupload.swfファイルの絶対パスまたは相対パス。相対パスは現在のページのアドレスを基準とします。swfuploadをインスタンス化した後は、このプロパティの値を変更できません。 | |
| prevent_swf_caching | Boolean | trueの場合、swfupload.swfアドレスの後ろにランダムな値を追加して、flashムービーがキャッシュされるのを防ぎます。これは、特定のバージョンのIEブラウザがキャッシュされたflashムービーを読み込む際に発生するバグを防ぐためです。 | |
| button_placeholder_id | String | DOM要素のidを指定します。このDOM要素はswfuploadのインスタンス化後にFlashボタンに置き換えられます。このDOM要素はプレースホルダーに相当します。 | |
| button_placeholder | DOMElement | DOM要素を指定します。このDOM要素はswfuploadのインスタンス化後にFlashボタンに置き換えられます。このDOM要素はプレースホルダーに相当します。button_placeholder_idとbutton_placeholderの両方が存在する場合、button_placeholder_idが優先されます。 | |
| button_image_url | String | Flashボタンの背景画像を指定します。相対アドレスでも絶対アドレスでも構いません。このアドレスはpreserve_relative_urls属性の影響を受け、upload_urlと同じ規則に従います。 この背景画像はスプライト画像である必要があり、上から下へFlashボタンの通常、マウスホバー、押下、無効の4つの状態が含まれています。したがって、この画像の高さはFlashボタンの高さの4倍である必要があります。 | |
| button_width | Number | Flashボタンの幅を指定 | |
| button_height | Number | Flashボタンの高さを指定します。button_image_urlで指定されたボタン背景画像の高さの1/4にする必要があります。 | |
| button_text | String | Flashボタン上のテキストを指定します。htmlコードにすることもできます。 | |
| button_text_style | String | Flashボタン上のテキストのスタイルです。使用方法は例を参照してください。 | |
| button_text_top_padding | Number | Flashボタンの上端の内側パディングを指定します。負の値も使用できます。 | |
| button_text_left_padding | Number | Flashボタンの左側のパディングを指定します。負の値も使用できます。 | |
| button_disabled | Boolean | false | trueの場合、Flashボタンは無効状態になり、クリックしても何の動作もトリガーされません。 |
| button_cursor | マウスがFlashボタン上にホバーしたときのカーソルスタイルを指定します。使用できる値はSWFUpload.CURSORで定義された定数です。 | ||
| button_window_mode | FlashボタンのWMODE属性を指定します。使用可能な値はSWFUpload.WINDOW_MODEで定義された定数です。 | ||
| file_dialog_start_handler | Function | fileDialogStartイベントリスナー関数 | |
| file_queued_handler | Function | fileQueuedイベントリスナー関数 | |
| file_queue_error_handler | Function | fileQueueErrorイベントリスナー関数 | |
| file_dialog_complete_handler | Function | fileDialogCompleteイベントリスナー関数 | |
| upload_start_handler | Function | uploadStartイベントリスナー関数 | |
| upload_progress_handler | Function | uploadProgressイベントリスナー関数 | |
| upload_error_handler | Function | uploadErrorイベントリスナー関数 | |
| upload_success_handler | Function | uploadSuccessイベントリスナー関数 | |
| upload_complete_handler | Function | uploadCompleteイベントリスナー関数 |
SWFuploadの各種イベントの説明
| fileDialogStart ( ) | ||
| ファイル選択ウィンドウがポップアップされる直前に発生します。 | ||
| fileQueued ( file object ) | ||
| ファイルがアップロードキューに追加されるとこのイベントがトリガーされます。提供される唯一のパラメータは、そのファイルの情報を含むfileオブジェクトです。 | ||
| fileQueueError ( file object, error code, message ) | ||
| ファイルがアップロードキューへの追加に失敗したときにこのイベントがトリガーされます。失敗の原因は、ファイルサイズが許可された値を超えている、ファイルが空である、ファイルキューが満杯であるなどが考えられます。 このイベントは3つのパラメータを提供します。1つ目のパラメータは問題が発生したファイルオブジェクト、2つ目のパラメータは具体的なエラーコードで、SWFUpload.QUEUE_ERRORで定義された定数を参照できます。 | ||
| fileDialogComplete ( number of files selected, number of files queued, total number of files in the queued ) | ||
| ファイルの選択が完了し、選択されたファイルが処理された（アップロードキューへの追加を指す）後、すぐにこのイベントがトリガーされます。このイベント内でthis.startUpload()メソッドを呼び出して、ファイルの自動アップロードを実現できます。 パラメータnumber of files selectedは、今回ファイル選択ダイアログで選択されたファイルの数を指します。 パラメータnumber of files queuedは、今回アップロードキューに追加されたファイルの数を指します。 パラメータtotal number of files in the queuedは、現在のアップロードキューに合計いくつのファイルがあるかを指します（今回追加されたファイルを含みます）。 | ||
| uploadStart ( file object ) | ||
| ファイルがアップロードされようとしているときにトリガーされるイベントです。このイベントは、ファイル情報の検証、アップロードに伴って送信する追加情報の付加、その他の作業を行うための、アップロード前の最後の機会を提供します。falseを返すことで、今回のファイルのアップロードをキャンセルできます。 パラメータfile objectは、現在アップロードしようとしているファイルの情報オブジェクトです。 | ||
| uploadProgress ( file object, bytes complete, total bytes ) | ||
| このイベントはファイルのアップロード中に繰り返しトリガーされます。このイベントを利用してアップロードのプログレスバーを実装できます。 パラメータfile objectはファイル情報オブジェクトです。 パラメータbytes completeは、現在アップロード済みのバイト数です。 パラメータtotal bytesは、ファイルの総バイト数です。 | ||
| uploadError ( file object, error code, message ) | ||
| ファイルのアップロードが中断されたり、ファイルが正常にアップロードされなかった場合にトリガーされるイベントです。アップロードの停止、キャンセル、またはuploadStartイベントでfalseを返すと、このイベントが発生します。ただし、ファイルがキャンセルされてもまだキュー内に残っている場合は、このイベントはトリガーされません。 パラメータfile objectはファイル情報オブジェクトです。 パラメータerror codeはエラーコードです。詳細はSWFUpload.UPLOAD_ERRORで定義された定数を参照してください。 | ||
| uploadSuccess ( file object, server data, received response ) | ||
| ファイルのアップロードが成功するとトリガーされるイベントです。 パラメータfile objectはファイル情報オブジェクトです。 パラメータserver dataは、サーバー側が出力したデータです。 | ||
| uploadComplete( file object ) | ||
| 1回のファイルアップロードのプロセスが完了したとき（成功したかどうかに関わらず）にトリガーされるイベントです。このイベントは、今回のアップロードが完了し、アップロードキューの次のファイルがアップロードを開始できることを示します。このイベントの発生後、キュー内の次のファイルのアップロードが開始されます。 |
swfuploadインスタンスのメソッド
メソッドの大部分は、パラメータ設定オブジェクトを動的に変更するメソッドです。
| destroy ( ) | ||
| SWFUploadをこれ以上使用する必要がなくなった場合、このメソッドを使用してそのインスタンスとDOM要素を破棄できます。 | ||
| startUpload( file_id ) | ||
| キュー内の指定されたファイルのアップロードを開始します。 パラメータfile_idは、アップロードするファイルのidを表します。このパラメータが指定されていない場合は、キュー内の最初のファイルがアップロードされます。 | ||
| cancelUpload ( file_id, trigger_error_event ) | ||
| ファイルのアップロードをキャンセル パラメータfile_idはキャンセルするファイルのidです。このパラメータがundefinedまたは未指定の場合、キュー内の最初のファイルがキャンセルされます。 パラメータtrigger_error_eventはブール値を受け取ります。falseの場合、ファイルのキャンセル時にuploadErrorイベントはトリガーされません。デフォルトはtrueです。 | ||
| stopUpload ( ) | ||
| 現在アップロード中のファイルを終了し、uploadErrorイベントがトリガーされます。現在アップロード中のファイルがない場合、このメソッドは何も行いません。 | ||
| getStats ( ) | ||
| キューのstatsオブジェクトを取得 | ||
| setStats ( stats_object ) | ||
| キューのstats_objectを変更します。変更したstats_objectをパラメータとして渡します。 | ||
| getFile ( file_id|index ) | ||
| ファイルidまたはファイルインデックスに基づいてFile Objectを取得します。ファイルidを使用する場合は、キュー内のファイルのみを取得できます。ファイルインデックスを使用する場合は、すべてのファイル（キュー内とキュー外の両方）を取得できます。 | ||
| addPostParam ( name, value) | ||
| 設定オブジェクトのpost_paramsで指定された追加情報オブジェクトに、キー/値ペアを追加します。 | ||
| removePostParam ( name) | ||
| 設定オブジェクト内のpost_paramsに含まれるキー/値ペアを削除します。パラメータnameは削除する値のキー名です。 | ||
| addFileParam ( file_id, name, value) | ||
| 特定のファイルに、一緒にアップロードされる追加情報を追加します。注意：指定されたそのファイルがアップロードされる場合にのみ、追加情報も一緒にアップロードされます。設定オブジェクトのpost_paramで設定された追加情報は、どのファイルがアップロードされる場合でも一緒に送信されます。 パラメータfile_idは指定するファイルのID、パラメータnameとvalueはそれぞれ追加情報の名前と値です。 | ||
| removeFileParam ( file_id, name) | ||
| addFileParamメソッドで追加した追加情報を削除します。2つのパラメータについては、説明は不要でしょう。 | ||
| setUploadURL ( url) | ||
| 設定オブジェクト内のupload_urlの値を動的に設定します。 | ||
| setPostParams ( param_object) | ||
| 設定オブジェクト内のpost_paramsプロパティの値を動的に設定します。新しい値は古い値を上書きします。 パラメータparam_objectはオブジェクトリテラルである必要があり、その中のプロパティと値は文字列のみでなければなりません。 | ||
| setFileTypes ( types, description) | ||
| 設定オブジェクト内のfile_typesとfile_types_descriptionプロパティの値を動的に設定します。2つのパラメータはどちらも省略できません。 | ||
| setFileSizeLimit ( file_size_limit) | ||
| 設定オブジェクト内のfile_size_limitプロパティの値を動的に設定します。 | ||
| setFileUploadLimit ( file_upload_limit) | ||
| 設定オブジェクト内のfile_upload_limitプロパティの値を動的に設定します。 | ||
| setFileQueueLimit ( file_queue_limit) | ||
| 設定オブジェクト内のfile_queue_limitプロパティの値を動的に設定します。 | ||
| setFilePostName ( file_post_name) | ||
| 設定オブジェクト内のfile_post_nameプロパティの値を動的に設定します。 | ||
| setUseQueryString ( use_query_string) | ||
| 設定オブジェクト内のuse_query_stringプロパティの値を動的に設定します。 | ||
| setButtonImageURL ( url) | ||
| 設定オブジェクト内のbutton_image_urlプロパティの値を動的に設定します。 | ||
| setButtonDimensions ( width, height) | ||
| Flashボタンの幅と高さを動的に設定します。2つのパラメータはそれぞれ幅と高さの値で、数値型であり、単位を付けることはできません。 | ||
| setButtonText ( text) | ||
| 設定オブジェクト内のbutton_textプロパティの値を動的に設定します。 | ||
| setButtonTextStyle ( css_style_text) | ||
| 設定オブジェクト内のbutton_text_styleプロパティの値を動的に設定します。 | ||
| setButtonTextPadding ( left, top ) | ||
| Flashボタンの左側のパディングと上端のパディングを動的に設定します。 | ||
| setButtonDisabled ( isDisabled ) | ||
| Flashボタンに対して無効/有効の操作を動的に行います。パラメータはブール値です。 | ||
| setButtonCursor ( buttonCursor ) | ||
| 設定オブジェクト内のbutton_cursorの値を動的に設定します。 |
ファイル情報オブジェクト File Object
イベントリスナー関数では、ファイル情報オブジェクトを使用してファイル情報を取得し、次の操作に役立てることがよくあります。
| 属性 | 类型 | 描述 |
| id | String | SWFUploadが定義するファイルIDで、ファイルのアップロードを制御するために使用されます。 |
| index | Number | ファイルのインデックス。getFile(i)メソッドで使用されます。 |
| name | String | ファイルの元の名前。パスは含みません。 |
| type | String | 文件类型 |
| creationdate | Date | ファイルの作成日 |
| modificationdate | Date | ファイルの最終更新日 |
| filestatus | Number | 現在のファイルの状態。詳細はSWFUpload.FILE_STATUSで定義されている定数を参照してください。 |
キュー状態オブジェクト Stats Object
現在のキューの状態を取得するために使用します。
| 属性 | 类型 | 描述 |
| in_progress | Number | 取得される値は1または0で、現在のキューにアップロード中のファイルがあるかどうかを示します。 |
| files_queued | Number | 現在のアップロードキュー内のファイル数。 |
| successful_uploads | Number | 正常にアップロードされた（uploadSuccessイベントがトリガーされた）ファイルの数。 |
| upload_errors | Number | アップロードに失敗したファイルの数（アップロードがキャンセルされたファイルを含む）。 |
| upload_cancelled | Number | アップロードがキャンセルされたファイル数。 |
| queue_errors | Number | fileQueueErrorイベントがトリガーされたファイルの数。 |
一些常量
理解を容易にするために、SWFUploadが定義するいくつかの定数。
下载地址
- SWFupload ダウンロードURL：https://code.google.com/p/swfupload/
- SWFUpload 公式ドキュメント（2.5.0版）：http://www.w3cschool.cc/w3cnote/swfupload-document.html