SWFUpload學習記錄

轉載自：

http://blog.csdn.net/zhyh1986/article/details/7926166

前言

        最近項目中要求使用HTTP做文件上傳，而且要求有進度顯示，在網上東找西尋了半天，解決方案倒也不少，比如使用Ajax上傳，但感覺這種方式的進度提示太麻煩，所以沒有采用，後來看到了SWFUpload，就找了些資料來看，覺得符合自己的要求，研究了足有兩天，略有心得，忙不迭地記錄下來，以防止時間長了遺忘，如果不小心幫助了別人，那就更好了，呵呵...

下面摘抄一段SWFUpload官網的介紹（別人翻譯過來的）：

SWFUpload 最初是由Vinterwebb.se 開發的客戶端文件上傳工具。它結合javascript和flash在瀏覽器中提供一個優於傳統上傳標籤 <input type="file" /> 的功能（和良好的用戶體驗）。

SWFUpload 的主要特性:

• 文件瀏覽對話框中可以選擇多個文件
• AJAX風格的上傳，不用重刷新
• 上傳過程中的各種事件.
• 可以在客戶端調節圖片大小
• 它使用的類命名空間兼容各種js庫(i.e., jQuery, Prototype, 等.).
• 支持 Flash 9 and Flash 10 (2.2.0版本後取消對flash 8的支持)

SWFUpload 的設計理念與其他基於flash的上傳工具不同。SWFUpload 給開發者儘可能多的UI控制能力. 開發者可以使用 XHTML, CSS, JavaScript 來使它更符合自己網站的樣式風格. 它提供一組簡單的js事件更新上傳狀態，開發者可以根據這些事件來在網頁中顯示文件上傳進度

好了，誇獎的話不多說了，既然它這麼受歡迎，想必是有一定優勢的。

下面記錄一下我做的一個小示例，先預覽一下程序運行效果：

有朋友索要例子源碼，其實我早已放在我的資源裏了，並沒有設置下載積分，有需要的朋友請到這裏下載：http://download.csdn.net/detail/zhangyihui1986/4538748

準備工作

現在SWFUpload項目託管於Google code下，URL爲：http://code.google.com/p/swfupload/  ，請自行下載，下載的壓縮文件中含有一個文檔，裏面詳細介紹了SWFUpload的配置參數、事件支持、支持方法等。

這裏是官網上的幾個例子：http://demo.swfupload.org/

網絡上關於SWFUpload的博客資源很多，但很多博客質量不太高，而且轉來轉去，內容重複，所以我在查資料的時候沒有找到太合適的資源，後來找到了這裏：http://webdeveloperplus.com/jquery/multiple-file-upload-with-progress-bar-using-jquery/ ，這是一個外國人寫的關於SWFUpload的小教程，UI做地也挺好，於是我就參照着做了個小例子。

不過，上面鏈接的教程是針對SWFUpload一個針對JQuery的插件寫的，這個插件地址爲：http://blogs.bigfish.tv/adam/2009/06/14/swfupload-jquery-plugin/，該插件好像僅僅是完善了一下SWFUpload的事件機制，使用它可採用JQuery的鏈式寫法，但我沒有用它，而是用的原生的SWFUpload2.2版本。

示例實現步驟

不多說，先貼出來我做的例子，然後再針對代碼作適當解釋。

例子使用了Struts2.3.4作爲後臺，當然，SWFUpload是不選擇後臺的，您可以使用任意的技術，只要是能實現HTTP協議即可。

1）將下載的壓縮文件解壓並拷到web項目中（此處我放到項目的js目錄下），建立其它資源（如JSP、Action等）後目錄結構如下圖所示：

2）在JSP文件中引入SWFUpload依賴的JS文件

<link href="<%=path %>/js/ligerUI/skins/Aqua/css/ligerui-all.css" type="text/css" rel="stylesheet" />
<script type="text/javascript" src="<%=path %>/js/jquery-1.7.2.min.js"></script>
<script type="text/javascript" src="<%=path %>/js/ligerUI/js/core/base.js"></script>
<script type="text/javascript" src="<%=path %>/js/ligerUI/js/plugins/ligerDrag.js"></script>
<script type="text/javascript" src="<%=path %>/js/ligerUI/js/plugins/ligerDialog.js"></script>
<script type="text/javascript" src="<%=path %>/js/swfupload/swfupload.js"></script>
<script type="text/javascript" src="<%=path %>/js/swfupload/plugins/swfupload.queue.js"></script>

在此處我用到了ligerUI框架，如果不使用它，那麼僅需要引jquery和swfupload.js兩個文件即可。

3）JSP文件中HTML結構

<div id="swfupload">
    <span id="spanButtonPlaceholder"></span>
    <p id="queueStatus"></p>
    <ol id="logList"></ol>
</div>

4）JSP文件中CSS，給文件上傳進度列表賦與樣式，我對CSS不夠熟悉，此處的樣式幾乎全部來自於前面那個教程，僅作了一些小的變動。如果您覺得這還不夠好，那您自己來實現漂亮的UI界面吧！

#logList { margin: 0; padding: 0; width: 500px }
#logList li { list-style-position: inside; margin: 2px; border: 1px solid #ccc; padding: 10px; color: #333;
            font-size: 15px; background: #FFF; position: relative; }
#logList li .progressBar { border:1px solid #333; height:5px; background:#fff; }
#logList li .progressValue { color: red; margin-left: 5px }
#logList li .progress { background:#999; width:0%; height:5px; }
#logList li p { margin:0; line-height:18px; }
#logList li.success { border:1px solid #339933; background:#ccf9b9; }
#logList li span.cancel { background:url('../images/delete.gif') no-repeat; position:absolute; top:5px;
            right:5px; width:16px; height:16px; cursor:pointer }

5）JSP中的Javascript，主要是創建SWFUpload組件實例，並綁定監聽函數，在監聽函數中處理進度提示：

var contextPath;
var queueErrorArray;
$(function(){
    contextPath = $("#contextPath").val();

    var swfUpload = new SWFUpload({
        upload_url: contextPath + '/swfupload/upload!upload.action',
        flash_url: contextPath + '/js/swfupload/Flash/swfupload.swf',

        file_post_name: 'fileData',
        use_query_string: true,
        post_params: {
            param1: 'Hello',
            param2: encodeURI('你好',"utf-8")
        },

        file_types: "*.rar;*.zip",
        file_types_description: '上報數據文件',
        file_size_limit: '102400',
//      file_upload_limit: 5,
        file_queue_limit: 3,

        // handlers
        file_dialog_start_handler: fileDialogStart,
        file_queued_handler: fileQueued,
        file_queue_error_handler: fileQueueError,
        file_dialog_complete_handler: fileDialogComplete,
        upload_start_handler: uploadStart,
        upload_progress_handler: uploadProgress,
        upload_success_handler: uploadSuccess,
        upload_complete_handler: uploadComplete,

        button_placeholder_id: 'spanButtonPlaceholder',
        button_text: '<span class="whiteFont">選擇文件</span>',
        button_text_style: '.whiteFont{ color: #FFFFFF; }',
        button_text_left_padding: 40,
        button_text_top_padding: 6,
        button_image_url: contextPath + '/images/button.png',
        button_width: 133,
        button_height: 33,
        button_cursor: SWFUpload.CURSOR.HAND,
        button_window_mode: SWFUpload.WINDOW_MODE.TRANSPARENT,

        debug: false,

        custom_settings: {}
    });
});

//========================================  回調函數Handlers  ===================================

/**
* 打開文件選擇對話框時響應
*/
function fileDialogStart() {
    if (queueErrorArray) {
        queueErrorArray = null;
    }
}

/**
* 文件被加入上傳隊列時的回調函數,增加文件信息到列表並自動開始上傳.<br />
* <p></p>
* SWFUpload.startUpload(file_id)方法導致指定文件開始上傳,
* 如果參數爲空,則默認上傳隊列第一個文件;<br />
* SWFUpload.cancelUpload(file_id,trigger_error_event)取消指定文件上傳並從隊列刪除,
* 如果file_id爲空,則刪除隊列第一個文件,trigger_error_event表示是否觸發uploadError事件.
* @param file 加入隊列的文件
*/
function fileQueued(file) {
    var swfUpload = this;
    var listItem = '<li id="' + file.id + '">';
    listItem += '文件:<em>' + file.name + '</em>(' + Math.round(file.size/1024) + ' KB)';
    listItem += '<span class="progressValue"></span>'
              + '<div class="progressBar"><div class="progress"></div></div>'
              + '<p class="status" >Pending</p>'
              + '<span class="cancel" > </span>'
              + '</li>';
    $("#logList").append(listItem);
    $("li#" + file.id + " .cancel").click(function(e) {
        swfUpload.cancelUpload(file.id);
        $("li#" + file.id).slideUp('fast');
    })
//  swfUpload.startUpload();
}

/**
* 文件加入上傳隊列失敗時觸發,觸發原因包括:<br />
* 文件大小超出限制<br />
* 文件類型不符合<br />
* 上傳隊列數量限制超出等.
* @param file 當前文件
* @param errorCode 錯誤代碼(參考SWFUpload.QUEUE_ERROR常量)
* @param message 錯誤信息
*/
function fileQueueError(file,errorCode,message) {
    if (errorCode == SWFUpload.QUEUE_ERROR.QUEUE_LIMIT_EXCEEDED) {
        alert("上傳隊列中最多隻能有3個文件等待上傳.");
        return;
    }
    if (!queueErrorArray) {
        queueErrorArray = [];
    }
    var errorFile = {
        file: file,
        code: errorCode,
        error: ''
    };
    switch (errorCode) {
    case SWFUpload.QUEUE_ERROR.FILE_EXCEEDS_SIZE_LIMIT:
        errorFile.error = '文件大小超出限制.';
        break;
    case SWFUpload.QUEUE_ERROR.INVALID_FILETYPE:
        errorFile.error = '文件類型受限.';
        break;
    case SWFUpload.QUEUE_ERROR.ZERO_BYTE_FILE:
        errorFile.error = '文件爲空文件.';
        break;
    default:
        alert('加載入隊列出錯.');
        break;
    }
    queueErrorArray.push(errorFile);
}

/**
* 選擇文件對話框關閉時觸發,報告所選文件個數、加入上傳隊列文件數及上傳隊列文件總數
* @param numSelected 選擇的文件數目
* @param numQueued 加入隊列的文件數目
* @param numTotalInQueued 上傳文件隊列中文件總數
*/
function fileDialogComplete(numSelected,numQueued,numTotalInQueued) {
    var swfupload = this;
    if (queueErrorArray && queueErrorArray.length) {
        var table = $('<table><tr><td>文件</td><td>大小</td></tr></table>');
        for(var i in queueErrorArray) {
            var tr = $('<tr></tr>');
            var info = '<td>' + queueErrorArray[i].file.name + '<span style="color:red">('
                        + queueErrorArray[i].error + ')</span></td>'
                        + '<td>' + queueErrorArray[i].file.size + 'bytes</td>';
            table.append(tr.append(info));
        }
        $.ligerDialog.open({
            width: 500,
            content: table,
            title: '文件選擇錯誤提示',
            buttons: [{
                text: '確定',
                onclick: function(btn,dialog,index) {
                    $("#queueStatus").text('選擇文件: ' + numSelected
                            + ' / 加入隊列文件: ' + numQueued);
                    swfupload.startUpload();
                    dialog.close();
                }
            }]
        });
        queueErrorArray = [];
    } else {
        this.startUpload();
    }
}

/**
* 文件開始上傳時觸發
* @param file 開始上傳目標文件
*/
function uploadStart(file) {
    if (file) {
        $("#logList li#" + file.id).find('p.status').text('上傳中...');
        $("#logList li#" + file.id).find('p.progressValue').text('0%');
    }
}

/**
* 文件上傳過程中定時觸發,更新進度顯示
* @param file 上傳的文件
* @param bytesCompleted 已上傳大小
* @param bytesTotal 文件總大小
*/
function uploadProgress(file,bytesCompleted,bytesTotal) {
    var percentage = Math.round((bytesCompleted / bytesTotal) * 100);
    $("#logList li#" + file.id).find('div.progress').css('width',percentage + '%');
    $("#logList li#" + file.id).find('span.progressValue').text(percentage + '%');
}

/**
* 文件上傳完畢並且服務器返回200狀態碼時觸發,此時文件的上傳週期並未完成,
* 不能在此事件監聽函數開始下一個文件的上傳
* @param file 上傳的文件
* @param serverData 服務器在執行完接收文件方法後返回的數據
* @param response Boolean類型,表示是否服務器返回數據
*/
function uploadSuccess(file,serverData,response) {
    var item = $("#logList li#" + file.id);
    item.find('div.progress').css('width','100%');
    item.find('span.progressValue').css('color','blue').text('100%');

    item.addClass('success').find('p.status').html('上傳完成!');
}

/**
* 在一個上傳週期結束後觸發(uploadError及uploadSuccess均觸發)
* 在此可以開始下一個文件上傳(通過上傳組件的uploadStart()方法)
* @param file 上傳完成的文件對象
*/
function uploadComplete(file) {
    this.uploadStart();
}

代碼解釋

1）SWFUpload組件的實例化

SWFUpload組件的實例化很簡單，就是new一個JS對象，如

var swfUpload = new SWFUpload({settings});

我們需要傳給它一個配置對象，這個配置對象的內容很多，詳細介紹請參照使用說明文檔，在此僅介紹幾個重要一些的配置參數，以註釋的形式寫在代碼裏。

upload_url: '',     // 上傳操作後臺處理URL，相當於form的action屬性
flash_url: '',      // swf文件的位置，指向JS目錄下的swfupload.swf文件即可

file_post_name: '', // 提交到後臺的文件的名字，相當於<input type='file' />域的name值，默認爲“Filedata”

file_types: "*.rar;*.zip",  // 可上傳的文件類型
file_types_description: '', // 可上傳文件類型的描述信息
file_size_limit: '',        // 上傳文件大小限制，接受值和單位，默認單位是KB，如'1024 MB'

button_placeholder_id: 'spanButtonPlaceholder', // 設置一個HTML元素，用以渲染Flash的Button
button_image_url: '',   // 按鈕圖片，Flash使用，可以有多種狀態（mouseout、hover等）
button_width: 270,      // 按鈕的寬，必須要設置，不設置按鈕無法顯示
button_height: 20,      // 按鈕的高，必須要設置，不設置按鈕無法顯示
button_cursor: SWFUpload.CURSOR.HAND,   // 鼠標移到按鈕上的光標樣式
button_window_mode: SWFUpload.WINDOW_MODE.TRANSPARENT,  // Flash剪輯的WMODE屬性

需要注意的是按鈕的高和寬一定要指定，否則flash無法顯示。

2）添加事件監聽器

        swfupload僅實現了後臺操作，前臺的處理空間留給了開發者，它採用事件觸發機制，讓開發者捕獲特定事件，自定義對應的事件處理函數進行相應處理。即當swfupload內部某一特定事件發生，便觸發相應的JS函數，並傳入合適的相關參數，開發者就可以拿着這些參數來更新UI界面以提示上傳進度了。Swfupload通過固定的事件函數名屬性值尋找自定義的JS函數，所以在初始化工作中，將自定義的JS函數名賦值給swfupload指定的對應屬性即可。

// handlers:事件監聽函數，請參考使用說明文檔
file_dialog_start_handler: fileDialogStart,// 文件選擇對話框打開時觸發，傳入SWFUpload定義的File參數
file_queued_handler: fileQueued,// 文件被加入隊列時觸發
file_queue_error_handler: fileQueueError,// 文件加入隊列出錯時觸發，包括大小限制，類型限制，空文件等均會觸發
file_dialog_complete_handler: fileDialogComplete,// 文件選擇對話框在文件選擇完成並關閉時觸發
upload_start_handler: uploadStart,// 文件開始上傳時觸發
upload_progress_handler: uploadProgress,// 上傳過程中定時觸發，此方法在更新進度條時比較重要
upload_success_handler: uploadSuccess,// 文件上傳成功時觸發
upload_complete_handler: uploadComplete,// 文件上傳完成時觸發，包括上傳成功與上傳失敗，此方法可以開始下一文件的上傳

3）開始文件上傳

        默認情況下，你選擇了文件並關閉了文件選擇對話框文件並不會自動開始上傳，你需要調用SWFUpload的startUpload()方法，該方法接收一個file_id作爲參數，如果參數爲空，則自動開始上傳文件隊列中的第一個文件。

另外，在所有的事件監聽器中，this關鍵字都是指向SWFUpload對象，所以你可以在file_queued_handler或file_dialog_complete_handler等事件監聽器中這樣開始文件上傳：

this.startUpload();

4）批量文件上傳

        默認情況下，你在第3步中開始了一個文件上傳，但是如果你選擇的是多個文件，那麼你會發現這個文件上傳後其它文件並不會自動開始上傳，這是爲什麼呢？原來Swfupload雖支持批量上傳，但本質仍是單個文件依次上傳，所以如果你的上傳是支持多個文件上傳那只有你自己去開始其它文件的自動上傳了，我們可以在upload_complete_handler事件監聽器中再調用一個startUpload()方法：

this.startUpload();

因爲upload_complete_handler事件是在一個文件上傳後觸發，不管該文件是否上傳成功都會觸發該事件，所以我們在這裏再調用一次startUpload方法是合適的，這樣SWFUpload組件在前一個文件上傳完成後就會自動開始下一個文件的上傳。

5）顯示上傳文件進度列表

        顯示出上傳文件進度列表能夠增強用戶體驗，因爲用戶將看見選擇的文件信息以及該文件的上傳進度，這些東西就完全由開者來定製了，SWFUpload組件將豐富的文件信息及上傳進度在調用事件監聽函數時以參數的形式傳進來，我們就可以利用這些信息動態更新文件上傳進度UI了。如前面的例子我們在file_queued_handler事件監聽函數中將文件信息及其進度條拼接到頁面的ol列表中，在upload_start_handler事件監聽函數中初始化進度條顯示，然後在文件上傳過程中會不停地觸發upload_progress_handler事件，我們就在這個事件監聽函數中獲取上傳進度，並將其更新到進度列表，這樣便可實現文件上傳的進度提示。在SWFUpload豐富的事件機制支持下，實現這些東西是很容易的事。

6）有關中文傳遞

在SWFUpload的配置參數中有一個post_params參數是用來向後臺傳遞參數的，默認情況好像是不能傳遞參數的，但是如果你將另一個配置參數use_query_string設置爲true之後就可以傳遞參數了。

該參數接收一個JS對象，類似於這樣：

use_query_string: true,
post_params: {
    param1: 'Hello',
    param2: '你好'
}

但是如果參數值中含有中文的話，那麼後臺會報錯，也取不到值，可以這樣解決：

在JS中先用UTF-8進行中文編碼

use_query_string: true,
post_params: {
    remark: encodeURI('中文',"utf-8")
}

然後在後臺再轉回來，在Java中就體現爲

URLDecoder.decode(request.getParameter("remark"), "utf-8");

如此便可解決中文參數傳遞問題。

7）有關頁面跳轉

        假設有這種需求：文件上傳完成後跳轉到指定的頁面，比如文件信息查看頁面，那我們可能會一時找不到好的方法，因爲SWFUpload上傳類似於Ajax上傳，涉及到的上傳交互操作並非是瀏覽器所發，而是由Flash發出的上傳請求，那麼後臺給出的跳轉信息瀏覽器自然接收不到，而是由Flash接收到了，既然瀏覽器接收不到跳轉信息，那麼自動跳轉就不會發生。

對於這種需求，我們可以參照Ajax提交跳轉的方式，在後臺成功接收文件後輸出一些信息，比如跳轉的頁面，或者僅僅是一個字符串，而把跳轉的任務交由Javascript來完成，那麼我們應該在什麼事件監聽函數中處理呢！您可以看看upload_success_handler這個事件的回調函數有什麼參數，如下：

uploadSuccess(file object, server data, received response)

        這個事件發生後會傳三個參數到我們定義的監聽函數中，第一個是上傳完成的文件對象（關於文件對象可參看SWFUpload的文檔，其實就是一個JS對象，包含一些重要的文件信息），第二個其實是服務器返回的數據，如果後臺用的直接跳轉，那麼這裏的server data就會是跳轉頁面的HTML結構，document.write()將其輸出，也算是完成跳轉了吧！如果你僅僅是向前臺輸出個字符串，並沒有跳轉，那麼這裏就應該是你輸出的字符串，在這裏就可以用location.href=“來實現跳轉；第三個參數是Boolean類型，表示是否接收到服務器傳回的數據。

        需要注意的是該事件在每個文件上傳成功均會觸發，如果同時在上傳多個文件，那麼第一個文件上傳完成後頁面就直接跳轉了，後臺的文件也就得不到機會上傳了，所以這裏需要判斷一下隊列裏是否還有沒有上傳完成的文件，如果沒有了再跳轉，就可以了，至於如何判斷隊列裏是否還有未上傳的文件，這裏用到了SWFUpload的另一個對象Stats。該對象提供了上傳隊列的狀態信息，訪問實例的getStats方法可獲取此對象，該對象中有一些屬性，其中有一個files_queued屬性可以表示是否還有未上傳的文件，如果該屬性爲0則表示全部上傳，可以這樣做

if(this.getStats().files_queued = 0) {
    // jump code
}

8）有關SWFUpload組件在非IE瀏覽器中不傳遞Cookie的問題

        最近在使用SWFUpload過程中發現一個問題，文件上傳成功後我需要將其移動到指定目錄下，由於目錄信息是在Session中的，這時在非IE瀏覽器中出現了問題，Session中沒有東西，用戶登錄信息也沒有了。經過調試才發現文件上傳成功後在後臺取到的Session與用戶登錄完成後的Session相比根本就不是一個Session了，它們的ID不同，也就是說文件上傳另生成了一個Session，而這個Session是全新的，當然沒有了登錄時存放的信息了。

        經過一番搜索，這是由於Flash Player在非IE瀏覽器下一個Bug引起的，這裏有一段描述：

Cookie issue

On Windows the Non-IE Flash Player plugin (FireFox, Opera, Safari, etc) sends the IE cookies regardless of the browser used. This breaks authentication and sessions for many server-side scripting technologies.

Developers should manually pass Session and Authentication cookie information and manually restore Sessions on the Server Side if they wish to use Sessions

The SWFUpload package contains work-around sample code for PHP and ASP.Net

        也就是說非IE瀏覽器下Flash Player插件發送的也是IE瀏覽器當前頁面的cookie，並且Session是靠Cookie中保存的SessionId實現的，因此後臺處理程序另新建了Session，程序也就出現了上述錯誤。

        找到的解決辦法是手動將SessionID傳到後臺服務端。

        在上傳路徑URL里加上jsessionid變量即可，如下：

upload_url: contextPath + '/web/user-upload!upload.action;jsessionid=<%=request.getSession().getId() %>'

         這樣就可以解決問題了，有人還說可以使用SWFUpload組件的一個插件：swfupload.cookies.js，但我沒有弄好，看它的源碼是分析瀏覽器的cookie然後將它們拼接到post_params配置項中，我手動拼上jsessionid也是不起作用，不知道是不是自己沒弄對，反正是這個插件我沒有成功使用。