URLLoader  - AS3

指出載入作業截至目前為止已載入的位元組數目。

指出下載資料中的位元組總數。 當載入作業正在進行時，這項屬性會包含 0；當作業完成時，這項屬性會填入不同的值。 此外，遺失 Content-Length 檔頭將會造成 bytesTotal 變為非確定式。

會從載入作業接收的資料。 只有當載入作業完成時，才能填入這項屬性。 資料的格式會取決於 dataFormat 屬性的設定而定：

如果 dataFormat 屬性為 URLLoaderDataFormat.TEXT，接收的資料就是包含載入檔文字的字串。

如果 dataFormat 屬性為 URLLoaderDataFormat.BINARY，接收的資料就是包含原始二進位資料的 ByteArray 物件。

如果 dataFormat 屬性為 URLLoaderDataFormat.VARIABLES，接收的資料就是包含 URL 編碼變數的 URLVariables 物件。

相關 API 元素

//params.txt is a local file that includes: firstName=Tom&lastName=Jones
var lbl:TextField = new TextField();
var urlRequest:URLRequest = new URLRequest("params.txt");
var urlLoader:URLLoader = new URLLoader();
urlLoader.dataFormat = URLLoaderDataFormat.VARIABLES;
urlLoader.addEventListener(Event.COMPLETE, urlLoader_complete);
urlLoader.load(urlRequest);
 
function urlLoader_complete(evt:Event):void {
    lbl.text = urlLoader.data.lastName + "," + urlLoader.data.firstName;
    addChild(lbl);
}

會控制要以文字 (URLLoaderDataFormat.TEXT)、原始二進位資料 (URLLoaderDataFormat.BINARY) 或 URL 編碼之變數 (URLLoaderDataFormat.VARIABLES) 的形式接收下載的資料。

如果 dataFormat 屬性值為 URLLoaderDataFormat.TEXT，接收的資料就是包含載入檔文字的字串。

如果 dataFormat 屬性值為 URLLoaderDataFormat.BINARY，接收的資料就是包含原始二進位資料的 ByteArray 物件。

如果 dataFormat 屬性值為 URLLoaderDataFormat.VARIABLES，接收的資料就是包含 URL 編碼變數的 URLVariables 物件。

預設值為 URLLoaderDataFormat.TEXT。

相關 API 元素

var PATH:String = "lorem.txt";
var urlRequest:URLRequest = new URLRequest(PATH);
var urlLoader:URLLoader = new URLLoader();
urlLoader.dataFormat = URLLoaderDataFormat.TEXT; // default
urlLoader.addEventListener(Event.COMPLETE, urlLoader_complete);
urlLoader.load(urlRequest);
 
function urlLoader_complete(evt:Event):void {
    textArea.text = urlLoader.data;
}

會建立 URLLoader 物件。

相關 API 元素

會在 EventDispatcher 物件註冊事件偵聽程式，以便讓偵聽程式收到事件的通知。您可以在顯示清單上的所有節點，為特定類型的事件、階段與優先順序註冊事件偵聽程式。

當您成功註冊事件偵聽程式後，就不可以透過對 addEventListener() 的額外呼叫來變更其優先順序。 若要變更偵聽程式的優先順序，您必須先呼叫 removeListener()。 然後，您就可以使用新的優先順序等級來重新註冊偵聽程式。

請記住，一旦您註冊了偵聽程式，對 addEventListener() 進行後續呼叫，若使用不同的 type 或 useCapture 值，將會導致建立個別的偵聽程式註冊程序。 例如，如果您先將 useCapture 設為 true 來註冊偵聽程式，則只會在捕捉階段進行偵聽。 如果您使用相同的偵聽程式物件，再次呼叫 addEventListener() (但將 useCapture 設為 false) 會得到兩個不同的偵聽程式： 一個會在捕捉階段進行偵聽，另一個則會在目標與反昇階段進行偵聽。

您無法單獨針對目標階段或反昇階段註冊事件偵聽程式。 由於反昇階段只適用於目標節點的祖系，因此這兩種階段必須一起進行註冊。

如果您不再需要事件偵聽程式，可以呼叫 removeEventListener() 來移除它，否則可能產生記憶體問題。 事件偵聽程式不會自動從記憶體中移除，因為只要傳送的物件存在，垃圾回收器就不會移除偵聽程式 (除非 useWeakReference 參數設定為 true)。

複製 EventDispatcher 實體並不會將附加在該實體上的事件偵聽程式一併複製 (如果新建立的節點需要事件偵聽程式，則您必須在建立節點後再附加偵聽程式)。 然而，如果您移動了 EventDispatcher 實體，則附加的事件偵聽程式也會跟著移動。

若於此節點正在處理事件的同時將事件偵聽程式註冊到某個節點上，則事件偵聽程式不會在目前階段觸發，但會在事件流程的後續階段 (例如反昇階段) 中觸發。

如果您在節點正在處理事件的同時將事件偵聽程式從節點中移除，則事件偵聽程式還是會被目前的動作觸發。 一旦移除了事件偵聽程式，就無法再叫用它 (除非您為了日後的處理而再次註冊它)。

參數

function(evt:Event):void

會關閉進行中的載入作業。 任何進行中的載入作業都會立即終止。 如果目前並未串流任何 URL，就會擲回無效的串流錯誤。

會從指定的 URL 傳送並載入資料。 根據 dataFormat 屬性設定的值而定，您能以文字、原始二進位資料或 URL 編碼之變數的形式接收此資料。 請注意，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" 參數指示) 的多部分 Content-Type (例如 "multipart/form-data")，POST 作業會受限於上載所套用的安全性規則：

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

此外，多部分的 Content-Type 語法必須有效 (符合 RFC2046 標準)。如果語法無效，POST 作業會受限於上載所套用的安全性規則。

如需安全性詳細資訊，請參閱「Flash Player 開發人員中心」主題：安全性。

參數

相關 API 元素

package {
    import flash.display.Sprite;
    import flash.events.Event;
    import flash.net.URLLoader;
    import flash.net.URLRequest;
    import flash.text.TextField;
    import flash.text.TextFieldAutoSize;
    import flash.xml.*;
    import flash.events.IOErrorEvent;
  
    public class URLLoader_loadExample extends Sprite {
        private var xmlTextField:TextField = new TextField();
        private var externalXML:XML;    
        private var loader:URLLoader;

        public function URLLoader_loadExample() {
            var request:URLRequest = new URLRequest("xmlFile.xml");

            loader = new URLLoader();
            
            try {
                loader.load(request);
            }
            catch (error:SecurityError)
            {
                trace("A SecurityError has occurred.");
            }

             loader.addEventListener(IOErrorEvent.IO_ERROR, errorHandler);
            loader.addEventListener(Event.COMPLETE, loaderCompleteHandler);

            xmlTextField.x = 10;
            xmlTextField.y = 10;
            xmlTextField.background = true;
            xmlTextField.autoSize = TextFieldAutoSize.LEFT;

            addChild(xmlTextField);
        }

        private function loaderCompleteHandler(event:Event):void {

                try {
                    externalXML = new XML(loader.data);
                    readNodes(externalXML);    
                } catch (e:TypeError) {
                    trace("Could not parse the XML file.");
                }
        }

        private function readNodes(node:XML):void {

                for each (var element:XML in node.elements()) {
                    xmlTextField.appendText(element.attributes()[0] + "\n");

                    readNodes(element);
                }    
        }

        private function errorHandler(e:IOErrorEvent):void {
            xmlTextField.text = "Had problem loading the XML File.";
        }
    }
}

在所有接收的資料都已解碼，並放置於 URLLoader 物件的 data 屬性之後傳送。一旦傳送這個事件，就可以存取接收的資料。

這個事件具有下列屬性：

相關 API 元素

當 load() 方法呼叫嘗試透過 HTTP 存取資料，而且 Adobe AIR 能夠偵測並傳回要求的狀態碼時傳送。

HTTPStatusEvent.HTTP_RESPONSE_STATUS 常數會定義 httpResponseStatus 事件物件的 type 屬性值。

這個事件具有下列屬性：

相關 API 元素

當 URLLoader.load() 呼叫嘗試透過 HTTP 存取資料時傳送。針對 Flash Player 中執行的內容，只有在目前的 Flash Player 環境能夠偵測並傳回要求的狀態碼時，才會傳送這個事件。(某些瀏覽器環境可能無法提供這項資訊)。 請注意，httpStatus 事件 (如果有的話) 會在 (另外) 任何 complete 或 error 事件之前傳送。

這個事件具有下列屬性：

相關 API 元素

在 URLLoader.load() 的呼叫產生終止下載的嚴重錯誤時傳送。

這個事件具有下列屬性：

相關 API 元素

會在呼叫 URLLoader.load() 方法後開始進行下載作業時傳送。

這個事件具有下列屬性：

相關 API 元素

在下載作業進行中收到資料時傳送。

請注意，使用 URLLoader 物件時，要等到完全接收資料之後，才能存取資料。 因此，進度事件只能做為目前下載進度的通知。 若要在完整下載前存取資料，請使用 URLStream 物件。

這個事件具有下列屬性：

相關 API 元素

當 URLLoader.load() 的呼叫嘗試從安全執行程序以外的伺服器載入資料時傳送。也會在 URLLoader.load() 呼叫嘗試載入 SWZ 檔且憑證無效或摘要字串與組件不符時傳送。

這個事件具有下列屬性：

相關 API 元素

注意：若要執行此範例，請將名為 urlLoaderExample.txt 的檔案與 SWF 檔放置於相同的目錄中。 該檔案應該僅包含下列文字行：answer=42&question=unknown

此範例程式碼會執行下列動作：

1. 建構函數會建立 URLLoader 實體 loader 和 URLRequest 實體 request，其中包含要載入之檔案的位置與檔名。
2. 將 loader 物件傳遞給 configureListeners() 方法後，再將偵聽程式加入每一個支援的 URLLoader 事件。
3. 然後將 request 物件傳遞給 loader.load() 方法，以便載入文字檔。
4. 當 URLLoader 完成文字檔的載入作業時，就會引發 Event.COMPLETE event，並觸發 completeHandler() 方法。 completeHandler() 方法會使用已載入檔案的文字來建立 URLVariables 物件。 URLVariables 物件會將已經過 URL 編碼之名稱/值的配對轉換成 ActionScript 屬性，使得載入的資料更容易操控。

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

    public class URLLoaderExample extends Sprite {
        
        private loader:URLoader;
        public function URLLoaderExample() {
            loader = new URLLoader();
            configureListeners(loader);

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

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

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

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

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

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

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

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