flash.net.URLLoader

	属性	定义方
		bytesLoaded : uint = 0 指示加载操作期间到目前为止加载的字节数。	URLLoader
		bytesTotal : uint = 0 指示所下载数据中的字节总数。	URLLoader
		constructor : Object 对类对象或给定对象实例的构造函数的引用。	Object
		data : * 从加载操作接收的数据。	URLLoader
		dataFormat : String = "text" 控制是以文本 (URLLoaderDataFormat.TEXT)、原始二进制数据 (URLLoaderDataFormat.BINARY) 还是 URL 编码变量 (URLLoaderDataFormat.VARIABLES) 形式接收下载的数据。	URLLoader
		prototype : Object [静态] 对类或函数对象的原型对象的引用。	Object

	方法	定义方
		URLLoader(request:URLRequest = null) 创建 URLLoader 对象。	URLLoader
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void [override] 使用 EventDispatcher 对象注册事件侦听器对象，以使侦听器能够接收事件通知。	URLLoader
		close():void 关闭进行中的加载操作。	URLLoader
		dispatchEvent(event:Event):Boolean 将事件调度到事件流中。	EventDispatcher
		hasEventListener(type:String):Boolean 检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。	EventDispatcher
		hasOwnProperty(name:String):Boolean 指示对象是否已经定义了指定的属性。	Object
		isPrototypeOf(theClass:Object):Boolean 指示 Object 类的实例是否在指定为参数的对象的原型链中。	Object
		load(request:URLRequest):void 从指定的 URL 发送和加载数据。	URLLoader
		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
		valueOf():Object 返回指定对象的原始值。	Object
		willTrigger(type:String):Boolean 检查是否用此 EventDispatcher 对象或其任何始祖为指定事件类型注册了事件侦听器。	EventDispatcher

摘要	定义方
activate	[广播事件] Flash Player 或 AIR 应用程序获得操作系统焦点并变为活动状态时将调度此事件。	EventDispatcher
complete	在对所有已接收数据进行解码并将其放在 URLLoader 对象的 data 属性中以后调度。	URLLoader
deactivate	[广播事件] Flash Player 或 AIR 应用程序失去操作系统焦点并变为非活动状态时将调度此事件。	EventDispatcher
httpResponseStatus	在 load() 方法调用尝试通过 HTTP 访问数据，并且 Adobe AIR 可以检测并返回请求的状态代码时调度。	URLLoader
httpStatus	在 URLLoader.load() 方法调用尝试通过 HTTP 访问数据时调度。	URLLoader
ioError	若对 URLLoader.load() 的调用导致致命错误并因此终止了下载，则进行调度。	URLLoader
open	在调用 URLLoader.load() 方法之后开始下载操作时调度。	URLLoader
progress	在下载操作过程中收到数据时调度。	URLLoader
securityError	若对 URLLoader.load() 的调用尝试从安全沙箱外部的服务器加载数据，则进行调度。	URLLoader

属性详细信息

bytesLoaded

属性

var bytesLoaded:uint = 0

运行时版本:

1.0

指示加载操作期间到目前为止加载的字节数。

bytesTotal

属性

var bytesTotal:uint = 0

运行时版本:

1.0

指示所下载数据中的字节总数。正在进行加载操作时该属性包含 0，完成操作时会填充该属性。另外，丢失的 Content-Length 标题将会导致 bytesTotal 不确定。

data

属性

var data:*

运行时版本:

1.0

从加载操作接收的数据。只有完成加载操作时，才会填充该属性。该数据的格式取决于 dataFormat 属性的设置：

如果 dataFormat 属性是 URLLoaderDataFormat.TEXT，则所接收的数据是一个包含已加载文件文本的字符串。

如果 dataFormat 属性是 URLLoaderDataFormat.BINARY，则所接收的数据是一个包含原始二进制数据的 ByteArray 对象。

如果 dataFormat 属性是 URLLoaderDataFormat.VARIABLES，则所接收的数据是一个包含 URL 编码变量的 URLVariables 对象。

另请参见

URLLoaderDataFormat
URLLoader.dataFormat

dataFormat

属性

var dataFormat:String = "text"

运行时版本:

1.0

控制是以文本 (URLLoaderDataFormat.TEXT)、原始二进制数据 (URLLoaderDataFormat.BINARY) 还是 URL 编码变量 (URLLoaderDataFormat.VARIABLES) 接收下载的数据。

如果 dataFormat 属性的值是 URLLoaderDataFormat.TEXT，则所接收的数据是一个包含已加载文件文本的字符串。

如果 dataFormat 属性的值是 URLLoaderDataFormat.BINARY，则所接收的数据是一个包含原始二进制数据的 ByteArray 对象。

如果 dataFormat 属性的值是 URLLoaderDataFormat.VARIABLES，则所接收的数据是一个包含 URL 编码变量的 URLVariables 对象。

默认值为 URLLoaderDataFormat.TEXT.

另请参见

URLLoaderDataFormat

构造函数详细信息

URLLoader

()

构造函数

function URLLoader(request:URLRequest = null)

运行时版本:

1.0

创建 URLLoader 对象。

参数

request:URLRequest (default = null) — 一个 URLRequest 对象，指定要下载的 URL。如果省略该参数，则不开始加载操作。如果已指定参数，则立即开始加载操作（有关详细信息，请参阅 load 条目）。

另请参见

URLLoader.load()

方法详细信息

addEventListener

()

方法

  function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void

运行时版本:

1.0

使用 EventDispatcher 对象注册事件侦听器对象，以使侦听器能够接收事件通知。

AIR 运行时中的 JavaScript 代码使用此方法注册 AIR API 定义的事件的事件侦听器。对于其它 JavaScript 事件（如 DOM body 对象的 onload 事件），您可以像对浏览器中运行的内容一样使用标准事件处理技术。

成功注册一个事件侦听器后，无法通过额外调用 addEventListener() 来更改其优先级。要更改侦听器的优先级，必须首先调用 removeListener()。然后，可以使用新的优先级再次注册该侦听器。

请记住，注册该侦听器后，如果继续调用具有不同 type 或 useCapture 值的 addEventListener()，则会创建单独的侦听器注册。

如果不再需要某个事件侦听器，可调用 removeEventListener() 删除它，否则会产生内存问题。由于垃圾回收器不会删除仍包含引用的对象，因此不会从内存中自动删除使用已注册事件侦听器的对象。

复制 EventDispatcher 实例时并不复制其中附加的事件侦听器。（如果新近创建的节点需要一个事件侦听器，必须在创建该节点后附加该侦听器。）但是，如果移动 EventDispatcher 实例，则其中附加的事件侦听器也会随之移动。

参数

	`type:String` — 事件的类型。

	`listener:Function` — 处理事件的侦听器函数。此函数必须接受 Event 对象作为其唯一的参数并且不能返回任何结果。函数可以有任何名称。

	`useCapture:Boolean` (default = `false`) — 此参数适用于 SWF 内容所使用的 ActionScript 3.0 显示列表体系结构中的显示对象。

	`priority:int` (default = `0`) — 事件侦听器的优先级。优先级由一个带符号的 32 位整数指定。数字越大，优先级越高。优先级为 n 的所有侦听器会在优先级为 n -1 的侦听器之前得到处理。如果两个或更多个侦听器共享相同的优先级，则按照它们的添加顺序进行处理。默认优先级为 0。

	`useWeakReference:Boolean` (default = `false`) — 确定对侦听器的引用是强引用，还是弱引用。强引用（默认值）可防止您的侦听器被当作垃圾回收。弱引用则没有此作用。类级别成员函数不属于垃圾回收的对象，因此可以对类级别成员函数将 `useWeakReference` 设置为 `true` 而不会使它们受垃圾回收的影响。如果对作为嵌套内部函数的侦听器将 `useWeakReference` 设置为 `true`，则该函数将作为垃圾回收并且不再是永久函数。如果创建对该内部函数的引用（将该函数保存到另一个变量中），则该函数将不作为垃圾回收并仍将保持永久。

()

方法

function close():void

运行时版本:

1.0

关闭进行中的加载操作。任何正在进行中的加载操作将立即终止。如果当前未对 URL 进行流式处理，将引发无效流错误。

load

()

方法

function load(request:URLRequest):void

运行时版本:

1.0

从指定的 URL 发送和加载数据。可以以文本、原始二进制数据或 URL 编码变量格式接收数据，这取决于为 dataFormat 属性所设置的值。请注意 dataFormat 属性的默认值为文本。如果想将数据发送至指定的 URL，则可以在 URLRequest 对象中设置 data 属性。

注意：如果要加载的文件包含非 ASCII 字符（在许多非英语的语言中出现），则建议使用 UTF-8 或 UTF-16 编码（而不是 ASCII 等非 Unicode 格式）来保存文件。

只能与本地文件系统内容交互的沙箱中的 SWF 文件无法加载网络沙箱中的资源所包含的数据，也无法为该资源提供数据。

默认情况下，执行调用的 SWF 文件和加载的 URL 必须在同一域中。例如，位于 www.adobe.com 的 SWF 文件只能从同样位于 www.adobe.com 的源中加载数据。若要从不同的域中加载数据，请在承载数据的服务器上放置一个 URL 策略文件。

无法连接到常用的保留端口。有关已阻止的端口的完整列表，请参阅《ActionScript 3.0 编程》一书中的“限制网络 API”。

在 Flash Player 10 和更高版本中，如果使用包含上载（由 POST 体内的“content-disposition”标头中的“filename”参数表示）的 multipart Content-Type（例如“multipart/form-data”），则 POST 操作会受应用于上载的安全规则的约束：

必须执行 POST 操作以响应用户启动的操作（如鼠标单击或按键）。
如果 POST 操作是跨域的（POST 目标与发送 POST 请求的 SWF 文件不在同一台服务器上），则目标服务器必须提供一个允许跨域访问的 URL 策略文件。

另外，对于任何 multipart Content-Type，语法必须有效（根据 RFC2046 标准）。如果语法无效，则 POST 操作受应用于上载的安全规则约束。

有关安全性的详细信息，请参阅以下部分：

《ActionScript 3.0 编程》一书中的“安全性”一章和 LiveDocs 上的最新评论
Developing AIR Applications（《开发 AIR 应用程序》）一书的“Getting started with Adobe AIR”（Adobe AIR 入门）一章中的“Understanding AIR Security”（了解 AIR 安全性）一节。
Flash Player 9 Security 安全性
Flash Player 开发人员中心主题：安全性

参数

request:URLRequest — 一个 URLRequest 对象，指定要下载的 URL。

事件

	`complete:Event` — 在成功加载数据后调度。

	`httpStatus:HTTPStatusEvent` — 如果通过 HTTP 进行访问，并且当前 Flash Player 环境支持获得状态代码，则除了 `complete` 或 `error` 事件，还可以接收到 HTTPStatusEvent 事件。

	`ioError:IOErrorEvent` — 无法完成加载操作。

	`progress:ProgressEvent` — 在下载操作过程中收到数据时调度。

	`securityError:SecurityErrorEvent` — 加载操作尝试从调用方安全沙箱外部的服务器检索数据。可以通过在服务器上使用策略文件来解决此问题。

	`securityError:SecurityErrorEvent` — 加载操作尝试加载 SWZ 文件（一个 Adobe 平台组件），但是证书无效或摘要与组件不匹配。

	`open:Event` — 在加载操作开始时调度。

	`httpResponseStatus:HTTPStatusEvent` — 在 `load()` 方法调用尝试通过 HTTP 访问数据，并且 Adobe AIR 可以检测并返回请求的状态代码时调度。

引发

	`ArgumentError` — `URLRequest.requestHeader` 对象不能包含某些被禁用的 HTTP 请求标头。有关详细信息，请参阅 URLRequestHeader 类的描述。

	`MemoryError` — 此错误可能由以下原因引起： 1) AIR 无法将 `URLRequest.data` 参数从 UTF8 转换为 MBCS。若传递给 `load()` 的 URLRequest 对象设置为执行 `GET` 操作并且 `System.useCodePage` 设置为 `true`，就会发生该错误。2) AIR 无法为 `POST` 数据分配内存。如果传递给 `load` 的 URLRequest 对象设置为执行 `POST` 操作，将发生该错误。

	`SecurityError` — 本地不受信任的文件可能无法与 Internet 进行通信。可通过将此文件重新分类为只能与远程内容交互或受信任来解决此问题。

	`SecurityError` — 如果尝试连接到常用的保留端口。有关已阻止的端口的完整列表，请参阅《ActionScript 3.0 编程》一书的“安全性”一章中的“限制网络 API”。

	`TypeError` — 所传递的请求参数值或 URLRequest 对象的 `URLRequest.url` 属性为 `null`。

另请参见

URLRequestHeader
URLRequest.requestHeaders
URLRequest.data
URLRequest.digest

事件详细信息

complete

事件

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

运行时版本:

1.0

在对所有已接收数据进行解码并将其放在 URLLoader 对象的 data 属性中以后调度。调度该事件后，可以访问已接收的数据。

Event.COMPLETE 常量定义 complete 事件对象的 type 属性值。

此事件具有以下属性：

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

另请参见

URLLoader.load()

httpResponseStatus

事件

事件对象类型: flash.events.HTTPStatusEvent
属性 HTTPStatusEvent.type = flash.events.HTTPStatusEvent.HTTP_RESPONSE_STATUS

运行时版本:

1.0 1.0

在 load() 方法调用尝试通过 HTTP 访问数据，并且 Adobe AIR 可以检测并返回请求的状态代码时调度。

与 httpStatus 事件不同，httpResponseStatus 事件在传送任何响应数据之前传送。此外，httpResponseStatus 事件还包括 responseHeaders 和 responseURL 属性的值（对于 httpStatus，这些属性未定义）。请注意，在发送任何 complete 或 error 事件之前还将发送 httpResponseStatus（如果有）。

HTTPStatusEvent.HTTP_RESPONSE_STATUS 常量定义 httpResponseStatus 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`responseURL`	从中返回响应的 URL。
`responseHeaders`	响应以 URLRequestHeader 对象的数组形式返回的响应标头。
`status`	由服务器返回的 HTTP 状态代码。
`target`	接收 HTTP 状态代码的网络对象。

另请参见

load()

httpStatus

事件

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

运行时版本:

1.0

在 URLLoader.load() 方法调用尝试通过 HTTP 访问数据时调度。请注意，在发送任何 complete 或 error 事件之前还将发送 httpStatus 事件（如果有）。

HTTPStatusEvent.HTTP_STATUS 常量定义 httpStatus 事件对象的 type 属性值。

此事件具有以下属性：

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

另请参见

URLLoader.load()

ioError

事件

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

运行时版本:

1.0

若对 URLLoader.load() 的调用导致致命错误并因此终止了下载，则进行调度。

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

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`errorID`	与特定错误关联的引用编号（仅限 AIR）。
`target`	发生输入/输出错误的网络对象。
`text`	要显示为错误消息的文本。

另请参见

URLLoader.load()

open

事件

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

运行时版本:

1.0

在调用 URLLoader.load() 方法和开始下载操作时调度。

Event.OPEN 常量用于定义 open 事件对象的 type 属性值。

此事件具有以下属性：

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

另请参见

URLLoader.load()

progress

事件

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

运行时版本:

1.0

在下载操作过程中收到数据时调度。

请注意，对于 URLLoader 对象，在完全接收数据前无法访问该数据。因此，该 progress 事件仅用作有关下载进展的通知。若要在完整下载前访问该数据，请使用 URLStream 对象。

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

此事件具有以下属性：

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

另请参见

URLLoader.load()

securityError

事件

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

运行时版本:

1.0

若对 URLLoader.load() 的调用尝试从安全沙箱外部的服务器加载数据，则进行调度。在对 URLLoader.load() 的调用尝试加载 SWZ 文件而证书无效或摘要字符串与组件不匹配时也会调度。

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

此事件具有以下属性：

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

另请参见

URLLoader.load()

示例

URLLoaderExample.as

下例加载并显示在本地文本文件中找到的数据。它还会跟踪事件处理信息。

注意：要测试此示例，请执行以下操作：

将 AIRAliases.js 文件添加到项目目录。
将名为 urlLoaderExample.txt 的文件放在 localhost HTTP 服务器上。该文件应仅包含以下文本行：answer=42&question=unknown
为该项目创建应用程序描述符文件，并使用 ADL 测试该项目。

该示例代码执行以下操作：

init() 函数创建名为 loader 的 URLLoader 实例和名为 request 的 URLRequest 实例，后者包含要加载的文件的位置和名称。
loader 对象被传递给 configureListeners() 方法，该方法可为每个受支持的 URLLoader 事件添加侦听器。
然后，request 对象被传递给 loader.load()，该方法可加载文本文件。
当 URLLoader 完成文本文件的加载时，将引发 Event.COMPLETE event，同时触发 completeHandler() 方法。completeHandler() 方法通过从该文件中加载的文本创建 URLVariables 对象。对象 URLVariables 将 URL 编码的名称/值对转换成 ActionScript 属性，从而更便于处理加载的数据。


<html>
    <head>
      <script src="AIRAliases.js" />
      <script>
        function init() {
            var loader = new air.URLLoader();
            configureListeners(loader);

            var request = new air.URLRequest("urlLoaderExample.txt");
            try {
                loader.load(request);
            } catch (error) {
                air.trace("Unable to load requested document.");
            }
        }

        function configureListeners(dispatcher) {
            dispatcher.addEventListener(air.Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(air.Event.OPEN, openHandler);
            dispatcher.addEventListener(air.ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(air.SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            dispatcher.addEventListener(air.HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
            dispatcher.addEventListener(air.IOErrorEvent.IO_ERROR, ioErrorHandler);
        }

        function completeHandler(event) {
            var loader = air.URLLoader(event.target);
            air.trace("completeHandler: " + loader.data);
    
            var vars = new air.URLVariables(loader.data);
            air.trace("The answer is " + vars.answer);
        }

        function openHandler(event) {
            air.trace("openHandler: " + event);
        }

        function progressHandler(event) {
            air.trace("progressHandler loaded:" + event.bytesLoaded + " total: " + event.bytesTotal);
        }

        function securityErrorHandler(event) {
            air.trace("securityErrorHandler: " + event);
        }

        function httpStatusHandler(event) {
            air.trace("httpStatusHandler: " + event);
        }

        function ioErrorHandler(event) {
            air.trace("ioErrorHandler: " + event);
        }
      </script>
    </head>
    <body onload='init()'>
    </body>
</html>

window.runtime 属性	window.runtime.flash.net.URLLoader

继承	URLLoader EventDispatcher Object

面向 HTML 开发人员的 AIR 语言参考
URLLoader