Reach Router 的 LocationProvider:location 上下文注入、history 注入与测试实战指南
Reach Router 的 LocationProvider:location 上下文注入、history 注入与测试实战指南
LocationProvider 是 Reach Router(即当前仓库 router)中负责监听 location 变化、并向整棵组件树注入 location 上下文的顶层组件。本文将以其官方 API 文档 LocationProvider.md 为骨架,结合 src/index.js 的源码实现与 src/index.test.js、src/lib/history.test.js 中的测试用例,深入讲解它的两种 children 用法、history 注入机制、默认行为,以及在测试与未来 React Native 场景中的实际应用。读完本文,你将掌握如何用 LocationProvider 自定义历史记录、如何通过 render prop 拿到 location 与 navigate,以及如何把它当作"测试底座"驱动整套路由组件。
一、LocationProvider 是什么
LocationProvider 会设置一个对 location 变化的监听器。Reach Router 中那些"需要 location 的 API"(如 Router、Link、Match、Redirect)会在内部自动完成这层包裹,所以大多数应用并不需要显式使用它。它最主要的应用场景有两个:
- 测试:在测试环境中注入自定义的 history(尤其是内存型 history),让组件可以脱离真实浏览器 URL 独立运行和断言;
- 未来扩展到 React Native:当应用运行在没有
window.history的平台上时,可以注入一个自定义 history 来源。
从源码 src/index.js 可以看到,LocationProvider 是一个 React 类组件,它维护着 context(即 { navigate, location })状态,并通过 <LocationContext.Provider value={context}> 向下传递:
class LocationProvider extends React.Component {
state = {
context: this.getContext(),
refs: { unlisten: null }
};
getContext() {
let {
props: {
history: { navigate, location }
}
} = this;
return { navigate, location };
}
// ...
}
也就是说,LocationProvider 的核心职责只有一件:从传入的 history 对象中取出 location 与 navigate,打包成 context 提供给所有后代组件。
二、最小使用示例
官方文档给出的完整示例同时演示了"浏览器 history"与"内存 history"两种来源:
import {
createMemorySource,
createHistory,
LocationProvider
} from "@reach/router"
let history = createHistory(window)
// for some types of tests you want a memory source
let source = createMemorySource("/starting/url")
let history = createHistory(source)
let App = () => (
<LocationProvider history={history}>
<div>
Alright, we've established some location
context
</div>
</LocationProvider>
)
这里的 createHistory 与 createMemorySource 同样来自仓库导出(见 src/index.js 的 export 列表),它们的实现位于 src/lib/history.js。
createHistory 做了什么
createHistory(source, options) 接收一个 location 来源(source),返回一个可 listen、可 navigate 的 history 对象(src/lib/history.js):
listen(listener):注册 location 变化监听,同时监听 source 上的popstate事件(对应浏览器前进/后退),返回一个取消监听的函数;navigate(to, { state, replace = false }):通过source.history.pushState或replaceState更新 URL,并依次通知所有监听者,返回一个 Promise(见下节说明)。
let history = createHistory(window)
此时 source 就是浏览器的 window,history 会读取 window.location 与 window.history,监听真实的 popstate 事件。
createMemorySource 做了什么
createMemorySource(initialPath = "/") 在内存中维护一个历史栈(src/lib/history.js),内部用 stack 数组和 index 游标模拟 history.pushState、replaceState、go:
let source = createMemorySource("/starting/url")
let history = createHistory(source)
它不会触碰浏览器地址栏,非常适合在测试(Jest + react-test-renderer 等)中模拟任意起始路径。src/lib/history.test.js 中就有对应的验证(src/lib/history.test.js):
const testHistory = createMemorySource("/test");
expect(testHistory.location.pathname).toBe("/test");
const testHistory2 = createMemorySource("/test?foo=bar");
expect(testHistory2.location.search).toBe("?foo=bar");
三、history 属性(可选):注入要监听的历史记录
3.1 参数说明
history 是 LocationProvider 的可选对象属性,表示要监听的 history。默认值是浏览器 history;如果在运行时找不到 DOM(如 Node 环境),则会回退为内存型 history。
在源码中,这个默认行为由 src/index.js 的 defaultProps 与 src/lib/history.js 的 getSource() 共同实现:
static defaultProps = {
history: globalHistory
};
let canUseDOM = !!(
typeof window !== "undefined" &&
window.document &&
window.document.createElement
);
let getSource = () => {
return canUseDOM ? window : createMemorySource();
};
let globalHistory = createHistory(getSource());
globalHistory 是仓库在模块加载时创建的单例:浏览器环境下以 window 为 source,无 DOM 环境下自动退化为内存 source。这正对应官方文档"Defaults to the browser history or a memory history if a DOM is not found"的描述。
3.2 显式注入用法
import { createHistory, LocationProvider } from '@reach/router'
let history = createHistory(window)
<LocationProvider history={history}/>
显式传入 history 的典型价值在于测试:你可以在每个测试用例里创建独立的内存 history,从而完全掌控起始路径与后续导航。
以仓库测试文件 src/index.test.js 为例,两个工具函数都是靠 LocationProvider history={testHistory} 驱动整个路由树的:
let snapshot = ({ pathname, element }) => {
let testHistory = createHistory(createMemorySource(pathname));
let wrapper = renderer.create(
<LocationProvider history={testHistory}>{element}</LocationProvider>
);
const tree = wrapper.toJSON();
expect(tree).toMatchSnapshot();
return tree;
};
let runWithNavigation = (element, pathname = "/") => {
let history = createHistory(createMemorySource(pathname));
let wrapper = renderer.create(
<LocationProvider history={history}>{element}</LocationProvider>
);
// ...
return { history, snapshot, wrapper };
};
在 runWithNavigation 中,测试可以通过返回的 history.navigate("/reports") 模拟导航,再断言渲染快照(见 src/index.test.js 的 transitions 测试组)。这正是 LocationProvider 作为"测试底座"的标准姿势。
四、children:element(元素用法)
LocationProvider 的 children 可以直接传入 JSX 元素,将这些元素包裹在 location 上下文中:
<LocationProvider>
<div>This is fine</div>
</LocationProvider>
在这种用法下,子元素自身不直接消费 context,但它们内部如果使用 Link、Match、Router 等组件,就能通过 React Context 自动拿到 location。源码中的 render 逻辑对此有明确处理(src/index.js):
render() {
let {
state: { context },
props: { children }
} = this;
return (
<LocationContext.Provider value={context}>
{typeof children === "function" ? children(context) : children || null}
</LocationContext.Provider>
);
}
可以看到:children 是函数时调用函数并传入 context;children 是元素(或节点数组)时直接作为 Provider 的子树渲染。这也是下面一节 render-prop 用法的源码依据。
五、children:func(render prop 用法)
如果向 LocationProvider 传入一个函数作为 children,它会把你创建的 context 以参数形式传回,其中包含 location 和 navigate:
<LocationProvider>
{context => {
console.log(context.location)
console.log(context.navigate)
}}
</LocationProvider>
其中 context.location 是一个包含 pathname、search、hash 等字段的对象(字段解析逻辑见 src/lib/history.js),context.navigate 则是与当前 history 绑定的导航函数。
官方文档特别提醒:如果你想在应用中任意位置访问这两个值,请使用 Location 组件而不是 LocationProvider。Location 是同一个 context 的消费者(src/index.js),它内部会自动补齐缺失的 Provider:
let Location = ({ children }) => (
<LocationContext.Consumer>
{context =>
context ? (
children(context)
) : (
<LocationProvider>{children}</LocationProvider>
)
}
</LocationContext.Consumer>
);
也就是说,Router、Link 等组件之所以"不需要你手动包裹 Provider",正是因为这个自动兜底逻辑。若需要了解 Location 的完整用法(包括与动画框架配合的常见模式),可参考 Location.md。
navigate 返回值说明
context 中的 navigate 来自 history.navigate。源码(src/lib/history.js)显示它返回一个 Promise:
navigate(to, { state, replace = false } = {}) {
// ...
transitioning = true;
let transition = new Promise(res => (resolveTransition = res));
listeners.forEach(listener => listener({ location, action: "PUSH" }));
return transition;
}
在 componentDidMount 与 componentDidUpdate 中,LocationProvider 会在 transition 完成后调用 history._onTransitionComplete()(src/index.js),从而使该 Promise resolve。有关 navigate 的 to、state、replace 参数语义,可进一步查阅 navigate.md。
六、LocationProvider 的监听生命周期
虽然文档只从"使用"层面描述 API,但理解其内部生命周期有助于排查导航不刷新的问题。源码 src/index.js 展示了完整的监听-清理流程:
componentDidMount() {
let {
state: { refs },
props: { history }
} = this;
history._onTransitionComplete();
refs.unlisten = history.listen(() => {
Promise.resolve().then(() => {
requestAnimationFrame(() => {
if (!this.unmounted) {
this.setState(() => ({ context: this.getContext() }));
}
});
});
});
}
componentWillUnmount() {
let {
state: { refs }
} = this;
this.unmounted = true;
refs.unlisten();
}
要点有三:
- 挂载时通过
history.listen(...)注册监听器,location 一旦变化就通过setState刷新 context; - 更新被调度到 rAF 中(注释中说明,未来计划替换为 React 的 deferred update API),避免在同一帧内过于频繁地触发渲染;
- 卸载时调用
refs.unlisten()取消监听,并通过unmounted标志防止卸载后异步setState告警。
listen 返回的取消函数来自 src/lib/history.js,它同时移除 popstate 事件监听并从监听者数组中过滤掉自身:
listen(listener) {
listeners.push(listener);
let popstateListener = () => {
location = getLocation(source);
listener({ location, action: "POP" });
};
source.addEventListener("popstate", popstateListener);
return () => {
source.removeEventListener("popstate", popstateListener);
listeners = listeners.filter(fn => fn !== listener);
};
}
注意:内存 source 的 addEventListener / removeEventListener 是空操作(src/lib/history.js),因此内存 history 主要靠 navigate 时手动调用监听者来驱动更新。
另外,LocationProvider 还实现了 componentDidCatch(src/index.js):当子树抛出 redirect 请求(isRedirect(error) 为真)时,会自动以 replace: true 导航到目标 URI,这保证了 <Redirect> 组件在普通客户端渲染中的行为一致。
七、在测试中使用 LocationProvider:完整示例
把前面的知识点串起来,一个标准的组件测试骨架如下:
import React from "react";
import renderer from "react-test-renderer";
import {
createMemorySource,
createHistory,
LocationProvider,
Router
} from "@reach/router";
const Home = () => <div>Home</div>;
const Reports = () => <div>Reports</div>;
test("渲染 /reports 路径", () => {
const history = createHistory(createMemorySource("/reports"));
const wrapper = renderer.create(
<LocationProvider history={history}>
<Router>
<Home path="/" />
<Reports path="/reports" />
</Router>
</LocationProvider>
);
expect(wrapper.toJSON()).toMatchSnapshot();
});
如果需要"导航后断言",可以直接调用 history.navigate(...) 并等待其返回的 Promise(参考 src/index.test.js 的 transitions 测试):
test("从首页导航到报告页", async () => {
const history = createHistory(createMemorySource("/"));
const wrapper = renderer.create(
<LocationProvider history={history}>
<Router>
<Home path="/" />
<Reports path="/reports" />
</Router>
</LocationProvider>
);
await history.navigate("/reports");
// 此时 snapshot 应反映 /reports 的渲染结果
expect(wrapper.toJSON()).toMatchSnapshot();
});
仓库测试中还验证了一个细节:点击当前路径的 <Link> 且 state 相同或为空时,会走 replaceState 而非 pushState(见 src/index.test.js),这与 Link 在 src/index.js 中基于 shallowCompare 的 replace 判断逻辑一致。
八、延伸:SSR 与 hooks 场景中的上下文
理解 LocationProvider 之后,几个相关 API 的上下文来源会更清晰:
- 服务端渲染:Node 环境没有可监听的 history,此时应使用
ServerLocation(ServerLocation.md)。它在 src/index.js 中直接向同一个LocationContext.Provider注入一个静态 location(仅含pathname、search、hash),并提供一个会抛错的navigate(服务端不允许导航)。 - Hooks:
useLocation通过useContext(LocationContext)读取location,若上方没有 Provider 会抛出明确的错误提示(src/index.js)。这再次说明:凡是依赖 location 的组件,都必须位于LocationProvider(或自动兜底的Location)之下。
结语
LocationProvider 是 Reach Router 中"location 即 Context"设计思想的落地组件:它以可注入的 history 为数据源,以 location + navigate 为上下文载荷,向上承接 createHistory / createMemorySource,向下服务 Router、Link、Match、useLocation 等全部路由 API。日常开发中你几乎感知不到它——但一旦进入测试编写、多实例历史隔离或非 DOM 平台适配,它就是你最直接的切入点。想深入源码细节,可继续阅读 src/index.js 与 src/lib/history.js;想系统了解配套 API,可浏览 website/src/markdown/api 目录下的相关文档。