flash.net.FileReference (ActionScript 3.0)

	属性	定义方
		constructor : Object 对类对象或给定对象实例的构造函数的引用。	Object
		creationDate : Date [read-only] 本地磁盘上文件的创建日期。	FileReference
		creator : String [read-only] 文件的 Macintosh 创建者类型。	FileReference
		modificationDate : Date [read-only] 本地磁盘上文件的上一次修改日期。	FileReference
		name : String [read-only] 本地磁盘上的文件的名称。	FileReference
		prototype : Object [static] 对类或函数对象的原型对象的引用。	Object
		size : uint [read-only] 本地磁盘上文件的大小（以字节为单位）。	FileReference
		type : String [read-only] 文件类型。	FileReference

	方法	定义方
		FileReference() 创建新的 FileReference 对象。	FileReference
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void 使用 EventDispatcher 对象注册事件侦听器对象，以使侦听器能够接收事件通知。	EventDispatcher
		browse(typeFilter:Array = null):Boolean 显示一个文件浏览对话框，让用户选择要上载的文件。	FileReference
		cancel():void 取消正在对该 FileReference 对象执行的任何上载或下载操作。	FileReference
		dispatchEvent(event:Event):Boolean 将事件调度到事件流中。	EventDispatcher
		download(request:URLRequest, defaultFileName:String = null):void 打开对话框，以允许用户从远程服务器下载文件。	FileReference
		hasEventListener(type:String):Boolean 检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。	EventDispatcher
		hasOwnProperty(name:String):Boolean 指示对象是否已经定义了指定的属性。	Object
		isPrototypeOf(theClass:Object):Boolean 指示 Object 类的实例是否在指定为参数的对象的原型链中。	Object
		propertyIsEnumerable(name:String):Boolean 指示指定的属性是否存在、是否可枚举。	Object
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void 从 EventDispatcher 对象中删除侦听器。	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 设置循环操作动态属性的可用性。	Object
		toString():String 返回指定对象的字符串表示形式。	Object
		upload(request:URLRequest, uploadDataFieldName:String = "Filedata", testUpload:Boolean = false):void 开始将用户选择的文件上载到远程服务器。	FileReference
		valueOf():Object 返回指定对象的原始值。	Object
		willTrigger(type:String):Boolean 检查是否用此 EventDispatcher 对象或其任何始祖为指定事件类型注册了事件侦听器。	EventDispatcher

摘要	定义方
activate	Flash Player 获得操作系统焦点并变为活动状态时调度。	EventDispatcher
cancel	当用户通过文件浏览对话框取消文件上载或下载时调度。	FileReference
complete	当下载操作完成或上载操作生成 HTTP 状态代码 200 时调度。	FileReference
deactivate	Flash Player 失去操作系统焦点并变为非活动状态时调度。	EventDispatcher
httpStatus	当上载失败并且存在可用来描述失败的 HTTP 状态代码时调度。	FileReference
ioError	当上载或下载失败时调度。	FileReference
open	当上载或下载操作开始时调度。	FileReference
progress	在文件上载或下载操作期间定期调度。	FileReference
securityError	当对 FileReference.upload() 或 FileReference.download() 方法的调用尝试将文件上载到调用方安全沙箱外部的服务器，或是从调用方安全沙箱外部的服务器上下载文件时进行调度。	FileReference
select	当用户从文件浏览对话框选择要上载或下载的文件时调度。	FileReference
uploadCompleteData	成功上载并从服务器接收数据之后调度。	FileReference

属性详细信息

creationDate

属性

creationDate:Date [read-only]

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

本地磁盘上文件的创建日期。如果未填充 FileReference 对象，则为获得此属性的值而执行的调用将返回 null。

实现
public function get creationDate():Date

引发

	`IllegalOperationError` — 若 `FileReference.browse()`、`FileReferenceList.browse()` 或 `FileReference.download()` 方法未能成功调用，将引发异常，同时显示一条信息，指出函数的调用顺序不正确或先前调用未成功。此时，`creationDate` 属性的值为 `null`。

	`IOError` — 若不能访问文件信息，则会引发一个异常，同时显示一条信息，指出发生文件 I/O 错误。

另请参见

FileReference.browse()

creator

属性

creator:String [read-only]

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

文件的 Macintosh 创建者类型。在 Windows 上，此属性为 null。如果未填充 FileReference 对象，则为获得此属性的值而执行的调用将返回 null。

实现
public function get creator():String

引发

IllegalOperationError — 在 Macintosh 系统上，若 FileReference.browse()、FileReferenceList.browse() 或 FileReference.download() 方法未能成功调用，将引发异常，同时显示一条信息，指出函数的调用顺序不正确或先前调用未成功。此时，creator 属性的值为 null。

另请参见

FileReference.browse()
处理文件上载和下载

modificationDate

属性

modificationDate:Date [read-only]

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

本地磁盘上文件的上一次修改日期。如果未填充 FileReference 对象，则为获得此属性的值而执行的调用将返回 null。

实现
public function get modificationDate():Date

引发

	`IllegalOperationError` — 若 `FileReference.browse()`、`FileReferenceList.browse()` 或 `FileReference.download()` 方法未能成功调用，将引发异常，同时显示一条信息，指出函数的调用顺序不正确或先前调用未成功。此时，`modificationDate` 属性的值为 `null`。

	`IOError` — 若不能访问文件信息，则会引发一个异常，同时显示一条信息，指出发生文件 I/O 错误。

另请参见

FileReference.browse()

name

属性

name:String [read-only]

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

本地磁盘上的文件的名称。如果未填充 FileReference 对象，则为获得此属性的值而执行的调用将返回 null。

FileReference 对象的所有属性都通过调用 browse() 方法进行填充。与其它 FileReference 属性不同，如果调用 download() 方法，则在调度 select 事件时将填充 name 属性。

实现
public function get name():String

引发

IllegalOperationError — 若 FileReference.browse()、FileReferenceList.browse() 或 FileReference.download() 方法未能成功调用，将引发异常，同时显示一条信息，指出函数的调用顺序不正确或先前调用未成功。此时，name 属性的值为 null。

另请参见

FileReference.browse()

size

属性

size:uint [read-only]

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

本地磁盘上文件的大小（以字节为单位）。如果 size 为 0，将引发异常。

实现
public function get size():uint

引发

	`IllegalOperationError` — 若 `FileReference.browse()`、`FileReferenceList.browse()` 或 `FileReference.download()` 方法未能成功调用，将引发异常，同时显示一条信息，指出函数的调用顺序不正确或先前调用未成功。此时，`size` 属性的值为 0。

	`IOError` — 若无法打开或读取文件，或者在访问文件时遇到类似错误，将引发异常，同时显示一条信息，指明发生文件 I/O 错误。此时，`size` 属性的值为 `0`。

另请参见

FileReference.browse()

type

属性

type:String [read-only]

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

文件类型。在 Windows 上，此属性是文件扩展名。在 Macintosh 上，此属性是由四个字符组成的文件类型。如果未填充 FileReference 对象，则为获得此属性的值而执行的调用将返回 null。

实现
public function get type():String

引发

构造函数详细信息

FileReference

()

构造函数

public function FileReference()

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

创建新的 FileReference 对象。在填充后，FileReference 对象表示用户本地磁盘上的文件。

另请参见

FileReference.browse()

方法详细信息

browse

()

方法

public function browse(typeFilter:Array = null):Boolean

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

显示一个文件浏览对话框，让用户选择要上载的文件。该对话框对于用户的操作系统来说是本机的。用户可以选择本地计算机上的文件，也可以选择其它系统上的文件，例如，通过 Windows 上的 UNC 路径选择文件。

当调用此方法并且用户成功选择文件时，会使用该文件的属性填充此 FileReference 对象的属性。以后每次调用 FileReference.browse() 方法时，FileReference 对象的属性都重置为用户在对话框中选择的文件。每次只能执行一个 browse() 或 download() 会话（因为每次只能调用一个对话框）。

使用 typeFilter 参数，可决定对话框显示哪些文件。

参数

typeFilter:Array (default = null) — 一个 FileFilter 实例数组，用于过滤在对话框中显示的文件。如果省略此参数，则显示所有文件。有关详细信息，请参阅 FileFilter 类。

Boolean — 如果参数有效并且打开了文件浏览对话框，则返回 true。在以下情况下，browse 方法返回 false：未打开对话框；正在进行另一个浏览器会话；使用 typelist 参数，但未能在数组的任一元素中提供描述或扩展名字符串。

事件

	`select:Event` — 当用户从浏览文件选择器成功选择了项目时调度。

	`cancel:Event` — 当用户取消文件上载浏览窗口时调度。

引发

	`IllegalOperationError` — 在以下情况下引发：1) 另一个 FileReference 或 FileReferenceList 浏览会话正在进行中；每次仅能执行一个文件浏览会话。 2) 用户 mms.cfg 文件中的某个设置禁止此操作。

	`ArgumentError` — 如果 `typeFilter` 数组包含格式不正确的 FileFilter 对象，将引发异常。有关 FileFilter 对象正确格式的信息，请参阅 FileFilter 类。

另请参见

select event
cancel event
FileReference.download()
FileReferenceList.browse()
处理文件上载和下载

cancel

()

方法

public function cancel():void

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

取消正在对该 FileReference 对象执行的任何上载或下载操作。调用此方法并不会调度 cancel 事件。仅在用户通过退出文件上载或下载对话框来取消操作时，才会调度该事件。

download

()

方法

public function download(request:URLRequest, defaultFileName:String = null):void

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

打开对话框，以允许用户从远程服务器下载文件。虽然 Flash Player 没有限制可上载或下载的文件的大小，但是播放器正式支持的上载或下载文件大小最大为 100 MB。

download() 方法首先打开一个操作系统对话框，让用户输入文件名并在本地计算机上选择用于保存文件的位置。用户选择了位置并确认下载操作时（例如，单击“保存”）后，开始从远程服务器下载。侦听器接收事件来指示下载的进度、成功或失败。为了在调用 download() 后确定对话框和下载操作的状态，ActionScript 代码必须对 cancel、open、progress 和 complete 等事件进行侦听。

FileReference.upload() 和 FileReference.download() 函数是非阻塞式的。这些函数在调用它们之后即返回，而不会等待文件传输完成。此外，若 FileReference 对象离开作用域，则对该对象尚未完成的上载或下载操作将在它离开作用域后被取消。只要希望上载或下载操作继续，就应确保将 FileReference 对象保留在作用域中。

成功下载文件之后，将使用本地文件的属性填充 FileReference 对象的属性。如果下载成功，将调度 complete 事件。

每次只能执行一个 browse() 或 download() 会话（因为每次只能调用一个对话框）。

此方法支持使用 HTTP 或 HTTPS 下载任何文件类型。

注意：如果服务器要求用户身份验证，则只有在浏览器中运行的 SWF 文件（即使用浏览器插件或 ActiveX 控件的文件）才可以提供对话框来提示用户输入用户名和密码以进行身份验证，并且只适用于下载。对于使用插件或 ActiveX 控件进行的上载操作，以及使用独立或外部播放器进行的上载和下载操作，文件传输会失败。

使用此方法时，请考虑 Flash Player 安全模型：

如果执行调用的 SWF 文件在不受信任的本地沙箱中，则不允许进行加载操作。
默认行为是拒绝沙箱之间的访问。网站可通过添加跨域策略文件来实现对资源的访问。
可以在包含 SWF 内容的 HTML 页中设置 object 和 embed 标签的 allowNetworking 参数，防止 SWF 文件使用此方法。

有关详细信息，请参阅以下部分：

security chapter（在《ActionScript 3.0 编程》一书中）和有关 LiveDocs 的最新注释
Flash Player 9 Security White Paper

参数

	`request:URLRequest` — URLRequest 对象。 URLRequest 对象的 `url` 属性应包含要下载到本地计算机的文件的 URL。若此参数为 `null`，将引发异常。要向服务器发送 `POST` 或 GET 参数，请将 `URLRequest.data` 的值设置为您的参数，并将 `URLRequest.method` 设置为 `URLRequestMethod.POST` 或 `URLRequestMethod.GET`。在某些浏览器上，URL 字符串长度受限。在某些浏览器或服务器上，长度超过 256 个字符的字符串可能失败。

	`defaultFileName:String` (default = `null`) — 对话框中显示的要下载文件的默认文件名。此字符串不能包含以下字符：/ \ : * ? " < > \| % 如果省略此参数，将分析出远程 URL 的文件名并用作默认文件名。

事件

	`open:Event` — 当下载操作开始时调度。

	`progress:ProgressEvent` — 在文件下载操作期间进行定期调度。

	`complete:Event` — 当文件下载操作成功完成时调度。

	`cancel:Event` — 当用户取消对话框时调度。

	`select:Event` — 当用户从对话框中选择要下载的文件时调度。

	`securityError:SecurityErrorEvent` — 当由于安全错误导致下载失败时调度。

	`ioError:IOErrorEvent` — 由于下列任一原因而调度：正在读取或传输文件时发生输入/输出错误。 SWF 文件尝试在独立或外部播放器中从要求身份验证的服务器下载文件。在下载期间，独立播放器和外部播放器不为用户提供用于输入密码的方法。如果这些播放器中的 SWF 文件尝试从要求身份验证的服务器下载文件，则下载会失败。只有在 ActiveX 控件和浏览器插件播放器中，文件下载才有可能成功。

引发

	`IllegalOperationError` — 在以下情况下引发：1) 另一个浏览会话正在进行中；每次仅能执行一个文件浏览会话。 2) 传递给 `request` 的值不包含有效的路径或协议。 3) 要下载的文件的名称中包含禁止使用的字符。 4) 用户 mms.cfg 文件中的某个设置禁止此操作。

	`SecurityError` — 本地不受信任的 SWF 文件可能无法与 Internet 进行通信。要避免这种情况，请将此 SWF 文件重新分类为只能与远程内容交互或受信任。引发此异常时会显示一条消息，指明由于本地文件安全性限制而不允许访问的文件名和 URL。

	`ArgumentError` — 如果 `url.data` 为 ByteArray 类型，将引发异常。当与 `FileReference.upload()` 和 `FileReference.download()` 方法一起使用时，`url.data` 只能为 URLVariables 或 String 类型。

	`MemoryError` — 发生此错误的原因有：1) Flash Player 无法将 `URLRequest.data` 参数从 UTF8 转换为 MBCS。如果传递给 `FileReference.download()` 方法的 URLRequest 对象设置为执行 GET 操作并且 `System.useCodePage` 设置为 `true`，将发生该错误。 2) Flash Player 无法为 `POST` 数据分配内存。如果传递给 `FileReference.download()` 方法的 URLRequest 对象设置为执行 `POST` 操作，将发生该错误。

另请参见

FileReference.browse()
FileReferenceList.browse()
FileReference.upload()
处理文件上载和下载
Flash Player 安全性

示例
如何使用示例

下面的示例演示 download 事件对象的用法。要运行此示例，请将 downloadURL.url 属性更改为指向一个实际的域和文件，而不是虚拟的 http://www.[yourDomain].com/SomeFile.pdf。您可能还需要编译 SWF 文件，将“本地回放安全性”设置为“只访问网络”，或更新 Flash Player 的安全设置，以允许此文件网络访问。


package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.FileReference;
    import flash.net.URLRequest;
    import flash.net.FileFilter;

    public class FileReference_download extends Sprite {
        private var downloadURL:URLRequest;
        private var fileName:String = "SomeFile.pdf";
        private var file:FileReference;

        public function FileReference_download() {
            downloadURL = new URLRequest();
            downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
            file = new FileReference();
            configureListeners(file);
            file.download(downloadURL, fileName);
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.CANCEL, cancelHandler);
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            dispatcher.addEventListener(Event.SELECT, selectHandler);
        }

        private function cancelHandler(event:Event):void {
            trace("cancelHandler: " + event);
        }

        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
        }

        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }

        private function openHandler(event:Event):void {
            trace("openHandler: " + event);
        }

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

        private function securityErrorHandler(event:SecurityErrorEvent):void {
            trace("securityErrorHandler: " + event);
        }

        private function selectHandler(event:Event):void {
            var file:FileReference = FileReference(event.target);
            trace("selectHandler: name=" + file.name + " URL=" + downloadURL.url);
        }
    }
}

upload

()

方法

public function upload(request:URLRequest, uploadDataFieldName:String = "Filedata", testUpload:Boolean = false):void

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

开始将用户选择的文件上载到远程服务器。虽然 Flash Player 没有限制可上载或下载的文件的大小，但是播放器正式支持的上载或下载文件大小最大为 100 MB。调用此方法之前，必须先调用 FileReference.browse() 或 FileReferenceList.browse() 方法。

侦听器接收事件来指示上载的进度、成功或失败。尽管可以使用 FileReferenceList 对象让用户选择多个要上载的文件，但必须逐个上载文件。为此，需遍历由 FileReference 对象组成的 FileReferenceList.fileList 数组。

文件上载到在 url 参数中传递的 URL。该 URL 必须是配置为接受上载的服务器脚本。 Flash Player 使用 HTTP POST 方法上载文件。处理上载的服务器脚本应收到包含下列元素的 POST 请求：

Content-Type ，属于 multipart/form-data
Content-Disposition，其 name 属性默认情况下设置为 "Filedata"，filename 属性设置为原始文件的名称
文件的二进制内容

对于范例 POST 请求，请参阅有关 uploadDataFieldName 参数的描述。可以使用 upload() 方法向服务器发送 POST 或 GET 参数，请参阅有关 request 参数的描述。

如果 testUpload 参数为 true，并且要上载的文件大于约 10 KB，则基于 Windows 的 Flash Player 在上载实际的文件之前，会先发送不带内容的测试上载 POST 操作，以验证传输操作是否可能成功。之后，Flash Player 会再次发送 POST 操作，这时其中将包含实际的文件内容。对于小于 10 KB 的文件，Flash Player 则仅执行一次上载 POST 操作，其中包含要上载的实际文件内容。基于 Macintosh 的 Flash Player 不执行测试上载 POST 操作。

使用此方法时，请考虑 Flash Player 安全模型的以下限制：

如果执行调用的 SWF 文件在不受信任的本地沙箱中，则不允许进行加载操作。
默认行为是拒绝沙箱之间的访问。网站可通过添加跨域策略文件来实现对资源的访问。
可以在包含 SWF 内容的 HTML 页中设置 object 和 embed 标签的 allowNetworking 参数，防止 SWF 文件使用此方法。

有关详细信息，请参阅以下部分：

security chapter（在《ActionScript 3.0 编程》一书中）和有关 LiveDocs 的最新注释
Flash Player 9 Security White Paper

参数

	`request:URLRequest` — URLRequest 对象，URLRequest 对象的 `url` 属性应包含特定服务器脚本的 URL，该服务器脚本被配置为通过 HTTP `POST` 调用处理上载。在某些浏览器上，URL 字符串长度受限。在某些浏览器或服务器上，长度超过 256 个字符的字符串可能失败。若此参数为 `null`，将引发异常。该 URL 可以是 HTTP，或者为了安全地进行上载，也可以是 HTTPS。若要使用 HTTPS，请在 `url` 参数中使用 HTTPS URL。如果在 `url` 参数中没有指定端口号，则默认情况下，Flash Player 将使用端口 80（对于 HTTP）或端口 443（对于 HTTPS）。要向服务器发送 `POST` 或 `GET` 参数，请将 URLRequest 对象的 `data` 属性设置为您的参数，并将 `method` 属性设置为 `URLRequestMethod.POST` 或 `URLRequestMethod.GET`。

	`uploadDataFieldName:String` (default = "`Filedata`") — 在上载 `POST` 操作中位于文件数据之前的字段名。 `uploadDataFieldName` 值必须为非空字符串。默认情况下，`uploadDataFieldName` 的值为 `"Filedata"`，如下面的范例 `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--

	`testUpload:Boolean` (default = `false`) — 请求上载测试文件的设置。如果 `testUpload` 为 `true`，则对于大于 10 KB 的文件，Flash Player 将尝试进行内容长度为 0 的测试文件上载 `POST`。测试上载将检查实际文件上载是否可能成功，以及服务器身份验证（如果需要）是否可能成功。测试上载仅适用于 Windows 播放器。

事件

	`open:Event` — 当上载操作开始时调度。

	`progress:ProgressEvent` — 在文件上载操作期间进行定期调度。

	`complete:Event` — 当文件上载操作成功完成时调度。

	`uploadCompleteData:Event` — 成功上载文件并从服务器接收数据之后调度。

	`securityError:SecurityErrorEvent` — 由于安全错误导致上载失败时调度。

	`httpStatus:HTTPStatusEvent` — 由于 HTTP 错误导致上载失败时调度。

	`ioError:IOErrorEvent` — 在下列任一情况下调用：由于 Flash Player 在读取、写入或传输文件时出现输入/输出错误，导致上载失败。由于 SWF 文件试图将文件上载到要求身份验证（如用户名和密码）的服务器上，导致上载失败。在上载期间，Flash Player 不为用户提供输入密码的方法。由于 `url` 参数包含无效协议，导致上载失败。 `FileReference.upload()` 必须使用 HTTP 或 HTTPS。

引发

	`SecurityError` — 本地不受信任的 SWF 文件可能无法与 Internet 进行通信。要避免这种情况，请将此 SWF 文件重新分类为只能与远程内容交互或受信任。引发此异常时会附带一个消息，指明不允许访问的本地文件和 URL 的名称。

	`IllegalOperationError` — 在以下情况下引发：1) 另一个 FileReference 或 FileReferenceList 浏览会话正在进行中；每次仅能执行一个文件浏览会话。 2) URL 参数为无效的路径或协议。文件上载必须使用 HTTP 协议，文件下载则必须使用 FTP 或 HTTP 协议。 3) `uploadDataFieldName` 参数设置为 `null`。 4) 用户 mms.cfg 文件中的某个设置禁止此操作。

	`ArgumentError` — 在以下情况下引发：1) `uploadDataFieldName` 参数为空字符串。 2) `url.data` 为 ByteArray 类型。当与 `FileReference.upload()` 和 `FileReference.download()` 方法一起使用时，`url.data` 只能为 URLVariables 或 String 类型。

	`MemoryError` — 发生此错误的原因有：1) Flash Player 无法将 `URLRequest.data` 参数从 UTF8 转换为 MBCS。如果传递给 `FileReference.upload()` 的 URLRequest 对象设置为执行 GET 操作并且 `System.useCodePage` 设置为 `true`，将发生该错误。 2) Flash Player 无法为 `POST` 数据分配内存。如果传递给 `FileReference.upload()` 的 URLRequest 对象设置为执行 `POST` 操作，将发生该错误。

另请参见

FileReference.browse()
FileReferenceList.browse()
FileReference.download()
FileReferenceList.fileList
处理文件上载和下载
Flash Player 安全性

事件详细信息

cancel

事件

事件对象类型: flash.events.Event
Event.type property = flash.events.Event.CANCEL

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

当用户通过文件浏览对话框取消文件上载或下载时调度。如果用户通过其它方式（关闭浏览器或停止当前应用程序）取消上载或下载，则 Flash Player 不会调度该事件。

定义 cancel 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	对已取消其操作的对象的引用。

示例
如何使用示例

下面的示例演示 cancel 事件对象的用法。要运行此示例，请将 downloadURL.url 属性更改为指向一个实际的域和文件，而不是虚拟的 http://www.[yourDomain].com/SomeFile.pdf。您可能还需要编译 SWF 文件，将“本地回放安全性”设置为“只访问网络”，或更新 Flash Player 的安全设置，以允许此文件网络访问。


package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.FileReference;
    import flash.net.URLRequest;

    public class FileReference_event_cancel extends Sprite {
        private var downloadURL:URLRequest;
        private var fileName:String = "SomeFile.pdf";
        private var file:FileReference;

        public function FileReference_event_cancel() {
            downloadURL = new URLRequest();
            downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
            file = new FileReference();
            file.addEventListener(Event.CANCEL, cancelHandler);
            file.download(downloadURL, fileName);
        }
        private function cancelHandler(event:Event):void {
            trace("cancelHandler: " + event);
        }
    }
}

complete

事件

事件对象类型: flash.events.Event
Event.type property = flash.events.Event.COMPLETE

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

当下载操作完成或上载操作生成 HTTP 状态代码 200 时调度。对于文件下载操作，在 Flash Player 将整个文件下载到磁盘上时调度此事件。对于文件上载操作，在 Flash Player 接收到 HTTP 状态代码 200（来自接收传输的服务器）之后调度此事件。

定义 complete 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	已完成加载的网络对象。

示例
如何使用示例

下面的示例演示 complete 事件对象的用法。要运行此示例，请将 downloadURL.url 属性更改为指向一个实际的域和文件，而不是虚拟的 http://www.[yourDomain].com/SomeFile.pdf。您可能还需要编译 SWF 文件，将“本地回放安全性”设置为“只访问网络”，或更新 Flash Player 的安全设置，以允许此文件网络访问。


package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.FileReference;
    import flash.net.URLRequest;

    public class FileReference_event_complete extends Sprite {
        private var downloadURL:URLRequest;
        private var fileName:String = "SomeFile.pdf";
        private var file:FileReference;

        public function FileReference_event_complete() {
            downloadURL = new URLRequest();
            downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
            file = new FileReference();
            configureListeners(file);
            file.download(downloadURL, fileName);
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.CANCEL, cancelHandler);
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            dispatcher.addEventListener(Event.SELECT, selectHandler);
        }

        private function cancelHandler(event:Event):void {
            trace("cancelHandler: " + event);
        }

        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
        }

        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }

        private function openHandler(event:Event):void {
            trace("openHandler: " + event);
        }

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

        private function securityErrorHandler(event:SecurityErrorEvent):void {
            trace("securityErrorHandler: " + event);
        }

        private function selectHandler(event:Event):void {
            var file:FileReference = FileReference(event.target);
            trace("selectHandler: name=" + file.name + " URL=" + downloadURL.url);
        }
    }
}

另请参见

FileReference.download()
FileReference.upload()

httpStatus

事件

事件对象类型: flash.events.HTTPStatusEvent
HTTPStatusEvent.type property = flash.events.HTTPStatusEvent.HTTP_STATUS

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

当上载失败并且存在可用来描述失败的 HTTP 状态代码时调度。调度 httpStatus 事件之后，将调度 ioError 事件。

仅在上载失败时才调度 httpStatus 事件。由于 Flash Player 在文件下载期间依赖浏览器的方式，此事件并不适用于下载失败。如果下载由于 HTTP 错误而失败，则将错误报告为 I/O 错误。

定义 httpStatus 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`status`	由服务器返回的 HTTP 状态代码。
`target`	接收 HTTP 状态代码的网络对象。

另请参见

FileReference.upload()

ioError

事件

事件对象类型: flash.events.IOErrorEvent
IOErrorEvent.type property = flash.events.IOErrorEvent.IO_ERROR

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

当上载或下载失败时调度。文件传输会失败的原因有：

当播放器正在读取、写入或传输文件时发生输入/输出错误。
SWF 文件尝试将文件上载到要求身份验证（如用户名和密码）的服务器。在上载期间，Flash Player 不为用户提供输入密码的方法。如果 SWF 文件尝试将文件上载到要求身份验证的服务器，上载将失败。
SWF 文件尝试在独立播放器或外部播放器中从要求身份验证的服务器下载文件。在下载期间，独立播放器和外部播放器不提供用户用于输入密码的方法。如果这些播放器中的 SWF 文件尝试从要求身份验证的服务器下载文件，则下载会失败。只有在 ActiveX 控件和浏览器插件播放器中，文件下载才有可能成功。
传递到 upload() 方法中的 url 参数的值包含无效协议。有效协议包括 HTTP 和 HTTPS。

重要提示：只有在浏览器中运行的 Flash 应用程序（即，使用浏览器插件或 ActiveX 控件的应用程序）才可以提供对话框来提示用户输入用户名和密码以进行身份验证，并且只适用于下载。对于使用插件或 ActiveX 控件进行的上载操作，以及使用独立播放器或外部播放器进行的上载或下载操作，文件传输会失败。

定义 ioError 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	发生输入/输出错误的网络对象。
`text`	要显示为错误消息的文本。

另请参见

FileReference.download()
FileReference.upload()

open

事件

事件对象类型: flash.events.Event
Event.type property = flash.events.Event.OPEN

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

当上载或下载操作开始时调度。

定义 open 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	已打开连接的网络对象。

示例
如何使用示例


package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.FileReference;
    import flash.net.URLRequest;
    import flash.net.FileFilter;

    public class FileReference_download extends Sprite {
        private var downloadURL:URLRequest;
        private var fileName:String = "SomeFile.pdf";
        private var file:FileReference;

        public function FileReference_download() {
            downloadURL = new URLRequest();
            downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
            file = new FileReference();
            configureListeners(file);
            file.download(downloadURL, fileName);
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.CANCEL, cancelHandler);
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            dispatcher.addEventListener(Event.SELECT, selectHandler);
        }

        private function cancelHandler(event:Event):void {
            trace("cancelHandler: " + event);
        }

        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
        }

        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }

        private function openHandler(event:Event):void {
            trace("openHandler: " + event);
        }

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

        private function securityErrorHandler(event:SecurityErrorEvent):void {
            trace("securityErrorHandler: " + event);
        }

        private function selectHandler(event:Event):void {
            var file:FileReference = FileReference(event.target);
            trace("selectHandler: name=" + file.name + " URL=" + downloadURL.url);
        }
    }
}

另请参见

FileReference.download()
FileReference.upload()

progress

事件

事件对象类型: flash.events.ProgressEvent
ProgressEvent.type property = flash.events.ProgressEvent.PROGRESS

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

在文件上载或下载操作期间定期调度。 progress 事件在 Flash Player 将字节传输到服务器时调度，即使传输最终没有成功，也会在传输期间定期调度。要确定文件传输是否真正成功和完成以及何时真正成功和完成，需要侦听 complete 事件。

在某些情况下，接收不到 progress 事件。例如，当所传输的文件非常小或者上载或下载速度非常快时，可能就不会调度 progress 事件。

在低于 OS X 10.3 版本的 Macintosh 平台上不能确定文件上载进度。progress 事件在上载操作期间调用，但 progress 事件的 bytesLoaded 属性值为 -1，表示不能确定进度。

定义 progress 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`bytesLoaded`	在侦听器处理事件时加载的项数或字节数。
`bytesTotal`	如果加载进程成功，最终将加载的项目或字节总数。
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	报告进度的网络对象。

示例
如何使用示例

下面的示例演示 progress 事件的用法。要运行此示例，请将 downloadURL.url 属性更改为指向一个实际的域和文件，而不是虚拟的 http://www.[yourDomain].com/SomeFile.pdf。您可能还需要编译 SWF 文件，将“本地回放安全性”设置为“只访问网络”，或更新 Flash Player 的安全设置，以允许此文件网络访问。


package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.FileReference;
    import flash.net.URLRequest;

    public class FileReference_event_progress extends Sprite {
        private var downloadURL:URLRequest;
        private var fileName:String = "SomeFile.pdf";
        private var file:FileReference;

        public function FileReference_event_progress() {
            downloadURL = new URLRequest();
            downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
            file = new FileReference();
            file.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            file.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            file.addEventListener(Event.COMPLETE, completeHandler);
            file.download(downloadURL, fileName);
        }

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler: name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }
        
        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }
        
        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
        }
    }
}

另请参见

FileReference.complete
flash.events.ProgressEvent
FileReference.download()
FileReference.upload()

securityError

事件

事件对象类型: flash.events.SecurityErrorEvent
SecurityErrorEvent.type property = flash.events.SecurityErrorEvent.SECURITY_ERROR

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

当对 FileReference.upload() 或 FileReference.download() 方法的调用尝试将文件上载到服务器，或是从调用方安全沙箱外部的服务器上下载文件时进行调度。用于描述发生的特定错误的文本属性的值通常为 "securitySandboxError"。执行调用的 SWF 可能已经尝试访问其域外部的 SWF 文件，但却无权这样做。您可以通过使用跨域策略文件来尝试纠正此错误。

SecurityErrorEvent.SECURITY_ERROR 常量定义 securityError 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	报告安全错误的网络对象。
`text`	要显示为错误消息的文本。

另请参见

FileReference.download()
FileReference.upload()
Flash Player 安全性

select

事件

事件对象类型: flash.events.Event
Event.type property = flash.events.Event.SELECT

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9

当用户从文件浏览对话框选择要上载或下载的文件时调度。（调用 FileReference.browse()、FileReferenceList.browse() 或 FileReference.download() 方法时将打开此对话框。）当用户选择文件并确认操作（例如，通过单击“确定”）时，会填充 FileReference 对象的属性。

select 事件的运行方式会稍有不同，具体取决于调用它的方法。在调用 browse() 后调度 select 事件时，Flash Player 能够读取 FileReference 对象的所有属性，因为用户所选的文件位于本地文件系统上。在调用 download() 后调度 select 时，Flash Player 只能读取 name 属性，因为在调度 select 时，文件尚未下载到本地文件系统。如果已下载了文件，则调度 complete 时，Flash Player 将可以读取 FileReference 对象的所有其它属性。

定义 select 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	FileReference 对象，已在其中选定了一个项目。

示例
如何使用示例

下面的示例演示 select 事件对象的用法。要运行此示例，请将 uploadURL.url 属性更改为指向一个实际的域和文件，而不是虚拟的 http://www.[yourDomain].com/SomeFile.pdf。您可能还需要编译 SWF 文件，将“本地回放安全性”设置为“只访问网络”，或更新 Flash Player 的安全设置，以允许此文件网络访问。要想可以从桌面运行这个示例，您的服务器还需要发送 crossdomain.xml 文件。如果触发了 ioErrorHandler() 函数，可能需要使用一个有效的 URL 来更新提供的 uploadURL，此有效的 URL 被配置成接收上载。

 
package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.FileReference;
    import flash.net.URLRequest;

    public class FileReference_event_select extends Sprite {
        private var uploadURL:URLRequest;
        private var file:FileReference;

        public function FileReference_event_select() {
            uploadURL = new URLRequest();
            uploadURL.url = "http://www.[yourDomain].com/yourUploadHandlerScript.cfm";
            file = new FileReference();
            file.addEventListener(Event.SELECT, selectHandler);
            file.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            file.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            file.addEventListener(Event.COMPLETE, completeHandler);
            file.browse();
        }

        private function selectHandler(event:Event):void {
            var file:FileReference = FileReference(event.target);
            trace("selectHandler: name=" + file.name + " URL=" + uploadURL.url);
            file.upload(uploadURL);
        }

        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler: name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
        }
    }
}

uploadCompleteData

事件

事件对象类型: flash.events.DataEvent
DataEvent.type property = flash.events.DataEvent.UPLOAD_COMPLETE_DATA

语言版本 :

ActionScript 3.0

Player 版本 :

Flash Player 9.0.28.0

成功上载然后从服务器接收数据之后调度。如果未从服务器返回数据，则不调度此事件。

定义 uploadCompleteData 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`data`	成功上载文件后从服务器返回的原始数据。
`target`	成功上载后接收数据的 FileReference 对象。

示例如何使用示例

下例显示在运行时加载的文件的数据格式和状态信息。

注意：若要运行此示例，请更改 uploadURL.url 属性以指向实际的 URL，而不是示例中虚拟的地址。 URL 应指向名为 yourUploadHandlerScript.cfm 的文件，该文件位于指定 URL 的根 Web 目录下。根据您的配置，您可能还需要编译 SWF 文件，将“本地回放安全性”设置为“只访问网络”，或更新 Flash Player 的安全设置，以允许此文件网络访问。

package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.FileFilter;
    import flash.net.FileReference;
    import flash.net.URLRequest;

    public class FileReferenceExample extends Sprite {
        private var uploadURL:URLRequest;
        private var file:FileReference;

        public function FileReferenceExample() {
            uploadURL = new URLRequest();
            uploadURL.url = "http://www.[yourDomain].com/yourUploadHandlerScript.cfm";
            file = new FileReference();
            configureListeners(file);
            file.browse(getTypes());
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.CANCEL, cancelHandler);
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            dispatcher.addEventListener(Event.SELECT, selectHandler);
            dispatcher.addEventListener(DataEvent.UPLOAD_COMPLETE_DATA,uploadCompleteDataHandler);
        }

        private function getTypes():Array {
            var allTypes:Array = new Array(getImageTypeFilter(), getTextTypeFilter());
            return allTypes;
        }

        private function getImageTypeFilter():FileFilter {
            return new FileFilter("Images (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg;*.jpeg;*.gif;*.png");
        }

        private function getTextTypeFilter():FileFilter {
            return new FileFilter("Text Files (*.txt, *.rtf)", "*.txt;*.rtf");
        }

        private function cancelHandler(event:Event):void {
            trace("cancelHandler: " + event);
        }

        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
        }

        private function uploadCompleteDataHandler(event:Event):void {
            trace("uploadCompleteData: " + event);
        }

        private function httpStatusHandler(event:HTTPStatusEvent):void {
            trace("httpStatusHandler: " + event);
        }
        
        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }

        private function openHandler(event:Event):void {
            trace("openHandler: " + event);
        }

        private function progressHandler(event:ProgressEvent):void {
            var file:FileReference = FileReference(event.target);
            trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

        private function securityErrorHandler(event:SecurityErrorEvent):void {
            trace("securityErrorHandler: " + event);
        }

        private function selectHandler(event:Event):void {
            var file:FileReference = FileReference(event.target);
            trace("selectHandler: name=" + file.name + " URL=" + uploadURL.url);
            file.upload(uploadURL);
        }
    }
}

当前页: http://livedocs.adobe.com/flash/9.0_cn/ActionScriptLangRefV3/flash/net/FileReference.html

ActionScript 3.0 语言和组件参考		全部包 \| 全部类 \| 语言元素 \| 索引 \| 附录 \| 约定 \| 帧无帧
FileReference	属性 \| 方法 \| 事件 \| 示例

包	flash.net
类	public class FileReference
继承	FileReference EventDispatcher Object