メインコンテンツまでスキップ
バージョン: v8

ハードウェアの戻るボタン

ハードウェアの戻るボタンは、ほとんどの Android デバイスにあります。ネイティブアプリケーションでは、これを使って、モデルを閉じたり、前のビューに移動したり、アプリを終了したりすることができる。既定値では、 戻るボタンを押すと、現在のビューがナビゲーションスタックからポップされ、前のビューが表示されます。ナビゲーションスタックに前のビューが存在しない場合は、何も起こりません。このガイドでは、ハードウェアの戻るボタンの動作をカスタマイズする方法について説明します。

注記

ハードウェアの 「戻る」 ボタンとは Android デバイスの物理的な 「戻る」 ボタンのことであり、ブラウザの 「戻る」 ボタンや ion-back-button ボタンと混同しないでください。このガイドの情報は、Android デバイスにのみ適用されます。

概要

Ionic Framework は、サポートされている環境でユーザーがハードウェアの戻るボタンを押すと、ionBackButtonイベントを発行します。

ionBackButton イベントを監視して、起動するハンドラを登録できます。このハンドラは、アプリケーションの終了や確認ダイアログのオープンなどのアクションを実行できます。各ハンドラには優先順位を割り当てる必要があります。既定では、ハードウェアの戻るボタンを押すごとに 1 つのハンドラだけが起動されます。優先順位の値は、どのコールバックを呼び出すかを決定するために使用されます。これが便利なのは、モーダルを開いている場合、ハードウェアの戻るボタンを押したときにモーダルが閉じられたり、アプリが後方に移動したりしないようにしたいからです。一度に 1 つのハンドラだけを実行すると、モーダルを閉じることができますが、戻るにはハードウェアの戻るボタンをもう一度押す必要があります。

複数のハンドラを起動したい場合があります。各ハンドラのコールバックは、フレームワークに次のハンドラを呼び出すように指示するために使用できるパラメーターとして関数を渡します。

Support

The table below shows how hardware back button support varies by environment.

EnvironmentStatus
CapacitorSupported only when the @capacitor/app package is installed.
CordovaSupported
BrowserSupported only when experimentalCloseWatcher is true and the platform supports the Close Watcher API.
PWASupported only when experimentalCloseWatcher is true and the platform supports the Close Watcher API.

Hardware Back Button in a Browser or a PWA

Ionic has experimental support for handling the hardware back button in a browser or a PWA by setting experimentalCloseWatcher: true in the IonicConfig. When this feature is enabled, Ionic will use the Close Watcher API to pass any close requests through the ionBackButton event. This includes pressing the hardware back button to navigate or the Escape key to dismiss a modal.

Chrome has support for Close Watcher starting in Chrome 120.

ハードウェアバックボタンを完全にサポートするには、Capacitor または Cordova の使用をお勧めします。

注記

The ionBackButton event will not be emitted when running an app in a browser or as a PWA if Close Watcher is unsupported or experimentalCloseWatcher is false.

Basic Usage

document.addEventListener('ionBackButton', (ev) => {
ev.detail.register(10, () => {
console.log('Handler was called!');
});
});

この例では、ハードウェアバックボタンが押されたときに呼び出されるハンドラを登録しています。優先度を 10 に設定し、次のハンドラを呼び出すことをフレームワークに指定していません。その結果、優先順位が 10 未満のハンドラは呼び出されません。優先度が 10 より大きいハンドラが最初に呼び出されます。

同じ優先順位値を持つハンドラが存在する場合は、最後に登録されたハンドラが呼び出されます。詳細は、 Handlers with the Same Priorities を参照してください。

複数ハンドラの呼び出し

各ハードウェアバックボタンコールバックには、 processNextHandler パラメータがあります。この関数を呼び出すと、ハードウェアバックボタンハンドラの呼び出しを続行できます。

document.addEventListener('ionBackButton', (ev) => {
ev.detail.register(5, () => {
console.log('Another handler was called!');
});

ev.detail.register(10, (processNextHandler) => {
console.log('Handler was called!');

processNextHandler();
});
});

この例は、次のハンドラを起動するように Ionic Framework に指示する方法を示しています。すべてのコールバックには、パラメータとして processNextHandler 関数が用意されています。これをコールすると、次のハンドラ (存在する場合) が起動されます。

同じ優先順位のハンドラ

内部的には、Ionic Framework はハードウェアのバックボタンハンドラを管理するためにプライオリティキューに似たものを使用します。優先順位の値が最大のハンドラが最初に呼び出されます。同じ優先順位のハンドラが複数存在する場合、このキューに追加された同じ優先順位の last handler が、最初に呼び出されるハンドラになります。

document.addEventListener('ionBackButton', (ev) => {
// Handler A
ev.detail.register(10, (processNextHandler) => {
console.log('Handler A was called!');

processNextHandler();
});

// Handler B
ev.detail.register(10, (processNextHandler) => {
console.log('Handler B was called!');

processNextHandler();
});
});

上の例では、ハンドラ A と B の両方の優先度は 10 です。ハンドラ B は最後に登録されているため、Ionic Framework はハンドラ A を呼び出す前にハンドラ B を呼び出します。

アプリの終了

場合によっては、ハードウェアの戻るボタンを押したときにアプリケーションを終了することをお勧めします。これは、Capacitor/Cordova が提供するメソッドと組み合わせた ionBackButton イベントを使用することで実現できます。

import { BackButtonEvent } from '@ionic/core';
import { App } from '@capacitor/app';

...

const routerEl = document.querySelector('ion-router');
document.addEventListener('ionBackButton', (ev: BackButtonEvent) => {
ev.detail.register(-1, () => {
const path = window.location.pathname;
if (path === routerEl.root) {
App.exitApp();
}
});
});

この例は、ユーザがハードウェアの戻るボタンを押したときにアプリケーションが終了し、ナビゲーションスタックに何も残っていないことを示しています。アプリを終了する前に確認ダイアログを表示することも可能です。

アプリケーションを終了する前に、ユーザーがルート・ページにあるかどうかを確認することをお勧めします。開発者は、Ionic Angular の IonRouterOutletcanGoBack 、 Ionic React および Ionic Vue の IonRoutercanGoBack メソッドを使用できます。

内部フレームワークハンドラ

次の表は、Ionic Framework が使用するすべての内部ハードウェアバックボタンイベントハンドラの一覧です。 Propagates 列は、その特定のハンドラが Ionic Framework に次の戻るボタンハンドラを呼び出すように指示するかどうかを示します。

HandlerPriorityPropagatesDescription
Overlays100NoApplies to overlay components ion-action-sheet, ion-alert, ion-loading, ion-modal, ion-popover, and ion-picker.
Menu99NoApplies to ion-menu.
Navigation0YesApplies to routing navigation (i.e. Angular Routing).