イベント

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
}

// listen for uncaught cordova callback errors
window.addEventListener("cordovacallbackerror", function (event) {
    // event.error contains the original error object
});

注：一般的に、アプリケーションはdocument.addEventListenerを使用して、devicereadyイベントが発生した後に、イベントリスナーをアタッチする必要があります。

次の表に、Cordovaイベントとそのサポートされているプラットフォームを示します。

サポートされているプラットフォーム/ イベント	android	ios
deviceready
pause
resume
backbutton
menubutton
searchbutton
startcallbutton
endcallbutton
volumedownbutton
volumeupbutton
activated
cordovacallbackerror

deviceready

デバイスクレディイベントは、Cordovaが完全にロードされたときに発生します。このイベントは、すべてのアプリケーションに不可欠です。CordovaのデバイスAPIがロードされ、アクセスできる状態になったことを示します。

Cordovaは、ネイティブとJavaScriptの2つのコードベースで構成されています。ネイティブコードがロードされると、カスタムのローディング画像が表示されます。ただし、JavaScriptはDOMがロードされた場合にのみロードされます。つまり、Webアプリケーションは、対応するネイティブコードが利用可能になる前に、根本的にCordova JavaScript関数を呼び出す可能性があります。

devicereadyイベントは、Cordovaが完全にロードされると1回発生します。イベントが発生すると、Cordova APIを安全に呼び出すことができます。HTMLドキュメントのDOMがロードされたら、アプリケーションは通常、document.addEventListenerを使用して、イベントリスナーをアタッチします。

devicereadyイベントは、他のイベントとやや異なる動作をします。devicereadyイベントの発生後に登録されたイベントハンドラがあれば、そのコールバック関数がすぐに呼び出されます。

簡単な例

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

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

pause

一時停止イベントは、ネイティブプラットフォームがアプリケーションをバックグラウンドに置くときに発生し、通常はユーザーが別のアプリケーションに切り替えたときに発生します。

簡単な例

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

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

iOSの癖

一時停止ハンドラのObjective-Cを通過するCordovaAPIまたはネイティブプラグインへの呼び出しは機能せず、アラートやconsole.log()などの対話的な呼び出しは機能しません。それらは、次の実行ループのアプリが再開されたときにのみ処理されます。

iOS 固有の resign イベントは pause の代替として使用でき、ユーザーがロックボタンを使用してデバイスをロックし、アプリがフォアグラウンドで実行されていることを検出します。アプリ（とデバイス）がマルチタスク用に有効になっている場合、このイベントは後続の pause イベントとペアになりますが、iOS 5の場合のみです。実際には、マルチタスクが有効になっているiOS 5のロックされたアプリはすべてバックグラウンドにプッシュされます。iOS 5でロック時にアプリを実行し続けるには、[UIApplicationExitsOnSuspend][UIApplicationExitsOnSuspend]をYESに設定してアプリのマルチタスクを無効にします。iOS 4でロック時に実行するには、この設定は関係ありません。

resume

ネイティブプラットフォームがアプリケーションをバックグラウンドからプッシュアウトすると、resumeイベントが発生します。

簡単な例

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

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

iOSの癖

resumeイベントによってシグナルが送信されると、pauseイベントハンドラから呼び出されたインタラクティブ関数は、アプリが再開すると後に実行されます。これらにはアラート、console.log()、Objective-Cを介して移動するプラグインやCordova APIからの呼び出しが含まれます。

active イベント

iOS 固有の active イベントは resume の代替として使用でき、ユーザーがロックボタンを使用してデバイスのロックを解除し、アプリがフォアグラウンドで実行されていることを検出します。アプリ（とデバイス）がマルチタスク用に有効になっている場合、このイベントは後続の resume イベントとペアになりますが、iOS 5の場合のみです。実際には、マルチタスクが有効になっているiOS 5のロックされたアプリはすべてバックグラウンドにプッシュされます。iOS 5でロック時にアプリを実行し続けるには、[UIApplicationExitsOnSuspend][UIApplicationExitsOnSuspend]をYESに設定してアプリのマルチタスクを無効にします。iOS 4でロック時に実行するには、この設定は関係ありません。
resumeイベント

resume イベントハンドラから呼び出されると、alert()などのインタラクティブ関数は、タイムアウト値を 0 に設定した setTimeout() 呼び出しでラップする必要があります。そうでない場合、アプリはハングします。次のような場合など
```
  document.addEventListener("resume", onResume, false);
  function onResume() {
      setTimeout(function() {
              // TODO: do your thing!
          }, 0);
  }
```

Android の癖

resume イベントでの Android の癖の詳細については、[Android ライフサイクルガイド][AndroidLifeCycleGuide] を参照してください。

backbutton

ユーザーが戻るボタンを押すと、そのイベントが発生します。デフォルトの戻るボタンの動作をオーバーライドするには、backbutton イベントのイベントリスナーを登録してください。他のメソッドを呼び出して戻るボタンの動作をオーバーライドする必要はなくなりました。

簡単な例

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

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

menubutton

ユーザーがメニューボタンを押すと、そのイベントが発生します。イベントハンドラを適用すると、デフォルトのメニューボタンの動作がオーバーライドされます。

簡単な例

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

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

searchbutton

ユーザーが Android で検索ボタンを押すと、そのイベントが発生します。Android でデフォルトの検索ボタンの動作をオーバーライドする必要がある場合は、「searchbutton」イベントのイベントリスナーを登録できます。

簡単な例

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

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

startcallbutton

ユーザーが通話開始ボタンを押すと、そのイベントが発生します。デフォルトの通話開始の動作をオーバーライドする必要がある場合は、「startcallbutton」イベントのイベントリスナーを登録できます。

簡単な例

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

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

endcallbutton

ユーザーが通話終了ボタンを押すと、このイベントが発生します。このイベントはデフォルトの通話終了動作をオーバーライドします。

簡単な例

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

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

volumedownbutton

ユーザーが音量ダウンボタンを押すと、そのイベントが発生します。デフォルトの音量ダウン動作をオーバーライドする必要がある場合は、「volumedownbutton」イベントのイベントリスナーを登録できます。

簡単な例

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

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

volumeupbutton

ユーザーが音量アップボタンを押すと、そのイベントが発生します。音量アップ動作をオーバーライドする必要がある場合は、「volumeupbutton」イベントのイベントリスナーを登録できます。

簡単な例

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

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

activated

このイベントは Cordova では発生しません。

cordovacallbackerror

ネイティブのコールバック（成功またはエラー）によってキャッチされていないエラーがスローされると、このイベントが発生します。

このイベントはエラーの伝播を停止しません。（例：window.onerror イベントも発生します。）

他のイベントとは少し異なります。document オブジェクトではなく、window オブジェクトでリッスンする必要があります。

event オブジェクトには次のプロパティがあります

error: コールバック内で発生した元の Error。

簡単な例

window.addEventListener("cordovacallbackerror", function (event) {
    // event.error contains the original error object
});