Loader  - AS3

Zawiera główny obiekt wyświetlany pliku SWF lub plik obrazu (JPG, PNG lub GIF), który został załadowany przy pomocy metod load() lub loadBytes().

Powiązane elementy interfejsu API

Zwraca obiekt LoaderInfo odpowiadający aktualnie ładowanemu obiektowi. Obiekty LoaderInfo są dzielone pomiędzy obiektem Loader a obiektem załadowanej zawartości. Obiekt LoaderInfo dostarcza informację postępu ładowania oraz statystyki ładowanego pliku.

Zdarzenia związane z ładowaniem są wywoływane przez obiekt LoaderInfo, odwoływany przez właściwość contentLoaderInfo obiektu Loader. Właściwość contentLoaderInfo jest ustawiona na prawidłowy obiekt LoaderInfo jeszcze przed ładowaniem zawartości, co pozwala na dodanie detektorów zdarzeń do obiektu przed ładowaniem.

Do wykrywania nieprzechwyconych błędów wywołanych w załadowanym pliku SWF należy używać właściwości Loader.uncaughtErrorEvents, a nie właściwości Loader.contentLoaderInfo.uncaughtErrorEvents.

Powiązane elementy interfejsu API

var url:String = "http://www.helpexamples.com/flash/images/image2.jpg";
var urlRequest:URLRequest = new URLRequest(url);
var loader:Loader = new Loader();
loader.contentLoaderInfo.addEventListener(Event.COMPLETE, loader_complete);
loader.load(urlRequest);
addChild(loader);
 
function loader_complete(evt:Event):void {
    var target_mc:Loader = evt.currentTarget.loader as Loader;
    target_mc.x = (stage.stageWidth - target_mc.width) / 2;
    target_mc.y = (stage.stageHeight - target_mc.height) / 2;
}

Obiekt, który wywołuje zdarzenie uncaughtError, gdy wystąpi nieobsłużony błąd w pliku SWF załadowanym przez ten obiekt Loader. Sytuacja taka ma miejsce, gdy błąd zostanie wywołany poza blokiem try..catch lub gdy zostanie wywołany obiekt zdarzenia ErrorEvent, dla którego nie zarejestrowano żadnych detektorów.

Należy pamiętać, że właściwość uncaughtErrorEvents obiektu Loader wywołuje zdarzenia, które są przez nią propagowane. Nie wywołuje zdarzeń bezpośrednio. W szczególności nigdy nie wywołuje zdarzenia uncaughtErrorEvent w fazie celu. Wywołuje to zdarzenie wyłącznie w fazach przechwytywania i propagacji. Aby wykryć nieprzechwycony błąd w bieżącym pliku SWF (pliku SWF, w którym jest zdefiniowany obiekt Loader), należy skorzystać właściwości LoaderInfo.uncaughtErrorEvents.

Jeśli treść ładowana przez obiekt Loader jest plikiem SWF AVM1 (ActionScript 2), wówczas nieprzechwycone błędy w pliku SWF AVM1 nie powodują zdarzenia uncaughtError.

Powiązane elementy interfejsu API

package
{
    import flash.display.Loader;
    import flash.display.Sprite;
    import flash.events.ErrorEvent;
    import flash.events.UncaughtErrorEvent;
    import flash.net.URLRequest;

    public class LoaderUncaughtErrorEventExample extends Sprite
    {
        private var ldr:Loader;
        
        public function LoaderUncaughtErrorEventExample()
        {
            ldr = new Loader();
            ldr.load(new URLRequest("child.swf"));
            ldr.uncaughtErrorEvents.addEventListener(UncaughtErrorEvent.UNCAUGHT_ERROR, uncaughtErrorHandler);
        }
        
        private function uncaughtErrorHandler(event:UncaughtErrorEvent):void
        {
            if (event.error is Error)
            {
                var error:Error = event.error as Error;
                // do something with the error
            }
            else if (event.error is ErrorEvent)
            {
                var errorEvent:ErrorEvent = event.error as ErrorEvent;
                // do something with the error
            }
            else
            {
                // a non-Error, non-ErrorEvent type was thrown and uncaught
            }
        }
    }
}

Tworzy obiekt Loader, który umożliwia ładowanie plików w formatach SWF, JPEG, GIF i PNG. Należy wywołać metodę load() w celu załadowania zasobu jako element podrzędny instancji Loader. Możliwe jest dodanie obiektu Loader do listy wyświetlania (na przykład przez zastosowanie metody addChild() instancji DisplayObjectContainer). Zasób pojawia się na obiekcie Stage w trakcie ładowania.

Możliwe jest również zastosowanie instancji klasy Loader „spoza listy”, bez dodawania jej do kontenera obiektów wyświetlanych na liście wyświetlania. W tym trybie instancja Loader może być wykorzystywana do ładowania pliku SWF zawierającego dodatkowe moduły aplikacji.

W celu wykrycia momentu zakończenia ładowania pliku SWF, możliwe jest wykorzystanie zdarzeń obiektu LoaderInfo skojarzonego z właściwością contentLoaderInfo obiektu Loader. W tym momencie kod znajdujący się w pliku modułu SWF może być wykonany w celu inicjalizacji i startu modułu. W trybie „spoza listy” instancja klasy Loader może być również wykorzystana do załadowania pliku SWF zawierającego składniki lub zasoby multimedialne. I ponownie możliwe jest korzystanie z powiadomień o zdarzeniach obiektu LoaderInfo w celu wykrywania zakończenia ładowania składników. W tym momencie aplikacja może zacząć korzystać ze składników i zasobów multimedialnych w bibliotece pliku SWF poprzez instancjonowanie klas ActionScript 3.0, które reprezentują te składniki i zasoby.

W celu określenia stanu obiektu Loader należy monitorować następujące zdarzenia skojarzone z właściwością contentLoaderInfo obiektu Loader:

• Zdarzenie open jest wywoływane przy rozpoczęciu ładowania.
• Zdarzenie ioError lub securityError jest wywoływane, w sytuacji gdy plik nie może być załadowany lub przy wystąpieniu błędu w trakcie ładowania.
• Zdarzenie progress jest wywoływane ciągle w trakcie ładowania pliku.
• Zdarzenie complete jest wywoływane w momencie zakończenia ładowania pliku, ale przed udostępnieniem metod i właściwości załadowanego klipu filmowego.
• Zdarzenie init jest wywoływane po udostępnieniu właściwości i metod załadowanego pliku SWF, co umożliwia jego manipulację. Zdarzenie jest wywoływane przed procedurą obsługi zdarzenia complete. Przy strumieniowaniu plików SWF zdarzenie init może pojawić się znacznie wcześniej niż zdarzenie complete. W większości przypadków należy korzystać z modułu obsługi zdarzenia init.

Uwagi (tylko iOS): Aplikacja AIR działająca w systemie iOS może wczytywać pliki SWF zawierające kod ActionScript tylko z pakietu aplikacji. To ograniczenie obowiązuje dla każdego kodu ActionScript, również dla zasobów z nazwami klas wyeksportowanymi do kodu ActionScript. Aby wczytać jakikolwiek plik SWF, należy to zrobić przy użyciu tej samej domeny aplikacji, której użyto dla macierzystego pliku SWF.

W wersjach środowiska AIR starszych niż 3.6 można wczytywać tylko pliki SWF niezawierające kodu bajtowego ActionScript — niezależnie od tego, czy wczytywanie odbywa się z pakietu aplikacji, czy przez sieć. Zamiast używać zewnętrznego pliku SWF z kodem ActionScript, można utworzyć bibliotekę SWC i połączyć ją z głównym plikiem SWF.

Te ograniczenia nie dotyczą aplikacji uruchamianych w symulatorze systemu iOS (z parametrem ipa-test-interpreter-simulator lub ipa-debug-interpreter-simulator) ani w trybie interpretera (z parametrem ipa-test-interpreter lub ipa-debug-interpreter).

Powiązane elementy interfejsu API

Anuluje operację metody load(), która jest w trakcie wykonywania dla instancji Loader.

Powiązane elementy interfejsu API

Ładuje plik SWF, JPEG, stopniowy JPG, nieanimowany GIF lub plik PNG do obiektu podrzędnego tego obiektu Loader. W przypadku ładowania animowanego pliku GIF wyświetlana jest tylko pierwsza klatka. Biorąc pod uwagę, iż obiekt Loader może zawierać wyłącznie pojedynczy obiekt podrzędny, wywoływanie kolejnego żądania load() kończy poprzednie żądanie, jeżeli takie oczekuje na wykonanie, oraz rozpoczyna nowe ładowanie.

Uwaga: W środowisku AIR 1.5 i programie Flash Player 10 maksymalna szerokość i wysokość ładowanego obrazu wynosi 8191 pikseli, a łączna liczba pikseli nie może przekroczyć 16 777 215. (A zatem, jeśli ładowany obraz ma szerokość 8,191 pikseli, nie może być wyższy niż 2048 pikseli). W prorgamie Flash Player 9 i wcześniejszych wersjach oraz w środowisku AIR 1.1 i wcześniejszych wersjach ograniczenie wysokości i szerokości wynosiło 2880 pikseli.

Plik SWF lub obraz załadowany do obiektu Loader dziedziczy położenie oraz właściwości obrotu i skali nadrzędnych obiektów wyświetlanych obiektu Loader.

Należy stosować metodę unload() do usuwania filmów lub obrazów załadowanych tą metodą, lub do anulowania operacji ładowania będących w trakcie wykonywania.

Istnieje możliwość zablokowania używania tej metody przez plik SWF. W tym celu należy ustawić parametr allowNetworking znaczników object oraz embed na stronie HTML zawierającej zawartość SWF.

Uwagi dotyczące systemu iOS

Aplikacja AIR działająca w systemie iOS może wczytywać pliki SWF zawierające kod ActionScript tylko z pakietu aplikacji. To ograniczenie obowiązuje dla każdego kodu ActionScript, również dla zasobów z nazwami klas wyeksportowanymi do kodu ActionScript. Aby wczytać jakikolwiek plik SWF, należy to zrobić przy użyciu tej samej domeny aplikacji, której użyto dla macierzystego pliku SWF. Przykład:

     var loader:Loader = new Loader();
     var url:URLRequest = new URLRequest("swfs/SecondarySwf.swf");
     var loaderContext:LoaderContext = new LoaderContext(false, ApplicationDomain.currentDomain, null);
     loader.load(url, loaderContext);

W systemie iOS nie można też wczytać pliku SWF zawierającego jakikolwiek kod bajtowy ActionScript, a następnie usunąć go i wczytać ponownie. Próba wykonania takiej operacji powoduje wygenerowanie przez środowisko wykonawcze błędu 3764.

W wersjach środowiska AIR starszych niż 3.6 można wczytywać tylko pliki SWF niezawierające kodu bajtowego ActionScript — niezależnie od tego, czy wczytywanie odbywa się z pakietu aplikacji, czy przez sieć. Zamiast używać zewnętrznego pliku SWF z kodem ActionScript, można utworzyć bibliotekę SWC i połączyć ją z głównym plikiem SWF.

Te ograniczenia nie dotyczą aplikacji uruchamianych w symulatorze systemu iOS (z parametrem ipa-test-interpreter-simulator lub ipa-debug-interpreter-simulator) ani w trybie interpretera (z parametrem ipa-test-interpreter lub ipa-debug-interpreter).

Zabezpieczenia modułu wczytującego

Korzystając z tej metody należy uwzględnić model zabezpieczeń programu Flash Player, który został przedstawiony w opisie klasy Loader.

W programie Flash Player 10 i nowszych wersjach, jeśli użyty zostanie wieloczęściowy nagłówek Content-Type (np. "multipart/form-data"), w którym przesyłane są pliki (wskazywane przez parametr "filename" w nagłówku "content-disposition" w treści operacji POST), wówczas operacja POST podlega regułom zabezpieczeń zastosowanym do wysyłania plików:

• Operację POST należy wykonać w odpowiedzi na działanie zainicjowane przez użytkownika, np. kliknięcie myszy lub naciśnięcie klawisza.
• Jeśli operacja POST jest operacją międzydomenową (cel operacji POST nie znajduje się na tym samym serwerze, co plik SWF, który wysyła żądanie POST), docelowy serwer musi dostarczyć plik reguł URL, który zezwoli na międzydomenowy dostęp.

Dla dowolnego wieloczęściowego nagłówka Content-Type również składnia musi być poprawna (zgodnie ze standardem RFC2046). Jeśli składnia okaże się niepoprawna, operacja POST będzie podlegać regułom zabezpieczeń stosowanym do wysyłania plików.

Więcej informacji na temat zabezpieczeń zawiera odpowiedni temat w Centrum programistów programu Flash Player w kategorii Bezpieczeństwo.

Parametry

Powiązane elementy interfejsu API

Wczytuje dane binarne przechowywane w obiekcie ByteArray.

Metoda loadBytes() jest asynchroniczna. Przed uzyskaniem dostępu do właściwości załadowanego obiektu należy poczekać na zdarzenie "init".

Podczas używania tej metody należy uwzględnić model zabezpieczeń programu Flash Player, który został przedstawiony w opisie klasy Loader.

Uwaga (tylko iOS): Aplikacja AIR działająca w systemie iOS może wczytywać pliki SWF zawierające kod ActionScript tylko z pakietu aplikacji. To ograniczenie obowiązuje dla każdego kodu ActionScript, również dla zasobów z nazwami klas wyeksportowanymi do kodu ActionScript. Aby wczytać jakikolwiek plik SWF, należy to zrobić przy użyciu tej samej domeny aplikacji, której użyto dla macierzystego pliku SWF.

W wersjach środowiska AIR starszych niż 3.6 wywołanie tej metody nie powoduje żadnej reakcji w systemie iOS.

Parametry

Powiązane elementy interfejsu API

Wczytuje wystąpienie klasy IFilePromise.

Metoda loadFilePromise przyjmuje obiekt IFilePromise i wczytuje dane binarne. Jeśli dane są w strumieniu progresywnym, na przykład jest to materiał wideo, program czeka na zdarzenia „init” lub „progress” przed uzyskaniem dostępu do właściwości wczytanego obiektu. Jeśli tak nie jest, program czeka na zdarzenie „complete”, aby uzyskać pewność, że dane zostały wczytane do końca.

Podczas używania tej metody należy uwzględnić model zabezpieczeń programu Flash Player, który został przedstawiony w opisie klasy Loader.

Parametry

Powiązane elementy interfejsu API

Usuwa element potomny tego obiektu Loader, który został wczytany za pomocą metody load(). Właściwość property powiązanego obiektu LoaderInfo jest resetowana do wartości null. Element potomny nie konieczne jest niszczony, dlatego że inne obiekty mogą odwoływać się do niego, jednakże nie jest to już potomek obiektu Loader.

Wywołanie metody unload() powoduje ustawienie właściwości contentLoaderInfo obiektu Loader na wartość null. Wszystkie zasoby wizualne wczytane razem z plikiem SWF są usuwane z pamięci. Definicje klas ActionScript pochodzące z wczytanego pliku SWF pozostają w pamięci, a kod w tej samej domenie aplikacji co wczytany plik SWF może uzyskiwać dostęp do tych klas i tworzyć ich nowe wystąpienia.

Uwaga (tylko system iOS): Ta metoda nie ma wpływu na system iOS w przypadku wersji środowiska AIR starszych niż 3.6.

W ramach najlepszej praktyki przed usunięciem załadowanego podrzędnego pliku SWF koniecznie należ zamknąć wszelkie strumienie w obiektach tego pliku, jak na przykład LocalConnection, NetConnection, NetStream oraz Sound. W innym przypadku audio w podrzędnym pliku SWF może być wciąż odgrywane, mimo iż plik ten został już usunięty. W celu zamknięcia strumieni w potomnym pliku SWF należy dodać detektor zdarzeń do potomka, który nasłuchuje zdarzenia unload. Gdy obiekt macierzysty wywołuje metodę Loader.unload(), wówczas do potomka wywoływane jest zdarzenieunload. Poniższy kod ilustruje jak można tego dokonać:

function closeAllStreams(evt:Event) { 
    myNetStream.close();
    mySound.close();
    myNetConnection.close();
    myLocalConnection.close();
}

myMovieClip.loaderInfo.addEventListener(Event.UNLOAD, closeAllStreams);

Powiązane elementy interfejsu API

Podejmuje próbę usunięcia załadowanej zawartości pochodnego pliku SWF oraz zatrzymuje wykonywanie poleceń z ładowanych plików SWF. Ta metoda podejmuje próbę usunięcia załadowanych plików SWF, które zostały załadowane za pomocą metody Loader.load() lub Loader.loadBytes() poprzez usunięcie odwołań do obiektów EventDispatcher, NetConnection, Timer, Sound lub Video podrzędnego pliku SWF. W rezultacie występują następujące zdarzenia dla podrzędnego pliku SWF oraz listy wyświetlanej tego pliku:

• Dźwięki zostają zatrzymane.
• Detektory zdarzeń stołu montażowego zostają usunięte.
• Detektory zdarzeń enterFrame, frameConstructed, exitFrame, activate i deactivate zostają usunięte.
• Czasomierze zostają zatrzymane.
• Instancje Camera i Microphone zostają odłączone.
• Klipy filmowe zostają zatrzymane.

Wywołanie metody unloadAndStop() powoduje ustawienie właściwości contentLoaderInfo obiektu Loader na wartość null. Wszystkie zasoby wizualne wczytane razem z plikiem SWF są usuwane z pamięci. Definicje klas ActionScript pochodzące z wczytanego pliku SWF pozostają w pamięci, a kod w tej samej domenie aplikacji co wczytany plik SWF może uzyskiwać dostęp do tych klas i tworzyć ich nowe wystąpienia.

Uwaga (tylko system iOS): Ta metoda nie ma wpływu na system iOS w przypadku wersji środowiska AIR starszych niż 3.6.

Parametry

Powiązane elementy interfejsu API

1. Tworzona jest właściwość url, która jest lokalizacją oraz nazwą pliku obrazu.
2. W konstruktorze LoaderExample nowy obiekt Loader nazwany loader jest tworzony, a następnie przekazywany do metody configureListeners(), opisanej w kroku nr 3.
3. Konstruktor tworzy nowe wystąpienie klasy URLRequest — request — z przekazaną właściwością url, aby nazwa i lokalizacja pliku były znane.
4. Obiekt request jest przekazywany do metody load() obiektu loader, który ładuje obraz do listy wyświetlania.
5. Detektor zdarzeń clickHandler jest zarejestrowany dla zdarzenia click w programie ładującym. Po kliknięciu myszą załadowany obraz jest usuwany.
6. Metoda configureListeners() dodaje siedem detektorów zdarzeń przy wykorzystaniu poniższych metod:
   • Metoda completeHandler() jest wykonywana w momencie zakończenia ładowania obrazu.
   • Metoda httpStatusHandler() jest wykonywana, jeśli obraz nie jest załadowany lokalne i tylko w sytuacji gdy żądanie sieciowe jest udostępnione, a moduł Flash Player może je wykryć.
   • Metoda initHandler() jest wykonywana przed metodą completeHandler() i po metodzie progressHandler(). Generalnie zdarzenie init jest bardziej przydatne przy ładowaniu plików SWF.
   • Metoda ioErrorHandler() jest wykonywana, jeżeli plik obrazu nie jest dostępny.
   • Metoda openHandler() jest wykonywana przy pierwszym otwarciu pliku.
   • Metoda progressHandler() jest wykonywana gdy rozpoczynane jest ładowanie pliku obrazu oraz ponownie, gdy ładowanie jest zakończone.
   • Metoda unLoadHandler() jest wykonywana, gdy załadowany obraz jest usuwany metodą unload() w momencie kliknięcia obrazu przez użytkownika.

Należy pamiętać o następujących wymaganiach:

• Dla zilustrowania tego przykładu konieczne jest umieszczenie pliku o nazwie Image.gif w tym samym katalogu, co skompilowany plik SWF. Należy korzystać z obrazu, którego obszar mieści się w granicy wymiarów głównego pliku SWF.
• Wprawdzie przykład ten ilustruje wykorzystanie wszystkich zdarzeń dostępnych dla obiektu LoaderInfo, jednak większość sytuacji wymaga wykorzystania jedynie podzbioru zdarzeń. W szczególności przy ładowaniu wyłącznie pliku obrazu zdarzenie complete (oraz być może zdarzenie ioError) są wystarczające przy ładowaniu lokalnego obrazu.

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

    public class LoaderExample extends Sprite {
        private var url:String = "Image.gif";

        public function LoaderExample() {
            var loader:Loader = new Loader();
            configureListeners(loader.contentLoaderInfo);
            loader.addEventListener(MouseEvent.CLICK, clickHandler);

            var request:URLRequest = new URLRequest(url);
            loader.load(request);

            addChild(loader);
        }

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

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

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

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

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

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

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

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

        private function clickHandler(event:MouseEvent):void {
            trace("clickHandler: " + event);
            var loader:Loader = Loader(event.target);
            loader.unload();
        }
    }
}