Add HardwareBackPressEvent with native timestamp (#56295)

Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/56295

Changelog: [Android][Added] - Pass event object to `BackHandler` `hardwareBackPress` events to access timeStamp from native event.

BackHandler on Android emits the `hardwareBackPress` event with a `null`
payload — no timestamp or event data. This means there is no way for
handlers to know when the user actually pressed the back button, which
prevents accurate performance tracing for back navigations.

This diff:
- Sends `SystemClock.uptimeMillis()` as `timestamp` in the native
  `DeviceEventManagerModule.emitHardwareBackPressed()` event payload
- Creates a new `HardwareBackPressEvent` class extending the DOM `Event`
  class, which overrides the `timeStamp` getter to return the native
  timestamp (falling back to `performance.now()` if unavailable)
- Makes the public constructor throw `TypeError("Illegal constructor")`
  following the `PerformanceEntry` pattern
- Updates all BackHandler platform files (Android, iOS, macOS, Windows)
  and type definitions (Flow, TypeScript) to create and pass the event
  to handlers
- Updates the BackHandler mock to pass events in `mockPressBack`
- Adds Fantom integration tests for both `HardwareBackPressEvent` and
  `BackHandler`

Reviewed By: huntie

Differential Revision: D98941079

fbshipit-source-id: baca35947cd7e8f598e9e040059579fb6e19553e
This commit is contained in:
Rubén Norte authored and meta-codesync[bot] committed 2026-04-01 10:50:36 -07:00
1 parent e7564d6a13
commit bf277cb6d4
10 files changed
+280 -13

No files matched your search

@@ -9,18 +9,26 @@
*/
import NativeDeviceEventManager from '../../Libraries/NativeModules/specs/NativeDeviceEventManager';
import {setEventInitTimeStamp} from '../../src/private/webapis/dom/events/internals/EventInternals';
import RCTDeviceEventEmitter from '../EventEmitter/RCTDeviceEventEmitter';
import {HardwareBackPressEvent} from './HardwareBackPressEvent';
const DEVICE_BACK_EVENT = 'hardwareBackPress';
type BackPressEventName = 'backPress' | 'hardwareBackPress';
type BackPressHandler = () => ?boolean;
type BackPressHandler = (event: HardwareBackPressEvent) => ?boolean;
const _backPressSubscriptions: Array<BackPressHandler> = [];
RCTDeviceEventEmitter.addListener(DEVICE_BACK_EVENT, function () {
RCTDeviceEventEmitter.addListener(DEVICE_BACK_EVENT, function (nativeEvent) {
const options = {};
const nativeTimestamp = nativeEvent?.timeStamp;
if (nativeTimestamp != null) {
setEventInitTimeStamp(options, nativeTimestamp);
}
const event = new HardwareBackPressEvent(options);
for (let i = _backPressSubscriptions.length - 1; i >= 0; i--) {
if (_backPressSubscriptions[i]?.()) {
if (_backPressSubscriptions[i]?.(event)) {
return;
}
}
+11 -1
View File
@@ -11,6 +11,16 @@ import {NativeEventSubscription} from '../EventEmitter/RCTNativeAppEventEmitter'
export type BackPressEventName = 'hardwareBackPress';
/**
* Event dispatched when the hardware back button is pressed.
* The `timeStamp` property reflects the native timestamp captured
* when the back press was emitted.
*/
export interface HardwareBackPressEvent {
readonly type: string;
readonly timeStamp: number;
}
/**
* Detect hardware back button presses, and programmatically invoke the
* default back button functionality to exit the app if there are no
@@ -26,7 +36,7 @@ export interface BackHandlerStatic {
exitApp(): void;
addEventListener(
eventName: BackPressEventName,
handler: () => boolean | null | undefined,
handler: (event: HardwareBackPressEvent) => boolean | null | undefined,
): NativeEventSubscription;
}
@@ -8,8 +8,10 @@
* @format
*/
import type {HardwareBackPressEvent} from './HardwareBackPressEvent';
type BackPressEventName = 'backPress' | 'hardwareBackPress';
type BackPressHandler = () => ?boolean;
type BackPressHandler = (event: HardwareBackPressEvent) => ?boolean;
function emptyFunction(): void {}
@@ -12,11 +12,16 @@
export type BackPressEventName = 'backPress' | 'hardwareBackPress';
export interface HardwareBackPressEvent {
+type: string;
+timeStamp: number;
}
type TBackHandler = {
exitApp(): void,
addEventListener(
eventName: BackPressEventName,
handler: () => ?boolean,
handler: (event: HardwareBackPressEvent) => ?boolean,
): {remove: () => void, ...},
};
@@ -0,0 +1,22 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @flow strict-local
* @format
*/
import type {EventInit} from '../../src/private/webapis/dom/events/Event';
import Event from '../../src/private/webapis/dom/events/Event';
/**
* Event dispatched when the hardware back button is pressed on Android.
*/
export class HardwareBackPressEvent extends Event {
constructor(options?: ?EventInit) {
super('hardwareBackPress', options);
}
}
@@ -9,15 +9,20 @@
*/
import type {BackPressEventName} from '../BackHandler';
import type {HardwareBackPressEvent} from '../HardwareBackPressEvent';
const _backPressSubscriptions = new Set<() => ?boolean>();
import {HardwareBackPressEvent as HardwareBackPressEventClass} from '../HardwareBackPressEvent';
const _backPressSubscriptions = new Set<
(event: HardwareBackPressEvent) => ?boolean,
>();
const BackHandler = {
exitApp: jest.fn() as () => void,
addEventListener: function (
eventName: BackPressEventName,
handler: () => ?boolean,
handler: (event: HardwareBackPressEvent) => ?boolean,
): {remove: () => void, ...} {
_backPressSubscriptions.add(handler);
return {
@@ -28,10 +33,11 @@ const BackHandler = {
},
mockPressBack: function () {
const event = new HardwareBackPressEventClass();
let invokeDefault = true;
const subscriptions = [..._backPressSubscriptions].reverse();
for (let i = 0; i < subscriptions.length; ++i) {
if (subscriptions[i]()) {
if (subscriptions[i](event)) {
invokeDefault = false;
break;
}
@@ -0,0 +1,144 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @flow strict-local
* @format
*/
import '@react-native/fantom/src/setUpDefaultReactNativeEnvironment';
import type {HardwareBackPressEvent} from 'react-native/Libraries/Utilities/BackHandler';
import RCTDeviceEventEmitter from 'react-native/Libraries/EventEmitter/RCTDeviceEventEmitter';
import BackHandler from 'react-native/Libraries/Utilities/BackHandler';
import {HardwareBackPressEvent as HardwareBackPressEventClass} from 'react-native/Libraries/Utilities/HardwareBackPressEvent';
describe('BackHandler', () => {
const subscriptions: Array<{remove: () => void, ...}> = [];
afterEach(() => {
for (const sub of subscriptions) {
sub.remove();
}
subscriptions.length = 0;
});
it('calls handlers in reverse order (LIFO)', () => {
const callOrder: Array<string> = [];
const handler1 = (_event: HardwareBackPressEvent) => {
callOrder.push('first');
return false;
};
const handler2 = (_event: HardwareBackPressEvent) => {
callOrder.push('second');
return true;
};
subscriptions.push(
BackHandler.addEventListener('hardwareBackPress', handler1),
);
subscriptions.push(
BackHandler.addEventListener('hardwareBackPress', handler2),
);
RCTDeviceEventEmitter.emit('hardwareBackPress', {timeStamp: 100});
expect(callOrder).toEqual(['second']);
});
it('calls all handlers when none return true', () => {
const callOrder: Array<string> = [];
const handler1 = (_event: HardwareBackPressEvent) => {
callOrder.push('first');
return false;
};
const handler2 = (_event: HardwareBackPressEvent) => {
callOrder.push('second');
return false;
};
subscriptions.push(
BackHandler.addEventListener('hardwareBackPress', handler1),
);
subscriptions.push(
BackHandler.addEventListener('hardwareBackPress', handler2),
);
RCTDeviceEventEmitter.emit('hardwareBackPress', {timeStamp: 100});
expect(callOrder).toEqual(['second', 'first']);
});
it('passes HardwareBackPressEvent to handlers', () => {
let receivedEvent: ?HardwareBackPressEvent = null;
const handler = (event: HardwareBackPressEvent) => {
receivedEvent = event;
return true;
};
subscriptions.push(
BackHandler.addEventListener('hardwareBackPress', handler),
);
RCTDeviceEventEmitter.emit('hardwareBackPress', {timeStamp: 42});
expect(receivedEvent).toBeInstanceOf(HardwareBackPressEventClass);
});
it('event has native timestamp as timeStamp', () => {
let receivedEvent: ?HardwareBackPressEvent = null;
const handler = (event: HardwareBackPressEvent) => {
receivedEvent = event;
return true;
};
subscriptions.push(
BackHandler.addEventListener('hardwareBackPress', handler),
);
RCTDeviceEventEmitter.emit('hardwareBackPress', {timeStamp: 42});
expect(receivedEvent?.timeStamp).toBe(42);
});
it('event falls back to performance.now() when no native timestamp', () => {
let receivedEvent: ?HardwareBackPressEvent = null;
const handler = (event: HardwareBackPressEvent) => {
receivedEvent = event;
return true;
};
subscriptions.push(
BackHandler.addEventListener('hardwareBackPress', handler),
);
const before = performance.now();
RCTDeviceEventEmitter.emit('hardwareBackPress', null);
const after = performance.now();
const timeStamp = receivedEvent?.timeStamp;
expect(timeStamp).not.toBeNull();
if (timeStamp != null) {
expect(timeStamp).toBeGreaterThanOrEqual(before);
expect(timeStamp).toBeLessThanOrEqual(after);
}
});
it('removes handler on subscription.remove()', () => {
let called = false;
const handler = (_event: HardwareBackPressEvent) => {
called = true;
return true;
};
const sub = BackHandler.addEventListener('hardwareBackPress', handler);
sub.remove();
RCTDeviceEventEmitter.emit('hardwareBackPress', {timeStamp: 100});
expect(called).toBe(false);
});
});
@@ -0,0 +1,65 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @flow strict-local
* @format
*/
import '@react-native/fantom/src/setUpDefaultReactNativeEnvironment';
import {HardwareBackPressEvent} from 'react-native/Libraries/Utilities/HardwareBackPressEvent';
import Event from 'react-native/src/private/webapis/dom/events/Event';
import {setEventInitTimeStamp} from 'react-native/src/private/webapis/dom/events/internals/EventInternals';
describe('HardwareBackPressEvent', () => {
it('extends Event', () => {
const event = new HardwareBackPressEvent();
expect(event).toBeInstanceOf(Event);
expect(event.type).toBe('hardwareBackPress');
expect(event.bubbles).toBe(false);
expect(event.cancelable).toBe(false);
expect(event.composed).toBe(false);
});
it('uses native timestamp as timeStamp when provided via setEventInitTimeStamp', () => {
const options = {};
setEventInitTimeStamp(options, 12345);
const event = new HardwareBackPressEvent(options);
expect(event.timeStamp).toBe(12345);
});
it('falls back to performance.now() when no timestamp is provided', () => {
const before = performance.now();
const event = new HardwareBackPressEvent();
const after = performance.now();
expect(event.timeStamp).toBeGreaterThanOrEqual(before);
expect(event.timeStamp).toBeLessThanOrEqual(after);
});
it('falls back to performance.now() when options is undefined', () => {
const before = performance.now();
const event = new HardwareBackPressEvent(undefined);
const after = performance.now();
expect(event.timeStamp).toBeGreaterThanOrEqual(before);
expect(event.timeStamp).toBeLessThanOrEqual(after);
});
it('does NOT allow changing the timeStamp value after construction', () => {
const options = {};
setEventInitTimeStamp(options, 12345);
const event = new HardwareBackPressEvent(options);
expect(() => {
'use strict';
// $FlowExpectedError[cannot-write]
event.timeStamp = 999;
}).toThrow();
});
});
@@ -36,7 +36,8 @@ public open class DeviceEventManagerModule(
public open fun emitHardwareBackPressed() {
val reactApplicationContext: ReactApplicationContext? =
getReactApplicationContextIfActiveOrWarn()
reactApplicationContext?.emitDeviceEvent("hardwareBackPress", null)
val map = buildReadableMap { put("timeStamp", System.nanoTime() / 1_000_000.0) }
reactApplicationContext?.emitDeviceEvent("hardwareBackPress", map)
}
/** Sends an event to the JS instance that a new intent was received. */
+7 -3
View File
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<481366a332c1435df38ef98031869bb9>>
* @generated SignedSource<<e41250cef6318ae48a9fc0246cc9b732>>
*
* This file was generated by scripts/js-api/build-types/index.js.
*/
@@ -2479,6 +2479,10 @@ declare function getWithFallback_DEPRECATED<Config extends {}>(
): React.ComponentType<Config>
declare type hairlineWidth = typeof hairlineWidth
declare type Handle = number
declare interface HardwareBackPressEvent {
readonly timeStamp: number
readonly type: string
}
declare type Headers = {
[name: string]: string
}
@@ -5076,7 +5080,7 @@ declare type TaskProvider = () => HeadlessTask
declare type TBackHandler = {
addEventListener(
eventName: BackPressEventName,
handler: () => boolean | undefined,
handler: (event: HardwareBackPressEvent) => boolean | undefined,
): {
remove: () => void
}
@@ -6015,7 +6019,7 @@ export {
AppStateStatus, // 447e5ef2
Appearance, // 00cbaa0a
AutoCapitalize, // c0e857a0
BackHandler, // 0b13c289
BackHandler, // f139fc69
BackPressEventName, // 4620fb76
BlurEvent, // 870b9bb5
BoxShadowValue, // b679703f