nuqs 中文文档 | React 类型安全的搜索参数状态管理

"use client";

import { parseAsInteger, useQueryState } from "nuqs";

export function Demo() {
  const [hello, setHello] = useQueryState("hello", { defaultValue: "" });
  const [count, setCount] = useQueryState(
    "count",
    parseAsInteger.withDefault(0),
  );
  return (
    <>
      <button onClick={() => setCount((c) => c + 1)}>计数: {count}</button>
      <input
        value={hello}
        placeholder="输入您的姓名"
        onChange={(e) => setHello(e.target.value || null)}
      />
      <p>你好，{hello || "匿名访客"}！</p>
    </>
  );
}

类型安全

服务器和客户端组件之间的端到端类型安全。

通用

支持 Next.js（app 和 pages 路由器）、React SPA、Remix、React Router、TanStack Router 等。

简单

一个熟悉的类似 React.useState 的 API，它与 URL 同步。

开箱即用

内置常见状态类型的解析器和序列化器。

历史记录控制

替换或追加到导航历史，并使用后退按钮导航状态更新。

客户端优先

默认浅层更新，选择性通知服务器重新渲染 RSC（带有节流控制）。

服务器缓存

在嵌套 React 服务器组件中类型安全的搜索参数访问。不需要 prop drilling。

过渡

支持 useTransition 以在服务器更新时获取加载状态。

可定制

创建自己的解析器和序列化器。

轻量

仅 6 kB gzipped。

已测试且可测试

针对每个 Next.js 版本进行测试。使用提供的测试适配器在隔离环境中测试您的组件。

赞助商

赞助我的工作

贡献者

被使用于

openpanel.dev

@nathanbrachotte

我开始构建自己的 hook 辅助工具来处理 URL 状态，但不得不应对一些性能问题。
最终发现了这个小小的宝藏，它拥有我想要的一切，甚至更多。

Marc Seitz

@mfts0

它是你的 URL 的数据库 ORM

Pontus Abrahamsson

@pontusab

我们几乎在所有地方都在使用 nuqs 🖤

kitze

@thekitze

nuqs 真的太牛逼了

Darathor17

非常感谢这个超棒的库！我之前按照 nextjs 的推荐与 URL 同步..性能很差，我正准备回到 useState。

KafKa

@KafKa303

这是个很棒的想法，比调用 useSearchParam 并自己动手造轮子好多了！nuqs 是 app router 如此重要的最后一块拼图！一个被严重低估的库！

ahmet

@bruvimtired

nuqs 必须是市面上最好的库之一。现在将状态提升到 url 变得如此简单，而且对用户体验来说好太多了。

Aryan

@AryaAmour08

今天第一次使用 nuqs 库……哇哦 - 在 Next.js 中同步 URL 查询参数从未如此优雅。
解析、默认值、clearOnDefault — 简直太神奇了
这东西怎么现在才出现？

Ru Chern Chong

@ruchernchong

有时候，管理状态并不需要搞得那么复杂。nuqs 真的非常强大。

Bharat Kara

@KaraBharat

nuqs 像魔法一样简化了你的 URL 逻辑。真的。

Ido Evergreen

@IdoEvergreen

它让我意识到 URL 应该成为设计讨论的一部分，而不仅仅是倾倒状态的地方。
自从我在生产环境中更重度地使用 nuqs 以来，我看待和对待 URL 的方式完全改变了。

Rhys Sullivan

@RhysSullivan

最牛的库

Virgile Rietsch

@virgilerietsch

有史以来最好的库

Dominik Koch

@dominikdoesdev

我爱 nuqs

Josh tried coding

@joshtriedcoding

nuqs 是我最近最喜欢的软件之一。不是要吹捧，但说真的，它是 react state 的类型安全、好得多的版本

Pavel Svitek

@pavelsvitek_

今天刚做了第一个自定义解析器，相当简单..很棒的 API 设计 👌

OrcDev

@theorcdev

继续加油！你们做得很棒！
我已经在真实的生产项目中使用 nuqs 了，控制 URL 参数的简便程度令人惊叹。

Brandon McConnell

@branmcconnell

nuqs 是解决查询参数状态管理这个普遍恼人问题的完美方案
真希望十年前就有这个

Iza

@izadoesdev

最牛的库

Code With Antonio

@YTCodeAntonio

每次能用上 nuqs 我都特别开心！

arth

@arthy

另外，nuqs 真的太棒了

Mr T.

@DorianTho5

有史以来最有用的库之一
感谢让我们的生活作为开发者变得更简单，让用户的体验变得更好

Hayden Bleasel

@haydenbleasel

nuqs

Christopher Burns

@BurnedChris

终于见到 nuqs 的 Francois 了，真的很高兴！我喜欢用它！

Chánh Đại

@iamncdai

我将 nuqs 集成到一个内部项目中，它帮助简化了与过滤器相关的查询逻辑并减少了开发时间。

Abhishek Chauhan

@abhishekashwinc

超级喜欢 nuqs！

Michael

@michael_chomsky

见到 nuqs 背后的大佬简直太疯狂了。这是每个 Web 开发者都应该知道的工具之一

James Perkins

@james_r_perkins

nuqs 太牛了

dmytro

@pqoqubbw

感谢你的辛勤工作 🫶
nuqs 太棒了

Suraj Jha

@surajtwt_

目前正在使用 nuqs 为我的 nextjs 应用添加分页和搜索功能，我超爱它