Skip to main content

硬件后退按钮

硬件返回按钮在大多数安卓设备上都有。在原生应用中，它可以用于关闭模态窗口、导航到上一个视图、退出应用等。默认情况下，在 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.

note

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

概述​

🌐 Overview

当用户在支持的环境中按下硬件返回按钮时，Ionic 框架会触发一个 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 且平台支持关闭监听器 API 时支持。
PWA仅在 experimentalCloseWatcher 为 true 且平台支持关闭监听器 API 时支持。

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

🌐 Hardware Back Button in a Browser or a PWA

Ionic 对在浏览器或 PWA 中处理硬件返回按钮提供了实验性支持，通过在 IonicConfig 中设置 experimentalCloseWatcher: true 来实现。启用此功能后，Ionic 将使用 Close Watcher 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.

note

如果不支持关闭监视器或 experimentalCloseWatcher 为 false，在浏览器中或作为 PWA 运行应用时，ionBackButton 事件将不会被触发。

基本用法​

🌐 Basic Usage

document.addEventListener('ionBackButton', (event) => {
  event.detail.register(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.

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

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

    processNextHandler();
  });
});

此示例显示了如何向 Ionic 框架指示你希望触发下一个处理程序。所有回调都提供了一个 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 框架使用类似于优先队列的机制来管理硬件返回按钮的处理程序。优先级值最大的处理程序将被首先调用。如果存在多个具有相同优先级值的处理程序，则添加到该队列中相同优先级的最后一个处理程序将是首先被调用的处理程序。

🌐 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', (event) => {
  // Handler A
  event.detail.register(10, (processNextHandler) => {
    console.log('Handler A was called!');

    processNextHandler();
  });

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

    processNextHandler();
  });
});

在上面的例子中，处理程序 A 和 B 的优先级都是 10。由于处理程序 B 是最后注册的，Ionic 框架将在调用处理程序 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.

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

...

const routerEl = document.querySelector('ion-router');
document.addEventListener('ionBackButton', (event: BackButtonEvent) => {
  event.detail.register(-1, () => {
    const path = window.location.pathname;
    if (path === routerEl.root) {
      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 框架使用的所有内部硬件返回按钮事件处理程序。Propagates 列说明了该处理程序是否会通知 Ionic 框架调用下一个返回按钮处理程序。

🌐 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 路由）。

目录