События

Cordova предоставляет различные события для использования в приложении. Код приложения может добавлять обработчики для этих событий. Например:

Файл HTML

<!DOCTYPE html>
<html>
    <head>
    <title>Device Ready Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8" src="example.js"></script>
    </head>
    <body onload="onLoad()">
    </body>
</html>

Файл JS

// example.js file
// Wait for device API libraries to load
//
function onLoad() {
    document.addEventListener("deviceready", onDeviceReady, false);
}

// device APIs are available
//
function onDeviceReady() {
    document.addEventListener("pause", onPause, false);
    document.addEventListener("resume", onResume, false);
    document.addEventListener("menubutton", onMenuKeyDown, false);
    // Add similar listeners for other events
}

function onPause() {
    // Handle the pause event
}

function onResume() {
    // Handle the resume event
}

function onMenuKeyDown() {
    // Handle the menubutton event
}

// Add similar event handlers for other events

Примечание: Приложения обычно должны использовать document.addEventListener для прикрепления обработчика события после deviceready

В следующей таблице перечислены события Cordova и поддерживаемые платформы:

Поддерживаемые платформы/ События	android	blackberry10	ios	Windows Phone 8	Windows
deviceready
pause
resume
backbutton
menubutton
searchbutton
startcallbutton
endcallbutton
volumedownbutton
volumeupbutton
activated

deviceready

Событие deviceready срабатывает, когда Cordova полностью загружен. Это событие необходимо для любого приложения. Оно сигнализирует о том, что устройства Cordova API загружены и готовы к доступу.

Cordova состоит из двух кодовых баз: нативного кода и JavaScript. Пока загружается нативный код, отображается пользовательская загрузка изображения. Однако JavaScript загружается только после загрузки DOM. Это означает, что веб-приложение потенциально может вызвать функцию JavaScript Cordova до того, как соответствующий нативный код станет доступным.

Событие deviceready срабатывает, когда Cordova полностью загрузился. После срабатывания события можно безопасно вызывать API Cordova. Приложения обычно прикрепляют обработчик событий с document.addEventListener после загрузки DOM документа HTML.

Событие deviceready ведет себя несколько иначе, чем другие. Любой обработчик событий, зарегистрированный после срабатывания события deviceready, вызывает свою функцию обратного вызова немедленно.

Быстрый пример

document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {
    // Now safe to use device APIs
}

pause

Событие pause срабатывает, когда нативная платформа помещает приложение в фоновый режим, обычно когда пользователь переключается на другое приложение.

Быстрый пример

document.addEventListener("pause", onPause, false);

function onPause() {
    // Handle the pause event
}

Особенности iOS

В обработчике pause любые вызовы API Cordova или нативных плагинов, проходящих через Objective-C, а также любые интерактивные вызовы, такие как всплывающие окна или console.log(), не работают. Они обрабатываются только при возобновлении работы приложения, в следующем цикле обработки.

Доступно iOS-специфическое событие resign как альтернатива pause, которое обнаруживает, когда пользователи включают кнопку Блокировка для блокировки устройства с приложением, работающим в фоновом режиме. Если приложение (и устройство) включено для многозадачности, это сопровождается последующим событием pause, но только под iOS 5. По сути, все заблокированные приложения в iOS 5, у которых включена многозадачность, переходят в фоновый режим. Чтобы приложения оставались работающими при блокировке под iOS 5, отключите многозадачность приложения, установив UIApplicationExitsOnSuspend в значение YES. Для работы при блокировке на iOS 4 это значение не имеет значения.

resume

Событие resume срабатывает, когда нативная платформа извлекает приложение из фонового режима.

Быстрый пример

document.addEventListener("resume", onResume, false);

function onResume() {
    // Handle the resume event
}

Особенности iOS

Любые интерактивные функции, вызываемые из обработчика события pause, выполняются позже при возобновлении работы приложения, как сигнализирует событие resume . К ним относятся всплывающие окна, console.log(), и любые вызовы из плагинов или API Cordova, которые проходят через Objective-C.

Событие active

iOS-специфическое событие active доступно в качестве альтернативы resume, и определяет, когда пользователи отключают кнопку Блокировка, чтобы разблокировать устройство с приложением, работающим в фоновом режиме. Если приложение (и устройство) включено для многозадачности, это сопровождается последующим событием resume, но только под iOS 5. По сути, все заблокированные приложения в iOS 5, у которых включена многозадачность, переходят в фоновый режим. Чтобы приложения оставались работающими при блокировке под iOS 5, отключите многозадачность приложения, установив UIApplicationExitsOnSuspend в значение YES. Для работы при блокировке на iOS 4 это значение не имеет значения.
Событие resume

При вызове из обработчика события resume интерактивные функции, такие как alert(), необходимо заключать в вызов setTimeout() с значением таймаута ноль, иначе приложение зависнет. Например:
```
document.addEventListener("resume", onResume, false);
function onResume() {
    setTimeout(function() {
            // TODO: do your thing!
        }, 0);
}
```

Особенности Android

См. Руководство по жизненному циклу Android для получения подробной информации об особенностях Android с событием resume.

кнопка Назад

Событие срабатывает, когда пользователь нажимает кнопку «Назад». Чтобы переопределить стандартное поведение кнопки «Назад», зарегистрируйте обработчик события backbutton . Больше нет необходимости вызывать какие-либо другие методы для переопределения поведения кнопки «Назад».

Быстрый пример

document.addEventListener("backbutton", onBackKeyDown, false);

function onBackKeyDown() {
    // Handle the back button
}

Особенности Windows

Вызовите ошибку в обработчике backbutton , чтобы принудительно использовать стандартное поведение, которое заключается в выходе из приложения:

document.addEventListener('backbutton', function (evt) {
    if (cordova.platformId !== 'windows') {
        return;
    }

    if (window.location.href !== firstPageUrl) {
        window.history.back();
    } else {
        throw new Error('Exit'); // This will suspend the app
    }
}, false);

кнопка Меню

Событие срабатывает, когда пользователь нажимает кнопку меню. Добавление обработчика переопределяет стандартное поведение кнопки меню.

Быстрый пример

document.addEventListener("menubutton", onMenuKeyDown, false);

function onMenuKeyDown() {
    // Handle the back button
}

кнопка Поиск

Событие срабатывает, когда пользователь нажимает кнопку поиска на Android. Если вам нужно переопределить стандартное поведение кнопки поиска на Android, вы можете зарегистрировать обработчик события 'searchbutton'.

Быстрый пример

document.addEventListener("searchbutton", onSearchKeyDown, false);

function onSearchKeyDown() {
    // Handle the search button
}

кнопка Начать звонок

Событие срабатывает, когда пользователь нажимает кнопку «Начать звонок». Если вам нужно переопределить стандартное поведение кнопки «Начать звонок», вы можете зарегистрировать обработчик события startcallbutton.

Быстрый пример

document.addEventListener("startcallbutton", onStartCallKeyDown, false);

function onStartCallKeyDown() {
    // Handle the start call button
}

кнопка Закончить звонок

Это событие срабатывает, когда пользователь нажимает кнопку «Закончить звонок». Событие переопределяет стандартное поведение кнопки «Закончить звонок».

Быстрый пример

document.addEventListener("endcallbutton", onEndCallKeyDown, false);

function onEndCallKeyDown() {
    // Handle the end call button
}

кнопка Уменьшения громкости

Событие срабатывает, когда пользователь нажимает кнопку уменьшения громкости. Если вам нужно переопределить стандартное поведение кнопки уменьшения громкости, вы можете зарегистрировать обработчик события volumedownbutton.

Быстрый пример

document.addEventListener("volumedownbutton", onVolumeDownKeyDown, false);

function onVolumeDownKeyDown() {
    // Handle the volume down button
}

кнопка Увеличения громкости

Событие срабатывает, когда пользователь нажимает кнопку увеличения громкости. Если вам нужно переопределить стандартное поведение кнопки увеличения громкости, вы можете зарегистрировать обработчик события volumeupbutton.

Быстрый пример

document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false);

function onVolumeUpKeyDown() {
    // Handle the volume up button
}

activated

Событие срабатывает, когда произошло активация Windows Runtime. Смотрите документацию MSDN для получения дополнительной информации и типов активации.

Быстрый пример

document.addEventListener("activated", activated, false);

function activated(args) {
    if (args && args.kind === Windows.ApplicationModel.Activation.ActivationKind.file) {
       // Using args.raw to get the native StorageFile object
        Windows.Storage.FileIO.readTextAsync(args.raw.detail[0].files[0]).done(function (text) {
            console.log(text);
        }, function (err) {
            console.error(err);
        });
    }
}

Особенности Windows

Исходные параметры события activated доступны в свойстве args.raw.detail[0] и могут использоваться для получения информации о типе или вызова методов одного из параметров активации,
Исходные параметры события activated также дублируются в args.detail[0] и могут использоваться в качестве резервного варианта в случае потери свойств параметров внутри.
См. https://issues.apache.org/jira/browse/CB-10653 для получения дополнительных сведений.
Событие activated может срабатывать до deviceready, поэтому вы должны сохранить флаг и параметры активации в контексте приложения, если вам они нужны — например, в случае с целью совместного использования. Подписка на событие activated должна быть выполнена до обработчика deviceready (в app.bindEvents в терминах шаблона Cordova).

© 2012, 2013, 2015 The Apache Software Foundation
Licensed under the Apache License 2.0.
https://cordova.apache.org/docs/en/6.x/cordova/events/events.html