載入外部資料

載入外部資料的許多 API 會使用 URLRequest 類別，定義必要網路要求的屬性。

URLLoader 類別可讓您將要求傳送至伺服器，以及存取傳回的資訊。您也可以使用 URLLoader 類別，存取位於允許本機檔案存取權限之內容 (例如 Flash Player 具有檔案系統的本機安全執行程序和 AIR 應用程式安全執行程序) 的本機檔案系統的檔案。URLLoader 類別能以文字、二進位資料或 URL 編碼變數的形式，從 URL 下載資料。URLLoader 類別會傳送事件 (例如 complete、httpStatus、ioError、open、progress 和 securityError)。

ActionScript 3.0 事件處理模型與 ActionScript 2.0 模型明顯不同，後者使用 LoadVars.onData、LoadVars.onHTTPStatus 和 LoadVars.onLoad 事件處理常式。如需有關在 ActionScript 3.0 中處理事件的詳細資訊，請參閱處理事件

下載的資料在下載完成之後才能使用。您可以偵聽傳送的 progress 事件來監視下載的進度 (已載入的位元組和總位元組數目)。不過，如果檔案載入夠快，就可能不會傳送 progress 事件。complete 事件會在檔案下載作業順利完成時傳送。設定 URLLoader dataFormat 屬性，可以接收資料做為文字、原始二進位資料或 URLVariables 物件。

URLLoader.load() 方法 (和選用 URLLoader 類別的建構函式) 所使用的單一參數 request 是一個 URLRequest 物件。URLRequest 物件包含單一 HTTP 要求的所有資訊，例如目標 URL、要求方法 (GET 或 POST)、額外的檔頭資訊和 MIME 類型。

例如，要上傳 XML 封包至伺服器端指令碼時，您可以使用下列程式碼：

var secondsUTC:Number = new Date().time; 
var dataXML:XML =  
    <clock> 
        <time>{secondsUTC}</time> 
    </clock>; 
var request:URLRequest = new URLRequest("http://www.yourdomain.com/time.cfm"); 
request.contentType = "text/xml"; 
request.data = dataXML.toXMLString(); 
request.method = URLRequestMethod.POST; 
var loader:URLLoader = new URLLoader(); 
loader.load(request); 

上一段程式碼片段會先建立 XML 文件 dataXML，內含要傳送至伺服器的 XML 封包。這個範例會將 URLRequest contentType 屬性設為 "text/xml"，並將 XML 文件指定給 URLRequest data 屬性。最後，這個範例會建立 URLLoader 物件，並使用 load() 方法，將要求傳送至遠端指令碼。

URLStream 類別提供的存取權限，可以在資料到達時下載資料。URLStream 類別也可以讓您在完成下載前關閉串流。 下載的資料是以原始二進位資料提供。

從 URLStream 物件讀取資料時，請使用 bytesAvailable 屬性判斷是否有足夠的資料可以使用，再進行讀取。如果您嘗試讀取的資料多於可用資料，則會擲回 EOFError 例外狀況。

建立動態應用程式時，從外部檔案或伺服器端指令碼載入資料非常有用。這讓您不需要編輯或重新編譯應用程式，就可以建立動態應用程式。例如，如果要建置「本日小秘訣」應用程式，您可以撰寫一個伺服器端指令碼，每天從資料庫隨機擷取一個提示，再將它儲存成文字檔案。然後您的 應用程式就可以載入靜態文字檔案的內容，不需要每次都先查詢資料庫。

下列程式碼片段會建立 URLRequest 和 URLLoader 物件，載入 params.txt 這個外部文字檔案的內容：

var request:URLRequest = new URLRequest("params.txt"); 
var loader:URLLoader = new URLLoader(); 
loader.load(request);

var request:URLRequest = new URLRequest("sendfeedback.cfm"); 
request.method = URLRequestMethod.POST;

在執行階段載入的 params.txt 外部文件包含下列資料：

monthNames=January,February,March,April,May,June,July,August,September,October,November,December&dayNames=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday

此檔案包含兩個參數：monthNames 和 dayNames。每個參數都包含一份以逗號區隔且已剖析為字串的清單。您可以使用 String.split() 方法，將這份清單分割成一個陣列。

請避免使用保留字或語言建構做為外部資料檔案中的變數名稱，因為這樣做會使程式碼的閱讀和除錯工作更為困難。

function completeHandler(event) 
{ 
    var loader2 = event.target; 
    air.trace(loader2.data); 
}

如果遠端文件包含名稱/數值配對，您可以先傳入已載入檔案的內容，然後使用 URLVariables 類別來剖析資料，如下所示：

private function completeHandler(event:Event):void 
{ 
    var loader2:URLLoader = URLLoader(event.target); 
    var variables:URLVariables = new URLVariables(loader2.data); 
    trace(variables.dayNames); 
}

從外部檔案建立的每對名稱/數值配對都會成為 URLVariables 物件中的屬性。在上一段程式碼樣本中，變數物件內的每個屬性都被視為一個字串。如果名稱/值配對的值是一份項目清單，您便可以呼叫 String.split() 方法，將字串轉換為陣列，如下所示：

var dayNameArray:Array = variables.dayNames.split(",");

如果從外部文字檔案載入數值資料，請使用最上層函數 (如 int()、uint() 或 Number()) 將這些值轉換成數值。

您也可以將 URLLoader.dataFormat 屬性設為 URLLoaderDataFormat 類別的其中一個靜態屬性，而不要載入遠端檔案的內容做為字串，然後建立新的 URLVariables 物件。URLLoader.dataFormat 屬性的值可以是下列三個值的其中一個：

• URLLoaderDataFormat.BINARY：URLLoader.data 屬性將包含儲存在 ByteArray 物件中的二進位資料。

• URLLoaderDataFormat.TEXT：URLLoader.data 屬性將包含 String 物件中的文字。

• URLLoaderDataFormat.VARIABLES：URLLoader.data 屬性將包含儲存在 URLVariables 物件中已經過 URL 編碼的變數。

下列程式碼會示範，將 URLLoader.dataFormat 屬性設為 URLLoaderDataFormat.VARIABLES 如何讓您自動將載入的資料解析為 URLVariables 物件：

package 
{ 
    import flash.display.Sprite; 
    import flash.events.*; 
    import flash.net.URLLoader; 
    import flash.net.URLLoaderDataFormat; 
    import flash.net.URLRequest; 
 
    public class URLLoaderDataFormatExample extends Sprite 
    { 
        public function URLLoaderDataFormatExample() 
        { 
            var request:URLRequest = new URLRequest("http://www.[yourdomain].com/params.txt"); 
            var variables:URLLoader = new URLLoader(); 
            variables.dataFormat = URLLoaderDataFormat.VARIABLES; 
            variables.addEventListener(Event.COMPLETE, completeHandler); 
            try 
            { 
                variables.load(request); 
            }  
            catch (error:Error) 
            { 
                trace("Unable to load URL: " + error); 
            } 
        } 
        private function completeHandler(event:Event):void 
        { 
        var loader:URLLoader = URLLoader(event.target); 
        trace(loader.data.dayNames); 
        } 
    } 
}

如下列範例所示，從外部檔案載入 XML 與載入 URLVariables 的程序是一樣的。您可以建立 URLRequest 實體和 URLLoader 實體，然後使用它們來下載遠端 XML 文件。檔案下載完成後，就會傳送 Event.COMPLETE 事件，外部檔案的內容也會轉換成 XML 實體，讓您可以使用 XML 方法和屬性來加以解析。

package 
{ 
    import flash.display.Sprite; 
    import flash.errors.*; 
    import flash.events.*; 
    import flash.net.URLLoader; 
    import flash.net.URLRequest; 
 
    public class ExternalDocs extends Sprite 
    { 
        public function ExternalDocs() 
        { 
            var request:URLRequest = new URLRequest("http://www.[yourdomain].com/data.xml"); 
            var loader:URLLoader = new URLLoader(); 
            loader.addEventListener(Event.COMPLETE, completeHandler); 
            try 
            { 
                loader.load(request); 
            } 
            catch (error:ArgumentError) 
            { 
                trace("An ArgumentError has occurred."); 
            } 
            catch (error:SecurityError) 
            { 
                trace("A SecurityError has occurred."); 
            } 
        } 
        private function completeHandler(event:Event):void 
        { 
            var dataXML:XML = XML(event.target.data); 
            trace(dataXML.toXMLString()); 
        } 
    } 
}

除了載入外部資料檔案以外，您也可以使用 URLVariables 類別，將變數傳送到伺服器端指令碼，並處理伺服器的回應。例如，如果您需要設計一個遊戲程式，不僅要將使用者的分數傳送到伺服器，以計算是否應該將分數列入最高分記錄，甚至還要將使用者的登入資訊傳送給伺服器進行驗證的話，這就是非常有用的方法。伺服器端指令碼可以處理使用者名稱和密碼、比對資料庫進行驗證，並傳回使用者提供的憑證是否有效的確認訊息。

下列程式碼片段將建立名為 variables 的 URLVariables 物件，它會再建立新的 name 變數。接下來，建立一個 URLRequest 物件，指定要做為傳送變數之目的地伺服器端指令碼的 URL。然後設定 URLRequest 物件的 method 屬性，將變數做為 HTTP POST 要求傳送。若要將 URLVariables 物件加入至 URL 要求，請將 URLRequest 物件的 data 屬性設定為之前建立的 URLVariables 物件。最後會建立 URLLoader 實體，並叫用 URLLoader.load() 方法，啟動要求。

var variables:URLVariables = new URLVariables("name=Franklin"); 
var request:URLRequest = new URLRequest(); 
request.url = "http://www.[yourdomain].com/greeting.cfm"; 
request.method = URLRequestMethod.POST; 
request.data = variables; 
var loader:URLLoader = new URLLoader(); 
loader.dataFormat = URLLoaderDataFormat.VARIABLES; 
loader.addEventListener(Event.COMPLETE, completeHandler); 
try 
{ 
    loader.load(request); 
} 
catch (error:Error) 
{ 
    trace("Unable to load URL"); 
} 
 
function completeHandler(event:Event):void 
{ 
    trace(event.target.data.welcomeMessage); 
}

下列程式碼包含上一個範例中所使用 Adobe ColdFusion® greeting.cfm 文件的內容：

<cfif NOT IsDefined("Form.name") OR Len(Trim(Form.Name)) EQ 0> 
    <cfset Form.Name = "Stranger" /> 
</cfif> 
<cfoutput>welcomeMessage=#UrlEncodedFormat("Welcome, " & Form.name)# 
</cfoutput>