硬件后退按钮

大多数 Android 设备上都有硬件后退按钮。在原生应用中，它可用于关闭模式、导航到上一个视图、退出应用等。默认情况下，在 Ionic 中，当按下后退按钮时，当前视图将从导航堆栈中弹出，并显示上一个视图。如果导航堆栈中不存在先前的视图，则不会发生任何事情。本指南将展示如何自定义硬件后退按钮的行为。

¥The hardware back button is found on most Android devices. In native applications it can be used to close modals, navigate to the previous view, exit an app, and more. By default in Ionic, when the back button is pressed, the current view will be popped off the navigation stack, and the previous view will be displayed. If no previous view exists in the navigation stack, nothing will happen. This guide will show how to customize the behavior of the hardware back button.

注意

硬件后退按钮是指 Android 设备上的物理后退按钮，不应与浏览器后退按钮或 ion-back-button 混淆。本指南中的信息仅适用于 Android 设备。

¥The hardware back button refers to the physical back button on an Android device and should not be confused with either the browser back button or ion-back-button. The information in this guide only applies to Android devices.

概述

¥Overview

当用户在支持的环境中按下硬件后退按钮时，Ionic Framework 会发出 ionBackButton 事件。

¥Ionic Framework emits an ionBackButton event when a user presses the hardware back button in supported environments.

当监听 ionBackButton 事件时，你可以注册一个要触发的处理程序。该处理程序可以执行退出应用或打开确认对话框等操作。必须为每个处理程序分配一个优先级。默认情况下，每次按下硬件后退按钮只会触发一个处理程序。优先级值用于确定应调用哪个回调。这很有用，因为如果你打开了模式，你可能不希望模式关闭并且应用在按下硬件后退按钮时向后导航。一次仅运行一个处理程序允许模式关闭，但仍需要再次按下硬件后退按钮才能向后导航。

¥When listening for the ionBackButton event, you can register a handler to be fired. This handler can perform actions such as quitting the app or opening a confirmation dialog. Each handler must be assigned a priority. By default, only one handler is fired per hardware back button press. The priority value is used to determine which callback should be called. This is useful because if you have a modal open, you likely would not want the modal to close and the app to navigate backwards when pressing the hardware back button. Only running one handler at a time allows the modal to close but still requires another press of the hardware back button to navigate backwards.

在某些情况下，你可能希望退出多个处理程序。每个处理程序回调都会传入一个函数作为参数，该参数可用于告诉 Ionic 调用下一个处理程序。

¥There are situations where you might want to have multiple handlers fired. Each handler callback passes in a function as a parameter that can be used to tell Ionic to call the next handler.

支持

¥Support

下表显示了硬件后退按钮支持如何因环境而异。

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

环境	状态
Capacitor	仅当安装了 @capacitor/app 软件包时才支持。
Cordova	支持的
浏览器	仅当 experimentalCloseWatcher 为 true 并且平台支持 Close Watcher API 时才支持。
PWA	仅当 experimentalCloseWatcher 为 true 并且平台支持 Close Watcher API 时才支持。

浏览器或 PWA 中的硬件后退按钮

¥Hardware Back Button in a Browser or a PWA

Ionic 通过设置 IonicConfig 中的 experimentalCloseWatcher: true 实验性支持处理浏览器或 PWA 中的硬件后退按钮。启用此功能后，Ionic 将使用 关闭观察者 API 通过 ionBackButton 事件传递任何关闭请求。这包括按硬件后退按钮进行导航或按 Escape 键关闭模式。

¥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 从 Chrome 120 开始支持 Close Watcher。

¥Chrome has support for Close Watcher starting in Chrome 120.

为了获得完整的硬件后退按钮支持，我们建议使用 Capacitor 或 Cordova。

¥For complete hardware back button support, we recommend using Capacitor or Cordova.

注意

如果不支持 Close Watcher 或 experimentalCloseWatcher 为 false，则在浏览器中运行应用或作为 PWA 运行应用时，不会发出 ionBackButton 事件。

¥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

JavaScript

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

Angular

import { Platform } from '@ionic/angular';



...

constructor(private platform: Platform) {
  this.platform.backButton.subscribeWithPriority(10, () => {
    console.log('Handler was called!');
  });
}

Angular (Standalone)

import { Platform } from '@ionic/angular/standalone';



...

constructor(private platform: Platform) {
  this.platform.backButton.subscribeWithPriority(10, () => {
    console.log('Handler was called!');
  });
}

React

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

Vue

import { useBackButton } from '@ionic/vue';



...

export default {
  setup() {
    useBackButton(10, () => {
      console.log('Handler was called!');
    });
  }
}

在此示例中，我们注册了一个处理程序，当按下硬件后退按钮时将调用该处理程序。我们已将优先级设置为 10，并且没有向框架表明我们希望调用下一个处理程序。因此，任何优先级小于 10 的处理程序都不会被调用。优先级大于 10 的处理程序将首先被调用。

¥In this example, we are registering a handler to be called when the hardware back button is pressed. We have set the priority to be 10, and we have not indicated to the framework that we want the next handler to be called. As a result, any handlers with a priority less than 10 will not be called. A handler that has a priority greater than 10 will be called first.

如果存在具有相同优先级值的处理程序，则将调用最后注册的处理程序。请参阅 具有相同优先级的处理程序 了解更多信息。

¥In the event that there are handlers with the same priority value, the handler that was registered last will be called. See Handlers with the Same Priorities for more information.

调用多个处理程序

¥Calling Multiple Handlers

每个硬件后退按钮回调都有一个 processNextHandler 参数。调用此函数允许你继续调用硬件后退按钮处理程序。

¥Each hardware back button callback has a processNextHandler parameter. Calling this function allows you to continue calling hardware back button handlers.

JavaScript

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

Angular

import { Platform } from '@ionic/angular';



...

constructor(private platform: Platform) {
  this.platform.backButton.subscribeWithPriority(5, () => {
    console.log('Another handler was called!');
  });

  this.platform.backButton.subscribeWithPriority(10, (processNextHandler) => {
    console.log('Handler was called!');

    processNextHandler();
  });
}

Angular (Standalone)

import { Platform } from '@ionic/angular/standalone';



...

constructor(private platform: Platform) {
  this.platform.backButton.subscribeWithPriority(5, () => {
    console.log('Another handler was called!');
  });

  this.platform.backButton.subscribeWithPriority(10, (processNextHandler) => {
    console.log('Handler was called!');

    processNextHandler();
  });
}

React

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

Vue

import { useBackButton } from '@ionic/vue';



...

export default {
  setup() {
    useBackButton(5, () => {
      console.log('Another handler was called!');
    });

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

      processNextHandler();
    });
  }
}

此示例演示如何向 Ionic Framework 指示你希望触发下一个处理程序。所有回调均提供 processNextHandler 函数作为参数。调用此函数将导致下一个处理程序（如果存在）被触发。

¥This example shows how to indicate to Ionic Framework that you want the next handler to be fired. All callbacks are provided with a processNextHandler function as a parameter. Calling this will cause the next handler, if any exists, to be fired.

具有相同优先级的处理程序

¥Handlers with the Same Priorities

在内部，Ionic Framework 使用类似于优先级队列的东西来管理硬件后退按钮处理程序。具有最大优先级值的处理程序将首先被调用。如果存在多个具有相同优先级值的处理程序，则添加到该队列的最后一个具有相同优先级的处理程序将是第一个被调用的处理程序。

¥Internally, Ionic Framework uses something similar to a priority queue to manage hardware back button handlers. The handler with the largest priority value will be called first. In the event that there are multiple handlers with the same priority value, the last handler of the same priority added to this queue will be the first handler to be called.

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。

¥In the example above, both handlers A and B have a priority of 10. Since handler B was registered last, Ionic Framework will call handler B before it calls handler A.

退出应用

¥Exiting the App

在某些情况下，可能需要在按下硬件后退按钮时退出应用。这可以通过结合使用 ionBackButton 事件和 Capacitor/Cordova 提供的方法来实现。

¥In some scenarios, it may be desirable to quit the app when pressing the hardware back button. This can be achieved through the use of the ionBackButton event combined with methods that Capacitor/Cordova provide.

JavaScript

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

Angular

import { Optional } from '@angular/core';




import { IonRouterOutlet, Platform } from '@ionic/angular';




import { App } from '@capacitor/app';



...

constructor(
  private platform: Platform,
  @Optional() private routerOutlet?: IonRouterOutlet
) {
  this.platform.backButton.subscribeWithPriority(-1, () => {
    if (!this.routerOutlet.canGoBack()) {
      App.exitApp();
    }
  });
}

Angular (Standalone)

import { Optional } from '@angular/core';




import { IonRouterOutlet, Platform } from '@ionic/angular/standalone';




import { App } from '@capacitor/app';



...

constructor(
  private platform: Platform,
  @Optional() private routerOutlet?: IonRouterOutlet
) {
  this.platform.backButton.subscribeWithPriority(-1, () => {
    if (!this.routerOutlet.canGoBack()) {
      App.exitApp();
    }
  });
}

React

import { useIonRouter } from '@ionic/react';




import { App } from '@capacitor/app';



...

const ionRouter = useIonRouter();
document.addEventListener('ionBackButton', (ev) => {
  ev.detail.register(-1, () => {
    if (!ionRouter.canGoBack()) {
      App.exitApp();
    }
  });
});

Vue

import { useBackButton, useIonRouter } from '@ionic/vue';




import { App } from '@capacitor/app';



...

export default {
  setup() {
    const ionRouter = useIonRouter();
    useBackButton(-1, () => {
      if (!ionRouter.canGoBack()) {
        App.exitApp();
      }
    });
  }
}

此示例显示当用户按下硬件后退按钮并且导航堆栈中没有任何内容时应用退出。还可以在退出应用之前显示确认对话框。

¥This example shows the application exiting when the user presses the hardware back button and there is nothing left in the navigation stack. It is also possible to display a confirmation dialog before quitting the app.

建议在退出应用之前检查用户是否位于根页面。开发者可以在 Ionic Angular 中的 IonRouterOutlet 上使用 canGoBack 方法，在 Ionic React 和 Ionic Vue 中使用 IonRouter 上的方法。

¥It is recommended to check whether or not the user is on the root page prior to exiting the application. Developers can use the canGoBack method on IonRouterOutlet in Ionic Angular and IonRouter in Ionic React and Ionic Vue.

内部框架处理程序

¥Internal Framework Handlers

下表列出了 Ionic Framework 使用的所有内部硬件后退按钮事件处理程序。Propagates 列指出该特定处理程序是否告诉 Ionic Framework 调用下一个后退按钮处理程序。

¥The table below lists all of the internal hardware back button event handlers that Ionic Framework uses. The Propagates column notes whether or not that particular handler tells Ionic Framework to call the next back button handler.

处理程序	优先事项	传播	描述
叠加层	100	不	适用于覆盖组件 ion-action-sheet、ion-alert、ion-loading、ion-modal、ion-popover 和 ion-picker。
菜单	99	不	适用于 ion-menu。
导航	0	是的	适用于路由导航（即 Angular Routing）。