React 第四十五节 Router 中 useHref() Hook的使用详解及注意事项

前言

React Router 中的 useHref 是一个用于生成完整 URL 路径的钩子，
它可以将相对路径解析为绝对路径，并确保在不同路由层级中正确工作。
它常用于自定义导航组件或需要手动构建链接的场景。

一、useHref核心用途

解析相对路径：自动将相对路径（如 ../settings）转换为基于当前路由的绝对路径。
生成完整 URL：适用于需要直接操作 href 的场景（如 <a> 标签或重定向）。
支持动态路由参数：正确处理包含参数的路由路径（如 /users/:id）。

二、useHref 基本用法

2.1、 基本示例：生成绝对路径

import { useHref } from "react-router-dom";

function CustomLink({ to, children }) {
  const href = useHref(to);
  return <a href={href}>{children}</a>;
}

// 使用示例
<CustomLink to="/about">关于我们</CustomLink>

2.2、参数说明

useHref 接收一个参数：
参数to：可以是字符串或对象（包含 pathname、search、hash 等属性）

说明：
字符串时：如"/users"，表示直接路径
对象时：如：{ pathname: “…/settings”, search: “?page=1” }，可以带查询参数的路径

三、useHref完整代码案例

场景：在嵌套路由中生成正确链接

// 路由配置
const router = createBrowserRouter([
  {
    path: "/dashboard",
    element: <Dashboard />,
    children: [
      {
        path: "profile",
        element: <Profile />,
      },
      {
        path: "settings",
        element: <Settings />,
      }
    ]
  }
]);

// Dashboard 组件（父路由）
function Dashboard() {
  return (
    <div>
      <h1>控制面板</h1>
      <nav>
        <CustomLink to="profile">个人资料</CustomLink> {/* 生成 /dashboard/profile */}
        <CustomLink to="../settings">设置</CustomLink> {/* 生成 /dashboard/settings */}
      </nav>
      <Outlet />
    </div>
  );
}

// 自定义链接组件
function CustomLink({ to, children }) {
  const href = useHref(to);
  return (
    <a 
      href={href}
      style={{ color: 'blue', textDecoration: 'underline' }}
    >
      {children}
    </a>
  );
}

四、useHref 高级用法

4.1、生成带查询参数的 URL

function ShareButton() {
  const href = useHref({
    pathname: "/share",
    search: "?utm_source=widget",
    hash: "#social"
  });

  return (
    <a href={href} target="_blank">
      分享到社交媒体
    </a>
  );
}
// 生成：/share?utm_source=widget#social

4.2、 useHref 处理动态路由参数

// 路由配置
{
  path: "/products/:id",
  element: <ProductDetail />
}

// 组件内使用
function ProductCard({ id }) {
  const href = useHref(`/products/${id}`);
  return (
    <a href={href}>
      查看商品详情
    </a>
  );
}

五、useHref 与直接字符串拼接的对比

useHref：可以自动处理相对路径和嵌套路由，但是需要引入 React Router
手动拼接字符串：不需要引入额外依赖，但是容易出错（特别是多层嵌套路由时）

六、 useHref 注意事项

6.1、必须在路由上下文中使用

组件需要包裹在 <Router> 组件内（如 <BrowserRouter>）

6.2、不会触发路由导航

生成的链接需要用户点击或自行处理导航逻辑

6.3、参数类型安全

TypeScript 用户应使用 To 类型定义参数：

import type { To } from "react-router-dom";

function CustomLink({ to }: { to: To }) {
  const href = useHref(to);
  // ...
}

七、useHref 与 <Link> 的使用及应用场景区别

useHref：需要用户点击原生链接，才可以进行导航，使用于 传统<a>标签的场景中；
<Link>：多用于内部路由跳转（无刷新），适用于 SPA 内部导航 场景中

八、useHref 应用场景

8.1、邮件模板中的链接生成

function EmailTemplate() {
  const resetPasswordHref = useHref("/reset-password");
  return (
    <div>
      <p>请点击链接重置密码：</p>
      <a href={resetPasswordHref}>{resetPasswordHref}</a>
    </div>
  );
}

8.2、SEO 优化静态页面

function Sitemap() {
  const pages = ['/', '/about', '/contact'];
  return (
    <ul>
      {pages.map(path => (
        <li key={path}>
          <a href={useHref(path)}>{path}</a>
        </li>
      ))}
    </ul>
  );
}

我们使用 useHref可以安全地生成符合当前路由结构的 URL，避免手动拼接路径导致的错误。
它是构建灵活导航系统的关键工具，特别适用于需要与传统 HTML 特性深度集成的场景。

个人见解，如有错误，欢迎批评指正