Loader  - AS3

包含使用 load() 或 loadBytes() 方法加载的 SWF 文件或图像（JPG、PNG 或 GIF）文件的根显示对象。

相关 API 元素

返回与正在加载的对象相对应的 LoaderInfo 对象。LoaderInfo 对象在 Loader 对象和加载的内容对象之间共享。LoaderInfo 对象提供有关加载的文件的加载进度信息和统计。

与加载相关的事件由 Loader 对象的 contentLoaderInfo 属性引用的 LoaderInfo 对象调度。contentLoaderInfo 属性设置为有效的 LoaderInfo 对象（即使在加载内容之前），这样您就可以在加载前将事件侦听器添加到该对象。

要检测加载的 SWF 中发生的未捕获错误，请使用 Loader.uncaughtErrorEvents 属性而不是 Loader.contentLoaderInfo.uncaughtErrorEvents 属性。

相关 API 元素

var url:String = "http://www.helpexamples.com/flash/images/image2.jpg";
var urlRequest:URLRequest = new URLRequest(url);
var loader:Loader = new Loader();
loader.contentLoaderInfo.addEventListener(Event.COMPLETE, loader_complete);
loader.load(urlRequest);
addChild(loader);
 
function loader_complete(evt:Event):void {
    var target_mc:Loader = evt.currentTarget.loader as Loader;
    target_mc.x = (stage.stageWidth - target_mc.width) / 2;
    target_mc.y = (stage.stageHeight - target_mc.height) / 2;
}

在此 Loader 对象加载的 SWF 中发生未处理错误时调度 uncaughtError 事件的对象。当任何 try..catch 块引发错误时，或调度的 ErrorEvent 对象没有注册的侦听器时，会发生未被捕获的错误。

请注意，Loader 对象的 uncaughtErrorEvents 属性调度通过该对象冒泡的事件，而不是该对象直接调度的事件。它永远不会在目标阶段调度 uncaughtErrorEvent。它仅在捕获阶段和冒泡阶段调度该事件。要检测当前 SWF（在其中定义 Loader 对象）中未被捕获的错误，请改用 LoaderInfo.uncaughtErrorEvents 属性。

如果 Loader 对象加载的内容是 AVM1 (ActionScript 2) SWF 文件，则 AVM1 SWF 文件中未被捕获的错误不会导致 uncaughtError 事件。

相关 API 元素

package
{
    import flash.display.Loader;
    import flash.display.Sprite;
    import flash.events.ErrorEvent;
    import flash.events.UncaughtErrorEvent;
    import flash.net.URLRequest;

    public class LoaderUncaughtErrorEventExample extends Sprite
    {
        private var ldr:Loader;
        
        public function LoaderUncaughtErrorEventExample()
        {
            ldr = new Loader();
            ldr.load(new URLRequest("child.swf"));
            ldr.uncaughtErrorEvents.addEventListener(UncaughtErrorEvent.UNCAUGHT_ERROR, uncaughtErrorHandler);
        }
        
        private function uncaughtErrorHandler(event:UncaughtErrorEvent):void
        {
            if (event.error is Error)
            {
                var error:Error = event.error as Error;
                // do something with the error
            }
            else if (event.error is ErrorEvent)
            {
                var errorEvent:ErrorEvent = event.error as ErrorEvent;
                // do something with the error
            }
            else
            {
                // a non-Error, non-ErrorEvent type was thrown and uncaught
            }
        }
    }
}

创建一个可用于加载文件（如 SWF、JPEG、GIF 或 PNG 文件）的 Loader 对象。调用 load() 方法可将资源加载为 Loader 实例的子级。然后，可以将 Loader 对象添加到显示列表（例如，通过使用 DisplayObjectContainer 实例的 addChild() 方法）。这样，资源在加载时会出现在舞台上。

您也可以在“offlist”模式下使用 Loader 实例，这样就不会将 Loader 实例添加到显示列表的显示对象容器中。在该模式下，Loader 实例可以用于加载包含应用程序的其它模块的 SWF 文件。

要检测何时可以完成 SWF 文件的加载，您可以使用与 Loader 对象的 contentLoaderInfo 属性相关联的 LoaderInfo 对象的事件。此时，便可执行模块 SWF 文件中的代码以初始化和启动模块。在 offlist 模式下，还可以使用 Loader 实例来加载包含组件或媒体资源的 SWF 文件。同时，您可以使用 LoaderInfo 对象事件通知来检测组件的加载何时完成。此时，应用程序可以通过实例化代表这些组件和资源的 ActionScript 3.0 类来开始使用 SWF 文件库中的组件和媒体资源。

要确定 Loader 对象的状态，请监视与 Loader 对象的 contentLoaderInfo 属性相关联的 LoaderInfo 对象的以下事件：

• 在加载开始时调度 open 事件。
• 在无法加载文件或在加载过程中出现错误时，调度 ioError 或 securityError 事件。
• 在文件加载过程中会不断引发 progress 事件。
• 在文件完成下载但加载的影片剪辑的方法和属性尚不可用时调度 complete 事件。
• 在可以访问加载的 SWF 文件的属性和方法，即可以开始操作加载的 SWF 文件时调度 init 事件。在 complete 处理函数之前调度该事件。在流式 SWF 文件中，init 事件可以在明显早于 complete 事件的时间发生。在大多数情况下，请使用 init 处理函数。

注意（仅限 iOS）：在 iOS 上的 AIR 应用程序中，只能从应用程序包加载包含 ActionScript 的 SWF 文件。此限制针对的是任何 ActionScript，如为 ActionScript 导出类名称的资源。若想加载 SWF 文件，加载的 SWF 必须与父 SWF 使用相同的应用程序域。

在 AIR 3.6 之前，无论是从应用程序包还是通过网络加载 SWF 文件，只能加载不包含 ActionScript 字节代码的 SWF 文件。若想使用包含 ActionScript 的外部 SWF 文件，可用一种替代方法，即创建一个 SWC 库，然后将其链接到您的主 SWF。

当应用程序运行在 iOS 模拟器中（ipa-test-interpreter-simulator 或 ipa-debug-interpreter-simulator）或解释器模式下（ipa-test-interpreter 或 ipa-debug-interpreter）时，这些限制不适用。

相关 API 元素

取消当前正在对 Loader 实例执行的 load() 方法操作。

相关 API 元素

将 SWF、JPEG、渐进式 JPEG、非动画 GIF 或 PNG 文件加载到此 Loader 对象的子对象中。如果加载 GIF 动画文件，将仅显示第一帧。由于 Loader 对象可以只包含一个子级，因此，发出后续 load() 请求将终止先前的请求，如果仍然存在未处理的请求，则会开始新的加载。

注意：在 AIR 1.5 和 Flash Player 10 中，所加载图像的最大宽度或高度为 8,191 像素，并且像素总数不能超过 16,777,215 像素。（因此，如果所加载图像的宽度为 8,191 像素，则其高度只能为 2,048 像素。）在 Flash Player 9 及早期版本和 AIR 1.1 及早期版本中，高度最大为 2,880 像素，宽度最大为 2,880 像素。

加载到 Loader 对象中的 SWF 文件或图像会继承该 Loader 对象的父显示对象的位置、旋转和缩放属性。

使用 unload() 方法可删除用此方法加载的影片或图像，或者取消正在进行中的加载操作。

可以在包含 SWF 内容的 HTML 页中设置 object 和 embed 标签的 allowNetworking 参数，防止 SWF 文件使用此方法。

iOS 注意事项

在 iOS 上的 AIR 应用程序中，只能从应用程序包加载包含 ActionScript 的 SWF 文件。此限制针对的是任何 ActionScript，如为 ActionScript 导出类名称的资源。若想加载 SWF 文件，加载的 SWF 必须与父 SWF 使用相同的应用程序域，如下例所示：

     var loader:Loader = new Loader();
     var url:URLRequest = new URLRequest("swfs/SecondarySwf.swf");
     var loaderContext:LoaderContext = new LoaderContext(false, ApplicationDomain.currentDomain, null);
     loader.load(url, loaderContext);

此外，在 iOS 上，您不能在加载包含任何 ActionScript 字节码 (ABC) 的 SWF 文件之后卸载它然后再重新加载它。如果您试图这样做，运行时会引发错误 3764。

在 AIR 3.6 之前，无论是从应用程序包还是通过网络加载 SWF 文件，只能加载不包含 ActionScript 字节代码的 SWF 文件。若想使用包含 ActionScript 的外部 SWF 文件，可用一种替代方法，即创建一个 SWC 库，然后将其链接到您的主 SWF。

当应用程序运行在 iOS 模拟器中（ipa-test-interpreter-simulator 或 ipa-debug-interpreter-simulator）或解释器模式下（ipa-test-interpreter 或 ipa-debug-interpreter）时，这些限制不适用。

Loader 安全性

使用此方法时，请考虑 Loader 类说明中描述的 Flash Player 安全模型。

在 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 操作受应用于上载的安全规则约束。

有关安全性的详细信息，请参阅 Flash Player 开发人员中心主题：安全性。

参数

相关 API 元素

从 ByteArray 对象中所存储的二进制数据中加载。

loadBytes() 方法是异步的。必须等待“init”事件出现才能访问已加载对象的属性。

使用此方法时，请考虑 Loader 类说明中描述的 Flash Player 安全模型。

注意（仅限 iOS）：在 iOS 上的 AIR 应用程序中，只能从应用程序包加载包含 ActionScript 的 SWF 文件。此限制针对的是任何 ActionScript，如为 ActionScript 导出类名称的资源。若想加载 SWF 文件，加载的 SWF 必须与父 SWF 使用相同的应用程序域。

在 AIR 3.6 之前，在 iOS 上调用此方法无效。

参数

相关 API 元素

加载 IFilePromise 实例。

loadFilePromise 方法使用 IFilePromise 对象并加载二进制数据。如果数据是渐进流，例如视频，则在访问加载的对象的属性之前等待“init”或 progress 事件。否则，等待 complete 事件以确保完全加载了数据。

使用此方法时，请考虑 Loader 类说明中描述的 Flash Player 安全模型。

参数

相关 API 元素

删除此 Loader 对象中使用 load() 方法加载的子项。将关联 LoaderInfo 对象的 property 重置为 null。不必破坏子级，因为其它对象可能要引用它；但是，它不再是 Loader 对象的子级。

调用 unload() 方法时，应将 Loader 对象的 contentLoaderInfo 属性设为 null。曾经与 SWF 一起加载的任何可视资源都将予以卸载，并从内存中删除。加载的 SWF 中的 ActionScript 类定义保留在内存中，与加载的 SWF 处于同一应用程序域中的代码可以访问这些类的实例并创建新的实例。

注意（仅限 iOS）：在 AIR 3.6 之前，此方法在 iOS 上无效。

最佳做法是，在卸载子 SWF 文件之前，您应该明确关闭子 SWF 文件的对象（如 LocalConnection、NetConnection、NetStream 和 Sound 对象）中的任何流。否则，子 SWF 文件中的音频可能会继续播放，即使已卸载子级 SWF 文件。要关闭子 SWF 文件中的流，请向子文件中添加事件侦听器以侦听 unload 事件。当父文件调用 Loader.unload() 时，将为子文件调度 unload 事件。以下代码显示了完成上述任务的方法：

function closeAllStreams(evt:Event) { 
    myNetStream.close();
    mySound.close();
    myNetConnection.close();
    myLocalConnection.close();
}

myMovieClip.loaderInfo.addEventListener(Event.UNLOAD, closeAllStreams);

相关 API 元素

尝试卸载子 SWF 文件内容并停止执行已加载的 SWF 文件中的命令。此方法尝试通过删除对子 SWF 文件的 EventDispatcher、NetConnection、Timer、Sound 或 Video 对象的引用，从而卸载使用 Loader.load() 或 Loader.loadBytes() 加载的 SWF 文件。因此，针对子 SWF 文件和子 SWF 文件的显示列表将发生以下行为：

• 停止声音。
• 删除舞台事件侦听器。
• 删除 enterFrame、frameConstructed、exitFrame、activate 和 deactivate 的事件侦听器。
• 停止计时器。
• 断开摄像头和麦克风实例
• 停止影片剪辑。

调用 unloadAndStop() 方法时，应将 Loader 对象的 contentLoaderInfo 属性设为 null。曾经与 SWF 一起加载的任何可视资源都将予以卸载，并从内存中删除。加载的 SWF 中的 ActionScript 类定义保留在内存中，与加载的 SWF 处于同一应用程序域中的代码可以访问这些类的实例并创建新的实例。

注意（仅限 iOS）：在 AIR 3.6 之前，此方法在 iOS 上无效。

参数

相关 API 元素

1. 创建 url 属性，它是图像文件的位置和名称
2. 在 LoaderExample 构造函数中，创建一个新的 Loader 对象，名为 loader，该对象随后被传递给 configureListeners() 方法，如步骤 3 所述。
3. 构造函数创建一个 URLRequest 对象的新实例 request，该实例带有传递的 url，这样，就可以知道文件的名称和位置。
4. request 对象传递给 loader 对象的 load() 方法，该方法会将图像加载到显示列表上。
5. 为加载器上的 click 事件注册 clickHandler 事件侦听器。在单击鼠标后，便可卸载加载的图像。
6. configureListeners() 方法通过以下方法添加 7 个事件侦听器：
   • 图像加载完成时，执行 completeHandler() 方法。
   • 图像不是在本地加载，并且只有在网络请求可用并可被 Flash Player 检测到的情况下，才会执行 httpStatusHandler() 方法。
   • initHandler() 方法在 completeHandler() 方法之前、progressHandler() 方法之后执行。通常，init 事件在加载 SWF 文件时更有用。
   • 图像文件不可用或不可访问，则执行 ioErrorHandler() 方法。
   • 首次打开图像文件时，执行 openHandler() 方法。
   • 图像文件开始下载和下载完成时，执行 progressHandler() 方法。
   • 通过使用用户单击图像时使用的 unload() 方法卸载图像时，执行 unLoadHandler() 方法。

请牢记以下要求：

• 该示例要求您将名为 Image.gif 的文件放置在与经过编译的 SWF 文件相同的目录中。使用具有一个适合主 SWF 文件尺寸的区域的图像。
• 虽然该示例使用可用于 LoaderInfo 对象的所有事件，但是在大部分情况下，只需要一个子集。特别是在只加载图像文件时，complete 事件（还可能是 ioError 事件）足够用于加载本地图像。

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

    public class LoaderExample extends Sprite {
        private var url:String = "Image.gif";

        public function LoaderExample() {
            var loader:Loader = new Loader();
            configureListeners(loader.contentLoaderInfo);
            loader.addEventListener(MouseEvent.CLICK, clickHandler);

            var request:URLRequest = new URLRequest(url);
            loader.load(request);

            addChild(loader);
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
            dispatcher.addEventListener(Event.INIT, initHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(Event.UNLOAD, unLoadHandler);
        }

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

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

        private function initHandler(event:Event):void {
            trace("initHandler: " + 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 {
            trace("progressHandler: bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

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

        private function clickHandler(event:MouseEvent):void {
            trace("clickHandler: " + event);
            var loader:Loader = Loader(event.target);
            loader.unload();
        }
    }
}