鸿蒙React Native返回拦截指南：from beforeRemove to usePreventRemove

一个老需求，换个平台就翻车了。公司这轮把React Native应用迁移到鸿蒙，我接手的是导航这一块。最典型的需求就是页面返回拦截：表单没保存时，用户点返回，要弹确认框。平时在StackNavigation里做这种事，靠的是beforeRemove事件；这个功能在Android上我写了几百遍，闭着眼都知道怎么挂BackHandler，但到了鸿蒙上，第一次真机测试就发现行为完全不对——从屏幕左边缘右滑返回，页面直接滑走，我挂在beforeRemove里的逻辑压根没等到弹窗。

后面几天我一直在翻react-native-harmony的源码和鸿蒙容器页的处理逻辑，把返回拦截整个链路重新捋了一遍。这篇文章就记录一下我在HarmonyOS NEXT上实现StackNavigation返回拦截的完整过程，包括为什么不能照搬Android方案、beforeRemove和usePreventRemove怎么选、系统侧滑手势拦不住时怎么兜底，以及几个容易被忽略的边界场景。如果你正在做RN鸿蒙化适配，或者准备把现有RN应用跑到鸿蒙设备上，这篇应该能帮你省不少排查时间。

1. 为什么鸿蒙上的返回拦截不能照搬Android方案

1.1 一次“看起来正常”的迁移，真机上却翻车了

先说背景。我们团队做的是跨端业务App，导航方案是React Navigation的StackNavigation，也就是@react-navigation/native-stack。返回拦截这个需求集中在几个页面：编辑草稿、填写表单、视频播放页，要求用户在离开前必须有确认动作。

Android上的做法很成熟，我一开始直接照搬：

tsx复制useEffect(() => {
  const unsub = navigation.addListener('beforeRemove', (e) => {
    if (!hasUnsaved) return;
    e.preventDefault();
    Alert.alert('提示', '当前内容尚未保存，确定离开吗？', [
      { text: '留下', style: 'cancel' },
      { text: '离开', onPress: () => navigation.dispatch(e.data.action) },
    ]);
  });
  return unsub;
}, [navigation, hasUnsaved]);

这段代码在Android模拟器、真机上都很稳。迁移到鸿蒙后，我第一时间在模拟器上跑了一遍，点击返回键、导航栏返回，弹窗都正常。当时我还松了口气，以为这块不用动。

结果真机一测就出问题了。HarmonyOS NEXT默认是手势导航，从屏幕左边缘右滑返回时，页面直接跟着手势滑走并退出了，压根没有触发beforeRemove。更诡异的是，某些场景下先触发了一次hardwareBackPress，然后又触发了beforeRemove，弹窗弹了两层，关掉一层后页面已经没了。

后来我翻react-native-harmony的issue和容器页源码才明白，鸿蒙的返回事件链路和Android不一样，不是一套逻辑能通吃的。

1.2 三个平台的返回事件差异

要想搞清楚鸿蒙上该怎么拦截，得先看三个平台的返回事件是怎么到RN层的。我整理了一个对比，方便你对照自己的场景：

关键点在于最后一行。Android上React Navigation会把系统返回事件转成导航器的pop动作，然后走一遍完整的动作分发，所以beforeRemove一定能在这个分发过程中被触发，拦截自然有效。iOS上侧滑手势虽然由系统控制，但React Navigation通过gestureEnabled和事件回调也能把手势和导航动作绑在一起。

鸿蒙不一样。RN页面本身跑在一个原生容器页里，这个容器页是ArkUI的@Entry页面。用户侧滑返回时，系统先把这个事件交给ArkUI页面的返回生命周期，然后容器页再决定要不要把事件转发给RN。如果容器页直接执行了返回，RN里的导航器根本来不及反应。这就是为什么我模拟器上正常、真机上失效——模拟器的输入事件模拟和真机手势走的路径有细微差别。

所以，在鸿蒙上做返回拦截，第一原则是：不要只依赖JS层的beforeRemove，要前先确认你的react-native-harmony版本对应的容器页是怎么处理返回事件的。

2. 核心拦截机制：beforeRemove 与 usePreventRemove 的取舍

2.1 beforeRemove 到底拦的是什么

先把概念理清楚。beforeRemove不是“返回事件拦截器”，它是“路由移除前的事件钩子”。只要是StackNavigation里某个路由要被移除，不管是通过返回手势、返回按钮、navigation.goBack()、navigation.pop()，还是navigation.replace()，都会先触发beforeRemove。你在监听器里调用e.preventDefault()，这次移除动作就被取消，页面留在原地。

用白话讲：导航器已经把“我要干掉这个页面”的决议做好了，beforeRemove是最后的听证会。你不喊停，页面就没了；你喊停，导航器就收回决议。

那为什么确认弹窗里要用navigation.dispatch(e.data.action)，而不是重新调一次goBack()？

因为你手动调goBack()会再次触发beforeRemove，造成递归：弹窗确认后调用goBack()，又进监听器，再次preventDefault，然后弹窗又弹出来。而e.data.action是这次被拦截的原始动作，dispatch这个动作时React Navigation内部会识别出它是同一次提议的延续，不会再触发第二次拦截。

我在鸿蒙上遇到过的问题就是这个：同事一开始写的是“离开”按钮里调navigation.goBack()，结果每次确认后页面都不走，弹窗反而又弹出来，他一度以为是鸿蒙的弹窗回调有问题。其实不是，就是典型的递归拦截。

2.2 usePreventRemove 为什么是更省心的选择

React Navigation 7.x推荐用usePreventRemove来代替手写beforeRemove。它的代码更简洁：

tsx复制import { useNavigation } from '@react-navigation/native';

export function DraftScreen() {
  const navigation = useNavigation();
  const [hasUnsaved, setHasUnsaved] = useState(false);

  usePreventRemove(hasUnsaved, ({ data }) => {
    Alert.alert('提示', '当前内容尚未保存，确定离开吗？', [
      { text: '留下', style: 'cancel' },
      { text: '离开', onPress: () => navigation.dispatch(data.action) },
    ]);
  });

  return (
    <TextInput
      onChangeText={(text) => setHasUnsaved(text.length > 0)}
    />
  );
}

usePreventRemove内部帮你处理了两件事：一是自动往当前路由挂beforeRemove监听，shouldPrevent为true时自动调用preventDefault()，不需要你手写；二是当shouldPrevent从true变成false时，它会自动解除拦截，不会出现“用户已经保存了内容，但页面还被锁死”的状态。

它的主要局限是只支持React Navigation 7.x。如果你的项目还在6.x，建议自己封装一个简化版hook，避免每个页面重复写样板代码：

tsx复制function usePreventRemoveCompat(shouldPrevent: boolean, onPrevent: (data: any) => void) {
  const navigation = useNavigation();
  const callbackRef = useRef(onPrevent);
  callbackRef.current = onPrevent;

  useEffect(() => {
    return navigation.addListener('beforeRemove', (e) => {
      if (!shouldPrevent) return;
      e.preventDefault();
      callbackRef.current({ action: e.data.action });
    });
  }, [navigation, shouldPrevent]);
}

这个封装比较粗糙，真实项目里建议把data.action用ref保存，避免回调里的闭包问题。后面第3章的通用hook就是按这个思路写的。

3. 实战：实现一个带确认弹窗的返回拦截

3.1 单页面表单拦截的完整代码

先给最直观的版本，在鸿蒙上我用的是自定义Modal，而不是系统Alert。原因后面详细说。

tsx复制import React, { useCallback, useRef, useState } from 'react';
import {
  View, Text, TextInput, Pressable, Modal,
} from 'react-native';
import { useNavigation, usePreventRemove } from '@react-navigation/native';

export function DraftScreen() {
  const navigation = useNavigation();
  const [content, setContent] = useState('');
  const [showConfirm, setShowConfirm] = useState(false);
  const pendingActionRef = useRef<any>(null);

  const hasUnsaved = content.trim().length > 0;

  usePreventRemove(hasUnsaved, ({ data }) => {
    pendingActionRef.current = data.action;
    setShowConfirm(true);
  });

  const stay = useCallback(() => {
    pendingActionRef.current = null;
    setShowConfirm(false);
  }, []);

  const leave = useCallback(() => {
    const action = pendingActionRef.current;
    pendingActionRef.current = null;
    setShowConfirm(false);
    if (action) {
      navigation.dispatch(action);
    }
  }, [navigation]);

  return (
    <View style={{ flex: 1, padding: 16 }}>
      <TextInput
        value={content}
        onChangeText={setContent}
        placeholder="输入草稿内容"
        multiline
        style={{
          height: 200,
          borderWidth: 1,
          borderColor: '#ccc',
          borderRadius: 8,
          padding: 12,
          textAlignVertical: 'top',
        }}
      />
      <Modal
        visible={showConfirm}
        transparent
        animationType="fade"
        onRequestClose={stay}
      >
        <View
          style={{
            flex: 1,
            justifyContent: 'center',
            alignItems: 'center',
            backgroundColor: 'rgba(0, 0, 0, 0.4)',
          }}
        >
          <View
            style={{
              width: 280,
              padding: 20,
              borderRadius: 12,
              backgroundColor: '#fff',
            }}
          >
            <Text style={{ fontSize: 16, fontWeight: '600' }}>
              当前内容尚未保存
            </Text>
            <Text style={{ marginTop: 8, fontSize: 14, color: '#666' }}>
              确定离开吗？离开后草稿将丢失。
            </Text>
            <View style={{ flexDirection: 'row', marginTop: 20 }}>
              <Pressable
                onPress={stay}
                style={{ flex: 1, paddingVertical: 10, alignItems: 'center' }}
              >
                <Text style={{ color: '#666' }}>暂不离开</Text>
              </Pressable>
              <Pressable
                onPress={leave}
                style={{ flex: 1, paddingVertical: 10, alignItems: 'center' }}
              >
                <Text style={{ color: '#FF4D4F', fontWeight: '600' }}>离开</Text>
              </Pressable>
            </View>
          </View>
        </View>
      </Modal>
    </View>
  );
}

这个版本我实测在HarmonyOS NEXT真机上是可以用的。关键点是：

• 用pendingActionRef保存被拦截的动作，而不是useState。因为弹窗弹出后用户可能再次触发返回，如果用useState存action，第二次usePreventRemove回调会把新动作覆盖掉，用户点“离开”时执行的可能不是最初的返回动作。用ref可以绕开这个问题，但也需要在回调里做防重入，见3.2。
• 使用Modal而不是Alert。鸿蒙版RN的Alert底层走的是promptAction.showDialog，弹窗按钮的数量、文案顺序、回调时机在部分版本上和Android有差异。最麻烦的是，系统级对话框出现时，如果用户又做了一次侧滑返回，某些版本会直接把对话框关掉，但页面也一起被pop了，你连“暂不离开”都来不及点。自定义Modal的层级在RN内部，不会触发系统返回手势的默认行为，可控性强很多。

3.2 确认弹窗里的竞态处理

这里有个很容易踩的坑：弹窗已经显示的时候，用户又按了一次返回。

usePreventRemove的shouldPrevent还是true，所以回调会再次执行。如果没有防重入判断，showConfirm仍然为true，Modal不会重新弹，但pendingActionRef.current会被新的action覆盖。理论上两次返回动作最终导航结果一样，但有些场景不一样——比如第一次是从A进B，第二次是B进C后的返回，那你最终dispatch的可能不是用户预期的动作。

解决办法是在回调入口做一个重入判断：

tsx复制const preventRef = useRef(false);

usePreventRemove(hasUnsaved, ({ data }) => {
  if (preventRef.current) return;
  preventRef.current = true;
  pendingActionRef.current = data.action;
  setShowConfirm(true);
});

然后在stay和leave里把preventRef.current重置为false。这样弹窗期间无论用户按几次返回，都只会保留第一次被拦截的动作，体验稳定。

还有一个细节：点“离开”按钮时，我建议先setShowConfirm(false)再dispatch(action)。有同事问过，要不要等Modal的关闭动画播完再dispatch？实际测试下来，在鸿蒙上先关Modal再dispatch，视觉上会有个“页面先闪一下再退出”的轻微撕裂感；直接dispatch让页面在Modal还在时就被移除，反而更干净。这个结论在不同设备上可能有差异，你可以在自己项目里对比一下，选感受更好的方案。

3.3 把拦截逻辑封装成通用Hook

项目里的表单页不止一个，我最终封装了一个useBackConfirm，统一处理弹窗和防重入：

tsx复制import { useCallback, useRef, useState } from 'react';
import { useNavigation, usePreventRemove } from '@react-navigation/native';

type BackConfirmOptions = {
  title?: string;
  message: string;
  confirmText?: string;
  cancelText?: string;
  onConfirm?: () => void;
};

export function useBackConfirm(shouldPrevent: boolean, options: BackConfirmOptions) {
  const navigation = useNavigation();
  const [visible, setVisible] = useState(false);
  const visibleRef = useRef(false);
  const actionRef = useRef<any>(null);
  const optionsRef = useRef(options);
  optionsRef.current = options;

  usePreventRemove(shouldPrevent, ({ data }) => {
    if (visibleRef.current) return;
    visibleRef.current = true;
    actionRef.current = data.action;
    setVisible(true);
  });

  const close = useCallback(() => {
    visibleRef.current = false;
    actionRef.current = null;
    setVisible(false);
  }, []);

  const cancel = useCallback(() => {
    close();
  }, [close]);

  const confirm = useCallback(() => {
    const action = actionRef.current;
    const onConfirmFn = optionsRef.current.onConfirm;
    close();
    if (onConfirmFn) {
      onConfirmFn();
    }
    if (action && navigation.canGoBack()) {
      navigation.dispatch(action);
    }
  }, [close, navigation]);

  const modal = visible ? (
    // 这里放你的通用确认弹窗组件，通过visible、options、onConfirm、onCancel渲染
    null
  ) : null;

  return { modal, confirm, cancel };
}

使用的时候特别简单：

tsx复制const { modal } = useBackConfirm(hasUnsaved, {
  message: '当前内容尚未保存，确定离开吗？',
  onConfirm: () => {
    // 比如上报埋点、清空草稿缓存等
  },
});

封装完之后，页面里只需要关心hasUnsaved这个状态，弹窗和拦截逻辑全部收敛到一个hook里。这个hook在后面几个也涉及到拦截的页面里直接复用，省了不少事。

4. 鸿蒙硬件返回与侧滑手势：拦不到的部分怎么办

4.1 BackHandler 在鸿蒙上的表现

React Navigation的beforeRemove只能拦截导航器内部的移除动作，但是鸿蒙上有些返回事件不一定会转化成导航器的pop动作，这时候就需要BackHandler补位。

RN core里的BackHandler在鸿蒙上是有对应的原生实现的。我在真机上测试，通过底部导航手势（HarmonyOS上从底部上滑停顿进入多任务、快速上滑返回桌面）这类系统级返回，不一定走到RN层，但侧滑返回和键盘返回大多数情况会触发hardwareBackPress。

代码写法和Android一样：

tsx复制useEffect(() => {
  const sub = BackHandler.addEventListener('hardwareBackPress', () => {
    if (hasUnsaved) {
      // 在这里弹你的确认逻辑
      return true; // 表示已消费，不让默认返回执行
    }
    return false;
  });
  return () => sub.remove();
}, [hasUnsaved]);

但注意：在StackNavigation里，如果你同时挂了usePreventRemove和BackHandler，同一个返回事件可能被处理两次。我的做法是二选一：优先用usePreventRemove管导航动作，BackHandler只用来兜底那些没有走到导航器的系统返回事件。

判断当前返回事件到底有没有被导航器消费，可以加一个日志，在hardwareBackPress里打印当前路由名和navigation.canGoBack()的状态，这样能明显看到哪些返回事件是导航器没接住的。

4.2 gestureEnabled 的坑：RN手势和系统手势抢事件

再来说gestureEnabled。这个配置在iOS上用于开启/关闭系统边缘返回手势，在native-stack里默认是开启的。到了鸿蒙上，这个字段的意义就变得模糊了。

我遇到的情况是：在某个页面里设置gestureEnabled: false，目的是禁止用户侧滑返回，必须点按钮退出。在iOS和Android上行为都正常，鸿蒙上却无效，用户照样可以从屏幕边缘右滑返回。

排查后发现，问题不是react-native-harmony没实现这个属性，而是鸿蒙的系统级手势优先级更高。RN层的手势处理器还没拿到触摸事件，ArkUI容器页已经把这次滑动手势判定为系统返回并开始执行页面转场了。这就像你和路人甲同时伸手去接一个球，系统规定路人甲先接。

如果你一定要在鸿蒙上禁掉侧滑返回，只靠RN层的gestureEnabled是做不到的。有两个方向：

一是改原生容器页，在ArkUI页面里关闭该页面的返回手势。具体做法取决于你用的react-native-harmony版本，有些版本在原生页面初始化时没有暴露这个配置，需要改容器工程的页面代码。

二是放弃拦截系统侧滑，回到usePreventRemove的体系里。系统侧滑会把页面pop掉，但pop动作在导航器层面是可见的，beforeRemove仍然能拦。换句话说：系统手势负责“把页面移除”这个意图，导航器负责“最终是否执行”。我一开始遇到的“页面直接滑走”问题，其实不是手势的问题，而是容器页把pop动作做在了导航器外面，JS层根本没看到。后来升级了容器页的适配版本，事件链路打通之后，侧滑返回也能被beforeRemove拦住了。

所以排查顺序应该是：先确认容器页有没有把返回事件完整转发给RN，再讨论gestureEnabled的配置。

4.3 原生化兜底：容器页 onBackPress 与JS桥

如果JS层怎么试都拦不住系统返回，说明你用的react-native-harmony容器页可能没有把返回事件转发出来。这时候只能原生兜底。

思路其实不复杂。ArkUI的@Entry页面有一个onBackPress生命周期，你在里面return true就能阻止页面默认返回，然后通过一个自研TurboModule或者事件总线，把这个“用户想返回”的通知发给JS层。JS层收到通知后走自己的确认逻辑，确认后调用原生的返回方法，真正执行pop。

这个方案最彻底，但成本也最高：要改原生工程、要自己维护桥接代码、还要处理JS层和原生层状态的同步。我不建议一上来就搞原生兜底。大多数业务场景里，升级到最新版react-native-harmony、确认容器页事件转发正常，JS层的beforeRemove已经够用了。

5. 踩坑实录：返回拦截的边界场景

5.1 页面卸载后仍弹确认框

这是React Navigation老问题了。有些页面会在异步回调里触发setShowConfirm(true)，比如网络请求失败后弹提示。如果用户在这个时刻已经离开了页面，回调里的setState会执行在一个已卸载的组件上，轻则告警，重则Modal关不掉。

我的习惯是所有页面的弹窗状态都加一个mountedRef：

tsx复制const mountedRef = useRef(true);

useEffect(() => {
  mountedRef.current = true;
  return () => {
    mountedRef.current = false;
  };
}, []);

// 在异步回调里：
if (mountedRef.current) {
  setShowConfirm(true);
}

鸿蒙上这个问题比Android更明显，因为页面转场动画时间更长，用户可能在动画期间连续操作，组件卸载和setState的竞态更容易触发。

5.2 弹窗期间连续按返回

这个在3.2里已经说了，核心是防重入。再补充一点：Android上连续按返回，系统可能会在500ms内忽略第二次；鸿蒙上不同版本的处理不一样，我在部分真机上遇到过弹窗弹出后立刻按返回，弹窗关闭但页面也跑了的偶发情况。用visibleRef防重入后，这个现象基本消失了，因为第二次返回事件直接被if (visibleRef.current) return挡掉，不会走到任何导航动作。

5.3 路由跳转 vs 返回离开的判断

beforeRemove不只拦截返回，也拦截所有“把当前路由移除”的导航动作，包括replace和reset。我踩过一个坑：表单编辑页保存成功后，用navigation.replace('Success')跳到成功页，结果beforeRemove弹了确认框，整个流程像吃了苍蝇一样难受。

原因是replace会移除当前路由，触发了beforeRemove。解决办法是在跳转前先把hasUnsaved置为false，再执行replace。更规范的做法是区分当前action类型，只拦截GO_BACK和POP，放行REPLACE：

tsx复制navigation.addListener('beforeRemove', (e) => {
  if (e.data.action.type === 'REPLACE') return;
  // ...
});

鸿蒙上这个问题容易被忽略，因为页面栈状态在不同版本里表现有差异，建议在用到replace的页面里多写一步类型判断。

5.4 和 React Navigation 7.x 新特性的兼容

如果你升级到React Navigation 7.x，请做好回归测试。7.x对navigation.reset、navigation.replace的内部动作类型做了调整，部分老代码里用action.type判断逻辑可能失效。

另外，native-stack在鸿蒙上并不是真正意义上的“原生栈”。react-native-harmony对@react-navigation/native-stack的适配，底层可能还是JS实现的转场动画，并不是调用鸿蒙原生Navigation组件。这就导致部分options在鸿蒙上不生效，比如某些转场动画参数、headerBackButtonDisplayMode等。遇到不支持的配置，去看react-native-harmony仓库里对应版本对native-stack的适配代码，比在业务层瞎猜快得多。

最后说点个人经验。返回拦截这件事，核心不是代码怎么写，而是要想清楚“这个页面到底允不允许用户被系统直接移除”。我现在的习惯是：能用usePreventRemove解决的，绝不用BackHandler；需要拦截系统侧滑的，先查react-native-harmony版本对容器页返回事件的处理；遇到JS层实在兜不住的情况，才去碰原生工程。鸿蒙这波适配，最大的感受就是不能把Android的经验无脑搬过来，事件链路不同，排查思路就得跟着变。希望这篇文章能帮你少踩几个坑。