LoaderContext  - AS3

指定您是否可以使用 Loader 物件，匯入具有可執行程式碼 (例如 SWF 檔案) 的內容至呼叫端的安全執行程序。有兩個受影響的匯入作業：Loader.loadBytes() 方法與 Loader.load() 方法加上 LoaderContext.securityDomain = SecurityDomain.currentDomain。(AIR 應用程式安全執行程序不支援後者。) 將 allowCodeImport 屬性設定為 false 時，這些匯入作業僅限於安全作業，如載入影像。一般，使用 Loader.load() 方法載入的非匯入 SWF 檔案，不會受到此屬性值的影響。

這個屬性對於您想要將影像內容匯入安全執行程序時會非常有用，例如，當您想要從不同網域複寫或處理影像，您只預期取得一個影像檔案，但不想冒安全性風險來接收 SWF 檔案。因為 SWF 檔案可能包含 ActionScript 程式碼，匯入 SWF 檔案是比匯入影像檔案更危險的作業。

在應用程式安全執行程序中的 AIR 內容中，預設值為 false。在非應用程式的內容中 (包括 Flash Player 中的所有內容)，預設值為 true。

allowCodeImport 屬性是 Flash Player 10.1 及 AIR 2.0 新增的屬性。不過當 Flash 執行階段支援它時，所有版本的 SWF 檔案與 AIR 作業都可以使用這個屬性。

相關 API 元素

舊版屬性，已由 allowCodeImport 取代，但仍然基於相容性而支援此屬性。之前，唯一受到 allowLoadBytesCodeExecution 影響的作業是 Loader.loadBytes() 方法，但是到了 Flash Player 10.1 與 AIR 2.0 時，Loader.load() 加上 LoaderContext.securityDomain = SecurityDomain.currentDomain 的匯入載入作業也受到影響。(AIR 應用程式安全執行程序不支援後者。) 這個雙重效果使得屬性名稱 allowLoadBytesCodeExecution 非常明確，因此現在 allowCodeImport 是慣用的屬性名稱。設定 allowCodeImport 或 allowLoadBytesCodeExecution 將會同時影響這兩者的值。

指定您是否可以使用 Loader 物件，匯入具有可執行程式碼 (例如 SWF 檔案) 的內容至呼叫端的安全執行程序。將這個屬性設定為 false 時，這些匯入作業僅限於安全作業，如載入影像。

在應用程式安全執行程序中的 AIR 內容中，預設值為 false。在非應用程式的內容中，預設值為 true。

相關 API 元素

會指定要用於 Loader.load() 或 Loader.loadBytes() 方法的應用程式網域。 請只在載入以 ActionScript 3.0 撰寫的 SWF 檔 (而非以 ActionScript 1.0 或 ActionScript 2.0 撰寫的影像或 SWF 檔) 時使用此屬性。

每個安全性網域都可分為一個或多個應用程式網域，並由 ApplicationDomain 物件表示。 應用程式網域不具安全性用途，這些網域是要用來管理 ActionScript 程式碼的相關單位。 如果您從另一個網域載入某個 SWF 檔，並允許將該檔案置於不同的安全性網域，您便無法控制要將載入的 SWF 檔置於哪個應用程式網域，而且即使您有指定應用程式網域的選擇，該選擇也會遭到忽略。 然而，如果您將載入的 SWF 檔置入自己的安全性網域 (不論是因為 SWF 檔來自於您自己的網域，還是因為您將該檔匯入至自己的安全性網域)，就可以控制載入之 SWF 檔的應用程式網域選擇。

您只能在 LoaderContext.applicationDomain 中，從自己的安全性網域傳遞應用程式網域。 若嘗試從其他任何安全性網域傳遞應用程式網域，都會造成 SecurityError 例外。

對於要使用何種 ApplicationDomain 屬性，您有下列四種選擇：

• 載入器之 ApplicationDomain 的子系。預設值。 您可以使用 new ApplicationDomain(ApplicationDomain.currentDomain) 語法明確表示這項選擇。 這樣會允許載入的 SWF 檔直接使用父輩的類別，例如藉由撰寫 new MyClassDefinedInParent()。 然而，父輩卻無法使用此語法。如果父輩希望使用子系的類別，便必須呼叫 ApplicationDomain.getDefinition() 以擷取這些類別。 這項選擇的優點在於，如果子系定義之類別的名稱，與父輩已定義的類別相同，並不會造成錯誤，子系將會直接繼承父輩對於該類別的定義，而且除非子系或父輩呼叫 ApplicationDomain.getDefinition() 方法以擷取定義，否則都不會使用到子系的衝突定義。
• 載入器自己的 ApplicationDomain。您可以在使用 ApplicationDomain.currentDomain 時，使用此應用程式網域。 當載入完成時，父輩和子系都可直接使用彼此的類別。 如果子系嘗試定義的類別與父輩已經定義的類別同名，就使用父類別，忽略子類別。
• 系統 ApplicationDomain 的子系。您可以在使用 new ApplicationDomain(null) 時，使用此應用程式網域。 這樣會完全分隔載入器和載入對象，允許兩者以相同的名稱定義不同的類別，而不會造成衝突或遮蓋。 兩端都能看到另一端之類別的唯一方式，便是呼叫 ApplicationDomain.getDefinition() 方法。
• 某些其他 ApplicationDomain 的子系。有時候，您可能會擁有更複雜的 ApplicationDomain 階層。 您可以從自己的 SecurityDomain，將 SWF 檔載入任何 ApplicationDomain。 例如，new ApplicationDomain(ApplicationDomain.currentDomain.parentDomain.parentDomain) 會將 SWF 檔載入至目前網域之祖父輩 (父輩的父輩) 的新子系中。

當載入完成時，任一端 (載入或被載入者) 都可能因為呼叫 ApplicationDomain.getDefinition() 的目的，而需要尋找自己的 ApplicationDomain，或是另一端的 ApplicationDomain。 任一端都可以使用 ApplicationDomain.currentDomain 來擷取或參照自己的應用程式網域。 載入的 SWF 檔可以透過 Loader.contentLoaderInfo.applicationDomain，擷取載入之 SWF 檔的 ApplicationDomain 參照。 如果遭載入的 SWF 檔知道本身載入的方式，便會知道如何找到執行載入之 SWF 檔的 ApplicationDomain 物件。 例如，如果子系是以預設方式載入，即可使用 ApplicationDomain.currentDomain.parentDomain，找到載入之 SWF 檔的應用程式網域。

如需詳細資訊，請參閱「ActionScript 3.0 開發人員指南」之「用戶端系統環境」一章的「ApplicationDomain 類別」一節。

相關 API 元素

指定應用程式是否應先嘗試從物件載入來源伺服器下載 URL 原則檔，再開始載入物件本身。此旗標適用於 Loader.load() 方法，但不適用於 Loader.loadBytes() 方法。

當您從呼叫之 SWF 檔案本身的網域之外載入影像 (JPEG、GIF 或 PNG)，而且期待需要從 ActionScript 存取該影像的內容時，請將此旗標設定為 true。 存取影像內容的範例包括參照 Loader.content 屬性以取得 Bitmap 物件，以及呼叫 BitmapData.draw() 方法以取得載入之影像像素的副本。 如果您嘗試這些作業其中一項，而又尚未在載入時間指定 checkPolicyFile，便可能會得到 SecurityError 例外，這是因為需要的原則檔案此時尚未下載。

當您呼叫 Loader.load() 方法，並將 LoaderContext.checkPolicyFile 設定為 true 時，應用程式會等到成功下載相關的 URL 原則檔，或發現這類原則檔不存在後，才開始下載 URLRequest.url 中的指定物件。Flash Player 或 AIR 會先考量已經下載的原則檔，然後嘗試下載 Security.loadPolicyFile() 方法呼叫所指定的任何擱置中原則檔，再嘗試從對應於 URLRequest.url 的預設位置下載原則檔 (該位置即 /crossdomain.xml，與 URLRequest.url 位於相同伺服器)。在所有情況下，指定的原則檔案必須根據它所在位置存在於 URLRequest.url，而該檔案也必須藉由一或多個 <allow-access-from> 標籤允許存取。

如果您將 checkPolicyFile 設定為 true，在原則檔案完全處理之後，Loader.load() 方法中指定的主要下載才會載入。因此，只要存在您所需要的原則檔案，在從 Loader 物件的 contentLoaderInfo 屬性收到任何 ProgressEvent.PROGRESS 或 Event.COMPLETE 事件之後，原則檔案便會立即下載完成，接著便可以安全地開始執行需要原則檔案的作業。

如果您將 checkPolicyFile 設定為 true，而且找不到相關的原則檔案，則直到嘗試某項作業並擲回 SecurityError 例外為止，您都不會收到任何錯誤指示。 然後，一旦 LoaderInfo 物件傳送 ProgressEvent.PROGRESS 或 Event.COMPLETE 事件，您便能檢查 LoaderInfo.childAllowsParent 屬性的值，以測試是否有找到相關的原則檔案。

如果您不會需要在載入影像時存取像素層級，就不應該將 checkPolicyFile 屬性設定為 true。 在此情況下並沒有必要檢查原則檔案，因為這樣做可能會延遲下載的開始時間，而且可能會不必要地消耗網路頻寬。

如果您在使用 Loader.load() 方法下載 SWF 檔，也請嘗試避免將 checkPolicyFile 設定為 true。 這是因為 SWF-to-SWF 權限不是由原則檔案，而是由 Security.allowDomain() 方法所控制的，因此當您載入 SWF 檔時，checkPolicyFile 不會具有效果。 在此情況下並沒有必要檢查原則檔案，因為這樣做可能會延遲 SWF 檔的下載，而且可能會不必要地消耗網路頻寬。(Flash Player 或 AIR 無法分辨您的主要下載會是 SWF 檔還是影像，因為原則檔下載是在主要下載之前發生)。

如果您所下載的物件來自於可能使用伺服器端 HTTP 重新導向的 URL，請謹慎使用 checkPolicyFile。原則檔案一定是從您在 URLRequest.url 中所指定對應的初始 URL 中擷取。如果因為 HTTP 重新導向，使得最終的物件來自於不同的 URL，則初始下載的原則檔案就可能不適用於物件的最終 URL，也就是在安全性決定中最重要的 URL。 如果發現自己處於這種狀況，您可以在收到 ProgressEvent.PROGRESS or Event.COMPLETE 事件 (會告訴您該物件的最終 URL) 之後，檢查 LoaderInfo.url 的值。 然後再根據該物件的最終 URL，以原則檔案 URL 呼叫 Security.loadPolicyFile() 方法。 接著輪詢 LoaderInfo.childAllowsParent 的值，直到該值成為 true。

在應用程式安全執行程序中執行的 AIR 內容不需要設定這個屬性。AIR 應用程式安全執行程序中的內容可以使用任何載入的影像內容當做來源，呼叫 BitmapData.draw() 方法。

相關 API 元素

指定是否要在使用或載入點陣圖影像資料時解碼影像資料。

根據預設原則 ImageDecodingPolicy.ON_DEMAND，執行階段會在需要顯示影像資料或基於其他目的時，解碼影像資料。此原則會維持舊版執行階段所使用的解碼行為。

根據 ImageDecodingPolicy.ON_LOAD 原則，執行階段會在載入影像之後且在傳送 complete 事件之前，立即解碼影像。在載入時解碼影像，而不是在需要時才解碼，可改善動畫和使用者介面效能。在快速連續顯示數個載入的影像時，就能看到改善的情形。快速顯示影像的範例包括捲動的清單或 Cover Flow 控制項。另一方面，隨意使用 onLoad 原則會提高應用程式的尖峰記憶體使用量。在 onDemand 原則控制的情況下，可能在同時之間有儲存更多的解碼影像資料記憶體中。

根據這兩個原則，執行階段會在將影像解碼之後，使用相同的快取和清除行為。執行階段可隨時清除解碼的資料，並在下一次需要時再次解碼影像。

若要設定影像解碼原則 (例如，設為 ON_LOAD)：

     var loaderContext:LoaderContext = new LoaderContext(); 
     loaderContext.imageDecodingPolicy = ImageDecodingPolicy.ON_LOAD 
     var loader:Loader = new Loader(); 
     loader.load(new URLRequest("http://www.adobe.com/myimage.png"), loaderContext);
     

相關 API 元素

包含要傳送至內容的 LoaderInfo 物件之參數的 Object。

一般而言，contentLoaderInfo.parameters 的值是透過剖析要求 URL 而取得。如果設定 parameters var，則 contentLoaderInfo.parameters 會從 LoaderContext 物件取得它的值，而非從要求 URL。parameters var 僅接受包含名稱/數值字串配對的物件，類似於 URL 參數。如果物件未包含名稱/數值字串配對，則會擲回 IllegalOperationError。

此 API 的用途是，讓要載入的 SWF 檔可以將它的參數傳送到已載入的 SWF 檔。當您使用 loadBytes() 方法時，此功能特別有用，因為 LoadBytes 並未提供透過 URL 傳遞參數的方式。參數只能成功傳送到另一個 AS3 SWF 檔；雖然 AVM1Movie 的 AS3 loaderInfo.parameters 物件將是傳送的物件，但是 AS1 或 AS2 SWF 檔無法接收可存取格式的參數。

例如，以下列 URL 為例：

http://yourdomain/users/jdoe/test01/child.swf?foo=bar;

下列程式碼使用 LoaderContext.parameters 屬性複寫傳遞至此 URL 的參數：

      import flash.system.LoaderContext; 
      import flash.display.Loader; 
      var l:Loader = new Loader(); 
      var lc:LoaderContext = new LoaderContext; 
      lc.parameters = { "foo": "bar" }; 
      l.load(new URLRequest("child.swf"), lc);
     

若要確認參數已正確傳遞，請在執行此程式碼之後，使用下列追蹤陳述式：

trace(loaderInfo.parameters.foo);

如果內容已成功載入，此追蹤就會列印 "bar"。

Loader 將嘗試新增載入內容的父輩。

當內容完全載入時，Loader 物件通常會成為內容的父輩。如果設定 requestedContentParent，所指定的物件會成為父輩，除非發生執行階段錯誤而無法指定。此重設父輩作業也可以在 complete 事件之後完成，而不需使用此屬性。不過，使用 LoaderContext.requestedContentParent 指定父輩還是可以減少發生額外的事件。

LoaderContext.requestedContentParent 會在載入內容中第一個影格指令碼執行之前、建構函式執行之後設定所需的父輩。如果 requestedContentParent 為 null (預設值)，則 Loader 物件會成為內容的父輩。

如果載入內容是 AVM1Movie 物件，或者在 requestedContentParent 物件上呼叫 addChild() 時擲回錯誤，將會發生下列動作：

• Loader 物件成為載入內容的父輩。
• 執行階段傳送 AsyncErrorEvent。

如果要求的父輩和載入內容位於不同的安全執行程序，並且要求的父輩沒有載入內容的存取權，將會發生下列動作：

• Loader 成為載入內容的父輩。
• 執行階段傳送 SecurityErrorEvent。

下列程式碼使用 requestedContentParent 將載入的內容置入 Sprite 物件：

      import flash.system.LoaderContext; 
      import flash.display.Loader; 
      import flash.display.Sprite; 
     
      var lc:LoaderContext = new LoaderContext(); 
      var l:Loader = new Loader(); 
      var s:Sprite = new Sprite(); 
      lc.requestedContentParent = s; 
      addChild(s); 
      l.load(new URLRequest("child.swf"), lc);
     

當此程式碼執行時，SWF 子檔案會出現在舞台上。這個事實證實，您加入舞台的 Sprite 物件是載入的 child.swf 檔案的父輩。

會指定要用於 Loader.load() 作業的安全性網域。 請只在載入 SWF 檔 (而非影像) 時使用這個屬性。

安全性網域的選擇，唯有當您載入的 SWF 檔可能來自不同於載入之 SWF 檔的網域 (不同伺服器) 時，才會具有意義。 當您從自己的網域載入 SWF 檔時，永遠都會將該檔置入您的安全性網域。 不過，當您從不同的網域載入 SWF 檔時，便有兩個選項。 您可以允許將載入的 SWF 檔案置入其「自然」安全性網域，此網域不同於載入之 SWF 檔的網域，這是預設值。 另一個選項則是藉由將 myLoaderContext.securityDomain 設定為等於 SecurityDomain.currentDomain，指定您要將載入的 SWF 檔置入與載入之 SWF 檔相同的安全性網域中。 這種做法稱為「匯入載入」，而且就安全性目的而言，相當於將載入的 SWF 檔複製到您自己的伺服器，並從該處載入此檔案。 為了使「匯入載入」能夠成功，載入的 SWF 檔的伺服器必須具有原則檔案，此檔案必須信任載入之 SWF 檔的網域。

您只能在 LoaderContext.securityDomain 中，傳遞自己的安全性網域。 嘗試傳遞其他任何的安全性網域，都會造成 SecurityError 例外。

AIR 應用程式安全執行程序中的內容無法將其他安全執行程序中的內容載入它的 SecurityDomain。

如需詳細資訊，請參閱「ActionScript 3.0 開發人員指南」中的「安全性」一章。

相關 API 元素

會以指定之設定建立新的 LoaderContext 物件。 如需這些設定的完整詳細資訊，請參閱此類別之屬性的描述。

相關 API 元素