nuqs 2 | nuqs 中文文档

nuqs@2.0.0 已可用，现在就试试吧：

npm install nuqs@latest

它带来了令人兴奋的新功能和改进，包括：

支持其他 React 框架：Next.js、React SPA、Remix、React Router，以及更多即将到来
内置测试适配器，用于隔离单元测试组件
捆绑大小改进
交互式文档，包含社区解析器

你好，React！ 👋 ⚛️

nuqs 最初是一个仅限 Next.js 的钩子，而 v2 带来了与其他 React 框架的兼容性：

Next.js 14 & 15（app & pages 路由器）
React SPA
Remix
React Router

使用 nuqs 钩子的组件无需更改代码，使它们在所有支持的框架中实现 通用性。

唯一的新要求是将你的 React 树用相应框架的适配器包裹。

使用 Vite 的 React SPA 示例：

src/main.tsx

import { NuqsAdapter } from 'nuqs/adapters/react'

createRoot(document.getElementById('root')!).render(
  <NuqsAdapter>
    <App />
  </NuqsAdapter>
)

适配器文档包含所有支持框架的示例。

测试

nuqs v1 的一个主要痛点是测试使用其钩子的组件。

Nuqs v2 带有内置测试适配器，它模拟 URL 行为，允许你在任何框架运行时之外隔离测试组件。

你可以使用任何渲染 React 组件的单元测试框架（我推荐 Vitest & Testing Library)。

counter-button.test.tsx

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { NuqsTestingAdapter, type UrlUpdateEvent } from 'nuqs/adapters/testing'
import { describe, expect, it, vi } from 'vitest'
import { CounterButton } from './counter-button'

it('should increment the count when clicked', async () => {
  const user = userEvent.setup()
  const onUrlUpdate = vi.fn<[UrlUpdateEvent]>()
  render(<CounterButton />, {
    // 1. 通过传递初始搜索参数 / 查询字符串来设置测试：
    wrapper: ({ children }) => (
      <NuqsTestingAdapter searchParams="?count=42" onUrlUpdate={onUrlUpdate}>
        {children}
      </NuqsTestingAdapter>
    )
  })
  // 2. 执行操作
  const button = screen.getByRole('button')
  await user.click(button)
  // 3. 断言状态变化以及（模拟的）URL 变化
  expect(button).toHaveTextContent('count is 43')
  expect(onUrlUpdate).toHaveBeenCalledOnce()
  expect(onUrlUpdate.mock.calls[0][0].queryString).toBe('?count=43')
  expect(onUrlUpdate.mock.calls[0][0].searchParams.get('count')).toBe('43')
  expect(onUrlUpdate.mock.calls[0][0].options.history).toBe('push')
})