导航 | TanStack Router React 文档

一切皆相对

信不信由你，应用中的每一次导航都是相对的，即使你没有使用显式的相对路径语法（../../somewhere）。任何时候点击链接或进行命令式导航调用，你总会有一个源路径和一个目标路径，这意味着你正在**从**一个路由导航**到**另一个路由。

TanStack Router 在每一次导航时都牢记相对导航这一恒定的概念，因此你将经常在 API 中看到两个属性：

from - 源路由路径
to - 目标路由路径

⚠️ 如果未提供 from 路由路径，路由器将假定你正在从根路径 / 进行导航，并且只自动完成绝对路径。毕竟，你需要知道你的起点才能知道你的目的地 😉。

TanStack Router 中的每一次导航和路由匹配 API 都使用相同的核心接口，只是根据 API 的不同而略有差异。这意味着你可以学习一次导航和路由匹配，然后在整个库中使用相同的语法和概念。

ToOptions 接口

这是在每个导航和路由匹配 API 中使用的核心 ToOptions 接口。

type ToOptions<
  TRouteTree extends AnyRoute = AnyRoute,
  TFrom extends RoutePaths<TRouteTree> | string = string,
  TTo extends string = '',
> = {
  // `from` is an optional route ID or path. If it is not supplied, only absolute paths will be auto-completed and type-safe. It's common to supply the route.fullPath of the origin route you are rendering from for convenience. If you don't know the origin route, leave this empty and work with absolute paths or unsafe relative paths.
  from?: string
  // `to` can be an absolute route path or a relative path from the `from` option to a valid route path. ⚠️ Do not interpolate path params, hash or search params into the `to` options. Use the `params`, `search`, and `hash` options instead.
  to: string
  // `params` is either an object of path params to interpolate into the `to` option or a function that supplies the previous params and allows you to return new ones. This is the only way to interpolate dynamic parameters into the final URL. Depending on the `from` and `to` route, you may need to supply none, some or all of the path params. TypeScript will notify you of the required params if there are any.
  params:
    | Record<string, unknown>
    | ((prevParams: Record<string, unknown>) => Record<string, unknown>)
  // `search` is either an object of query params or a function that supplies the previous search and allows you to return new ones. Depending on the `from` and `to` route, you may need to supply none, some or all of the query params. TypeScript will notify you of the required search params if there are any.
  search:
    | Record<string, unknown>
    | ((prevSearch: Record<string, unknown>) => Record<string, unknown>)
  // `hash` is either a string or a function that supplies the previous hash and allows you to return a new one.
  hash?: string | ((prevHash: string) => string)
  // `state` is either an object of state or a function that supplies the previous state and allows you to return a new one. State is stored in the history API and can be useful for passing data between routes that you do not want to permanently store in URL search params.
  state?:
    | Record<string, any>
    | ((prevState: Record<string, unknown>) => Record<string, unknown>)
}

type ToOptions<
  TRouteTree extends AnyRoute = AnyRoute,
  TFrom extends RoutePaths<TRouteTree> | string = string,
  TTo extends string = '',
> = {
  // `from` is an optional route ID or path. If it is not supplied, only absolute paths will be auto-completed and type-safe. It's common to supply the route.fullPath of the origin route you are rendering from for convenience. If you don't know the origin route, leave this empty and work with absolute paths or unsafe relative paths.
  from?: string
  // `to` can be an absolute route path or a relative path from the `from` option to a valid route path. ⚠️ Do not interpolate path params, hash or search params into the `to` options. Use the `params`, `search`, and `hash` options instead.
  to: string
  // `params` is either an object of path params to interpolate into the `to` option or a function that supplies the previous params and allows you to return new ones. This is the only way to interpolate dynamic parameters into the final URL. Depending on the `from` and `to` route, you may need to supply none, some or all of the path params. TypeScript will notify you of the required params if there are any.
  params:
    | Record<string, unknown>
    | ((prevParams: Record<string, unknown>) => Record<string, unknown>)
  // `search` is either an object of query params or a function that supplies the previous search and allows you to return new ones. Depending on the `from` and `to` route, you may need to supply none, some or all of the query params. TypeScript will notify you of the required search params if there are any.
  search:
    | Record<string, unknown>
    | ((prevSearch: Record<string, unknown>) => Record<string, unknown>)
  // `hash` is either a string or a function that supplies the previous hash and allows you to return a new one.
  hash?: string | ((prevHash: string) => string)
  // `state` is either an object of state or a function that supplies the previous state and allows you to return a new one. State is stored in the history API and can be useful for passing data between routes that you do not want to permanently store in URL search params.
  state?:
    | Record<string, any>
    | ((prevState: Record<string, unknown>) => Record<string, unknown>)
}

🧠 每个路由对象都有一个 to 属性，它可以作为任何导航或路由匹配 API 的 to 使用。在可能的情况下，这将允许你避免使用纯字符串，而是使用类型安全的路由引用。

tsx

import { Route as aboutRoute } from './routes/about.tsx'

function Comp() {
  return <Link to={aboutRoute.to}>About</Link>
}

import { Route as aboutRoute } from './routes/about.tsx'

function Comp() {
  return <Link to={aboutRoute.to}>About</Link>
}

NavigateOptions 接口

这是核心 NavigateOptions 接口，它扩展了 ToOptions。任何实际执行导航的 API 都将使用此接口。

export type NavigateOptions<
  TRouteTree extends AnyRoute = AnyRoute,
  TFrom extends RoutePaths<TRouteTree> | string = string,
  TTo extends string = '',
> = ToOptions<TRouteTree, TFrom, TTo> & {
  // `replace` is a boolean that determines whether the navigation should replace the current history entry or push a new one.
  replace?: boolean
  // `resetScroll` is a boolean that determines whether scroll position will be reset to 0,0 after the location is committed to browser history.
  resetScroll?: boolean
  // `hashScrollIntoView` is a boolean or object that determines whether an id matching the hash will be scrolled into view after the location is committed to history.
  hashScrollIntoView?: boolean | ScrollIntoViewOptions
  // `viewTransition` is either a boolean or function that determines if and how the browser will call document.startViewTransition() when navigating.
  viewTransition?: boolean | ViewTransitionOptions
  // `ignoreBlocker` is a boolean that determines if navigation should ignore any blockers that might prevent it.
  ignoreBlocker?: boolean
  // `reloadDocument` is a boolean that determines if navigation to a route inside of router will trigger a full page load instead of the traditional SPA navigation.
  reloadDocument?: boolean
  // `href` is a string that can be used in place of `to` to navigate to a full built href, e.g. pointing to an external target.
  href?: string
}

export type NavigateOptions<
  TRouteTree extends AnyRoute = AnyRoute,
  TFrom extends RoutePaths<TRouteTree> | string = string,
  TTo extends string = '',
> = ToOptions<TRouteTree, TFrom, TTo> & {
  // `replace` is a boolean that determines whether the navigation should replace the current history entry or push a new one.
  replace?: boolean
  // `resetScroll` is a boolean that determines whether scroll position will be reset to 0,0 after the location is committed to browser history.
  resetScroll?: boolean
  // `hashScrollIntoView` is a boolean or object that determines whether an id matching the hash will be scrolled into view after the location is committed to history.
  hashScrollIntoView?: boolean | ScrollIntoViewOptions
  // `viewTransition` is either a boolean or function that determines if and how the browser will call document.startViewTransition() when navigating.
  viewTransition?: boolean | ViewTransitionOptions
  // `ignoreBlocker` is a boolean that determines if navigation should ignore any blockers that might prevent it.
  ignoreBlocker?: boolean
  // `reloadDocument` is a boolean that determines if navigation to a route inside of router will trigger a full page load instead of the traditional SPA navigation.
  reloadDocument?: boolean
  // `href` is a string that can be used in place of `to` to navigate to a full built href, e.g. pointing to an external target.
  href?: string
}

LinkOptions 接口

任何实际的 <a> 标签，LinkOptions 接口（扩展自 NavigateOptions）都将可用。

tsx

export type LinkOptions<
  TRouteTree extends AnyRoute = AnyRoute,
  TFrom extends RoutePaths<TRouteTree> | string = string,
  TTo extends string = '',
> = NavigateOptions<TRouteTree, TFrom, TTo> & {
  // The standard anchor tag target attribute
  target?: HTMLAnchorElement['target']
  // Defaults to `{ exact: false, includeHash: false }`
  activeOptions?: {
    exact?: boolean
    includeHash?: boolean
    includeSearch?: boolean
    explicitUndefined?: boolean
  }
  // If set, will preload the linked route on hover and cache it for this many milliseconds in hopes that the user will eventually navigate there.
  preload?: false | 'intent'
  // Delay intent preloading by this many milliseconds. If the intent exits before this delay, the preload will be cancelled.
  preloadDelay?: number
  // If true, will render the link without the href attribute
  disabled?: boolean
}

export type LinkOptions<
  TRouteTree extends AnyRoute = AnyRoute,
  TFrom extends RoutePaths<TRouteTree> | string = string,
  TTo extends string = '',
> = NavigateOptions<TRouteTree, TFrom, TTo> & {
  // The standard anchor tag target attribute
  target?: HTMLAnchorElement['target']
  // Defaults to `{ exact: false, includeHash: false }`
  activeOptions?: {
    exact?: boolean
    includeHash?: boolean
    includeSearch?: boolean
    explicitUndefined?: boolean
  }
  // If set, will preload the linked route on hover and cache it for this many milliseconds in hopes that the user will eventually navigate there.
  preload?: false | 'intent'
  // Delay intent preloading by this many milliseconds. If the intent exits before this delay, the preload will be cancelled.
  preloadDelay?: number
  // If true, will render the link without the href attribute
  disabled?: boolean
}

现在我们已经了解了相对导航和所有接口，让我们来谈谈可用的各种导航 API。

<Link> 组件
- 生成一个实际的 <a> 标签，带有一个有效的 href，可以点击或按住 Cmd/Ctrl 键点击在新标签页中打开。
useNavigate() hook
- 如果可能，应使用 Link 组件进行导航，但有时你需要作为副作用的结果而进行命令式导航。 useNavigate 返回一个可以调用的函数来执行即时的客户端导航。
<Navigate> 组件
- 渲染为空，并执行即时的客户端导航。
Router.navigate() 方法
- 这是 TanStack Router 中最强大的导航 API。与 useNavigate 类似，它进行命令式导航，但可以在你能够访问路由器的地方使用。

⚠️ 这些 API 都不能替代服务器端重定向。如果你需要在应用程序挂载之前立即将用户从一个路由重定向到另一个路由，请使用服务器端重定向而不是客户端导航。

`<Link>` 组件

Link 组件是应用内导航最常见的方式。它渲染一个实际的 <a> 标签，带有一个有效的 href 属性，可以点击或按住 Cmd/Ctrl 键点击在新标签页中打开。它还支持任何普通的 <a> 属性，包括 target 以在新窗口中打开链接等。

除了 LinkOptions 接口之外，Link 组件还支持以下 props：

tsx

export type LinkProps<
  TFrom extends RoutePaths<RegisteredRouter['routeTree']> | string = string,
  TTo extends string = '',
> = LinkOptions<RegisteredRouter['routeTree'], TFrom, TTo> & {
  // A function that returns additional props for the `active` state of this link. These props override other props passed to the link (`style`'s are merged, `className`'s are concatenated)
  activeProps?:
    | FrameworkHTMLAnchorTagAttributes
    | (() => FrameworkHTMLAnchorAttributes)
  // A function that returns additional props for the `inactive` state of this link. These props override other props passed to the link (`style`'s are merged, `className`'s are concatenated)
  inactiveProps?:
    | FrameworkHTMLAnchorAttributes
    | (() => FrameworkHTMLAnchorAttributes)
}

export type LinkProps<
  TFrom extends RoutePaths<RegisteredRouter['routeTree']> | string = string,
  TTo extends string = '',
> = LinkOptions<RegisteredRouter['routeTree'], TFrom, TTo> & {
  // A function that returns additional props for the `active` state of this link. These props override other props passed to the link (`style`'s are merged, `className`'s are concatenated)
  activeProps?:
    | FrameworkHTMLAnchorTagAttributes
    | (() => FrameworkHTMLAnchorAttributes)
  // A function that returns additional props for the `inactive` state of this link. These props override other props passed to the link (`style`'s are merged, `className`'s are concatenated)
  inactiveProps?:
    | FrameworkHTMLAnchorAttributes
    | (() => FrameworkHTMLAnchorAttributes)
}

绝对路径链接

让我们创建一个简单的静态链接！

tsx

import { Link } from '@tanstack/react-router'

const link = <Link to="/about">About</Link>

import { Link } from '@tanstack/react-router'

const link = <Link to="/about">About</Link>

动态链接

动态链接是指其包含动态段的链接。例如，指向博客文章的链接可能如下所示：

tsx

const link = (
  <Link
    to="/blog/post/$postId"
    params={{
      postId: 'my-first-blog-post',
    }}
  >
    Blog Post
  </Link>
)

const link = (
  <Link
    to="/blog/post/$postId"
    params={{
      postId: 'my-first-blog-post',
    }}
  >
    Blog Post
  </Link>
)

请记住，通常情况下，动态段参数是 string 类型的值，但它们也可以是你解析为的其他任何类型。无论如何，类型将在编译时进行检查，以确保你传递了正确的类型。

相对路径链接

默认情况下，所有链接都是绝对路径，除非提供了 from 路由路径。这意味着无论你当前在哪个路由上，上面的链接始终会导航到 /about 路由。

相对路径链接可以与 from 路由路径结合使用。如果未提供 from 路由路径，相对路径将默认为当前活动位置。

tsx

const postIdRoute = createRoute({
  path: '/blog/post/$postId',
})

const link = (
  <Link from={postIdRoute.fullPath} to="../categories">
    Categories
  </Link>
)

const postIdRoute = createRoute({
  path: '/blog/post/$postId',
})

const link = (
  <Link from={postIdRoute.fullPath} to="../categories">
    Categories
  </Link>
)

如上所示，通常将 route.fullPath 作为 from 路由路径提供。这是因为 route.fullPath 是一个引用，如果你重构应用程序，它会更新。然而，有时无法直接导入路由，在这种情况下，直接将路由路径作为字符串提供也是可以的。它仍然会像往常一样进行类型检查！

特殊相对路径："." 和 ".."

很多时候，你可能想重新加载当前位置或其他 from 路径，例如，重新运行当前和/或父路由的加载器，或者导航回父路由。这可以通过指定 to 路由路径为 "." 来实现，这将重新加载当前位置或提供的 from 路径。

另一个常见的需求是相对于当前位置或另一个路径导航回一个路由。通过指定 to 路由路径为 ".."，导航将被解析到当前位置之前的第一个父路由。

tsx

export const Route = createFileRoute('/posts/$postId')({
  component: PostComponent,
})

function PostComponent() {
  return (
    <div>
      <Link to=".">Reload the current route of /posts/$postId</Link>
      <Link to="..">Navigate back to /posts</Link>
      // the below are all equivalent
      <Link to="/posts">Navigate back to /posts</Link>
      <Link from="/posts" to=".">
        Navigate back to /posts
      </Link>
      // the below are all equivalent
      <Link to="/">Navigate to root</Link>
      <Link from="/posts" to="..">
        Navigate to root
      </Link>
    </div>
  )
}

export const Route = createFileRoute('/posts/$postId')({
  component: PostComponent,
})

function PostComponent() {
  return (
    <div>
      <Link to=".">Reload the current route of /posts/$postId</Link>
      <Link to="..">Navigate back to /posts</Link>
      // the below are all equivalent
      <Link to="/posts">Navigate back to /posts</Link>
      <Link from="/posts" to=".">
        Navigate back to /posts
      </Link>
      // the below are all equivalent
      <Link to="/">Navigate to root</Link>
      <Link from="/posts" to="..">
        Navigate to root
      </Link>
    </div>
  )
}

搜索参数链接

搜索参数是为路由提供额外上下文的好方法。例如，你可能想为搜索页面提供搜索查询。

tsx

const link = (
  <Link
    to="/search"
    search={{
      query: 'tanstack',
    }}
  >
    Search
  </Link>
)

const link = (
  <Link
    to="/search"
    search={{
      query: 'tanstack',
    }}
  >
    Search
  </Link>
)

通常，你也可能想更新单个搜索参数，而不提供关于现有路由的任何其他信息。例如，你可能想更新搜索结果的页码。

tsx

const link = (
  <Link
    to="."
    search={(prev) => ({
      ...prev,
      page: prev.page + 1,
    })}
  >
    Next Page
  </Link>
)

const link = (
  <Link
    to="."
    search={(prev) => ({
      ...prev,
      page: prev.page + 1,
    })}
  >
    Next Page
  </Link>
)

搜索参数类型安全

搜索参数是高度动态的状态管理机制，因此确保你为搜索参数传递正确的类型非常重要。我们将在后面的部分详细介绍如何验证和确保搜索参数的类型安全，以及其他很棒的功能！

哈希链接

哈希链接是链接到页面特定部分的绝佳方式。例如，你可能想链接到博客文章的特定部分。

tsx

const link = (
  <Link
    to="/blog/post/$postId"
    params={{
      postId: 'my-first-blog-post',
    }}
    hash="section-1"
  >
    Section 1
  </Link>
)

const link = (
  <Link
    to="/blog/post/$postId"
    params={{
      postId: 'my-first-blog-post',
    }}
    hash="section-1"
  >
    Section 1
  </Link>
)

使用可选参数进行导航

可选路径参数提供了灵活的导航模式，你可以根据需要包含或省略参数。可选参数使用 {-$paramName} 语法，并提供对 URL 结构的精细控制。

参数继承 vs. 删除

使用可选参数进行导航时，有两种主要策略：

继承当前参数 使用 params: {} 来继承所有当前路由参数。

tsx

// Inherits current route parameters
<Link to="/posts/{-$category}" params={{}}>
  All Posts
</Link>

// Inherits current route parameters
<Link to="/posts/{-$category}" params={{}}>
  All Posts
</Link>

删除参数
将参数设置为 undefined 以显式删除它们。

tsx

// Removes the category parameter
<Link to="/posts/{-$category}" params={{ category: undefined }}>
  All Posts
</Link>

// Removes the category parameter
<Link to="/posts/{-$category}" params={{ category: undefined }}>
  All Posts
</Link>

tsx

// Navigate with optional parameter
<Link
  to="/posts/{-$category}"
  params={{ category: 'tech' }}
>
  Tech Posts
</Link>

// Navigate without optional parameter
<Link
  to="/posts/{-$category}"
  params={{ category: undefined }}
>
  All Posts
</Link>

// Navigate using parameter inheritance
<Link
  to="/posts/{-$category}"
  params={{}}
>
  Current Category
</Link>

// Navigate with optional parameter
<Link
  to="/posts/{-$category}"
  params={{ category: 'tech' }}
>
  Tech Posts
</Link>

// Navigate without optional parameter
<Link
  to="/posts/{-$category}"
  params={{ category: undefined }}
>
  All Posts
</Link>

// Navigate using parameter inheritance
<Link
  to="/posts/{-$category}"
  params={{}}
>
  Current Category
</Link>

函数式参数更新

函数式参数更新对于可选参数尤其有用。

tsx

// Remove a parameter using function syntax
<Link
  to="/posts/{-$category}"
  params={(prev) => ({ ...prev, category: undefined })}
>
  Clear Category
</Link>

// Update a parameter while keeping others
<Link
  to="/articles/{-$category}/{-$slug}"
  params={(prev) => ({ ...prev, category: 'news' })}
>
  News Articles
</Link>

// Conditionally set parameters
<Link
  to="/posts/{-$category}"
  params={(prev) => ({
    ...prev,
    category: someCondition ? 'tech' : undefined
  })}
>
  Conditional Category
</Link>

// Remove a parameter using function syntax
<Link
  to="/posts/{-$category}"
  params={(prev) => ({ ...prev, category: undefined })}
>
  Clear Category
</Link>

// Update a parameter while keeping others
<Link
  to="/articles/{-$category}/{-$slug}"
  params={(prev) => ({ ...prev, category: 'news' })}
>
  News Articles
</Link>

// Conditionally set parameters
<Link
  to="/posts/{-$category}"
  params={(prev) => ({
    ...prev,
    category: someCondition ? 'tech' : undefined
  })}
>
  Conditional Category
</Link>

多个可选参数

当处理多个可选参数时，你可以混合搭配包含哪些参数。

tsx

// Navigate with some optional parameters
<Link
  to="/posts/{-$category}/{-$slug}"
  params={{ category: 'tech', slug: undefined }}
>
  Tech Posts
</Link>

// Remove all optional parameters
<Link
  to="/posts/{-$category}/{-$slug}"
  params={{ category: undefined, slug: undefined }}
>
  All Posts
</Link>

// Set multiple parameters
<Link
  to="/posts/{-$category}/{-$slug}"
  params={{ category: 'tech', slug: 'react-tips' }}
>
  Specific Post
</Link>

// Navigate with some optional parameters
<Link
  to="/posts/{-$category}/{-$slug}"
  params={{ category: 'tech', slug: undefined }}
>
  Tech Posts
</Link>

// Remove all optional parameters
<Link
  to="/posts/{-$category}/{-$slug}"
  params={{ category: undefined, slug: undefined }}
>
  All Posts
</Link>

// Set multiple parameters
<Link
  to="/posts/{-$category}/{-$slug}"
  params={{ category: 'tech', slug: 'react-tips' }}
>
  Specific Post
</Link>

混合必需和可选参数

可选参数与必需参数无缝协作。

tsx

// Required 'id', optional 'tab'
<Link
  to="/users/$id/{-$tab}"
  params={{ id: '123', tab: 'settings' }}
>
  User Settings
</Link>

// Remove optional parameter while keeping required
<Link
  to="/users/$id/{-$tab}"
  params={{ id: '123', tab: undefined }}
>
  User Profile
</Link>

// Use function style with mixed parameters
<Link
  to="/users/$id/{-$tab}"
  params={(prev) => ({ ...prev, tab: 'notifications' })}
>
  User Notifications
</Link>

// Required 'id', optional 'tab'
<Link
  to="/users/$id/{-$tab}"
  params={{ id: '123', tab: 'settings' }}
>
  User Settings
</Link>

// Remove optional parameter while keeping required
<Link
  to="/users/$id/{-$tab}"
  params={{ id: '123', tab: undefined }}
>
  User Profile
</Link>

// Use function style with mixed parameters
<Link
  to="/users/$id/{-$tab}"
  params={(prev) => ({ ...prev, tab: 'notifications' })}
>
  User Notifications
</Link>

高级可选参数模式

带前缀和后缀的参数 带前缀/后缀的可选参数与导航配合使用。

tsx

// Navigate to file with optional name
<Link
  to="/files/prefix{-$name}.txt"
  params={{ name: 'document' }}
>
  Document File
</Link>

// Navigate to file without optional name
<Link
  to="/files/prefix{-$name}.txt"
  params={{ name: undefined }}
>
  Default File
</Link>

// Navigate to file with optional name
<Link
  to="/files/prefix{-$name}.txt"
  params={{ name: 'document' }}
>
  Document File
</Link>

// Navigate to file without optional name
<Link
  to="/files/prefix{-$name}.txt"
  params={{ name: undefined }}
>
  Default File
</Link>

所有可选参数 所有参数都是可选的路由。

tsx

// Navigate to specific date
<Link
  to="/{-$year}/{-$month}/{-$day}"
  params={{ year: '2023', month: '12', day: '25' }}
>
  Christmas 2023
</Link>

// Navigate to partial date
<Link
  to="/{-$year}/{-$month}/{-$day}"
  params={{ year: '2023', month: '12', day: undefined }}
>
  December 2023
</Link>

// Navigate to root with all parameters removed
<Link
  to="/{-$year}/{-$month}/{-$day}"
  params={{ year: undefined, month: undefined, day: undefined }}
>
  Home
</Link>

// Navigate to specific date
<Link
  to="/{-$year}/{-$month}/{-$day}"
  params={{ year: '2023', month: '12', day: '25' }}
>
  Christmas 2023
</Link>

// Navigate to partial date
<Link
  to="/{-$year}/{-$month}/{-$day}"
  params={{ year: '2023', month: '12', day: undefined }}
>
  December 2023
</Link>

// Navigate to root with all parameters removed
<Link
  to="/{-$year}/{-$month}/{-$day}"
  params={{ year: undefined, month: undefined, day: undefined }}
>
  Home
</Link>

可选参数与搜索参数结合使用效果很好。

tsx

// Combine optional path params with search params
<Link
  to="/posts/{-$category}"
  params={{ category: 'tech' }}
  search={{ page: 1, sort: 'newest' }}
>
  Tech Posts - Page 1
</Link>

// Remove path param but keep search params
<Link
  to="/posts/{-$category}"
  params={{ category: undefined }}
  search={(prev) => prev}
>
  All Posts - Same Filters
</Link>

// Combine optional path params with search params
<Link
  to="/posts/{-$category}"
  params={{ category: 'tech' }}
  search={{ page: 1, sort: 'newest' }}
>
  Tech Posts - Page 1
</Link>

// Remove path param but keep search params
<Link
  to="/posts/{-$category}"
  params={{ category: undefined }}
  search={(prev) => prev}
>
  All Posts - Same Filters
</Link>

所有相同的模式都适用于命令式导航。

tsx

function Component() {
  const navigate = useNavigate()

  const clearFilters = () => {
    navigate({
      to: '/posts/{-$category}/{-$tag}',
      params: { category: undefined, tag: undefined },
    })
  }

  const setCategory = (category: string) => {
    navigate({
      to: '/posts/{-$category}/{-$tag}',
      params: (prev) => ({ ...prev, category }),
    })
  }

  const applyFilters = (category?: string, tag?: string) => {
    navigate({
      to: '/posts/{-$category}/{-$tag}',
      params: { category, tag },
    })
  }
}

function Component() {
  const navigate = useNavigate()

  const clearFilters = () => {
    navigate({
      to: '/posts/{-$category}/{-$tag}',
      params: { category: undefined, tag: undefined },
    })
  }

  const setCategory = (category: string) => {
    navigate({
      to: '/posts/{-$category}/{-$tag}',
      params: (prev) => ({ ...prev, category }),
    })
  }

  const applyFilters = (category?: string, tag?: string) => {
    navigate({
      to: '/posts/{-$category}/{-$tag}',
      params: { category, tag },
    })
  }
}

`active` & `inactive` 属性

Link 组件支持两个附加 props：activeProps 和 inactiveProps。这些 props 是函数，它们为链接的 active 和 inactive 状态返回额外的 props。在此处传递的除样式和类之外的所有 props 都将覆盖传递给 Link 的原始 props。任何传递的样式或类都会合并在一起。

这是一个例子

tsx

const link = (
  <Link
    to="/blog/post/$postId"
    params={{
      postId: 'my-first-blog-post',
    }}
    activeProps={{
      style: {
        fontWeight: 'bold',
      },
    }}
  >
    Section 1
  </Link>
)

const link = (
  <Link
    to="/blog/post/$postId"
    params={{
      postId: 'my-first-blog-post',
    }}
    activeProps={{
      style: {
        fontWeight: 'bold',
      },
    }}
  >
    Section 1
  </Link>
)

`data-status` 属性

除了 activeProps 和 inactiveProps props 之外，Link 组件还在链接处于活动状态时向渲染的元素添加 data-status 属性。此属性将为 active 或 undefined，具体取决于链接的当前状态。如果你更喜欢使用 data-attributes 来设置链接样式而不是 props，这会很有用。

Active Options

Link 组件带有一个 activeOptions 属性，该属性提供了一些选项来确定链接是否处于活动状态。以下接口描述了这些选项：

tsx

export interface ActiveOptions {
  // If true, the link will be active if the current route matches the `to` route path exactly (no children routes)
  // Defaults to `false`
  exact?: boolean
  // If true, the link will only be active if the current URL hash matches the `hash` prop
  // Defaults to `false`
  includeHash?: boolean // Defaults to false
  // If true, the link will only be active if the current URL search params inclusively match the `search` prop
  // Defaults to `true`
  includeSearch?: boolean
  // This modifies the `includeSearch` behavior.
  // If true,  properties in `search` that are explicitly `undefined` must NOT be present in the current URL search params for the link to be active.
  // defaults to `false`
  explicitUndefined?: boolean
}

export interface ActiveOptions {
  // If true, the link will be active if the current route matches the `to` route path exactly (no children routes)
  // Defaults to `false`
  exact?: boolean
  // If true, the link will only be active if the current URL hash matches the `hash` prop
  // Defaults to `false`
  includeHash?: boolean // Defaults to false
  // If true, the link will only be active if the current URL search params inclusively match the `search` prop
  // Defaults to `true`
  includeSearch?: boolean
  // This modifies the `includeSearch` behavior.
  // If true,  properties in `search` that are explicitly `undefined` must NOT be present in the current URL search params for the link to be active.
  // defaults to `false`
  explicitUndefined?: boolean
}

默认情况下，它将检查生成的**路径名**是否是当前路由的前缀。如果提供了任何搜索参数，它将检查它们是否*包含性地*匹配当前位置中的参数。默认情况下不检查哈希。

例如，如果你在 /blog/post/my-first-blog-post 路由上，以下链接将处于活动状态：

tsx

const link1 = (
  <Link to="/blog/post/$postId" params={{ postId: 'my-first-blog-post' }}>
    Blog Post
  </Link>
)
const link2 = <Link to="/blog/post">Blog Post</Link>
const link3 = <Link to="/blog">Blog Post</Link>

const link1 = (
  <Link to="/blog/post/$postId" params={{ postId: 'my-first-blog-post' }}>
    Blog Post
  </Link>
)
const link2 = <Link to="/blog/post">Blog Post</Link>
const link3 = <Link to="/blog">Blog Post</Link>

但是，以下链接将不处于活动状态：

tsx

const link4 = (
  <Link to="/blog/post/$postId" params={{ postId: 'my-second-blog-post' }}>
    Blog Post
  </Link>
)

const link4 = (
  <Link to="/blog/post/$postId" params={{ postId: 'my-second-blog-post' }}>
    Blog Post
  </Link>
)

对于某些链接，它们只在精确匹配时才处于活动状态是很常见的。一个很好的例子是链接到主页。在这些情况下，你可以传递 exact: true 选项。

tsx

const link = (
  <Link to="/" activeOptions={{ exact: true }}>
    Home
  </Link>
)

const link = (
  <Link to="/" activeOptions={{ exact: true }}>
    Home
  </Link>
)

这将确保当你处于子路由时，该链接不处于活动状态。

还有一些其他选项需要注意。

如果你想在匹配中包含哈希，你可以传递 includeHash: true 选项。
如果你*不想*在匹配中包含搜索参数，你可以传递 includeSearch: false 选项。

将 isActive 传递给子组件

Link 组件接受一个函数作为其子组件，允许你将 isActive 属性传播给子组件。例如，你可以根据父链接是否处于活动状态来设置子组件的样式。

tsx

const link = (
  <Link to="/blog/post">
    {({ isActive }) => {
      return (
        <>
          <span>My Blog Post</span>
          <icon className={isActive ? 'active' : 'inactive'} />
        </>
      )
    }}
  </Link>
)

const link = (
  <Link to="/blog/post">
    {({ isActive }) => {
      return (
        <>
          <span>My Blog Post</span>
          <icon className={isActive ? 'active' : 'inactive'} />
        </>
      )
    }}
  </Link>
)

链接预加载

Link 组件支持在用户意图（目前是悬停或 touchstart）时自动预加载路由。这可以在路由器的选项中配置（我们稍后会详细介绍），或者通过将 preload='intent' prop 传递给 Link 组件来实现。这是一个例子：

tsx

const link = (
  <Link to="/blog/post/$postId" preload="intent">
    Blog Post
  </Link>
)

const link = (
  <Link to="/blog/post/$postId" preload="intent">
    Blog Post
  </Link>
)

通过启用预加载和相对快速的异步路由依赖项（如果有），这个简单的技巧可以以很小的努力提高你的应用程序的感知性能。

更棒的是，通过使用像 @tanstack/query 这样的缓存优先库，预加载的路由将得以保留，并在用户决定稍后导航到该路由时准备好进行 stale-while-revalidate 体验。

链接预加载延迟

除了预加载，还有一个可配置的延迟，它决定了用户必须将鼠标悬停在链接上多长时间才能触发基于意图的预加载。默认延迟为 50 毫秒，但你可以通过将 preloadDelay prop 传递给 Link 组件并指定你希望等待的毫秒数来更改它。

tsx

const link = (
  <Link to="/blog/post/$postId" preload="intent" preloadDelay={100}>
    Blog Post
  </Link>
)

const link = (
  <Link to="/blog/post/$postId" preload="intent" preloadDelay={100}>
    Blog Post
  </Link>
)

useNavigate

⚠️ 由于 Link 组件内置的 href、Cmd/Ctrl + 点击能力以及活动/非活动能力，因此建议使用 Link 组件而不是 useNavigate 来处理用户可以交互的任何内容（例如，链接、按钮）。但是，在某些情况下，useNavigate 对于处理副作用导航（例如，成功的异步操作导致导航）是必要的。

useNavigate hook 返回一个 navigate 函数，该函数可以被调用以命令式地进行导航。这是从副作用（例如，成功的异步操作）导航到路由的好方法。这是一个例子：

tsx

function Component() {
  const navigate = useNavigate({ from: '/posts/$postId' })

  const handleSubmit = async (e: FrameworkFormEvent) => {
    e.preventDefault()

    const response = await fetch('/posts', {
      method: 'POST',
      body: JSON.stringify({ title: 'My First Post' }),
    })

    const { id: postId } = await response.json()

    if (response.ok) {
      navigate({ to: '/posts/$postId', params: { postId } })
    }
  }
}

function Component() {
  const navigate = useNavigate({ from: '/posts/$postId' })

  const handleSubmit = async (e: FrameworkFormEvent) => {
    e.preventDefault()

    const response = await fetch('/posts', {
      method: 'POST',
      body: JSON.stringify({ title: 'My First Post' }),
    })

    const { id: postId } = await response.json()

    if (response.ok) {
      navigate({ to: '/posts/$postId', params: { postId } })
    }
  }
}

🧠 如上所示，你可以传递 from 选项来指定在 hook 调用中导航的源路由。虽然每次调用 navigate 函数时也可以传递它，但建议在此处传递，以减少潜在的错误，并且打字也少！

navigate Options

useNavigate 返回的 navigate 函数接受 NavigateOptions 接口。

Navigate Component

有时，你可能需要在组件挂载时立即导航。你的第一反应可能是使用 useNavigate 和即时副作用（例如，useEffect），但这没有必要。相反，你可以渲染 Navigate 组件来实现相同的结果。

tsx

function Component() {
  return <Navigate to="/posts/$postId" params={{ postId: 'my-first-post' }} />
}

function Component() {
  return <Navigate to="/posts/$postId" params={{ postId: 'my-first-post' }} />
}

将 Navigate 组件视为在组件挂载时立即导航到某个路由的方法。它是处理仅客户端重定向的好方法。它*绝对不是*用于在服务器上负责任地处理服务器感知重定向的替代品。

router.navigate

router.navigate 方法与 useNavigate 返回的 navigate 函数相同，并接受相同的 NavigateOptions 接口。与 useNavigate hook 不同，它可以在你的 router 实例可用的任何地方使用，因此它是从应用程序的任何地方（包括框架外部）进行命令式导航的好方法。

useMatchRoute 和 <MatchRoute>

useMatchRoute hook 和 <MatchRoute> 组件是同一件事，但 hook 更灵活一些。它们都接受标准的导航 ToOptions 接口（作为选项或 props），并返回 true/false（如果该路由当前匹配）。它还有一个方便的 pending 选项，当路由正在进行中（例如，路由正在向该路由过渡）时，它将返回 true。这对于显示用户导航的乐观 UI 非常有用。

tsx

function Component() {
  return (
    <div>
      <Link to="/users">
        Users
        <MatchRoute to="/users" pending>
          <Spinner />
        </MatchRoute>
      </Link>
    </div>
  )
}

function Component() {
  return (
    <div>
      <Link to="/users">
        Users
        <MatchRoute to="/users" pending>
          <Spinner />
        </MatchRoute>
      </Link>
    </div>
  )
}

组件版本 <MatchRoute> 也可以使用函数作为子组件来渲染路由匹配时的内容。

tsx

function Component() {
  return (
    <div>
      <Link to="/users">
        Users
        <MatchRoute to="/users" pending>
          {(match) => {
            return <Spinner show={match} />
          }}
        </MatchRoute>
      </Link>
    </div>
  )
}

function Component() {
  return (
    <div>
      <Link to="/users">
        Users
        <MatchRoute to="/users" pending>
          {(match) => {
            return <Spinner show={match} />
          }}
        </MatchRoute>
      </Link>
    </div>
  )
}

hook 版本 useMatchRoute 返回一个函数，该函数可以被编程调用以检查路由是否匹配。

tsx

function Component() {
  const matchRoute = useMatchRoute()

  useEffect(() => {
    if (matchRoute({ to: '/users', pending: true })) {
      console.info('The /users route is matched and pending')
    }
  })

  return (
    <div>
      <Link to="/users">Users</Link>
    </div>
  )
}

function Component() {
  const matchRoute = useMatchRoute()

  useEffect(() => {
    if (matchRoute({ to: '/users', pending: true })) {
      console.info('The /users route is matched and pending')
    }
  })

  return (
    <div>
      <Link to="/users">Users</Link>
    </div>
  )
}

呼！导航的东西可真多！不过，希望你现在对如何在应用程序中导航感觉良好。让我们继续吧！

导航

一切皆相对

共享导航 API

ToOptions 接口

NavigateOptions 接口

LinkOptions 接口

导航 API

`<Link>` 组件

绝对路径链接

动态链接

相对路径链接

特殊相对路径："." 和 ".."

搜索参数链接

搜索参数类型安全

哈希链接

使用可选参数进行导航

参数继承 vs. 删除

基本可选参数导航

函数式参数更新

多个可选参数

混合必需和可选参数

高级可选参数模式

带搜索参数和可选参数的导航

带可选参数的命令式导航

`active` & `inactive` 属性

`data-status` 属性

Active Options

将 isActive 传递给子组件

链接预加载

链接预加载延迟

useNavigate

navigate Options

Navigate Component

router.navigate

useMatchRoute 和 <MatchRoute>

订阅 Bytes

订阅 Bytes

导航

一切皆相对

共享导航 API

ToOptions 接口

NavigateOptions 接口

LinkOptions 接口

导航 API

<Link> 组件

绝对路径链接

动态链接

相对路径链接

特殊相对路径："." 和 ".."

搜索参数链接

搜索参数类型安全

哈希链接

使用可选参数进行导航

参数继承 vs. 删除

基本可选参数导航

函数式参数更新

多个可选参数

混合必需和可选参数

高级可选参数模式

带搜索参数和可选参数的导航

带可选参数的命令式导航

active & inactive 属性

data-status 属性

Active Options

将 isActive 传递给子组件

链接预加载

链接预加载延迟

useNavigate

navigate Options

Navigate Component

router.navigate

useMatchRoute 和 <MatchRoute>

订阅 Bytes

订阅 Bytes

`<Link>` 组件

`active` & `inactive` 属性

`data-status` 属性