导航 | TanStack Router Solid 文档

一切皆相对

信不信由你，应用中的每一次导航都是相对的，即使你没有使用显式的相对路径语法（../../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 组件还支持以下属性：

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/solid-router'

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

import { Link } from '@tanstack/solid-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 结构的精细控制。

参数继承与移除

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

继承当前参数 使用 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 组件支持两个额外的属性：activeProps 和 inactiveProps。这些属性是函数，它们返回链接处于 active（活跃）和 inactive（不活跃）状态时的附加属性。这里传递的除样式和类之外的所有属性都将覆盖传递给 Link 的原始属性。任何传递的样式或类都会合并。

这是一个例子

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 属性之外，当 Link 组件处于活跃状态时，它还会向渲染的元素添加一个 data-status 属性。根据链接的当前状态，此属性将为 active 或 undefined。如果你更喜欢使用 data-attributes 来设置链接的样式而不是属性，这会很有用。

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）时预加载路由。这可以在路由器的选项中配置（稍后会详细介绍），或者通过向 Link 组件传递 preload='intent' 属性来配置。这是一个例子：

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 毫秒，但你可以通过向 Link 组件传递 preloadDelay 属性来设置你希望等待的毫秒数。

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 组件

偶尔，你可能会发现需要在组件挂载时立即导航。你的第一反应可能是使用 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 接口（作为选项或属性），并返回 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>` 组件

绝对路径链接

动态链接

相对路径链接

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

搜索参数链接

搜索参数类型安全

哈希链接

使用可选参数进行导航

参数继承与移除

基本可选参数导航

函数式参数更新

多个可选参数

混合必需和可选参数

高级可选参数模式

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

带有可选参数的命令式导航

`active & inactive` 属性

`data-status` 属性

Active Options（活跃选项）

将 isActive 传递给子组件

链接预加载

链接预加载延迟

useNavigate

navigate Options（导航选项）

Navigate 组件

router.navigate

useMatchRoute 和 <MatchRoute>

订阅 Bytes

订阅 Bytes

导航

一切皆相对

共享导航 API

ToOptions 接口

NavigateOptions 接口

LinkOptions 接口

导航 API

<Link> 组件

绝对路径链接

动态链接

相对路径链接

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

搜索参数链接

搜索参数类型安全

哈希链接

使用可选参数进行导航

参数继承与移除

基本可选参数导航

函数式参数更新

多个可选参数

混合必需和可选参数

高级可选参数模式

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

带有可选参数的命令式导航

active & inactive 属性

data-status 属性

Active Options（活跃选项）

将 isActive 传递给子组件

链接预加载

链接预加载延迟

useNavigate

navigate Options（导航选项）

Navigate 组件

router.navigate

useMatchRoute 和 <MatchRoute>

订阅 Bytes

订阅 Bytes

`<Link>` 组件

`active & inactive` 属性

`data-status` 属性