載入外部資料

Flash Player 9 以及更新的版本,Adobe AIR 1.0 以及更新的版本

ActionScript 3.0 包含可從外部來源載入資料的機制。這些來源可以提供靜態內容 (例如文字檔) 或網頁指令碼產生的動態內容。資料的格式可以形形色色,而 ActionScript 會提供解碼與存取資料所需的功能。您也可以在擷取資料的過程中,將資料傳送至外部伺服器中。

使用 URLRequest 類別

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

URLRequest 屬性

您可以在任何安全執行程序中設定 URLRequest 物件的下列屬性:

屬性

說明

contentType

以 URL 要求所傳送任何資料的 MIME 內容類型。如果沒有設定 contentType,則會以 application/x-www-form-urlencoded 送出值。

data

一種物件,其中包含要使用 URL 要求傳輸的資料。

digest

字串,唯一識別儲存到 Adobe® Flash® Player 快取 (或從中擷取) 的已簽署 Adobe 平台組件。

method

HTTP 要求方法,例如 GET 或 POST。(在 AIR 應用程式安全性網域中執行的內容可以指定 "GET""POST" 之外的字串做為 method 屬性。任何 HTTP 動詞都允許,而 "GET" 是預設方法。請參閱:AIR 安全性)。

requestHeaders

要附加至 HTTP 要求之該 HTTP 要求檔頭的陣列。請注意,在 Flash Player 以及在應用程式安全執行程序外部執行的 AIR 內容中,會限制設定部分檔頭的權限。

url

指定將要求的 URL。

在 AIR 中,您可以設定 URLRequest 類別的其他屬性,而這些屬性只能供應用程式安全執行程序中執行的 AIR 內容使用。應用程式安裝執行程序中的內容也可以使用新的 URL 配置 (除了 filehttp 等標準配置之外) 來定義 URL。

屬性

說明

followRedirects

指定是 (true,預設值) 否 (false) 要追蹤重新導向。AIR 應用程式安全執行程序才支援此項。

manageCookies

指定 HTTP 通訊協定堆疊是 (true,預設值) 否 (false) 應該為此要求管理 Cookie。在 AIR 應用程式安全執行程序才支援設定此屬性。

authenticate

指定是否應該 (true) 針對此要求,處理驗證要求。在 AIR 應用程式安全執行程序才支援設定此屬性。預設值是驗證要求,所以如果伺服器要求認證,可能會顯示驗證對話方塊。您也可以使用 URLRequestDefaults 類別設定使用者名稱和密碼;請參閱設定 URLRequest 預設值 (僅限 AIR)

cacheResponse

指定是否應該快取這個要求的回應資料。在 AIR 應用程式安全執行程序才支援設定此屬性。預設值是快取回應 (true)。

useCache

指定在此 URLRequest 取回資料之前,是否應該參考本機快取。在 AIR 應用程式安全執行程序才支援設定此屬性。預設值 (true) 是使用本機快取版本 (如果有的話)。

userAgent

指定要用在 HTTP 要求中的使用者代理程式字串。

備註: HTMLLoader 類別有相關的屬性,以供設定與由 HTMLLoader 物件載入之內容相關的設定。如需詳細資訊,請參閱關於 HTMLLoader 類別

設定 URLRequest 預設值 (僅限 AIR)

URLRequestDefaults 類別可讓您定義 URLRequest 物件的應用程式特定預設設定。例如,下列程式碼設定 manageCookiesuseCache 屬性的預設值。所有新的 URLRequest 物件都會使用這些屬性的指定值,而非一般預設值。

URLRequestDefaults.manageCookies = false; 
URLRequestDefaults.useCache = false;
備註: 僅可針對在 Adobe AIR 中執行的內容來定義 URLRequestDefaults 類別。Flash Player 不支援。

URLRequestDefaults 類別包含 setLoginCredentialsForHost() 方法,可以讓您指定特定主機的預設使用者名稱和密碼。主機是在方法的主機名稱參數中定義,可以是網域 (如 "www.example.com"),也可以是網域加連接埠號 (如 "www.example.com:80")。請注意,"example.com""www.example.com""sales.example.com" 都會被視為唯一的主機。

這些憑證只有在伺服器需要時才會使用。如果使用者已通過驗證 (例如,使用驗證對話方塊),則呼叫 setLoginCredentialsForHost() 方法並不會變更驗證過的使用者。

下列程式碼設定傳送至 www.example.com 要求所使用的預設使用者名稱和密碼:

URLRequestDefaults.setLoginCredentialsForHost("www.example.com", "Ada", "love1816$X"); 

URLRequestDefaults 設定只會套用至目前應用程式網域,但有一個例外。傳遞給 setLoginCredentialsForHost() 方法的認證,會供 AIR 應用程式內任何應用程式網域中進行的要求使用。

如需詳細資訊,請參閱適用於 Adobe Flash Platform 的 ActionScript 3.0 參考中的 URLRequestDefaults 類別。

URI 配置

從任何安全執行程序進行的要求,都可以使用標準 URI 配置 (如下所示):

http: 與 https:

上述項目適用於標準網際網路 URL (與網頁瀏覽器使用的方式相同)。

file:

使用 file: 指定位於本機檔案系統的檔案 URL。例如:

file:///c:/AIR Test/test.txt 

在 AIR 中,為應用程式安全執行程序中執行的內容定義 URL 時,您也可以使用下列配置:

app:

使用 app: 來指定相對於已安裝應用程式根目錄的路徑。例如,下列路徑指向已安裝應用程式目錄的資源子目錄:

app:/resources 

使用 AIR Debug Launcher (ADL) 啟動 AIR 應用程式時,應用程式目錄是含有應用程式描述器檔案的目錄。

app-storage:

使用 app-storage: 來指定相對於應用程式資料儲存目錄的路徑。針對每一個安裝的應用程式 (和使用者),AIR 都會建立唯一的應用程式儲存目錄,可以用來儲存該應用程式專屬的資料。例如,下列路徑會指向應用程式儲存目錄之 settings 子目錄中的 prefs.xml 檔案:

app-storage:/settings/prefs.xml 

這個應用程式儲存目錄的位置是根據使用者名稱、應用程式 ID 和發行者 ID 而定 (適用時):

  • 在 Mac OS 中,位置為:

    /Users/使用者名稱/Library/Preferences/applicationID.publisherID/Local Store/

    例如:

    /Users/babbage/Library/Preferences/com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1/Local Store
  • 在 Windows 中,則是位於 Documents and Settings 目錄內,位置為:

    使用者名稱/Application Data/applicationID.publisherID/Local Store/

    例如:

    C:\Documents and Settings\babbage\Application Data\com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1\Local Store
  • Linux—位於:

    /home/使用者名稱/.appdata/applicationIDpublisherID/Local Store/

    例如:

    /home/babbage/.appdata/com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1\Local Store
備註: 從 AIR 1.5.3 開始,並非所有 AIR 應用程式都有發行者 ID。

File.applicationStorageDirectory 所建立 File 物件的 URL (和 url 屬性) 會使用 app-storage URI 配置,如下所示:

var dir:File = File.applicationStorageDirectory; 
dir = dir.resolvePath("preferences"); 
trace(dir.url); // app-storage:/preferences 

mailto:

傳遞至 navigateToURL() 函數的 URLRequest 物件中有 mailto 配置,您可以使用該配置。請參閱在其他應用程式中開啟 URL

您可以使用 URLRequest 物件,它使用所有這些 URI 配置來定義一些不同物件 (例如 FileStream 或 Sound 物件) 的 URL 要求。您也可以在 AIR 中執行的 HTML 內容裡使用這些配置,例如,您可以使用在 img 標籤的 src 特質中。

但是您只能在應用程安全執行程序的內容中使用這些 AIR 特定 URI 配置 (app:app-storage:)。如需詳細資訊,請參閱:AIR 安全性

禁止的 URI 配置 (在 AIR 中)

有些 API 允許您在網頁瀏覽器中啟動內容。基於安全考量,在 AIR 中使用這些 API 時會禁止使用一些 URI 配置。禁止使用的配置清單會依使用 API 的程式碼安全執行程序而有所不同。如需詳細資訊,請參閱在其他應用程式中開啟 URL

設定 URL 變數

雖然您可以將變數直接新增至 URL 字串。不過,使用 URLVariables 類別來定義要求所需的任何變數,可以更輕鬆地完成此任務。

您有三種方式,可以將參數新增至 URLVariables 物件:

  • 在 URLVariables 建構函式內

  • 使用 URLVariables.decode() 方法

  • 做為 URLVariables 物件本身的動態屬性

下列範例說明這三種方法,也說明如何將變數指定給 URLRequest 物件:

var urlVar:URLVariables = new URLVariables( "one=1&two=2" ); 
urlVar.decode("amp=" + encodeURIComponent( "&" ) ); 
urlVar.three = 3; 
urlVar.amp2 = "&&"; 
trace(urlVar.toString()); //amp=%26&amp2=%26%26&one=1&two=2&three=3 
 
var urlRequest:URLRequest = new URLRequest( "http://www.example.com/test.cfm" ); 
urlRequest.data = urlVar;

當您在 URLVariables 建構函式或 URLVariables.decode() 方法內定義變數時,請確定針對 URI 字串中具有特殊意義的字元進行 URL 編碼。例如,當您在參數名稱或值中使用 & 符號時,必須將 & 符號從 & 變更為 %26 (因為 & 符號是做為參數分界的符號),以編碼 & 符號。最上層 encodeURIComponent() 函數可以用於此用途。

使用 URLLoader 類別

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

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

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

URLLoader.load() 方法 (和選用 URLLoader 類別的建構函式) 所使用的單一參數 request 是一個 URLRequest 物件。URLRequest 物件包含單一 HTTP 要求的所有資訊,例如目標 URL、要求方法 (GETPOST)、額外的檔頭資訊和 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 類別也可以讓您在完成下載前關閉串流。 下載的資料是以原始二進位資料提供。

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

httpResponseStatus 事件 (AIR)

在 Adobe AIR 中,除了 httpStatus 事件之外,URLStream 類別還會傳送 httpResp nseStatus 事件。httpResponseStatus 事件會在任何回應資料之前進行傳遞。httpResponseStatus 事件 (透過 HTTPStatusEvent 類別代表) 包括 responseURL 屬性 (這是從中傳回回應的 URL),以及 responseHeaders 屬性 (這是代表傳回回應之回應檔頭的 URLRequestHeader 物件陣列)。

從外部文件載入資料

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

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

var request:URLRequest = new URLRequest("params.txt"); 
var loader:URLLoader = new URLLoader(); 
loader.load(request);
根據預設,若未定義要求的方法,Flash Player 和 Adobe AIR 會使用 HTTP GET 方法載入內容。若要使用 POST 方法來傳送資料,請使用靜態常數 URLRequestMethod.POSTrequest.method 屬性設為 POST,如下列程式碼所示:
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

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

請避免使用保留字或語言建構做為外部資料檔案中的變數名稱,因為這樣做會使程式碼的閱讀和除錯工作更為困難。
資料一旦完全載入,就會傳送 complete 事件,而外部文件的內容將提供在 URLLoader 的 data 屬性中,如下列程式碼所示:
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.BINARYURLLoader.data 屬性將包含儲存在 ByteArray 物件中的二進位資料。

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

  • URLLoaderDataFormat.VARIABLESURLLoader.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); 
        } 
    } 
}
備註: URLLoader.dataFormat 的預設值是 URLLoaderDataFormat.TEXT

如下列範例所示,從外部檔案載入 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>