TanStackRouter v1
自动
框架
版本
菜单
开始上手
路由
指南
API
ESLint
Router 示例

自定义搜索参数序列化

默认情况下，TanStack Router 使用 JSON.stringify 和 JSON.parse 自动解析和序列化您的 URL 搜索参数。此过程除了搜索对象的序列化和反序列化之外，还涉及转义和取消转义搜索字符串，这对于 URL 搜索参数是一种常见的做法。

例如，使用默认配置，如果您有以下搜索对象

tsx
const search = {
  page: 1,
  sort: 'asc',
  filters: { author: 'tanner', min_words: 800 },
}

const search = {
  page: 1,
  sort: 'asc',
  filters: { author: 'tanner', min_words: 800 },
}

它将被序列化并转义为以下搜索字符串

txt
?page=1&sort=asc&filters=%7B%22author%22%3A%22tanner%22%2C%22min_words%22%3A800%7D

?page=1&sort=asc&filters=%7B%22author%22%3A%22tanner%22%2C%22min_words%22%3A800%7D

我们可以使用以下代码实现默认行为

tsx
import {
  createRouter,
  parseSearchWith,
  stringifySearchWith,
} from '@tanstack/react-router'

const router = createRouter({
  // ...
  parseSearch: parseSearchWith(JSON.parse),
  stringifySearch: stringifySearchWith(JSON.stringify),
})

import {
  createRouter,
  parseSearchWith,
  stringifySearchWith,
} from '@tanstack/react-router'

const router = createRouter({
  // ...
  parseSearch: parseSearchWith(JSON.parse),
  stringifySearch: stringifySearchWith(JSON.stringify),
})

但是，这种默认行为可能不适用于所有用例。例如，您可能希望使用不同的序列化格式，例如 base64 编码，或者您可能希望使用专门构建的序列化/反序列化库，例如 query-string、JSURL2 或 Zipson。

这可以通过在 Router 配置中，为您自己的序列化和反序列化函数提供 parseSearch 和 stringifySearch 选项来实现。在执行此操作时，您可以利用 TanStack Router 的内置辅助函数 parseSearchWith 和 stringifySearchWith 来简化此过程。

提示

序列化和反序列化的一个重要方面是，反序列化后您能够获得相同的对象。这很重要，因为如果序列化和反序列化过程未正确完成，您可能会丢失一些信息。例如，如果您使用的库不支持嵌套对象，则在反序列化搜索字符串时，您可能会丢失嵌套对象。

Diagram showing idempotent nature of URL search param serialization and deserialization

以下是一些示例，说明如何在 TanStack Router 中自定义搜索参数序列化

使用 Base64

通常的做法是对您的搜索参数进行 base64 编码，以实现跨浏览器和 URL 展开器等的最大兼容性。这可以使用以下代码完成

tsx
import {
  Router,
  parseSearchWith,
  stringifySearchWith,
} from '@tanstack/react-router'

const router = createRouter({
  parseSearch: parseSearchWith((value) => JSON.parse(decodeFromBinary(value))),
  stringifySearch: stringifySearchWith((value) =>
    encodeToBinary(JSON.stringify(value)),
  ),
})

function decodeFromBinary(str: string): string {
  return decodeURIComponent(
    Array.prototype.map
      .call(atob(str), function (c) {
        return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2)
      })
      .join(''),
  )
}

function encodeToBinary(str: string): string {
  return btoa(
    encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, function (match, p1) {
      return String.fromCharCode(parseInt(p1, 16))
    }),
  )
}

import {
  Router,
  parseSearchWith,
  stringifySearchWith,
} from '@tanstack/react-router'

const router = createRouter({
  parseSearch: parseSearchWith((value) => JSON.parse(decodeFromBinary(value))),
  stringifySearch: stringifySearchWith((value) =>
    encodeToBinary(JSON.stringify(value)),
  ),
})

function decodeFromBinary(str: string): string {
  return decodeURIComponent(
    Array.prototype.map
      .call(atob(str), function (c) {
        return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2)
      })
      .join(''),
  )
}

function encodeToBinary(str: string): string {
  return btoa(
    encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, function (match, p1) {
      return String.fromCharCode(parseInt(p1, 16))
    }),
  )
}

⚠️ 为什么此代码片段不使用 atob/btoa？

因此，如果我们使用此配置将之前的对象转换为搜索字符串，它将如下所示

txt
?page=1&sort=asc&filters=eyJhdXRob3IiOiJ0YW5uZXIiLCJtaW5fd29yZHMiOjgwMH0%3D

?page=1&sort=asc&filters=eyJhdXRob3IiOiJ0YW5uZXIiLCJtaW5fd29yZHMiOjgwMH0%3D

警告

如果您将用户输入序列化为 Base64，则您有导致 URL 反序列化冲突的风险。这可能会导致意外行为，例如 URL 未正确解析或被解释为不同的值。为避免这种情况，您应该使用安全的二进制编码/解码方法对搜索参数进行编码（请参见下文）。

使用 query-string 库

query-string 库因能够可靠地解析和字符串化查询字符串而广受欢迎。您可以使用它来自定义搜索参数的序列化格式。这可以使用以下代码完成

tsx
import { createRouter } from '@tanstack/react-router'
import qs from 'query-string'

const router = createRouter({
  // ...
  stringifySearch: stringifySearchWith((value) =>
    qs.stringify(value, {
      // ...options
    }),
  ),
  parseSearch: parseSearchWith((value) =>
    qs.parse(value, {
      // ...options
    }),
  ),
})

import { createRouter } from '@tanstack/react-router'
import qs from 'query-string'

const router = createRouter({
  // ...
  stringifySearch: stringifySearchWith((value) =>
    qs.stringify(value, {
      // ...options
    }),
  ),
  parseSearch: parseSearchWith((value) =>
    qs.parse(value, {
      // ...options
    }),
  ),
})

因此，如果我们使用此配置将之前的对象转换为搜索字符串，它将如下所示

txt
?page=1&sort=asc&filters=author%3Dtanner%26min_words%3D800

?page=1&sort=asc&filters=author%3Dtanner%26min_words%3D800

使用 JSURL2 库

JSURL2 是一个非标准库，可以压缩 URL，同时仍保持可读性。这可以使用以下代码完成

tsx
import {
  Router,
  parseSearchWith,
  stringifySearchWith,
} from '@tanstack/react-router'
import { parse, stringify } from 'jsurl2'

const router = createRouter({
  // ...
  parseSearch: parseSearchWith(parse),
  stringifySearch: stringifySearchWith(stringify),
})

import {
  Router,
  parseSearchWith,
  stringifySearchWith,
} from '@tanstack/react-router'
import { parse, stringify } from 'jsurl2'

const router = createRouter({
  // ...
  parseSearch: parseSearchWith(parse),
  stringifySearch: stringifySearchWith(stringify),
})

因此，如果我们使用此配置将之前的对象转换为搜索字符串，它将如下所示

txt
?page=1&sort=asc&filters=(author~tanner~min*_words~800)~

?page=1&sort=asc&filters=(author~tanner~min*_words~800)~

使用 Zipson 库

Zipson 是一个非常用户友好且高性能的 JSON 压缩库（在运行时性能和最终压缩性能方面）。要使用它压缩您的搜索参数（这也需要转义/取消转义和 base64 编码/解码它们），您可以使用以下代码

tsx
import {
  Router,
  parseSearchWith,
  stringifySearchWith,
} from '@tanstack/react-router'
import { stringify, parse } from 'zipson'

const router = createRouter({
  parseSearch: parseSearchWith((value) => parse(decodeFromBinary(value))),
  stringifySearch: stringifySearchWith((value) =>
    encodeToBinary(stringify(value)),
  ),
})

function decodeFromBinary(str: string): string {
  return decodeURIComponent(
    Array.prototype.map
      .call(atob(str), function (c) {
        return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2)
      })
      .join(''),
  )
}

function encodeToBinary(str: string): string {
  return btoa(
    encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, function (match, p1) {
      return String.fromCharCode(parseInt(p1, 16))
    }),
  )
}

import {
  Router,
  parseSearchWith,
  stringifySearchWith,
} from '@tanstack/react-router'
import { stringify, parse } from 'zipson'

const router = createRouter({
  parseSearch: parseSearchWith((value) => parse(decodeFromBinary(value))),
  stringifySearch: stringifySearchWith((value) =>
    encodeToBinary(stringify(value)),
  ),
})

function decodeFromBinary(str: string): string {
  return decodeURIComponent(
    Array.prototype.map
      .call(atob(str), function (c) {
        return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2)
      })
      .join(''),
  )
}

function encodeToBinary(str: string): string {
  return btoa(
    encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, function (match, p1) {
      return String.fromCharCode(parseInt(p1, 16))
    }),
  )
}

⚠️ 为什么此代码片段不使用 atob/btoa？

因此，如果我们使用此配置将之前的对象转换为搜索字符串，它将如下所示

txt
?page=1&sort=asc&filters=JTdCJUMyJUE4YXV0aG9yJUMyJUE4JUMyJUE4dGFubmVyJUMyJUE4JUMyJUE4bWluX3dvcmRzJUMyJUE4JUMyJUEyQ3UlN0Q%3D

?page=1&sort=asc&filters=JTdCJUMyJUE4YXV0aG9yJUMyJUE4JUMyJUE4dGFubmVyJUMyJUE4JUMyJUE4bWluX3dvcmRzJUMyJUE4JUMyJUEyQ3UlN0Q%3D

安全二进制编码/解码

在浏览器中，atob 和 btoa 函数不能保证与非 UTF8 字符一起正常工作。我们建议您改用这些编码/解码实用程序

从字符串编码为二进制字符串

typescript
export function encodeToBinary(str: string): string {
  return btoa(
    encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, function (match, p1) {
      return String.fromCharCode(parseInt(p1, 16))
    }),
  )
}

export function encodeToBinary(str: string): string {
  return btoa(
    encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, function (match, p1) {
      return String.fromCharCode(parseInt(p1, 16))
    }),
  )
}

从二进制字符串解码为字符串

typescript
export function decodeFromBinary(str: string): string {
  return decodeURIComponent(
    Array.prototype.map
      .call(atob(str), function (c) {
        return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2)
      })
      .join(''),
  )
}

export function decodeFromBinary(str: string): string {
  return decodeURIComponent(
    Array.prototype.map
      .call(atob(str), function (c) {
        return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2)
      })
      .join(''),
  )
}
在 GitHub 上编辑
导航阻塞
历史记录类型
订阅 Bytes

您的每周 JavaScript 新闻。每周一免费发送给超过 100,000 名开发人员。

Bytes

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