Home > react-nav-router

react-nav-router package

Functions

Function	Description
createLocation(route)	生成URL地址
createRoute(location)	生成路由对象
createRouter(options)	创建路由控制器
NavStack(props)	Nav 页面栈控制器组件 维护一个「页面栈」，按栈顶渲染当前页面；在 stack 发生 push / pop / replace 时同时渲染新旧两个页面，通过 CSS transition 实现 iOS 风格的过渡动画： - push：新页面从右滑入，旧页面左移 50% 淡出 - pop： 旧页面向右滑出，新页面从左 50% 位置滑入 - replace：新旧页面交叉淡入淡出 工作流程： 1. stack 变化触发 effect，用**双 requestAnimationFrame** 保证浏览器 先绘制一帧"开始态"，再切换到"结束态"——两帧间的样式差异是 CSS transition 生效的必要条件（与 React 批处理无关；同步 DOM 写入 会被合并为一次绘制，transition 不会触发） 2. 动画跑满 transitionDuration 后把动画基线推进到新 stack，回到稳态 3. 动画未结束前又发生 stack 变化：丢弃中间态，直接以当前 stack 作为 新的动画基线（不累积动画队列，避免视觉错乱）
useNavRoute()	获取当前路由上下文 通常在受 NavRouter 控制的页面组件中使用，可读取当前 route、调用 navigateTo / navigateBack 进行跳转。

Interfaces

Interface	Description
NavRouteContextValue	Nav 路由上下文值 通过 useNavRoute() 在路由视图组件中获取。
NavRouterProps	Nav路由控制器组件
NavStackProps	Nav页面栈控制器组件 Props
NavViewContextValue	Nav 页面上下文值 由 NavStack 在每个页面视图外层注入，用于通知 NavView（或其它消费者） 该视图当前所处的外观状态与对应的栈元素标识。
NavViewProps	Nav 页面生命周期回调 四个回调对应页面可见性的四个时机，与 iOS UIViewController 的 viewWillAppear / viewDidAppear / viewWillDisappear / viewDidDisappear 语义一致： hidden ── willAppear ──► entering ── didAppear ──► visible │ willDisappear ▼ hidden ◄── didDisappear ── leaving
Route	路由信息
Router	路由控制器
RouterOptions	路由控制器创建配置

Variables

Variable	Description
AppearStatus	Nav 视图外观状态编码 由 NavStack 写入、NavView 消费。用于描述视图在过渡动画各阶段的样式/可见性状态。 取值约定： - 正数：动画「结束态」（transition 生效后的目标样式） - 负数：动画「开始态」（transition 生效前的初始样式） - 0 / 1：非动画稳态（分别对应 隐藏 / 显示） 方向语义需要结合"上一次 appearStatus"推断（从 0 出发 = 进入；从 1 出发 = 离开）。 具体语义参见下表： | 值 | 含义 | |----|-----------------------------------------------------------| | 0 | 完全隐藏（display: none），不参与布局 | | 1 | 正常显示（无 transform / opacity 修饰） | | 2 | 淡入结束 / 淡出开始：opacity = 1 | | -2 | 淡入开始 / 淡出结束：opacity = 0 | | 3 | pop 新页结束 / push 旧页开始：居中、不透明 | | -3 | pop 新页开始 / push 旧页结束：左移 50%、透明 | | 4 | pop 旧页开始 / push 新页结束：居中、不透明 | | -4 | pop 旧页结束 / push 新页开始：右移 100%（屏幕外）、透明 |
NavRouteContext	Nav 路由上下文 默认值表示"未被 NavRouter 包裹"的空壳状态：无路由、栈长度为 0、 navigate 方法为 no-op。实际使用中，值由 NavRouter 注入。
NavRouter	Nav 路由控制器组件 职责： 1. 订阅 Router 的路由栈变化，驱动视图重渲染 2. 把路由栈交给 NavStack() 负责堆叠渲染与过渡动画 3. 为每个路由视图注入 NavRouteContext，让页面组件可通过 useNavRoute() 读取当前路由、调用 navigateTo / navigateBack 设计说明： - 使用 useSyncExternalStore 订阅 router： · 天然解决 React 18 并发模式下 useEffect 订阅时机晚于首次 render 导致丢更新的问题 · 订阅函数 subscribe 与 router 绑定，router 不变则订阅不会重挂 - 订阅函数使用 useCallback 稳定引用，避免 StrictMode 等场景下 subscribe 引用变化触发重复订阅 - navigate 方法对外暴露的引用在同一个 router 实例上是稳定的， 因此 Context value 的 navigate 部分用 useMemo 固化， 降低 Context 消费者（AppAside 等）不必要的重渲染
NavView	Nav 页面组件 包裹页面内容，并根据父级 NavStack 注入的 NavViewContext 中的 appearStatus 变化，在合适的时机触发 willAppear / didAppear / willDisappear / didDisappear 回调。 典型使用： <NavView willAppear={() => stat('show', 'claw_d_xxx')} didDisappear={() => cleanup()} > <PageContent /> </NavView> 实现说明： - 使用 ref 保存"上一次 appearStatus"以推断动画方向；初始值为 null， 这样首次 effect 能识别出"从无到有"的阶段变化（如首帧就是 Normal 的栈顶页面， 会被认定为 entering → visible，并触发 willAppear + didAppear） - 回调通过 ref 读取最新引用，避免依赖 willAppear 等 prop 导致 effect 频繁重跑
NavViewContext	Nav 页面上下文 默认值表示"未被 NavStack 包裹"的空壳状态：视图隐藏、无栈元素。 实际值由 NavStack 注入。

Type Aliases

Type Alias	Description
RouterAction	路由跳转类型
RouterEvent	路由事件，路由跳转时触发 使用 Discriminated Union 表达不同 action 对应的 payload 语义： - navigateTo → payload 为目标 Route - navigateBack → payload 为回退后的新栈长度（见 Router.navigateBack()） - historyPop → 由浏览器 popstate 触发，无 payload
RouterListener	路由监听器