Next.js 状态管理利器：next-usequerystate 内置解析器详解

前言

在现代前端开发中，URL 查询参数(Query String)的管理是一个常见需求。next-usequerystate 是一个专为 Next.js 设计的轻量级状态管理库，它通过将状态与 URL 查询参数同步，实现了简单高效的状态管理方案。

本文将重点介绍 next-usequerystate 提供的内置解析器(parsers)，这些解析器能够帮助开发者处理各种数据类型，从简单的字符串到复杂的 JSON 对象。

为什么需要解析器？

默认情况下，URL 查询参数都是以字符串形式存在的。但在实际应用中，我们经常需要处理更复杂的数据类型：

• 数字（整数、浮点数）
• 布尔值
• 日期和时间
• 枚举值
• 数组和对象

解析器的作用就是在 URL 字符串和 JavaScript 数据类型之间进行双向转换，确保类型安全。

基础类型解析器

字符串解析器

import { parseAsString } from 'nuqs'

虽然查询参数本身就是字符串，但字符串解析器在以下场景很有用：

1. 声明式定义查询参数
2. 设置默认值
3. 配置选项（如是否启用浅层路由）

类型安全提示：parseAsString 不会进行任何验证，会接受任何字符串值。如果需要限制特定字符串值，可以使用字面量解析器。

数字解析器

next-usequerystate 提供了多种数字处理方式：

1. 整数解析器：使用 parseInt 转换

   import { parseAsInteger } from 'nuqs'
   

2. 浮点数解析器：使用 parseFloat 转换

   import { parseAsFloat } from 'nuqs'
   

3. 十六进制解析器：处理十六进制数字

   import { parseAsHex } from 'nuqs'
   

4. 索引解析器：专为分页设计，会自动进行 ±1 偏移

   import { parseAsIndex } from 'nuqs'
   

布尔值解析器

import { parseAsBoolean } from 'nuqs'

布尔值解析器会将字符串 "true" 转换为 true，其他任何值都会转换为 false。

高级类型解析器

字面量解析器

当需要限制为特定值时，可以使用字面量解析器：

1. 字符串字面量：

   const sortOrder = ['asc', 'desc'] as const
   parseAsStringLiteral(sortOrder)
   

2. 数字字面量：

   const diceSides = [1, 2, 3, 4, 5, 6] as const
   parseAsNumberLiteral(diceSides)
   

重要提示：声明字面量数组时务必使用 as const，以确保类型推断正确。

枚举解析器

支持 TypeScript 字符串枚举：

enum Direction {
  up = 'UP',
  down = 'DOWN'
}

parseAsStringEnum<Direction>(Object.values(Direction))

注意：查询字符串中存储的是枚举值（如 "UP"），而非枚举名称（"up"）。

日期和时间解析器

next-usequerystate 提供了三种日期处理方式：

1. ISO 8601 日期时间：完整日期时间格式

   import { parseAsIsoDateTime } from 'nuqs'
   

2. ISO 8601 日期：仅日期部分（时间设为 00:00:00 UTC）

   import { parseAsIsoDate } from 'nuqs'
   

3. 时间戳：Unix 时间戳（毫秒）

   import { parseAsTimestamp } from 'nuqs'
   

集合类型解析器

数组解析器

可以将任何基础解析器转换为数组解析器：

import { parseAsArrayOf, parseAsInteger } from 'nuqs'

// 默认使用逗号分隔
parseAsArrayOf(parseAsInteger)

// 自定义分隔符
parseAsArrayOf(parseAsInteger, ';')

JSON 解析器

对于复杂数据结构，可以使用 JSON 解析器：

import { parseAsJson } from 'nuqs'
import { z } from 'zod'

const schema = z.object({
  pkg: z.string(),
  version: z.number()
})

const [json, setJson] = useQueryState('json', parseAsJson(schema))

JSON 解析器支持多种验证方案：

1. Zod 等标准 Schema
2. 自定义验证函数（如 Yup、Joi）

验证函数要求：必须同步执行，对无效数据应抛出错误或返回 null。

服务端使用解析器

在 Next.js 应用路由中共享代码时，应从 nuqs/server 导入解析器：

import { parseAsString } from 'nuqs/server'

这样可以确保代码在服务端和客户端都能正常工作。

结语

next-usequerystate 的内置解析器提供了丰富的数据类型支持，从简单的基础类型到复杂的 JSON 对象都能轻松处理。通过合理使用这些解析器，开发者可以构建类型安全、状态持久化的 Next.js 应用，同时保持代码的简洁和可维护性。

对于更特殊的需求，next-usequerystate 还支持自定义解析器，这将在后续文章中详细介绍。