Reach Router 的 LocationProvider:location 上下文注入、history 注入与测试实战指南

原创2026-10-10 23:31:461,731 阅读
文章标签:前端

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)会在内部自动完成这层包裹,所以大多数应用并不需要显式使用它。它最主要的应用场景有两个:

  1. 测试:在测试环境中注入自定义的 history(尤其是内存型 history),让组件可以脱离真实浏览器 URL 独立运行和断言;
  2. 未来扩展到 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();
}

要点有三:

  1. 挂载时通过 history.listen(...) 注册监听器,location 一旦变化就通过 setState 刷新 context;
  2. 更新被调度到 rAF 中(注释中说明,未来计划替换为 React 的 deferred update API),避免在同一帧内过于频繁地触发渲染;
  3. 卸载时调用 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 目录下的相关文档。

登录后查看全文
router