深入react-native-app-tour源码：findNodeHandle与NativeModules如何打通JS与原生App Tour视图

深入react-native-app-tour源码：findNodeHandle与NativeModules如何打通JS与原生App Tour视图

【免费下载链接】react-native-app-tourReact Native: Native App Tour Library项目地址: https://gitcode.com/gh_mirrors/re/react-native-app-tour

react-native-app-tour 是一款 React Native 原生 App Tour（应用引导）库：它把 Android 的 TapTargetView 和 iOS 的 MaterialShowcase 封装成一套 JS API，让"聚光灯 + 气泡文案"式的功能引导只需几行代码。本文从 RNAppTour.js 入手，拆解findNodeHandle与NativeModules这两个 React Native 桥接核心 API，讲清楚 JS 侧的组件引用是如何一路变成原生视图坐标的。

🧭 30秒看懂：这个库在桥接什么

先建立一个整体印象。整个库只有 3 个核心类：

它们的分工可以概括为一句话：JS 负责"指哪"，原生负责"怎么秀"。桥接就发生在"指哪"被翻译成原生视图 ID 的那一刻。

🪝 上半场：findNodeHandle 把 React 组件变成原生视图 ID

注册入口：AppTourView.for 的三重保险

引导开始前，你先用AppTourView.for(view, props)注册目标。这段源码（RNAppTour.js）做了三件关键事：

1. 空引用校验：view为null/undefined直接抛错，避免后续在原生侧查无此视图；
2. 区分组件类型：检查view._reactInternalFiber是否存在——存在说明是 React 组件实例，不存在（如原生组件）则走_nativeTag分支（RNAppTour.js）；
3. 强制 key 校验：React 组件必须带keyprop，否则抛错提示"Each tour view should have a key prop"。

为什么key是必填项？因为key会作为属性包props的索引键，在多目标序列中原生侧靠它把每个视图 ID 与对应文案对上号。

findNodeHandle：JS 世界的"名牌"

最后一步只有一行：

view: findNodeHandle(view)

（RNAppTour.js）

findNodeHandle是 React Native 提供的 API，它返回组件在原生视图树中的数字 ID（即_nativeTag）。有了这个数字，JS 组件引用就变成了一把能在原生世界直接"点名"的钥匙——后面 Android 和 iOS 都靠它找回真正的View/UIView。

🌉 下半场：NativeModules 把调用交棒给原生

桥的起点：一行解构

RNAppTour.js 顶部就声明了这条桥：

const { RNAppTour } = NativeModules

NativeModules是 JS 侧访问原生模块的总入口。Android 侧，模块名"RNAppTour"由 RNAppTourModule.java 的getName()返回，并通过 RNAppTourPackage.java 注册进 React 实例。于是RNAppTour.ShowSequence(...)/RNAppTour.ShowFor(...)就会跨越桥，直达原生方法。

Android：按 tag 找回视图，再量出坐标

Android 原生模块的ShowSequence（RNAppTourModule.java）流程是：

1. activity.runOnUiThread保证操作 UI 在线程上安全；
2. 用uiManager.addUIBlock拿到NativeViewHierarchyManager；
3. 循环调用nativeViewHierarchyManager.resolveView(viewId)——这里把findNodeHandle传来的 ID 解析成真正的 AndroidView；
4. 调用generateTapTarget（RNAppTourModule.java）：用view.getLocationOnScreen()取屏幕坐标、getWidth()/getHeight()取尺寸，构造Rect边界，再套上TapTarget.forBounds(...)；
5. 剩余工作交给TapTargetSequence完成动画与顺序控制。

注意源码里的try { resolveView } catch { continue }——查不到视图就跳过而不是崩溃，这是个对新手友好的容错设计。

iOS：viewForReactTag 一步到位

iOS 侧更直接，核心就一行（RNAppTour.m）：

UIView *target = [self.bridge.uiManager viewForReactTag: view];

RCTBridge的uiManager负责用 React tag 反查UIView，随后generateMaterialShowcase（RNAppTour.m）解析颜色、字号、动画时长等 props，交给MaterialShowcase展示。序列则由自定义的MutableOrderedDictionary（RNAppTour.h）按插入顺序维护，每完成一步在showCaseDidDismiss里弹出队首、递归展示下一个（RNAppTour.m）。

iOS 工程在 Xcode 中的配置界面（示例工程 Identity / Signing 页）如下：

🔁 闭环：原生事件如何流回 JS

桥是双向的。原生 Tour 每前进一步、结束或取消时，都会通过DeviceEventManagerModule（Android）或eventDispatcher（iOS）发回事件，JS 侧用DeviceEventEmitter.addListener监听：

• onShowSequenceStepEvent：进入下一步
• onFinishSequenceEvent：序列完成
• onCancelStepEvent：被用户取消

示例工程的完整监听写法见 App.js。这样 JS 就能在"用户看完引导"时更新状态、写入埋点。

✅ 快速上手清单

1. 安装：npm install react-native-app-tour --save（需 React Native 61+）；如需离线阅读源码，可git clone https://gitcode.com/gh_mirrors/re/react-native-app-tour
2. 配置原生依赖：Android 在build.gradle添加 jitpack 仓库；iOS 在Podfile中引入RNAppTour与MaterialShowcase
3. 给组件加key，并在ref中调用AppTourView.for(ref, {...})（完整写法见 Top.js）
4. 每个目标必须带order：JS 侧按order排序后再发给原生（RNAppTour.js），顺序即播放顺序
5. 调起：单目标用AppTour.ShowFor(target)，多目标序列用AppTour.ShowSequence(sequence)，参考 App.js

📌 总结

回顾这条链路：ref→AppTourView.for校验并取key→findNodeHandle得到原生视图 ID →NativeModules.RNAppTour跨桥 → 原生resolveView/viewForReactTag找回真实视图 → 坐标计算 + 动画库展示 → 事件流回 JS。

理解了findNodeHandle（把 JS 引用翻译成 ID）和NativeModules（把调用送进原生）这两个枢纽，你不仅用好了 react-native-app-tour，也掌握了 React Native 中几乎所有"JS 操作原生视图"类库的通用套路——这在自研桥接模块时同样派得上用场。

【免费下载链接】react-native-app-tourReact Native: Native App Tour Library项目地址: https://gitcode.com/gh_mirrors/re/react-native-app-tour