TanStack
Router v1
自动
框架
版本
菜单
入门
路由
指南
API
ESLint
路由器示例

搜索参数

正如 TanStack Query 能够轻松处理 React 和 Solid 应用程序中的服务器状态一样，TanStack Router 旨在释放您应用程序中 URL 搜索参数的功能。

🧠 如果您使用的是非常旧的浏览器，例如 IE11，您可能需要为 URLSearchParams 使用 polyfill。

为什么不直接使用 URLSearchParams？

我们明白，您最近听到了很多关于“使用平台”的说法，而且在大多数情况下，我们都同意。然而，我们也认为认识到平台在更高级用例中的不足之处很重要，我们认为 URLSearchParams 就是其中之一。

传统的搜索参数 API 通常假定以下几点

  • 搜索参数始终是字符串
  • 它们主要是扁平的
  • 使用 URLSearchParams 进行序列化和反序列化已经足够好（剧透：事实并非如此。）
  • 搜索参数的修改与 URL 的路径名紧密耦合，并且必须一起更新，即使路径名没有改变。

但现实情况与这些假设大相径庭。

  • 搜索参数代表应用程序状态，因此不可避免地，我们将期望它们具有与其他状态管理器相同的 DX。这意味着能够区分原始值类型，并高效地存储和操作复杂数据结构，如嵌套数组和对象。
  • 有许多方法可以对状态进行序列化和反序列化，每种方法都有不同的权衡。您应该能够为您的应用程序选择最佳的方法，或者至少获得比 URLSearchParams 更好的默认值。
  • 不变性 & 结构共享。每次对 URL 搜索参数进行字符串化和解析时，引用完整性和对象标识都会丢失，因为每次新的解析都会创建一个具有唯一内存引用的全新数据结构。如果其生命周期管理不当，这种持续的序列化和解析可能会导致意外且不良的性能问题，尤其是在 React 等通过不变性跟踪响应性的框架中，或者在 Solid 中，Solid 通常依赖于协调来检测来自反序列化数据源的更改。
  • 搜索参数虽然是 URL 的重要组成部分，但经常独立于 URL 的路径名而改变。例如，用户可能希望更改分页列表的页码，而无需修改 URL 的路径名。

搜索参数，“OG” 状态管理器

您可能在 URL 中看到过类似 ?page=3 或 ?filter-name=tanner 的搜索参数。毫无疑问，这确实是存在于 URL 中的一种全局状态。将特定状态存储在 URL 中很有价值，因为

  • 用户应该能够
    • 按 Cmd/Ctrl + Click 在新标签页中打开链接，并可靠地看到期望的状态
    • 书签并与他人分享您的应用程序的链接，并保证他们将看到与复制链接时完全相同的状态。
    • 刷新您的应用程序或在页面之间来回导航而不会丢失其状态
  • 开发人员应该能够轻松地
    • 以与其他状态管理器相同的出色 DX 添加、删除或修改 URL 中的状态
    • 轻松验证来自 URL 的搜索参数，使其格式和类型对您的应用程序来说是安全的
    • 读取和写入搜索参数，而不必担心底层的序列化格式

基于 JSON 的搜索参数

为了实现上述目标，TanStack Router 内置的第一步是一个强大的搜索参数解析器，它会自动将 URL 的搜索字符串转换为结构化的 JSON。这意味着您可以将任何可 JSON 序列化的数据结构存储在搜索参数中，它将被解析和序列化为 JSON。与 URLSearchParams 相比，这是一个巨大的改进，因为后者对类数组结构和嵌套数据支持有限。

例如，导航到以下路由

tsx
const link = (
  <Link
    to="/shop"
    search={{
      pageIndex: 3,
      includeCategories: ['electronics', 'gifts'],
      sortBy: 'price',
      desc: true,
    }}
  />
)

const link = (
  <Link
    to="/shop"
    search={{
      pageIndex: 3,
      includeCategories: ['electronics', 'gifts'],
      sortBy: 'price',
      desc: true,
    }}
  />
)

将产生以下 URL

/shop?pageIndex=3&includeCategories=%5B%22electronics%22%2C%22gifts%22%5D&sortBy=price&desc=true

/shop?pageIndex=3&includeCategories=%5B%22electronics%22%2C%22gifts%22%5D&sortBy=price&desc=true

当解析此 URL 时，搜索参数将被准确地转换回以下 JSON

json
{
  "pageIndex": 3,
  "includeCategories": ["electronics", "gifts"],
  "sortBy": "price",
  "desc": true
}

{
  "pageIndex": 3,
  "includeCategories": ["electronics", "gifts"],
  "sortBy": "price",
  "desc": true
}

如果您注意到，这里有几件事在发生

  • 搜索参数的第一层是扁平的、基于字符串的，就像 URLSearchParams 一样。
  • 不是字符串的第一层值被准确地保留为实际的数字和布尔值。
  • 嵌套数据结构会自动转换为 URL 安全的 JSON 字符串

🧠 其他工具通常假定搜索参数始终是扁平的、基于字符串的，这就是为什么我们选择在第一层保持与 URLSearchParam 的兼容性。这最终意味着，尽管 TanStack Router 将您的嵌套搜索参数管理为 JSON，但其他工具仍然可以正常写入 URL 和读取第一层参数。

验证和类型化搜索参数

尽管 TanStack Router 能够将搜索参数解析为可靠的 JSON，但它们最终仍然来自用户可见的原始文本输入。与其他序列化边界类似，这意味着在您使用搜索参数之前，它们应该被验证为您的应用程序可以信任和依赖的格式。

输入验证 + TypeScript！

TanStack Router 提供了便捷的 API 来验证和类型化搜索参数。这一切都始于 Route 的 validateSearch 选项

tsx
// /routes/shop.products.tsx

type ProductSearchSortOptions = 'newest' | 'oldest' | 'price'

type ProductSearch = {
  page: number
  filter: string
  sort: ProductSearchSortOptions
}

export const Route = createFileRoute('/shop/products')({
  validateSearch: (search: Record<string, unknown>): ProductSearch => {
    // validate and parse the search params into a typed state
    return {
      page: Number(search?.page ?? 1),
      filter: (search.filter as string) || '',
      sort: (search.sort as ProductSearchSortOptions) || 'newest',
    }
  },
})

// /routes/shop.products.tsx

type ProductSearchSortOptions = 'newest' | 'oldest' | 'price'

type ProductSearch = {
  page: number
  filter: string
  sort: ProductSearchSortOptions
}

export const Route = createFileRoute('/shop/products')({
  validateSearch: (search: Record<string, unknown>): ProductSearch => {
    // validate and parse the search params into a typed state
    return {
      page: Number(search?.page ?? 1),
      filter: (search.filter as string) || '',
      sort: (search.sort as ProductSearchSortOptions) || 'newest',
    }
  },
})

在上面的示例中，我们正在验证 Route 的搜索参数，并返回一个类型化的 ProductSearch 对象。然后，此类型化对象可用于此路由的其他选项以及任何子路由！

验证搜索参数

validateSearch 选项是一个函数，它接收 JSON 解析（但未验证）的搜索参数作为 Record<string, unknown>，并返回您选择的类型化对象。通常最好为格式错误或意外的搜索参数提供合理的默认值，以确保用户的体验不会中断。

这是一个例子

tsx
// /routes/shop.products.tsx

type ProductSearchSortOptions = 'newest' | 'oldest' | 'price'

type ProductSearch = {
  page: number
  filter: string
  sort: ProductSearchSortOptions
}

export const Route = createFileRoute('/shop/products')({
  validateSearch: (search: Record<string, unknown>): ProductSearch => {
    // validate and parse the search params into a typed state
    return {
      page: Number(search?.page ?? 1),
      filter: (search.filter as string) || '',
      sort: (search.sort as ProductSearchSortOptions) || 'newest',
    }
  },
})

// /routes/shop.products.tsx

type ProductSearchSortOptions = 'newest' | 'oldest' | 'price'

type ProductSearch = {
  page: number
  filter: string
  sort: ProductSearchSortOptions
}

export const Route = createFileRoute('/shop/products')({
  validateSearch: (search: Record<string, unknown>): ProductSearch => {
    // validate and parse the search params into a typed state
    return {
      page: Number(search?.page ?? 1),
      filter: (search.filter as string) || '',
      sort: (search.sort as ProductSearchSortOptions) || 'newest',
    }
  },
})

这是一个使用 Zod 库（但您可以随时使用任何验证库）的示例，用于在一步中同时验证和类型化搜索参数

tsx
// /routes/shop.products.tsx

import { z } from 'zod'

const productSearchSchema = z.object({
  page: z.number().catch(1),
  filter: z.string().catch(''),
  sort: z.enum(['newest', 'oldest', 'price']).catch('newest'),
})

type ProductSearch = z.infer<typeof productSearchSchema>

export const Route = createFileRoute('/shop/products')({
  validateSearch: (search) => productSearchSchema.parse(search),
})

// /routes/shop.products.tsx

import { z } from 'zod'

const productSearchSchema = z.object({
  page: z.number().catch(1),
  filter: z.string().catch(''),
  sort: z.enum(['newest', 'oldest', 'price']).catch('newest'),
})

type ProductSearch = z.infer<typeof productSearchSchema>

export const Route = createFileRoute('/shop/products')({
  validateSearch: (search) => productSearchSchema.parse(search),
})

因为 validateSearch 也接受一个带有 parse 属性的对象，所以可以将其缩写为

tsx
validateSearch: productSearchSchema

validateSearch: productSearchSchema

在上面的示例中，我们使用了 Zod 的 .catch() 修饰符而不是 .default() 来避免向用户显示错误，因为我们坚信如果搜索参数格式错误，您可能不希望通过应用程序中断用户的体验来显示一个大大的错误消息。不过，有时您确实希望显示错误消息。在这种情况下，您可以使用 .default() 而不是 .catch()。

这能奏效的底层机制依赖于 validateSearch 函数抛出错误。如果抛出错误，路由的 onError 选项将被触发（并且 error.routerCode 将被设置为 VALIDATE_SEARCH），并且 errorComponent 将被渲染而不是路由的 component，您可以在那里按需处理搜索参数错误。

适配器

当使用 Zod 等库验证搜索参数时，您可能希望在将搜索参数提交到 URL 之前 transform 搜索参数。一个常见的 zod transform 是 default，例如。

tsx
import { createFileRoute } from '@tanstack/solid-router'
import { z } from 'zod'

const productSearchSchema = z.object({
  page: z.number().default(1),
  filter: z.string().default(''),
  sort: z.enum(['newest', 'oldest', 'price']).default('newest'),
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: productSearchSchema,
})

import { createFileRoute } from '@tanstack/solid-router'
import { z } from 'zod'

const productSearchSchema = z.object({
  page: z.number().default(1),
  filter: z.string().default(''),
  sort: z.enum(['newest', 'oldest', 'price']).default('newest'),
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: productSearchSchema,
})

当您尝试导航到此路由时，search 是必需的，这可能会令人惊讶。下面的 Link 会出现类型错误，因为 search 丢失了。

tsx
<Link to="/shop/products" />

<Link to="/shop/products" />

对于验证库，我们建议使用适配器，它们会推断正确的 input 和 output 类型。

Zod

为 Zod 提供了一个适配器，它将正确传递 input 类型和 output 类型

tsx
import { createFileRoute } from '@tanstack/solid-router'
import { zodValidator } from '@tanstack/zod-adapter'
import { z } from 'zod'

const productSearchSchema = z.object({
  page: z.number().default(1),
  filter: z.string().default(''),
  sort: z.enum(['newest', 'oldest', 'price']).default('newest'),
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: zodValidator(productSearchSchema),
})

import { createFileRoute } from '@tanstack/solid-router'
import { zodValidator } from '@tanstack/zod-adapter'
import { z } from 'zod'

const productSearchSchema = z.object({
  page: z.number().default(1),
  filter: z.string().default(''),
  sort: z.enum(['newest', 'oldest', 'price']).default('newest'),
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: zodValidator(productSearchSchema),
})

这里重要的是，下面的 Link 使用不再需要 search 参数

tsx
<Link to="/shop/products" />

<Link to="/shop/products" />

然而，这里使用 catch 会覆盖类型，并使 page、filter 和 sort unknown，导致类型丢失。我们通过提供一个 fallback 泛型函数来处理这种情况，该函数在验证失败时保留类型但提供一个 fallback 值。

tsx
import { createFileRoute } from '@tanstack/solid-router'
import { fallback, zodValidator } from '@tanstack/zod-adapter'
import { z } from 'zod'

const productSearchSchema = z.object({
  page: fallback(z.number(), 1).default(1),
  filter: fallback(z.string(), '').default(''),
  sort: fallback(z.enum(['newest', 'oldest', 'price']), 'newest').default(
    'newest',
  ),
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: zodValidator(productSearchSchema),
})

import { createFileRoute } from '@tanstack/solid-router'
import { fallback, zodValidator } from '@tanstack/zod-adapter'
import { z } from 'zod'

const productSearchSchema = z.object({
  page: fallback(z.number(), 1).default(1),
  filter: fallback(z.string(), '').default(''),
  sort: fallback(z.enum(['newest', 'oldest', 'price']), 'newest').default(
    'newest',
  ),
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: zodValidator(productSearchSchema),
})

因此，当导航到此路由时，search 是可选的，并保留了正确的类型。

虽然不推荐，但也可以配置 input 和 output 类型，以防 output 类型比 input 类型更准确。

tsx
const productSearchSchema = z.object({
  page: fallback(z.number(), 1).default(1),
  filter: fallback(z.string(), '').default(''),
  sort: fallback(z.enum(['newest', 'oldest', 'price']), 'newest').default(
    'newest',
  ),
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: zodValidator({
    schema: productSearchSchema,
    input: 'output',
    output: 'input',
  }),
})

const productSearchSchema = z.object({
  page: fallback(z.number(), 1).default(1),
  filter: fallback(z.string(), '').default(''),
  sort: fallback(z.enum(['newest', 'oldest', 'price']), 'newest').default(
    'newest',
  ),
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: zodValidator({
    schema: productSearchSchema,
    input: 'output',
    output: 'input',
  }),
})

这提供了在导航和读取搜索参数时想要推断的类型的灵活性。

Valibot

警告

Router 期望已安装 valibot 1.0 包。

当使用 Valibot 时，不需要适配器来确保为导航和读取搜索参数使用正确的 input 和 output 类型。这是因为 valibot 实现 Standard Schema

tsx
import { createFileRoute } from '@tanstack/solid-router'
import * as v from 'valibot'

const productSearchSchema = v.object({
  page: v.optional(v.fallback(v.number(), 1), 1),
  filter: v.optional(v.fallback(v.string(), ''), ''),
  sort: v.optional(
    v.fallback(v.picklist(['newest', 'oldest', 'price']), 'newest'),
    'newest',
  ),
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: productSearchSchema,
})

import { createFileRoute } from '@tanstack/solid-router'
import * as v from 'valibot'

const productSearchSchema = v.object({
  page: v.optional(v.fallback(v.number(), 1), 1),
  filter: v.optional(v.fallback(v.string(), ''), ''),
  sort: v.optional(
    v.fallback(v.picklist(['newest', 'oldest', 'price']), 'newest'),
    'newest',
  ),
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: productSearchSchema,
})

Arktype

警告

Router 期望已安装 arktype 2.0-rc 包。

当使用 ArkType 时，不需要适配器来确保为导航和读取搜索参数使用正确的 input 和 output 类型。这是因为 ArkType 实现 Standard Schema

tsx
import { createFileRoute } from '@tanstack/solid-router'
import { type } from 'arktype'

const productSearchSchema = type({
  page: 'number = 1',
  filter: 'string = ""',
  sort: '"newest" | "oldest" | "price" = "newest"',
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: productSearchSchema,
})

import { createFileRoute } from '@tanstack/solid-router'
import { type } from 'arktype'

const productSearchSchema = type({
  page: 'number = 1',
  filter: 'string = ""',
  sort: '"newest" | "oldest" | "price" = "newest"',
})

export const Route = createFileRoute('/shop/products/')({
  validateSearch: productSearchSchema,
})

Effect/Schema

当使用 Effect/Schema 时，不需要适配器来确保为导航和读取搜索参数使用正确的 input 和 output 类型。这是因为 Effect/Schema 实现 Standard Schema

tsx
import { createFileRoute } from '@tanstack/solid-router'
import { Schema as S } from 'effect'

const productSearchSchema = S.standardSchemaV1(
  S.Struct({
    page: S.NumberFromString.pipe(
      S.optional,
      S.withDefaults({
        constructor: () => 1,
        decoding: () => 1,
      }),
    ),
    filter: S.String.pipe(
      S.optional,
      S.withDefaults({
        constructor: () => '',
        decoding: () => '',
      }),
    ),
    sort: S.Literal('newest', 'oldest', 'price').pipe(
      S.optional,
      S.withDefaults({
        constructor: () => 'newest' as const,
        decoding: () => 'newest' as const,
      }),
    ),
  }),
)

export const Route = createFileRoute('/shop/products/')({
  validateSearch: productSearchSchema,
})

import { createFileRoute } from '@tanstack/solid-router'
import { Schema as S } from 'effect'

const productSearchSchema = S.standardSchemaV1(
  S.Struct({
    page: S.NumberFromString.pipe(
      S.optional,
      S.withDefaults({
        constructor: () => 1,
        decoding: () => 1,
      }),
    ),
    filter: S.String.pipe(
      S.optional,
      S.withDefaults({
        constructor: () => '',
        decoding: () => '',
      }),
    ),
    sort: S.Literal('newest', 'oldest', 'price').pipe(
      S.optional,
      S.withDefaults({
        constructor: () => 'newest' as const,
        decoding: () => 'newest' as const,
      }),
    ),
  }),
)

export const Route = createFileRoute('/shop/products/')({
  validateSearch: productSearchSchema,
})

读取搜索参数

一旦您的搜索参数被验证和类型化，您就可以开始读取和写入它们了。在 TanStack Router 中有几种方法可以做到这一点，让我们来看看它们。

在加载器中使用搜索参数

请阅读 加载器中的搜索参数 部分，了解更多关于如何使用 loaderDeps 选项在加载器中读取搜索参数的信息。

搜索参数从父路由继承

父级的搜索参数和类型会随着您在路由树中向下移动而合并，因此子路由也可以访问其父级的搜索参数。

  • shop.products.tsx
tsx
const productSearchSchema = z.object({
  page: z.number().catch(1),
  filter: z.string().catch(''),
  sort: z.enum(['newest', 'oldest', 'price']).catch('newest'),
})

type ProductSearch = z.infer<typeof productSearchSchema>

export const Route = createFileRoute('/shop/products')({
  validateSearch: productSearchSchema,
})

const productSearchSchema = z.object({
  page: z.number().catch(1),
  filter: z.string().catch(''),
  sort: z.enum(['newest', 'oldest', 'price']).catch('newest'),
})

type ProductSearch = z.infer<typeof productSearchSchema>

export const Route = createFileRoute('/shop/products')({
  validateSearch: productSearchSchema,
})
  • shop.products.$productId.tsx
tsx
export const Route = createFileRoute('/shop/products/$productId')({
  beforeLoad: ({ search }) => {
    search
    // ^? ProductSearch ✅
  },
})

export const Route = createFileRoute('/shop/products/$productId')({
  beforeLoad: ({ search }) => {
    search
    // ^? ProductSearch ✅
  },
})

组件中的搜索参数

您可以通过 useSearch hook 在路由的 component 中访问路由的已验证搜索参数。

tsx
// /routes/shop.products.tsx

export const Route = createFileRoute('/shop/products')({
  validateSearch: productSearchSchema,
})

const ProductList = () => {
  const { page, filter, sort } = Route.useSearch()

  return <div>...</div>
}

// /routes/shop.products.tsx

export const Route = createFileRoute('/shop/products')({
  validateSearch: productSearchSchema,
})

const ProductList = () => {
  const { page, filter, sort } = Route.useSearch()

  return <div>...</div>
}

提示

如果您的组件是代码拆分，您可以使用 getRouteApi 函数 来避免导入 Route 配置以访问类型化的 useSearch() hook。

路由组件之外的搜索参数

您可以使用 useSearch hook 在应用程序中的任何位置访问路由的已验证搜索参数。通过传递源路由的 from ID/路径，您将获得更好的类型安全性。

tsx
// /routes/shop.products.tsx
export const Route = createFileRoute('/shop/products')({
  validateSearch: productSearchSchema,
  // ...
})

// Somewhere else...

// /components/product-list-sidebar.tsx
const routeApi = getRouteApi('/shop/products')

const ProductList = () => {
  const routeSearch = routeApi.useSearch()

  // OR

  const { page, filter, sort } = useSearch({
    from: Route.fullPath,
  })

  return <div>...</div>
}

// /routes/shop.products.tsx
export const Route = createFileRoute('/shop/products')({
  validateSearch: productSearchSchema,
  // ...
})

// Somewhere else...

// /components/product-list-sidebar.tsx
const routeApi = getRouteApi('/shop/products')

const ProductList = () => {
  const routeSearch = routeApi.useSearch()

  // OR

  const { page, filter, sort } = useSearch({
    from: Route.fullPath,
  })

  return <div>...</div>
}

或者，您可以放宽类型安全性，通过传递 strict: false 来获得可选的 search 对象。

tsx
function ProductList() {
  const search = useSearch({
    strict: false,
  })
  // {
  //   page: number | undefined
  //   filter: string | undefined
  //   sort: 'newest' | 'oldest' | 'price' | undefined
  // }

  return <div>...</div>
}

function ProductList() {
  const search = useSearch({
    strict: false,
  })
  // {
  //   page: number | undefined
  //   filter: string | undefined
  //   sort: 'newest' | 'oldest' | 'price' | undefined
  // }

  return <div>...</div>
}

写入搜索参数

既然您已经学会了如何读取路由的搜索参数，您会很高兴地知道您已经看到了修改和更新它们的主要 API。让我们回顾一下。

<Link search />

更新搜索参数的最佳方法是使用 <Link /> 组件上的 search 属性。

如果当前页面的搜索参数需要更新并且指定了 from 属性，则可以省略 to 属性。
这是一个例子

tsx
// /routes/shop.products.tsx
export const Route = createFileRoute('/shop/products')({
  validateSearch: productSearchSchema,
})

const ProductList = () => {
  return (
    <div>
      <Link from={Route.fullPath} search={(prev) => ({ page: prev.page + 1 })}>
        Next Page
      </Link>
    </div>
  )
}

// /routes/shop.products.tsx
export const Route = createFileRoute('/shop/products')({
  validateSearch: productSearchSchema,
})

const ProductList = () => {
  return (
    <div>
      <Link from={Route.fullPath} search={(prev) => ({ page: prev.page + 1 })}>
        Next Page
      </Link>
    </div>
  )
}

如果您想在渲染在多个路由上的通用组件中更新搜索参数，指定 from 可能会很困难。

在这种情况下，您可以设置 to="."，这将为您提供对松散类型化搜索参数的访问。
下面是一个说明此点的示例

tsx
// `page` is a search param that is defined in the __root route and hence available on all routes.
const PageSelector = () => {
  return (
    <div>
      <Link to="." search={(prev) => ({ ...prev, page: prev.page + 1 })}>
        Next Page
      </Link>
    </div>
  )
}

// `page` is a search param that is defined in the __root route and hence available on all routes.
const PageSelector = () => {
  return (
    <div>
      <Link to="." search={(prev) => ({ ...prev, page: prev.page + 1 })}>
        Next Page
      </Link>
    </div>
  )
}

如果通用组件仅在路由树的特定子树中渲染，您可以使用 from 来指定该子树。这里您可以省略 to='.'，如果您愿意。

tsx
// `page` is a search param that is defined in the /posts route and hence available on all of its child routes.
const PageSelector = () => {
  return (
    <div>
      <Link
        from="/posts"
        to="."
        search={(prev) => ({ ...prev, page: prev.page + 1 })}
      >
        Next Page
      </Link>
    </div>
  )

// `page` is a search param that is defined in the /posts route and hence available on all of its child routes.
const PageSelector = () => {
  return (
    <div>
      <Link
        from="/posts"
        to="."
        search={(prev) => ({ ...prev, page: prev.page + 1 })}
      >
        Next Page
      </Link>
    </div>
  )

useNavigate()，navigate({ search })

navigate 函数还接受一个 search 选项，其工作方式与 <Link /> 上的 search 属性相同。

tsx
// /routes/shop.products.tsx
export const Route = createFileRoute('/shop/products/$productId')({
  validateSearch: productSearchSchema,
})

const ProductList = () => {
  const navigate = useNavigate({ from: Route.fullPath })

  return (
    <div>
      <button
        onClick={() => {
          navigate({
            search: (prev) => ({ page: prev.page + 1 }),
          })
        }}
      >
        Next Page
      </button>
    </div>
  )
}

// /routes/shop.products.tsx
export const Route = createFileRoute('/shop/products/$productId')({
  validateSearch: productSearchSchema,
})

const ProductList = () => {
  const navigate = useNavigate({ from: Route.fullPath })

  return (
    <div>
      <button
        onClick={() => {
          navigate({
            search: (prev) => ({ page: prev.page + 1 }),
          })
        }}
      >
        Next Page
      </button>
    </div>
  )
}

router.navigate({ search })

router.navigate 函数的工作方式与上面的 useNavigate/navigate hook/function 完全相同。

<Navigate search />

<Navigate search /> 组件的工作方式与上面的 useNavigate/navigate hook/function 完全相同，但它接受的选项是 props 而不是函数参数。

使用搜索中间件转换搜索参数

当构建链接 href 时，默认情况下，查询字符串部分唯一重要的是 <Link> 的 search 属性。

TanStack Router 提供了一种方法，可以通过搜索中间件在生成 href 之前操作搜索参数。搜索中间件是为路由或其后代生成新链接时转换搜索参数的函数。它们也在搜索验证后导航时执行，以允许修改查询字符串。

以下示例展示了如何确保对于每个正在构建的链接，都会添加 rootValue 搜索参数如果它包含在当前搜索参数中。如果链接在 search 中指定了 rootValue，那么该值将用于构建链接。

tsx
import { z } from 'zod'
import { createFileRoute } from '@tanstack/solid-router'
import { zodValidator } from '@tanstack/zod-adapter'

const searchSchema = z.object({
  rootValue: z.string().optional(),
})

export const Route = createRootRoute({
  validateSearch: zodValidator(searchSchema),
  search: {
    middlewares: [
      ({ search, next }) => {
        const result = next(search)
        return {
          rootValue: search.rootValue,
          ...result,
        }
      },
    ],
  },
})

import { z } from 'zod'
import { createFileRoute } from '@tanstack/solid-router'
import { zodValidator } from '@tanstack/zod-adapter'

const searchSchema = z.object({
  rootValue: z.string().optional(),
})

export const Route = createRootRoute({
  validateSearch: zodValidator(searchSchema),
  search: {
    middlewares: [
      ({ search, next }) => {
        const result = next(search)
        return {
          rootValue: search.rootValue,
          ...result,
        }
      },
    ],
  },
})

由于这种特定用例非常常见，TanStack Router 提供了一个通用实现，可以通过 retainSearchParams 保留搜索参数。

tsx
import { z } from 'zod'
import { createFileRoute, retainSearchParams } from '@tanstack/solid-router'
import { zodValidator } from '@tanstack/zod-adapter'

const searchSchema = z.object({
  rootValue: z.string().optional(),
})

export const Route = createRootRoute({
  validateSearch: zodValidator(searchSchema),
  search: {
    middlewares: [retainSearchParams(['rootValue'])],
  },
})

import { z } from 'zod'
import { createFileRoute, retainSearchParams } from '@tanstack/solid-router'
import { zodValidator } from '@tanstack/zod-adapter'

const searchSchema = z.object({
  rootValue: z.string().optional(),
})

export const Route = createRootRoute({
  validateSearch: zodValidator(searchSchema),
  search: {
    middlewares: [retainSearchParams(['rootValue'])],
  },
})

另一个常见用例是从链接中删除搜索参数（如果其默认值已设置）。TanStack Router 通过 stripSearchParams 为此用例提供了一个通用实现。

tsx
import { z } from 'zod'
import { createFileRoute, stripSearchParams } from '@tanstack/solid-router'
import { zodValidator } from '@tanstack/zod-adapter'

const defaultValues = {
  one: 'abc',
  two: 'xyz',
}

const searchSchema = z.object({
  one: z.string().default(defaultValues.one),
  two: z.string().default(defaultValues.two),
})

export const Route = createFileRoute('/hello')({
  validateSearch: zodValidator(searchSchema),
  search: {
    // strip default values
    middlewares: [stripSearchParams(defaultValues)],
  },
})

import { z } from 'zod'
import { createFileRoute, stripSearchParams } from '@tanstack/solid-router'
import { zodValidator } from '@tanstack/zod-adapter'

const defaultValues = {
  one: 'abc',
  two: 'xyz',
}

const searchSchema = z.object({
  one: z.string().default(defaultValues.one),
  two: z.string().default(defaultValues.two),
})

export const Route = createFileRoute('/hello')({
  validateSearch: zodValidator(searchSchema),
  search: {
    // strip default values
    middlewares: [stripSearchParams(defaultValues)],
  },
})

可以链式调用多个中间件。以下示例展示了如何组合 retainSearchParams 和 stripSearchParams。

tsx
import {
  Link,
  createFileRoute,
  retainSearchParams,
  stripSearchParams,
} from '@tanstack/solid-router'
import { z } from 'zod'
import { zodValidator } from '@tanstack/zod-adapter'

const defaultValues = ['foo', 'bar']

export const Route = createFileRoute('/search')({
  validateSearch: zodValidator(
    z.object({
      retainMe: z.string().optional(),
      arrayWithDefaults: z.string().array().default(defaultValues),
      required: z.string(),
    }),
  ),
  search: {
    middlewares: [
      retainSearchParams(['retainMe']),
      stripSearchParams({ arrayWithDefaults: defaultValues }),
    ],
  },
})

import {
  Link,
  createFileRoute,
  retainSearchParams,
  stripSearchParams,
} from '@tanstack/solid-router'
import { z } from 'zod'
import { zodValidator } from '@tanstack/zod-adapter'

const defaultValues = ['foo', 'bar']

export const Route = createFileRoute('/search')({
  validateSearch: zodValidator(
    z.object({
      retainMe: z.string().optional(),
      arrayWithDefaults: z.string().array().default(defaultValues),
      required: z.string(),
    }),
  ),
  search: {
    middlewares: [
      retainSearchParams(['retainMe']),
      stripSearchParams({ arrayWithDefaults: defaultValues }),
    ],
  },
})
在 GitHub 上编辑
路径参数
链接选项
我们的合作伙伴
Code Rabbit
Netlify
Neon
Clerk
Convex
Sentry
订阅 Bytes

您的每周 JavaScript 资讯。每周一免费发送给超过 10 万开发者。

Bytes

无垃圾邮件。您可以随时取消订阅。

订阅 Bytes

您的每周 JavaScript 资讯。每周一免费发送给超过 10 万开发者。

Bytes

无垃圾邮件。您可以随时取消订阅。