Loader  - AS3

包含使用 load() 或 loadBytes() 方法載入的 SWF 檔案或影像檔 (JPG、PNG、或 GIF) 的根顯示物件。

相關 API 元素

傳回與載入中物件相對應的 LoaderInfo 物件。 Loader 物件與載入的內容物件會共用 LoaderInfo 物件。 LoaderInfo 物件會提供與載入檔案相關的載入進度資訊與統計資料。

與載入有關的事件都會由 LoaderInfo 物件 (由 Loader 物件的 contentLoaderInfo 屬性所參照) 來傳送。 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
            }
        }
    }
}

建立一個 Loader 物件，可用來載入檔案 (如 SWF、JPEG、GIF，或是 PNG 檔)。 呼叫 load() 方法，將資源做為 Loader 實體的子系載入。 接著，您可以將 Loader 物件載入顯示物件 (例如，您可以使用 DisplayObjectContainer 實體的 addChild() 方法)。 資源會在載入「舞台」時顯示。

您也可以在「清單外」使用 Loader 實體，也就是說，不要將它加入至顯示清單中的顯示物件容器。 在這種模式裡，您可以使用 Loader 實體載入包含額外應用程式模組的 SWF 檔案。

若要偵測 SWF 檔案是否已經完成載入，您可以使用與 Loader 物件的 contentLoaderInfo 屬性關聯之 LoaderInfo 物件事件。 在這個階段，可以執行 SWF 檔案模組中的程式碼來初始化並起始模組。 在「清單外」模式中，您也可以使用 Loader 實體來載入包含組件或媒體資源的 SWF 檔案。 同樣，您也可以使用 LoaderInfo 物件事件通知來偵測組件是否已經完成載入。在這個階段，應用程式會實體化代表這些元件與資源的 ActionScript 3.0 類別，以使用 SWF 檔案元件庫的組件與媒體資源開始動作。

若要判斷 Loader 物件的狀態，請監視下列與 Loader 物件之 contentLoaderInfo 屬性關聯的 LoaderInfo 物件事件：

• 開始載入時，會傳送 open 事件。
• 如果無法載入檔案，或者載入程序當中發生錯誤，便會傳送 ioError 或 securityError 事件。
• 在載入檔案的過程中，會持續觸發 progress 事件。
• 當檔案下載完成，但是尚未取得載入的影片片段的方法和屬性之前，會傳送 complete 事件。
• 一旦取得了載入的 SWF 檔案之屬性與方法，便會傳送 init 事件，方便您開始操作載入的 SWF 檔案。 這個事件會在 complete 處理常式之前傳送。 在串流 SWF 檔案時，init 事件的發生時間會比 complete 事件提早很多。 在大部分的情況下，請使用 init 處理常式。

備註 (僅 iOS)：在 iOS 的 AIR 應用程式中，您只能從應用程式套件中載入包含 ActionScript 的 SWF 檔案。這項限制包括任何 ActionScript，例如，具有為 ActionScript 而匯出之類別名稱的資源。若要載入任何 SWF 檔案，您必須使用與父輩 SWF 相同的應用程式網域來載入 SWF。

在 AIR 3.6 之前，只能載入未包含 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 像素。

載入 Loader 物件的 SWF 檔案或影像會繼承 Loader 物件之上層顯示物件的位置、旋轉與縮放屬性。

請使用 unload() 方法，將使用此方法載入的影片或影像移除，或是取消正在進行中的載入作業。

您可以拒絕 SWF 檔使用這個方法，方式是在包含 SWF 內容的 HTML 網頁中，設定 object 和 embed 標籤的 allowNetworking 參數。

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 ByteCode (ABC) 的 SWF 檔案，然後取消載入檔案後再重新載入檔案。如果您嘗試執行此操作，執行階段就會擲回錯誤 3764。

在 AIR 3.6 之前，只能載入未包含 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" 參數指示) 的多部分 Content-Type (例如 "multipart/form-data")，POST 作業會受限於上載所套用的安全性規則：

• 必須執行 POST 作業，以回應使用者啟動的動作 (例如按下滑鼠或按下按鍵)。
• 如果 POST 作業會跨越網域 (POST 目標與傳送 POST 要求的 SWF 檔不在同一部伺服器上)，目標伺服器必須提供允許跨網域存取的 URL 原則。

此外，多部分的 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" 或進度事件。否則，請等待完整的事件，以確認完整載入資料。

當您使用這個方法時，請考慮 Loader 類別說明中所述的 Flash Player 安全性模型。

參數

相關 API 元素

移除使用 load() 方法載入 Loader 物件的子系。 與 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 子檔案及其顯示清單會發生下列狀況：

• 聲音已停止。
• 舞台事件偵聽程式已移除。
• enterFrame、frameConstructed、exitFrame、activate 和 deactivate 的事件偵聽程式已移除。
• 計時器已停止。
• Camera 和 Microphone 實體已拆離。
• 影片片段已停止。

當您呼叫 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. clickHandler 事件偵聽程式會在載入器上註冊為 click 事件。 按一下滑鼠後，載入的影像便會取消載入。
6. configureListeners() 方法會使用下列方法加入七個事件偵聽程式：
   • completeHandler() 方法會在影像載入完成後執行。
   • 如果本機未載入影像，而且網路要求已可使用且 Flash Player 可以偵測到網路要求，則會執行 httpStatusHandler() 方法。
   • initHandler() 方法會在 completeHandler() 方法之前以及 progressHandler() 方法之後執行。 一般來說，init 事件在載入 SWF 檔案時比較有用。
   • ioErrorHandler() 方法會在影像檔不可使用或無法存取時執行。
   • openHandler() 方法會在第一次開啟影像檔時執行。
   • progressHandler() 方法會在影像檔開始載入，以及影像載入完成時各執行一次。
   • unLoadHandler() 方法會在使用者按一下影像，要使用 unload() 方法取消載入影像時執行。

請牢記下面的需求：

• 在此範例中，您需要將名為 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();
        }
    }
}