LoaderContext  - AS3

Określa, czy można użyć obiektu Loader w celu zaimportowania obiektu zawierającego kod wykonywalny, takiego jak plik SWF, do obszaru izolowanego strony wywołującej. Ustawienie wpływa na dwie operacje importu: metodę Loader.loadBytes() i metodę Loader.load() z ustawieniem LoaderContext.securityDomain = SecurityDomain.currentDomain. (Druga operacja nie jest obsługiwana w obszarze izolowanym aplikacji AIR). Jeśli właściwość allowCodeImport jest ustawiona na false, te operacje importu są ograniczone do operacji bezpiecznych, takich jak ładowanie obrazów. Wartość tej właściwości nie wpływa na normalny, nie importowany plik SWF ładowany za pomocą metody Loader.load().

Ta właściwość jest używana, gdy wymagane jest zaimportowanie treści obrazu do obszaru izolowanego — np. gdy wymagane jest zreplikowanie lub przetworzenie obrazu z innej domeny, ale nie jest dopuszczalne otrzymanie pliku SWF, gdy oczekiwany jest plik obrazu. Pliki SWF mogą zawierać kod ActionScript, dlatego zaimportowanie pliku SWF jest bardziej ryzykowne niż zaimportowanie pliku obrazu.

W zawartości AIR obszaru izolowanego aplikacji wartością domyślną jest false. W treści spoza aplikacji (która obejmuje całą treść programu Flash Player) wartością domyślną jest true.

Właściwość allowCodeImport została dodana w programie Flash Player 10.1 oraz w środowisku AIR 2.0. Jednak ta właściwość jest dostępna dla plików SWF oraz aplikacji AIR we wszystkich wersjach, pod warunkiem że środowisko wykonawcze Flash obsługuje tę właściwość.

Powiązane elementy interfejsu API

Wcześniejsza właściwość, zastąpiona przez allowCodeImport, ale nadal obsługiwana w celu zapewnienia zgodności. Poprzednio jedyną operacją, na którą wpływała właściwość allowLoadBytesCodeExecution, była metoda Loader.loadBytes(), ale w programie Flash Player od wersji 10.1 i w środowisku AIR od wersji 2.0, właściwość ta wpływa również na operację importu i ładowania, jaką wykonuje metoda Loader.load() z ustawieniem LoaderContext.securityDomain = SecurityDomain.currentDomain. (Druga operacja nie jest obsługiwana w obszarze izolowanym aplikacji AIR). Ten podwójny wpływ sprawia, że nazwa allowLoadBytesCodeExecution stała się zbyt szczegółowa, więc teraz preferowaną nazwą właściwości jest allowCodeImport. Ustawienie właściwości allowCodeImport lub allowLoadBytesCodeExecution będzie miało wpływ na obydwie metody.

Określa, czy można użyć obiektu Loader w celu zaimportowania obiektu zawierającego kod wykonywalny, takiego jak plik SWF, do obszaru izolowanego strony wywołującej. Jeśli ta właściwość jest ustawiona na false, te operacje importu są ograniczone do operacji bezpiecznych, takich jak ładowanie obrazów.

W treści obszaru izolowanego aplikacji AIR wartością domyślną jest false. W nieaplikacyjnej treści wartością domyślną jest true.

Powiązane elementy interfejsu API

Określa domenę aplikacji, która będzie używana w metodach Loader.load() lub Loader.loadBytes(). Z tej właściwości można korzystać tylko w przypadku ładowania pliku SWF zapisanego w języku ActionScript 3.0 (a nie w przypadku obrazu lub pliku SWF zapisanego w języku ActionScript 1.0 albo ActionScript 2.0).

Każda domena zabezpieczeń jest podzielona na jeden lub większą liczbę domen aplikacji, które są reprezentowane przez obiekty ApplicationDomain. Domeny aplikacji nie są przeznaczone dla celów zabezpieczeń; służą do zarządzania współpracującymi modułami kodu ActionScript. Jeśli plik SWF jest ładowany z innej domeny i zostanie umieszczony w osobnej domenie, wówczas nie można wybrać domeny aplikacji, w której zostanie umieszczony ładowany plik SWF; wybór domeny aplikacji zostanie zignorowany. Jeśli jednak użytkownik ładuje plik SWF do własnej domeny zabezpieczeń — np. dlatego, że plik SWF pochodzi z domeny własnej lub importowany jest do domeny zabezpieczeń — wówczas użytkownik może wybrać domenę aplikacji, do której plik SWF zostanie załadowany.

Domenę aplikacji można wprowadzić tylko z własnej domeny zabezpieczeń w LoaderContext.applicationDomain. Próba przekazania domeny aplikacji z innej domeny zabezpieczeń spowoduje wyjątek SecurityError.

W przypadku właściwości ApplicationDomain tego rodzaju istnieją cztery możliwości:

• Element potomny domeny ApplicationDomain strony ładującej. Domyślne. Wybranie tej pozycji można określić, wprowadzając składnię new ApplicationDomain(ApplicationDomain.currentDomain). W takim przypadku ładowany plik SWF może korzystać bezpośrednio z klas elementu nadrzędnego — w tym celu należy napisać na przykład: new MyClassDefinedInParent(). Element macierzysty nie może jednak korzystać z tej składni; jeśli element macierzysty chce korzystać z klas elementu potomnego, musi wywołać metodę ApplicationDomain.getDefinition() w celu pobrania tych klas. Zaletą takiego rozwiązania jest to, że jeśli element potomny definiuje klasę o takiej samej nazwie, co klasa zdefiniowana już przez element macierzysty, nie występują żadne błędy; element potomny po prostu dziedziczy definicję klasy od elementu macierzystego, a powodująca konflikt definicja elementu potomnego pozostaje niewykorzystana, chyba że element potomny lub macierzysty wywoła metodę ApplicationDomain.getDefinition() w celu pobrania tej definicji.
• Własna domena ApplicationDomain strony ładującej. Z domeny aplikacji należy korzystać w przypadku korzystania z właściwości ApplicationDomain.currentDomain. Po zakończeniu ładowania element macierzysty i potomny mogą korzystać wzajemnie i bezpośrednio z własnych klas. Jeśli element potomny podejmie próbę zdefiniowania klasy o takiej samej nazwie, jak klasa zdefiniowana przez element macierzysty, zostaje użyta klasa macierzysta, a klasa potomna jest ignorowana.
• Element potomny domeny ApplicationDomain. Z domeny aplikacji należy korzystać w przypadku korzystania z właściwości new ApplicationDomain(null). W tym przypadku strona ładująca i ładowana jest całkowicie oddzielona, co umożliwia im zdefiniowanie osobnych wersji klas o takiej samej nazwie bez konfliktów i bez hierarchizacji. Jedna strona widzi klasy innej strony tylko po wywołaniu metody ApplicationDomain.getDefinition().
• Element potomny innej domeny ApplicationDomain. Czasami hierarchia domeny ApplicationDomain może być bardziej złożona. Plik SWF można załadować do dowolnej domeny ApplicationDomain z własnej domeny SecurityDomain. Przykład: instrukcja new ApplicationDomain(ApplicationDomain.currentDomain.parentDomain.parentDomain) ładuje plik SWF do nowego elementu potomnego elementu macierzystego bieżącej domeny.

Po zakończeniu ładowania możliwe jest, że każda strona (ładująca lub ładowana) będzie musiała znaleźć własną domenę ApplicationDomain lub domenę ApplicationDomain drugiej strony w celu wywołania metody ApplicationDomain.getDefinition(). Każda ze stron może pobrać odwołanie do własnej domeny aplikacji, korzystając z właściwości ApplicationDomain.currentDomain. Ładujący plik SWF może pobrać odwołanie do domeny ApplicationDomain ładowanego pliku SWF za pomocą właściwości Loader.contentLoaderInfo.applicationDomain. Jeśli załadowany plik SWF zna sposób, w jaki został załadowany, może znaleźć obiekt SWF ApplicationDomain ładującego pliku SWF. Przykład: jeśli obiekt podrzędny został załadowany w sposób domyślny, może znaleźć domenę aplikacji ładującego pliku SWF za pomocą właściwości ApplicationDomain.currentDomain.parentDomain.

Więcej informacji zawiera sekcja „Klasa ApplicationDomain” w rozdziale „Środowisko systemu klienckiego” w podręczniku ActionScript 3.0 — Podręcznik dla programistów.

Powiązane elementy interfejsu API

Określa, czy przed rozpoczęciem ładowania obiektu aplikacja powinna podjąć próbę pobrania z serwera ładowanego obiektu pliku reguł URL. Ta flaga ma zastosowanie dla metody Loader.load(), ale nie dla metody Loader.loadBytes().

Dla tej flagi należy ustawić wartość true w przypadku pobierania obrazu (JPEG, GIF lub PNG) spoza domeny wywołującego pliku SWF, gdy oczekiwana jest potrzeba dostępu do zawartości obrazu z ActionScript. Do przykładów uzyskiwania dostępu do zawartości obrazu należą: tworzenie odwoływań do właściwości Loader.content w celu pobrania obiektu Bitmap, a także wywołanie metody BitmapData.draw() w celu pobrania kopii pikseli ładowanego obrazu. Próba wykonania jednej z tych operacji bez określenia właściwości checkPolicyFile w czasie wywołania spowoduje wygenerowanie wyjątku SecurityError, ponieważ żądany plik reguł nie został jeszcze pobrany.

Wywołanie metody Loader.load() po ustawieniu wartości true dla właściwości LoaderContext.checkPolicyFile powoduje, że aplikacja nie rozpoczyna pobierania określonego obiektu (URLRequest.url) do czasu pomyślnego pobrania odpowiedniego pliku reguł URL lub wykrycia, że żaden taki plik nie istnieje. Program Flash Player lub środowisko AIR najpierw uwzględnia pliki reguł, które zostały już pobrane, a następnie podejmuje próbę pobrania oczekujących plików reguł określonych w wywołaniach metody Security.loadPolicyFile(), następnie podejmuje próbę pobrania pliku reguł z lokalizacji domyślnej, która odpowiada wartości URLRequest.url, którą jest /crossdomain.xml na tym samym serwerze co URLRequest.url. We wszystkich przypadkach wymagane jest istnienie danego pliku reguł w miejscu określanym właściwością URLRequest.url za sprawą lokalizacji pliku reguł oraz plik musi zezwalać na dostęp za pośrednictwem jednego lub większej liczby znaczników <allow-access-from>.

Jeśli właściwość checkPolicyFile zostanie ustawiona na wartość true, główna operacja pobierania określona w metodzie Loader.load() nie zostanie załadowana do momentu całkowitego przetworzenia pliku reguł. Dlatego jeśli istnieje wymagany plik reguł, po odebraniu jakichkolwiek zdarzeń ProgressEvent.PROGRESS lub Event.COMPLETE z właściwości contentLoaderInfo obiektu Loader, pobieranie pliku reguł zostaje zakończone i wówczas możliwe jest bezpieczne rozpoczęcie operacji, które wymagają pliku reguł.

Jeśli dla właściwości checkPolicyFile zostanie ustawiona wartość true i nie zostanie znaleziony poprawny plik reguł, nie zostanie odebrane powiadomienie o błędzie do czasu podjęcia próby wykonania operacji, która zgłosi wyjątek SecurityError. Gdy jednak obiekt LoaderInfo wywoła zdarzenie ProgressEvent.PROGRESS lub Event.COMPLETE, możliwe będzie sprawdzenie, czy odpowiedni plik reguł został znaleziony — w tym celu należy sprawdzić wartość właściwości LoaderInfo.childAllowsParent.

Jeśli wymagany będzie dostęp do ładowanego obrazu na poziomie pikseli, nie należy ustawiać dla właściwości checkPolicyFile wartości true. Sprawdzanie, czy istnieje plik reguł w takim przypadku jest zbędne, ponieważ może opóźnić rozpoczęcie pobierania i spowoduje zbędne wykorzystanie przepustowości sieci.

Dla właściwości checkPolicyFile nie należy również ustawiać wartości true, jeśli do pobierania pliku SWF używana jest metoda Loader.load(). Jest to istotne, ponieważ uprawnienia „SWF dla SWF” nie są kontrolowane przez pliki reguł, ale przez metodę Security.allowDomain() i dlatego właściwość checkPolicyFile nie jest istotna podczas ładowania pliku SWF. Sprawdzanie, czy istnieje plik reguł w takim przypadku jest zbędne, ponieważ może opóźnić pobieranie pliku SWF i spowoduje zbędne wykorzystanie przepustowości sieci. (Program Flash Player lub środowisko AIR nie może określić, czy główna operacja pobierania będzie dotyczyła pliku SWF lub obrazu, ponieważ plik reguł jest pobierany przed wykonaniem głównej operacji pobierania).

Korzystając z właściwości checkPolicyFile, należy zachować ostrożność, jeśli obiekt jest pobierany za pomocą adresu URL, dla którego mogą być używane przekierowania HTTP po stronie serwera. Pliki reguł są zawsze pobierane z odpowiedniego początkowego adresu URL, który został określony we właściwości URLRequest.url. Jeśli z powodu przekierowań HTTP końcowy obiekt pochodzi z innego adresu URL, wtedy początkowo pobrane pliki reguł mogą nie odpowiadać końcowemu adresowi URL obiektu, który ma znaczenie w zakresie decyzji dotyczących zabezpieczeń. W takiej sytuacji można sprawdzić wartość LoaderInfo.url po odebraniu zdarzenia ProgressEvent.PROGRESS lub Event.COMPLETE, które określa końcowy adres URL obiektu. Następnie należy wywołać metodę Security.loadPolicyFile() z adresem URL pliku reguł na podstawie adresu URL obiektu końcowego. Następnie należy sprawdzać właściwość LoaderInfo.childAllowsParent do czasu, aż będzie miała wartość true.

Nie należy ustawiać tej właściwości dla treści środowiska AIR działającej w obszarze izolowanym aplikacji. Treść w obszarze izolowanym aplikacji AIR może wywołać metodę BitmapData.draw(), używając jako źródła dowolnej treści załadowanego obrazu.

Powiązane elementy interfejsu API

Określa, czy dane obrazu bitmapowego mają być dekodowane, gdy będzie on używany, czy podczas wczytywania.

W przypadku domyślnej zasady ImageDecodingPolicy.ON_DEMAND środowisko wykonawcze dekoduje dane obrazu, gdy te dane są potrzebne (w celu wyświetlenia lub w innym celu). Ta zasada utrzymuje zachowanie dekodowania używane we wcześniejszych wersjach środowiska wykonawczego.

W przypadku zasady ImageDecodingPolicy.ON_LOAD środowisko wykonawcze dekoduje obraz natychmiast po jego wczytaniu i przed wywołaniem zdarzenia complete. Dekodowanie obrazów podczas wczytywania, a nie w razie potrzeby, może zwiększyć wydajność interfejsu użytkownika i animacji. Różnice będą widoczne w przypadku wyświetlania kilku wczytywanych obrazów w krótkich odstępach czasu. Przykładami szybkiego wyświetlania obrazów mogą być listy przewijania lub element sterujący z okładkami. Z drugiej strony niepotrzebne używanie zasady onLoad może zwiększyć maksymalne użycie pamięci przez aplikację. Naraz w pamięci może znajdować się więcej zdekodowanych danych obrazów, niż miałoby to miejsce w przypadku zasady onDemand.

W przypadku obu zasad po zdekodowaniu obrazu środowisko wykonawcze używa tego samego zachowania w zakresie buforowania i opróżniania bufora. Środowisko wykonawcze może w dowolnej chwili usunąć zdekodowane dane z bufora, aby przeprowadzić ich ponowne dekodowanie następnym razem, gdy będą one potrzebne.

Aby ustawić zasadę dekodowania obrazów (na przykład na wartość 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);
     

Powiązane elementy interfejsu API

Obiekt klasy Object zawierający parametry do przekazania do obiektu LoaderInfo zawartości.

W normalnej sytuacji wartość właściwości contentLoaderInfo.parameters można uzyskać przez analizę adresu URL zgłaszającego żądanie. Jeśli wartość parameters jest ustawiona, za pomocą wywołania contentLoaderInfo.parameters można sprawdzić wartość obiektu LoaderContext bez konieczności badania adresu URL zgłaszającego żądanie. Wartość parameters akceptuje tylko obiekty zawierające pary ciągów (typu String) nazwa-wartość podobne do parametrów adresu URL. Jeśli obiekt nie zawiera par nazwa-wartość typu String, jest generowany wyjątek IllegalOperationError.

Ten interfejs API jest przeznaczony do wczytywania plików SWF w celu przekazywania ich parametrów do wczytanego pliku SWF. Jest to szczególnie przydatne w przypadku używania metody loadBytes(), gdyż klasa LoadBytes nie pozwala przekazywać parametrów za pośrednictwem adresu URL. Parametry można przekazać dalej tylko do innego pliku SWF opartego na języku ActionScript 3. Plik SWF oparty na języku ActionScript 1 lub 2 nie może odebrać parametrów w formie dostępnej do odczytania, mimo iż jest przekazywany obiekt loaderInfo.parameters klasy AVM1Movie języka ActionScript 3.

Przykładem może być następujący adres URL:

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

W poniższym kodzie użyto właściwości LoaderContext.parameters w celu powielenia parametru przekazanego do tego adresu 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);
     

Aby sprawdzić, czy parametr został przekazany poprawnie, po uruchomieniu tego kodu należy użyć następującej instrukcji śledzenia:

trace(loaderInfo.parameters.foo);

Jeśli zawartość została wczytana pomyślnie, instrukcja śledzenia wyświetli komunikat „bar”.

Element macierzysty, do którego obiekt Loader spróbuje dodać wczytaną zawartość.

Po ukończeniu wczytywania zawartości obiekt Loader zazwyczaj staje się elementem macierzystym zawartości. Jeśli jest ustawiona właściwość requestedContentParent, elementem macierzystym staje się określony w niej obiekt, chyba że przypisanie jest niemożliwe z powodu błędu czasu wykonywania. Taka zmiana elementu macierzystego może nastąpić bez stosowania tej właściwości po wywołaniu zdarzenia complete. Określenie elementu macierzystego we właściwości LoaderContext.requestedContentParent eliminuje jednak nadmiarowe zdarzenia.

Właściwość LoaderContext.requestedContentParent pozwala ustawić żądany element macierzysty przed wykonaniem skryptów w pierwszej klatce wczytanej zawartości, ale po uruchomieniu konstruktora. Jeśli właściwość requestedContentParent ma (domyślną) wartość null, obiekt Loader staje się elementem macierzystym zawartości.

Jeśli wczytana zawartość będzie obiektem AVM1Movie lub po wywołaniu metody addChild() obiektu requestedContentParent wystąpi błąd, zostaną wykonane następujące operacje:

• Obiekt Loader stanie się elementem macierzystym wczytanej zawartości.
• Środowisko wykonawcze wywoła zdarzenie AsyncErrorEvent.

Jeśli żądany element macierzysty i wczytana zawartość będą w innych obszarach zabezpieczeń, a żądany element macierzysty nie będzie miał dostępu do wczytanej zawartości, zostaną wykonane następujące operacje:

• Obiekt Loader stanie się elementem macierzystym wczytanej zawartości.
• Środowisko wykonawcze wywoła zdarzenie SecurityErrorEvent.

W poniższym kodzie zastosowano właściwość requestedContentParent w celu umieszczenia wczytanej zawartości w obiekcie 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);
     

Po uruchomieniu tego kodu na stole montażowym pojawi się potomny plik SWF. Ten fakt potwierdza, że obiekt Sprite dodany do stołu montażowego jest elementem macierzystym wczytanego pliku child.swf.

Określa domenę zabezpieczeń, jaka będzie używana dla operacji Loader.load(). Z tej właściwości można korzystać tylko podczas ładowania pliku SWF (nie obrazu).

Wybór domeny zabezpieczeń jest istotny tylko wówczas, gdy ładowany jest plik SWF, który może pochodzić z innej domeny (innego Serwera niż ładujący plik SWF. W przypadku ładowania pliku SWF z własnej domeny plik jest zawsze umieszczany we własnej domenie zabezpieczeń. Jeśli jednak plik SWF jest ładowany z innej domeny, istnieją dwie możliwości. Można zezwolić na umieszczenie ładowanego pliku SWF w odpowiedniej dla niego domenie zabezpieczeń, która jest inna niż domena ładującego pliku SWF; jest to opcja domyślna. Druga możliwość: należy określić, że ładowany plik SWF ma zostać umieszczony w tej samej domenie zabezpieczeń, co ładujący plik SWF — w tym celu należy ustawić dla właściwości myLoaderContext.securityDomain wartość równą właściwości SecurityDomain.currentDomain. Jest to określane jako ładowanie z importem i jest równoważne — w zakresie zabezpieczeń — skopiowaniu ładowanego pliku SWF do własnego serwera i załadowaniu go z tego serwera. Ładowanie z importem zakończy się pomyślnie, jeśli serwer ładowanego pliku SWF zawiera plik reguł określający zaufanie dla domeny ładującego pliku SWF.

Własną domenę zabezpieczeń można wprowadzić tylko do LoaderContext.securityDomain. Próba wprowadzenia innej domeny zabezpieczeń spowoduje wyjątek SecurityError.

Treść w obszarze izolowanym aplikacji AIR nie może ładować treści z innych obszarów izolowanych do własnego obiektu SecurityDomain.

Więcej informacji zawiera rozdział „Zabezpieczenia” w publikacji ActionScript 3.0 — Podręcznik dla programistów.

Powiązane elementy interfejsu API

Tworzy nowy obiekt LoaderContext z określonymi ustawieniami. Szczegółowe informacje na temat tych ustawień zawierają opisy właściwości tej klasy.

Powiązane elementy interfejsu API