Obsługa zdarzeń powiązanych z HTML w środowisku AIR

Adobe AIR 1.0 i starsze wersje

System obsługi zdarzeń umożliwia programistom określanie reakcji na czynności użytkownika i zdarzenia systemowe w wygodny sposób. Model zdarzeń Adobe® AIR® jest nie tylko wygodny, ale również zgodny ze standardami. Zgodnie ze specyfikacją Document Object Model (DOM) Level 3 Events Specification, która jest branżowym standardem architektury obsługi zdarzeń, model zdarzeń stanowi wydajne i intuicyjne w obsłudze narzędzie dla programistów.

HTMLLoader, zdarzenia

Obiekt HTMLLoader wywołuje następujące zdarzenia Adobe® ActionScript® 3.0:

Zdarzenie

Opis

htmlDOMInitialize

Wywoływane po utworzeniu dokumentu HTML, ale przed analizą skryptów oraz przed dodaniem węzłów DOM do strony.

complete

Wywoływane po utworzeniu DOM HTML w odpowiedzi na operację ładowania, natychmiast po zdarzeniu onload na stronie HTML.

htmlBoundsChanged

Wywoływane przy zmianie jednej lub obydwu właściwości: contentWidth i contentHeight .

locationChange

Wywoływane po zmianie właściwości location obiektu HTMLLoader.

locationChanging

To zdarzenie jest wywoływane przed zmianą lokalizacji obiektu HTMLLoader spowodowaną przez działanie użytkownika, wywołanie języka JavaScript lub przekierowanie. Zdarzenie locationChanging nie jest wywoływane w przypadku użycia następujących metod: load() , loadString() , reload() , historyGo() , historyForward() i historyBack() .

Wywołanie metody preventDefault() obiektu wywołanego zdarzenia powoduje anulowanie nawigacji.

Zdarzenie locationChanging nie jest wywoływane w przypadku otwarcia łącza w przeglądarce systemowej, gdyż nie zmienia się wtedy lokalizacja obiektu HTMLLoader.

scroll

Wywoływane za każdym razem, gdy mechanizm HTML zmieni położenie przewijania. Zdarzenia scroll mogą występować z powodu nawigacji do odsyłaczy kotwiczących (odsyłacze # ) na stronie lub z powodu wywołań metody window.scrollTo() . Wprowadzenie tekstu do obszaru tekstu wejściowego lub do obszaru tekstowego również może spowodować wywołanie zdarzenia scroll.

uncaughtScriptException

Wywoływane w przypadku wystąpienia wyjątku JavaScript w module HTMLLoader, gdy wyjątek nie zostanie wychwycony w kodzie JavaScript.

Dla zdarzenia JavaScript (takiego jak onClick ) można również zarejestrować funkcję ActionScript. Szczegółowe informacje zawiera sekcja Obsługa zdarzeń DOM za pomocą kodu ActionScript .

Obsługa zdarzeń DOM za pomocą kodu ActionScript

Istnieje możliwość zarejestrowania funkcji ActionScript w celu reagowania na zdarzenia JavaScript. Weźmy na przykład pod uwagę następującą treść HTML: 

<html> 
<body> 
    <a href="#" id="testLink">Click me.</a> 
</html>

Możliwe jest zarejestrowanie funkcji ActionScript jako modułu obsługi dla dowolnego zdarzenia na stronie. Na przykład: poniższy kod dodaje funkcję clickHandler() jako detektor zdarzenia onclick elementu testLink na stronie HTML: 

var html:HTMLLoader = new HTMLLoader( ); 
var urlReq:URLRequest = new URLRequest("test.html"); 
html.load(urlReq); 
html.addEventListener(Event.COMPLETE, completeHandler); 
 
function completeHandler(event:Event):void { 
    html.window.document.getElementById("testLink").onclick = clickHandler; 
} 
 
function clickHandler( event:Object ):void { 
    trace("Event of type: " + event.type ); 
}

Wywoływany obiekt zdarzenia nie należy do typu flash.events.Event ani do żadnej z podklas klasy Event. Typ argumentu funkcji obsługi zdarzenia należy zadeklarować jako klasę Object.

Możliwe jest również użycie metody addEventListener() w celu zarejestrowania dla tych zdarzeń. Na przykład: możliwe jest zastąpienie metody completeHandler() z poprzedniego przykładu następującym kodem: 

function completeHandler(event:Event):void { 
    var testLink:Object = html.window.document.getElementById("testLink"); 
    testLink.addEventListener("click", clickHandler); 
}

Gdy detektor odwołuje się do konkretnego elementu DOM, dobrą metodą jest oczekiwanie na wywołanie zdarzenia complete przez obiekt nadrzędny HTMLLoader, a dopiero potem dodanie detektorów zdarzeń. Strony HTML często ładują wiele plików i wówczas model DOM HTML nie zostaje w pełni zbudowany do czasu załadowania i przeanalizowania wszystkich plików. Obiekt HTMLLoader wywołuje zdarzenie complete po utworzeniu wszystkich elementów.

Reagowanie na niewychwycone wyjątki JavaScript

Rozważmy poniższy kod HTML: 

<html> 
<head> 
    <script> 
        function throwError() { 
            var x = 400 * melbaToast; 
        } 
    </script> 
</head> 
<body> 
    <a href="#" onclick="throwError()">Click me.</a> 
</html>

Zawiera on funkcję JavaScript throwError() , która odwołuje się do nieznanej zmiennej melbaToast : 

var x = 400 * melbaToast;

Gdy operacja JavaScript napotka niedozwoloną operację, która nie zostanie wychwycona w kodzie JavaScript za pomocą struktury try / catch , wówczas obiekt HTMLLoader zawierający stronę wywołuje zdarzenie HTMLUncaughtScriptExceptionEvent. Dla tego zdarzenia można zarejestrować moduł obsługi, jak w poniższym przykładzie: 

var html:HTMLLoader = new HTMLLoader(); 
var urlReq:URLRequest = new URLRequest("test.html"); 
html.load(urlReq); 
html.width = container.width; 
html.height = container.height; 
container.addChild(html); 
html.addEventListener(HTMLUncaughtScriptExceptionEvent.UNCAUGHT_SCRIPT_EXCEPTION, 
                           htmlErrorHandler); 
function htmlErrorHandler(event:HTMLUncaughtJavaScriptExceptionEvent):void  
{ 
    event.preventDefault(); 
    trace("exceptionValue:", event.exceptionValue) 
    for (var i:int = 0; i < event.stackTrace.length; i++) 
    { 
        trace("sourceURL:", event.stackTrace[i].sourceURL); 
        trace("line:", event.stackTrace[i].line); 
        trace("function:", event.stackTrace[i].functionName); 
    } 
}

W kodzie JavaScript to samo zdarzenie można obsługiwać za pomocą właściwości window.htmlLoader: 

<html> 
<head> 
<script language="javascript" type="text/javascript" src="AIRAliases.js"></script> 
 
    <script> 
        function throwError() { 
            var x = 400 * melbaToast; 
        } 
         
        function htmlErrorHandler(event) { 
            event.preventDefault(); 
            var message = "exceptionValue:" + event.exceptionValue + "\n"; 
            for (var i = 0; i < event.stackTrace.length; i++){ 
                message += "sourceURL:" + event.stackTrace[i].sourceURL +"\n"; 
                message += "line:" + event.stackTrace[i].line +"\n"; 
                message += "function:" + event.stackTrace[i].functionName + "\n"; 
            } 
            alert(message); 
        } 
         
        window.htmlLoader.addEventListener("uncaughtScriptException", htmlErrorHandler); 
    </script> 
</head> 
<body> 
    <a href="#" onclick="throwError()">Click me.</a> 
</html>

Moduł obsługi zdarzenia htmlErrorHandler() anuluje domyślne zachowanie zdarzenia (domyślnie zdarzenie wysyła komunikat o błędzie JavaScript jako wynik działania aplikacji AIR) i generuje własny komunikat wyjściowy. Wartością wyjściową jest wartość exceptionValue obiektu HTMLUncaughtScriptExceptionEvent. Wartością wyjściową są właściwości poszczególnych obiektów z tablicy stackTrace : 

exceptionValue: ReferenceError: Can't find variable: melbaToast 
sourceURL: app:/test.html 
line: 5 
function: throwError 
sourceURL: app:/test.html 
line: 10 
function: onclick

Obsługa zdarzeń środowiska wykonawczego za pomocą JavaScript

Klasy środowiska wykonawczego obsługują moduły obsługi zdarzeń za pomocą metody addEventListener() . W celu dodania funkcji modułu obsługi dla zdarzenia należy wywołać metodę addEventListener() obiektu, który wywołał zdarzenie, udostępniając typ zdarzenia i funkcję obsługi. Na przykład: w celu wykrycia zdarzenia closing wywołanego, gdy użytkownik kliknął przycisk zamknięcia okna na pasku tytułu, należy użyć poniższej instrukcji: 

window.nativeWindow.addEventListener(air.NativeWindow.CLOSING, handleWindowClosing);

Tworzenie funkcji modułu obsługi zdarzeń

Poniższy kod tworzy przykładowy plik HTML, który wyświetla informacje o pozycji w oknie głównym. Funkcja modułu obsługi o nazwie moveHandler() wykrywa zdarzenie move (zdefiniowane przez klasę NativeWindowBoundsEvent) okna głównego. 

<html> 
    <script src="AIRAliases.js" /> 
    <script> 
        function init() { 
            writeValues(); 
            window.nativeWindow.addEventListener(air.NativeWindowBoundsEvent.MOVE, 
                                                     moveHandler); 
        } 
        function writeValues() { 
            document.getElementById("xText").value = window.nativeWindow.x; 
            document.getElementById("yText").value = window.nativeWindow.y; 
        } 
        function moveHandler(event) { 
            air.trace(event.type); // move 
            writeValues(); 
        } 
    </script> 
    <body onload="init()" /> 
        <table> 
            <tr> 
                <td>Window X:</td> 
                <td><textarea id="xText"></textarea></td> 
            </tr> 
            <tr> 
                <td>Window Y:</td> 
                <td><textarea id="yText"></textarea></td> 
            </tr> 
        </table> 
    </body> 
</html>

Gdy użytkownik przesunie okno, w obszarze tekstowym pojawią się nowe pozycje X i Y okna:

Należy zauważyć, że obiekt zdarzenia został przekazany jako argument do metody moveHandler() . Parametr zdarzenia umożliwia funkcji modułu obsługi sprawdzenie obiektu zdarzenia. W tym przykładzie właściwość type obiektu zdarzenia służy do zgłoszenia, czy zdarzenie jest zdarzeniem move .

Usuwanie detektorów zdarzeń

Do usuwania zbędnych detektorów zdarzeń służy metoda removeEventListener() . Usuwanie detektorów, które nie będą używane, jest bardzo dobrym sposobem postępowania. Do wymaganych parametrów należą eventName i listener i są to te same parametry, jak parametry wymagane dla metody addEventListener() .

Usuwanie detektorów zdarzeń ze stron HTML, które nawigują

Jeśli treść HTML służy do nawigacji lub treść HTML jest usuwana, ponieważ okno (w której się znajduje) zostało zamknięte, wówczas detektory zdarzeń, które odwołują się do obiektów na niezaładowanej stronie, nie są automatycznie usuwane. Gdy obiekt wywoła zdarzenie dla modułu obsługi, który został już usunięty z pamięci, zostanie wyświetlony następujący komunikat podobny do następującego: „Aplikacja podjęła próbę utworzenia odwołania do obiektu JavaScript na stronie HTML, która nie jest już załadowana”.

W celu uniknięcia tego błędu należy usunąć detektory zdarzeń JavaScript ze strony HTML przed jej dezaktywacją. W przypadku nawigacji na stronie (w obiekcie HTMLLoader) należy usunąć detektor zdarzeń podczas zdarzenia unload obiektu window .

Na przykład: poniższy kod JavaScript usuwa detektor zdarzenia uncaughtScriptException : 

window.onunload = cleanup; 
window.htmlLoader.addEventListener('uncaughtScriptException', uncaughtScriptException); 
function cleanup() 
{ 
    window.htmlLoader.removeEventListener('uncaughtScriptException', 
                            uncaughtScriptExceptionHandler); 
}

Aby zapobiec występowaniu błędu podczas zamykania okna, które zawiera treść HTML, należy wywołać funkcję czyszczenia w odpowiedzi na zdarzenie closing obiektu NativeWindow ( window.nativeWindow ). Na przykład: poniższy kod JavaScript usuwa detektor zdarzenia uncaughtScriptException : 

window.nativeWindow.addEventListener(air.Event.CLOSING, cleanup); 
function cleanup() 
{ 
    window.htmlLoader.removeEventListener('uncaughtScriptException', 
                            uncaughtScriptExceptionHandler); 
}

Można zapobiec występowaniu tego błędu, usuwając detektor zdarzenia natychmiast po jego wykonaniu (jeśli zdarzenie ma być obsłużone tylko raz). Przykład: poniższy kod JavaScript tworzy okno html poprzez wywołanie metody createRootWindow() klasy HTMLLoader, a następnie dodaje detektor dla zdarzenia complete . Gdy zostanie wywołany moduł obsługi zdarzenia complete , usuwa on własny detektor zdarzeń za pomocą funkcji removeEventListener() : 

var html = runtime.flash.html.HTMLLoader.createRootWindow(true); 
html.addEventListener('complete', htmlCompleteListener); 
function htmlCompleteListener() 
{ 
    html.removeEventListener(complete, arguments.callee) 
    // handler code.. 
} 
html.load(new runtime.flash.net.URLRequest("second.html"));

Usuwanie zbędnych detektorów zdarzeń umożliwia również modułowi czyszczenia pamięci odzyskanie pamięci skojarzonej z tymi detektorami.

Sprawdzanie dostępności detektorów zdarzeń

Metoda hasEventListener() umożliwia sprawdzenie dostępności detektora zdarzenia w obiekcie.