From 8b240bcc7e18052870227bb0271b4c4fb9383519 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 5 Jan 2024 09:39:40 -0500 Subject: [PATCH 1/2] docs(config): add experimentalCloseWatcher --- docs/developing/config.md | 77 ++++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 38 deletions(-) diff --git a/docs/developing/config.md b/docs/developing/config.md index b5cb57a36c6..b97ec2cd1ae 100644 --- a/docs/developing/config.md +++ b/docs/developing/config.md @@ -162,41 +162,42 @@ class AppComponent { Below are the config options that Ionic uses. -| Config | Type | Description | -| --------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `actionSheetEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-action-sheet`, overriding the default "animation". | -| `actionSheetLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-action-sheet`, overriding the default "animation". | -| `alertEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-alert`, overriding the default "animation". | -| `alertLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-alert`, overriding the default "animation". | -| `animated` | `boolean` | If `true`, Ionic will enable all animations and transitions across the app. | -| `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | -| `backButtonIcon` | `string` | Overrides the default icon in all `` components. | -| `backButtonText` | `string` | Overrides the default text in all `` components. | -| `innerHTMLTemplatesEnabled` | `boolean` | Relevant Components: `ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-toast`. If `true`, content passed to the relevant components will be parsed as HTML instead of plaintext. Defaults to `false`. | -| `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | -| `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | -| `loadingLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-loading`, overriding the default "animation". | -| `loadingSpinner` | `SpinnerTypes` | Overrides the default spinner for all `ion-loading` overlays. | -| `menuIcon` | `string` | Overrides the default icon in all `` components. | -| `menuType` | `string` | Overrides the default menu type for all `` components. | -| `modalEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-modal`, overriding the default "animation". | -| `modalLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-modal`, overriding the default "animation". | -| `mode` | `Mode` | The mode determines which platform styles to use for the whole application. | -| `navAnimation` | `AnimationBuilder` | Overrides the default "animation" of all `ion-nav` and `ion-router-outlet` across the whole application. | -| `pickerEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-picker`, overriding the default "animation". | -| `pickerLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-picker`, overriding the default "animation". | -| `platform` | [`PlatformConfig`](/docs/angular/platform#customizing-platform-detection-methods) | Overrides the default platform detection methods. | -| `popoverEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-popover`, overriding the default "animation". | -| `popoverLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-popover`, overriding the default "animation". | -| `refreshingIcon` | `string` | Overrides the default icon in all `` components. | -| `refreshingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `sanitizerEnabled` | `boolean` | If `true`, Ionic will enable a basic DOM sanitizer on component properties that accept custom HTML. | -| `spinner` | `SpinnerTypes` | Overrides the default spinner in all `` components. | -| `statusTap` | `boolean` | If `true`, clicking or tapping the status bar will cause the content to scroll to the top. | -| `swipeBackEnabled` | `boolean` | If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application. | -| `tabButtonLayout` | `TabButtonLayout` | Overrides the default "layout" of all `ion-bar-button` across the whole application. | -| `toastDuration` | `number` | Overrides the default `duration` for all `ion-toast` components. | -| `toastEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-toast`, overriding the default "animation". | -| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". | -| `toggleOnOffLabels` | `boolean` | Overrides the default `enableOnOffLabels` in all `ion-toggle` components. | +| Config | Type | Description | +| --------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `actionSheetEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-action-sheet`, overriding the default "animation". | +| `actionSheetLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-action-sheet`, overriding the default "animation". | +| `alertEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-alert`, overriding the default "animation". | +| `alertLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-alert`, overriding the default "animation". | +| `animated` | `boolean` | If `true`, Ionic will enable all animations and transitions across the app. | +| `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | +| `backButtonIcon` | `string` | Overrides the default icon in all `` components. | +| `backButtonText` | `string` | Overrides the default text in all `` components. | +| `innerHTMLTemplatesEnabled` | `boolean` | Relevant Components: `ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-toast`. If `true`, content passed to the relevant components will be parsed as HTML instead of plaintext. Defaults to `false`. | +| `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | +| `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | +| `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | +| `loadingLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-loading`, overriding the default "animation". | +| `loadingSpinner` | `SpinnerTypes` | Overrides the default spinner for all `ion-loading` overlays. | +| `menuIcon` | `string` | Overrides the default icon in all `` components. | +| `menuType` | `string` | Overrides the default menu type for all `` components. | +| `modalEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-modal`, overriding the default "animation". | +| `modalLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-modal`, overriding the default "animation". | +| `mode` | `Mode` | The mode determines which platform styles to use for the whole application. | +| `navAnimation` | `AnimationBuilder` | Overrides the default "animation" of all `ion-nav` and `ion-router-outlet` across the whole application. | +| `pickerEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-picker`, overriding the default "animation". | +| `pickerLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-picker`, overriding the default "animation". | +| `platform` | [`PlatformConfig`](/docs/angular/platform#customizing-platform-detection-methods) | Overrides the default platform detection methods. | +| `popoverEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-popover`, overriding the default "animation". | +| `popoverLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-popover`, overriding the default "animation". | +| `refreshingIcon` | `string` | Overrides the default icon in all `` components. | +| `refreshingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | +| `sanitizerEnabled` | `boolean` | If `true`, Ionic will enable a basic DOM sanitizer on component properties that accept custom HTML. | +| `spinner` | `SpinnerTypes` | Overrides the default spinner in all `` components. | +| `statusTap` | `boolean` | If `true`, clicking or tapping the status bar will cause the content to scroll to the top. | +| `swipeBackEnabled` | `boolean` | If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application. | +| `tabButtonLayout` | `TabButtonLayout` | Overrides the default "layout" of all `ion-bar-button` across the whole application. | +| `toastDuration` | `number` | Overrides the default `duration` for all `ion-toast` components. | +| `toastEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-toast`, overriding the default "animation". | +| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". | +| `toggleOnOffLabels` | `boolean` | Overrides the default `enableOnOffLabels` in all `ion-toggle` components. | +| `experimentalCloseWatcher` | `boolean` | If `true`, the [CloseWatcher API](https://github.com/WICG/close-watcher) will be used to handle all Escape key and hardware back button presses to dismiss menus and overlays and to navigate. Note that the `hardwareBackButton` config option must also be `true`. (experimental) | From bcd372ecaa161842569366e70cb718c2c75ff9dd Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 5 Jan 2024 09:39:54 -0500 Subject: [PATCH 2/2] docs(hbb): document browser and PWA behavior --- docs/developing/hardware-back-button.md | 29 ++++++++++++++++--------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/developing/hardware-back-button.md b/docs/developing/hardware-back-button.md index d41db0d4e91..3f7b0d9f4ad 100644 --- a/docs/developing/hardware-back-button.md +++ b/docs/developing/hardware-back-button.md @@ -19,26 +19,35 @@ The hardware back button is found on most Android devices. In native application 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. ::: -## Hardware Back Button in Capacitor and Cordova +## Overview -:::note -The `@capacitor/app` package must be installed in Capacitor apps to use the hardware back button. -::: - -When running in a Capacitor or Cordova application, Ionic Framework will emit an `ionBackButton` event when a user presses the hardware back button. +Ionic Framework emits an `ionBackButton` event when a user presses the hardware back button in supported environments. 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. -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 the framework to call the next handler. +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. + +| Environment | Status | +| ----------- | --------------------------------------------------------------------------------------------------------- | +| Capacitor | Supported only when the `@capacitor/app` package is installed. | +| Cordova | Supported | +| Browser | Supported only when `experimentalCloseWatcher` is `true` and the platform supports the Close Watcher API. | +| PWA | Supported only when `experimentalCloseWatcher` is `true` and the platform supports the Close Watcher API. | + +### Hardware Back Button in a Browser or a PWA -## Hardware Back Button in a Browser +Ionic has experimental support for handling the hardware back button in a browser or a PWA by setting [`experimentalCloseWatcher: true` in the IonicConfig](./config.md). When this feature is enabled, Ionic will use the [Close Watcher API](https://github.com/WICG/close-watcher) 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. -When running your app in a mobile browser or as a PWA, hardware back button customization will be limited. This is because Capacitor and Cordova expose additional features that are not exposed in a normal web browser. For example, closing overlays and menus via the hardware back button are functionalities that are currently not supported when running your app in a mobile browser. These are known limitations and do not currently have straightforward solutions. +Chrome has support for Close Watcher starting in [Chrome 120](https://developer.chrome.com/blog/new-in-chrome-120). For complete hardware back button support, we recommend using Capacitor or Cordova. :::note -The `ionBackButton` event will not be emitted when running an app in a browser or as a PWA. +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