Обработка в AIR событий HTML

Adobe AIR 1.0 и более новых версий

События HTMLLoader
Обработка событий DOM с помощью ActionScript
Ответ на необрабатываемые исключения JavaScript
Обработка событий среды выполнения с помощью JavaScript
- Создание функции обработчика события

Система обработки событий облегчает для программистов процедуру ответа на действия пользователя и события системы. Модель событий Adobe® AIR® не только удобна, но и соответствует принятым стандартам. Модель событий, основанная на Спецификации событий DOM 3-го уровня — архитектуре обработки событий, принятой в отрасли, — предоставляет эффективный и несложный инструмент обработки событий для программистов.

События HTMLLoader

Объект HTMLLoader отправляет следующие события Adobe® ActionScript® 3.0:

Событие	Описание
`htmlDOMInitialize`	Отправляется после создания HTML-документа, но до разбора каких-либо сценариев или добавления к странице узлов DOM.
`complete`	Отправляется при создании модели DOM HTML в ответ на загрузку, сразу после выполнения события `onload` на HTML-странице.
`htmlBoundsChanged`	Отправляется при изменении одного из свойств `contentWidth` и `contentHeight` или обоих этих свойств.
`locationChange`	Отправляется при изменении свойства location объекта HTMLLoader.
`scroll`	Отправляется при любом изменении положения прокрутки в HTML. События scroll могут быть вызваны переходами по якорным ссылкам (содержащим символ `#`) на странице или в результате вызова метода `window.scrollTo()`. Ввод текста в текстовое поле или область также может вызывать событие scroll.
`uncaughtScriptException`	Отправляется при генерации в объекте HTMLLoader исключения JavaScript, которое не обнаруживается кодом JavaScript.

Также можно зарегистрировать функцию ActionScript для события JavaScript (например, onClick). Дополнительные сведения см. в разделе Обработка событий DOM с помощью ActionScript.

Обработка событий DOM с помощью ActionScript

Функции ActionScript могут быть зарегистрированы для ответа на события JavaScript. Например, рассмотрим следующее HTML-содержимое:

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

Функция ActionScript может быть зарегистрирована в качестве обработчика любого события на этой странице. Например, в коде ниже функция clickHandler() добавляется на HTML-страницу в качестве прослушивателя события onclick элемента testLink:

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 ); 
}

Отправляемый объект события не является типом flash.events.Event или одним из подклассов Event. Используйте класс Object для объявления типа аргумента функции обработчика событий.

Для регистрации прослушивателей этих событий также может использоваться метод addEventListener(). Например, метод completeHandler() из предыдущего примера может быть заменен:

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

Когда прослушиватель обращается к какому-либо элементу DOM, рекомендуется дождаться, пока родительский объект HTMLLoader отправит событие complete, и только после этого добавлять прослушиватели. HTML-страницы часто загружают несколько файлов, а модель DOM в HTML не может быть полностью построена, пока все файлы не будут загружены и разобраны. Объект HTMLLoader отправляет событие complete, когда все элементы уже созданы.

Ответ на необрабатываемые исключения JavaScript

Рассмотрим следующий HTML-документ:

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

Он содержит функцию JavaScript throwError(), обращающуюся к неизвестной переменной melbaToast:

var x = 400 * melbaToast;

Когда операция JavaScript сталкивается с недопустимой операцией, которую код JavaScript не обрабатывает с помощью структуры try/catch, объект HTMLLoader, в котором содержится страница, отправляет событие HTMLUncaughtScriptExceptionEvent. Для этого события можно зарегистрировать прослушиватель, как показано ниже:

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); 
    } 
}

В JavaScript можно обрабатывать одно и то же событие с помощью свойства 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>

Обработчик события htmlErrorHandler() отменяет поведение события по умолчанию (т. е. отправку сообщения об ошибке JavaScript в выводе трассировочных данных AIR) и генерирует собственное сообщение об ошибке вывода. Выводится значение exceptionValue объекта HTMLUncaughtScriptExceptionEvent. Выводятся свойства каждого объекта в массиве stackTrace:

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

Обработка событий среды выполнения с помощью JavaScript

Классы среды выполнения позволяют добавлять обработчики событий методом addEventListener(). Для добавления функции обработчика события вызовите метод addEventListener() объекта, который отправляет это событие, указав тип события и функцию обработчика. Например, чтобы прослушивать событие closing, отправляемое по щелчку мыши на значке закрытия окна, воспользуйтесь следующей инструкцией:

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

Создание функции обработчика события

Ниже показан код, в котором создается простой HTML-файл, отображающий информацию о положении главного окна. Функция обработчика moveHandler() прослушивает событие move (определено в классе NativeWindowBoundsEvent) главного окна.

<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>

Когда пользователь смещает окно, элементы textarea отображают новые положения по осям X и Y для этого окна:

Обратите внимание, что объект события передается методу moveHandler() в качестве аргумента. Параметр события позволяет функции обработчика исследовать объект события. В этом примере свойство type объекта события указывает, что событие относится к типу move.

Удаление прослушивателей событий

Метод removeEventListener() можно использовать для удаления неиспользуемых прослушивателей событий. Ненужные прослушиватели рекомендуется удалять. Обязательными являются параметры eventName и listener — как и для метода addEventListener().

Удаление прослушивателей событий на HTML-страницах с навигацией

При навигации по HTML-содержимому или его сбрасывании из-за закрытия содержащего его окна прослушиватели событий, указывающие на объекты на незагруженной странице, не удаляются автоматически. Когда объект отправляет событие уже выгруженному обработчику, появляется следующее сообщение об ошибке: «Приложение ссылается на объект JavaScript на HTML-странице, которая более не загружена».

Чтобы эта ошибка не возникала, удалите прослушиватели событий JavaScript с HTML-страницы, прежде чем она будет закрыта. При навигации по странице (в объекте HTMLLoader) удалите прослушиватель во время события unload объекта window.

Например, показанный ниже код JavaScript удаляет прослушиватель события uncaughtScriptException:

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

Чтобы эта ошибка не возникала при закрытии окон с HTML-содержимым, вызовите функцию cleanup в ответ на событие closing объекта NativeWindow (window.nativeWindow). Например, показанный ниже код JavaScript удаляет прослушиватель события uncaughtScriptException:

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

Вы также можете предупредить эту ошибку удалением прослушивателя события, как только он запустится (если событие требует лишь разовой обработки). Например, в следующем коде JavaScript окно HTML создается в результате вызова метода createRootWindow() класса HTMLLoader и добавления прослушивателя события complete. При вызове обработчика события complete он удаляет собственный прослушиватель с помощью функции 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"));

Удаление ненужных прослушивателей событий также позволяет системному сборщику мусора восстанавливать память, занятую этими прослушивателями.

Проверка существующих прослушивателей событий

Метод hasEventListener() позволяет проверить, зарегистрирован ли для объекта прослушиватель.