upload（FileReference.upload 方法）

開始將用戶選擇的文件上載到遠程服務器。雖然 Flash Player 沒有限製可上載或下載的文件的大小，但是播放器正式支持的上載或下載文件大小最大為 100 MB。必須在調用 FileReference.browse() 或 FileReferenceList.browse() 後，才能調用此方法。

偵聽器接收事件來表示上載的進度、成功或失敗。盡管可以使用 FileReferenceList 對象來允許用戶選擇多個要上載的文件，您必須逐個上載這些文件。為此，請循環訪問 FileReference 對象的 FileReferenceList.fileList 數組。

FileReference.upload() 和 FileReference.download() 函數是非阻塞式的。這些函數在調用它們之後即返回，而不會等待文件傳輸完成。此外，若 FileReference 對象離開作用域，則該對象上尚未完成的上載或下載操作將在它離開作用域時被取消。因此，隻要上載或下載操作有可能繼續，就應確保您的 FileReference 對象一直處於作用域之中。

文件上載到在 url 參數中傳遞的 URL。該 URL 必須是配置為接受上載的服務器腳本。Flash Player 使用 HTTP POST 方法上載文件。處理上載的服務器腳本應收到包含下列元素的 POST 請求：

• multipart/form-data 的 Content-Type 元素
• Content-Disposition 元素，其 name 屬性默認情況下設置為 "Filedata"，filename 屬性設置為原始文件的名稱
• 文件的二進製內容

下麵是一個 POST 請求示例：

 Content-Type: multipart/form-data; boundary=AaB03x
 --AaB03x 
 Content-Disposition: form-data; name="Filedata"; filename="example.jpg" 
 Content-Type: application/octet-stream
 ... contents of example.jpg ... 
 --AaB03x-- 

若要向服務器發送 POST 參數，請將 FileReference.postData 的值設置為您的參數。您可以通過將參數追加到 URL 使用 upload() 調用將 GET 參數發送至服務器。

如果要上載的文件大於約 10 KB，則 Windows 版本的 Flash Player 在上載實際的文件之前，會先發送不帶內容的測試上載 POST，以驗證傳輸是否可能成功。第二次 POST 將包含實際的文件內容。對於較小的文件，Flash Player 對要上載的文件隻執行一次上載 POST。 Macintosh 播放器當前不執行測試上載 POST。

注意：如果服務器要求用戶身份驗證，則隻有在瀏覽器中運行的 SWF 文件（即使用瀏覽器插件或 ActiveX 控件的文件）才可以提供對話框來提示用戶輸入用戶名和密碼以進行身份驗證，並且隻適用於下載。對於使用插件或 ActiveX 控件進行的上載以及使用獨立或外部播放器進行的上載和下載，文件傳輸會失敗。

使用此方法時，請考慮 Flash Player 安全模型：

• 如果執行調用的 SWF 文件在不受信任的本地沙箱中，則不允許使用此方法。
• 默認的安全設置將拒絕沙箱之間的訪問。網站可以通過添加跨域策略文件來實現對資源的訪問。

有關詳細信息，請參閱以下部分：

• 《學習 Flash 中的 ActionScript 2.0》中的"了解安全性"
• Flash Player 9 安全性白皮書（位於 http://www.adobe.com/go/fp9_0_security）
• Flash Player 8 與安全相關的 API 白皮書（位於 http://www.adobe.com/go/fp8_security_apis_cn）

可用性：ActionScript 1.0、Flash Player 8

參數

url:String ─ 配置為通過 HTTP POST 調用處理上載的服務器腳本的 URL。該 URL 可以是 HTTP，或者為了安全地進行上載，也可以是 HTTPS。

uploadDataFieldName:String ─ 在上載 POST 中位於文件數據之前的字段名。隻有 Flash Player 9.0.28.0 及更高版本中支持此參數。uploadDataFieldName 值必須有效並且不能為空字符串。默認情況下，uploadDataFieldName 的值為 "Filedata"：

 Content-Type: multipart/form-data; boundary=AaB03x
 --AaB03x 
 Content-Disposition: form-data; name="Filedata"; filename="example.jpg" 
 Content-Type: application/octet-stream
 ... contents of example.jpg ... 
 --AaB03x-- 

testUpload:Boolean ─ 請求對文件上載進行測試的設置。如果 testUpload 為 true，則對於大於 10 KB 的文件，Flash Player 將嚐試進行內容長度為 0 的測試文件上載 POST。測試上載的目的是檢查實際文件上載是否可能成功以及服務器身份驗證（如果需要）是否可能成功。 默認情況下，testUpload 為 false。 此時，測試上載僅針對 Windows 播放器執行。

您可以通過將參數追加到 URL 使用 upload() 調用將 GET 參數發送至服務器；例如，http://www.myserver.com/upload.cgi?userID=jdoe

在某些瀏覽器上，URL 字符串長度受限。在某些瀏覽器或服務器上，長度超過 256 個字符的字符串可能失敗。

返回

Boolean ─ 在下列任何情況下，值為 false

• FileReference.browse() 尚未對此對象成功調用；或者 FileReferenceList.browse() 尚未在其 filelist 數組中對此對象成功調用。
• 協議不是 HTTP 或 HTTPS。
• 發生了安全侵犯；SWF 文件試圖從位於該 SWF 文件的安全沙箱外的服務器訪問某個文件。
• url 參數的類型或格式不正確。
• 此調用的參數數目不正確。

示例

下麵的示例說明 upload() 方法的實現，方法是：首先提示用戶選擇要上載的文件，然後處理 onSelect 偵聽器和 onCancel 偵聽器，最後處理實際文件上載的結果。

import flash.net.FileReference;

var allTypes:Array = new Array();
var imageTypes:Object = new Object();
imageTypes.description = "Images (*.jpg, *.jpeg, *.gif, *.png)";
imageTypes.extension = "*.jpg; *.jpeg; *.gif; *.png";
allTypes.push(imageTypes);

var listener:Object = new Object();

listener.onSelect = function(file:FileReference):Void {
trace("onSelect: " + file.name);
if(!file.upload("http://www.yourdomain.com/yourUploadHandlerScript.cfm")) {
trace("Upload dialog failed to open.");
}
}

listener.onCancel = function(file:FileReference):Void {
trace("onCancel");
}

listener.onOpen = function(file:FileReference):Void {
trace("onOpen: " + file.name);
}

listener.onProgress = function(file:FileReference, bytesLoaded:Number, bytesTotal:Number):Void {
trace("onProgress with bytesLoaded: " + bytesLoaded + " bytesTotal: " + bytesTotal);
}

listener.onComplete = function(file:FileReference):Void {
trace("onComplete: " + file.name);
}

listener.onHTTPError = function(file:FileReference):Void {
trace("onHTTPError: " + file.name);
}

listener.onIOError = function(file:FileReference):Void {
trace("onIOError: " + file.name);
}

listener.onSecurityError = function(file:FileReference, errorString:String):Void {
trace("onSecurityError: " + file.name + " errorString: " + errorString);
}

var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
fileRef.browse(allTypes);