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);