搜索参数

类似于 TanStack Query 让您的 React 和 Solid 应用程序中的服务器状态处理变得轻而易举，TanStack Router 旨在释放 URL 搜索参数在您的应用程序中的强大功能。

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

为什么不直接使用 URLSearchParams？

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

传统的搜索参数 API 通常假设几件事

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

然而，现实与这些假设大相径庭。

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

搜索参数，原始状态管理器

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

用户应该能够
- Cmd/Ctrl + 点击在新标签页中打开链接，并可靠地看到他们预期的状态
- 从您的应用程序中收藏和分享链接给其他人，并确保他们将看到与复制链接时完全相同的状态。
- 刷新您的应用程序或在页面之间来回导航而不会丢失状态
开发人员应该能够轻松地
- 以与其他状态管理器一样出色的开发体验在 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 字符串

🧠 其他工具通常假设搜索参数始终是扁平的且基于字符串，这就是我们选择在第一层保持 URLSearchParams 兼容的原因。这最终意味着，即使 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/react-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/react-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/react-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/react-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/react-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/react-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/react-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/react-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/react-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/react-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/react-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/react-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 函数，以避免为了访问类型化的 useSearch() Hook 而不得不导入 Route 配置。

路由组件外的搜索参数

您可以使用 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/函数完全相同。

<Navigate search />

<Navigate search /> 组件的工作方式与上面的 useNavigate/navigate Hook/函数完全相同，但它以属性而不是函数参数的形式接受其选项。

使用搜索中间件转换搜索

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

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

以下示例展示了如何确保对于**每个**正在构建的链接，如果 rootValue 搜索参数是当前搜索参数的一部分，则添加它。如果链接在 search 中指定了 rootValue，则该值将用于构建链接。

tsx

import { z } from 'zod'
import { createFileRoute } from '@tanstack/react-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/react-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/react-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/react-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/react-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/react-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/react-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/react-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 }),
    ],
  },
})