前端状态管理【免费下载链接】next-usequerystateType-safe search params state manager for React frameworks - Like useState, but stored in the URL query string.项目地址https://gitcode.com/gh_mirrors/ne/next-usequerystate点击查看免费下载nuqs 是一个像useState一样、但状态存储在 URL 查询字符串中的类型安全状态管理器。自 v2 起nuqs 通过NuqsAdapter上下文提供器将核心逻辑与具体框架解耦从而可以接入 Next.js、React Router、Remix、TanStack Router 之外的任意 React 框架。One.js 正是这样一个通过社区贡献获得支持的框架本指南将说明为何 One.js 适配器未随核心包内置、如何安装并把它集成进根布局以及透过适配器源码理解 nuqs 自定义适配器nuqs/adapters/custom的工作原理。One.js 适配器社区贡献而非内置One.js基于 React Web 与 React Native 的框架在 nuqs 中的支持来自社区贡献的适配器而不是核心包的一部分。相关注册元数据位于 adapter-onejs.json其描述为Using nuqs in One.js applications作者为 nuqs 维护者 François Best归类为adapter声明依赖one与nuqs。不将其内置的原因在 adapter-onejs.md 中有明确说明One.js 同时基于 React Web 和 React Native会把大量依赖带入 nuqs 的构建过程使依赖安装时间翻倍。也就是说将 One.js 作为硬依赖会显著增加所有 nuqs 使用者的安装成本因此官方选择了社区适配器路线适配器代码保留在 nuqs 生态内但由使用方显式安装。同时文档也给出了明确的演进预期如果 One.js 适配器变得流行且需求足够它可能会被并入核心包。这意味着当前以独立注册项分发只是一种过渡形态你可以在官方 registry 中随时跟踪它的状态变化。安装适配器CLI 或复制粘贴与 registry 中其他条目一样安装 One.js 适配器有两种方式使用 CLI 安装通过 registry 机制拉取 adapter-onejs.source 文件并将其放置到目标路径。手动复制粘贴直接复制adapter-onejs.source的源码内容。从注册表配置可以看到文件的目标位置约定{ type: registry:item, name: adapter-onejs, title: One.js Adapter, description: Using nuqs in One.js applications., author: François Best franky47, categories: [adapter], dependencies: [one, nuqs], files: [ { type: registry:file, path: src/registry/items/adapter-onejs.source, target: ~/app/nuqs-onejs-adapter.tsx } ] }target字段表明适配器源码最终会落在应用的~/app/nuqs-onejs-adapter.tsx其中~指项目根目录这也是后续从根布局导入NuqsAdapter时使用的模块路径。安装前请确保项目已安装one与nuqs两个依赖。集成到根布局包裹Slot组件安装完成后将适配器集成进 One.js 应用的根布局文件app/_layout.tsx用NuqsAdapter包裹框架的Slot组件import { NuqsAdapter } from ./nuqs-one-adapter import { Slot } from one export default function Layout() { return ( {typeof document ! undefined ( meta charSetutf-8 / meta httpEquivX-UA-Compatible contentIEedge / meta nameviewport contentwidthdevice-width, initial-scale1, maximum-scale5 / link relicon href/favicon.svg / / )} NuqsAdapter Slot / /NuqsAdapter / ) }这段代码展示了两个关键点Slot /是 One.js 的页面出口组件等价于 Next.js App Router 的{children}、Remix 的Outlet /NuqsAdapter必须位于其上层才能让子树中的所有useQueryState/useQueryStates钩子拿到适配器上下文typeof document ! undefined的守卫表明这份布局同时参与服务端与客户端渲染meta标签仅在浏览器端输出——这与 One.js 跨 Web / Native 的渲染模型相呼应。与其它框架的集成方式保持一致Next.js App Router 用NuqsAdapter包裹{children}React SPA 在createRoot(...).render()处包裹App /Remix 与 React Router v7/v8 包裹Outlet /详见 adapters.mdx。适配器模式的目标就是让 nuqs 的核心逻辑与框架无关任何框架只要提供适配器即可接入。源码解析One.js 适配器如何工作安装到~/app/nuqs-onejs-adapter.tsx的源码完整内容位于 adapter-onejs.source全文如下import { type unstable_AdapterOptions as AdapterOptions, unstable_createAdapterProvider as createAdapterProvider, renderQueryString } from nuqs/adapters/custom import { useActiveParams, useRouter } from one function useNuqsOneAdapter() { const router useRouter() const searchParams new URLSearchParams(useActiveParams() as {}) const updateUrl (search: URLSearchParams, options: AdapterOptions) { if (options.history push) { router.push(renderQueryString(search), { scroll: options.scroll }) } else { router.replace(renderQueryString(search), { scroll: options.scroll }) } } return { searchParams, updateUrl } } export const NuqsAdapter createAdapterProvider(useNuqsOneAdapter)这段代码可以拆解为三个层面1. 输入读取当前查询参数const searchParams new URLSearchParams(useActiveParams() as {})useActiveParams()是 One.js 提供的钩子返回当前激活的 URL 参数适配器将其转换为标准的URLSearchParams对象作为searchParams暴露给 nuqs。从 nuqs 的角度看适配器只需要回答当前 URL 的查询参数是什么即可。2. 输出更新 URLconst updateUrl (search: URLSearchParams, options: AdapterOptions) { ... }updateUrl是适配器向 nuqs 暴露的回调负责把新的查询参数写回 URL。这里的options类型AdapterOptions在 defs.ts 中定义export type AdapterOptions PickOptions, history | scroll | shallow即从 nuqs 全局选项defs.ts中选取history、scroll、shallow三个字段history: push | replace——决定 URL 更新是入栈可后退还是原地替换scroll: boolean——更新后是否滚动到页面顶部shallow: boolean——是否仅做客户端浅更新。One.js 适配器据此把 push 映射到router.push(...)、其余情况映射到router.replace(...)并把scroll选项透传给路由方法。从源码结构看shallow在 One.js 适配器中未做显式处理其行为取决于 One.js 路由自身的实现——这与 React SPA 适配器文档中没有已知服务器时shallow: false无效的说明见 adapters.mdx属于同类框架约束。3. 组装createAdapterProviderexport const NuqsAdapter createAdapterProvider(useNuqsOneAdapter)unstable_createAdapterProvider从nuqs/adapters/custom导入是 nuqs 提供的工厂函数其实现位于 context.ts它接收一个useAdapter钩子返回一个基于 React Context 的 Provider 组件并把useAdapter、defaultOptions、processUrlSearchParams一并放入 Context value。此后应用内任意位置的useQueryState都会通过useAdapter(watchKeys)拿到该钩子返回的AdapterInterfaceexport type AdapterInterface { searchParams: URLSearchParams pathname?: string updateUrl: UpdateUrlFunction getSearchParamsSnapshot?: () URLSearchParams rateLimitFactor?: number autoResetQueueOnUpdate?: boolean }UpdateUrlFunction的完整签名还允许返回一个 Promise用于在路由加载完成后才结束 React 过渡状态startTransition的isPendingexport type UpdateUrlFunction ( search: URLSearchParams, options: RequiredAdapterOptions ) void | PromisevoidOne.js 适配器未使用pathname、rateLimitFactor等可选字段属于最小可用实现——这恰好是理解自定义适配器 API 的绝佳范例你只需要提供searchParams与updateUrl两样东西nuqs 就能完成其余全部工作。底层原理renderQueryString 与 URL 编码安全适配器中用renderQueryString(search)把URLSearchParams序列化为查询字符串。其实现位于 url-encoding.ts编码规则值得注意export function renderQueryString(search: URLSearchParams): string { if (search.size 0) { return } const query: string[] [] for (const [key, value] of search.entries()) { // Replace disallowed characters in keys const safeKey key .replace(/#/g, %23) .replace(//g, %26) .replace(/\/g, %2B) .replace(//g, %3D) .replace(/\?/g, %3F) query.push(${safeKey}${encodeQueryValue(value)}) } const queryString ? query.join() warnIfURLIsTooLong(queryString) return queryString }几个值得深挖的细节key 需要单独转义#、、、、?在键名中会被替换为百分号编码对应 issue #599 的修复因为它们在查询串中具有语法含义值编码采用encodeQueryValue先转义已有的%%25避免被误读为不完整的转义序列再转义%2B随后把空格编码为 RFC 3986 规定的并处理#、、引号、反引号、尖括号以及不可见的 ASCII 控制字符\x00-\x1F空查询串返回空字符串当所有键都被清除时renderQueryString返回此时router.push()的效果等价于清理查询参数超长 URL 警告warnIfURLIsTooLong在非生产环境且location可用时检查拼接后 URL 是否超过 2000 字符上限并给出警告对应错误码 NUQS-414可参考 errors/NUQS-414.md。这意味着适配器写入的 URL 同样受 nuqs 统一的长 URL 防护约束。横向对比One.js 适配器与 React SPA 适配器One.js 适配器并非孤例nuqs 还内置了nuqs/adapters/reactReact SPA / Vite 等其实现见 react.ts。两者对比可以更清楚地看出适配器边界关注点One.js 适配器社区React SPA 适配器内置读取 URL 参数useActiveParams()One.js 钩子location.searchuseSyncExternalStore更新 URLrouter.push/replacehistory.pushState/replaceState订阅变更依赖 One.js 路由popstate事件 内部 emitter键隔离key isolation未实现透传全部参数filterSearchParams(watchKeys)按需过滤React SPA 适配器中filterSearchParams的使用见 react.ts体现了 nuqs 的键隔离机制useSyncExternalStore的快照只包含被watchKeys监视的键未监视键的变化不会触发重渲染且快照保持引用稳定以满足Object.is的 bail-out 要求。One.js 适配器当前将useActiveParams()全部结果直接转为URLSearchParams从源码结构看尚未做等价的键隔离优化——这是社区适配器与内置适配器在成熟度上的典型差异也是后续演进可能的改进方向。限制与适用前提非内置 APIunstable_createAdapterProvider、unstable_AdapterOptions等带unstable_前缀意味着自定义适配器 API 在 nuqs 未来版本如 v3中可能发生变化升级时需留意 changelog仓库变更历史见 packages/docs/content/blog 相关文章依赖成本使用 One.js 适配器需要在项目中同时安装one与nuqs并将适配器源码纳入应用代码管理~/app/nuqs-onejs-adapter.tsx框架行为差异scroll、history选项依赖 One.js 路由实现shallow等选项的实际效果以 One.js 行为为准社区维护状态One.js 适配器为社区贡献是否并入核心包取决于其流行度与需求若希望长期依赖建议关注官方 registry 的更新。综上借助 adapter-onejs.source 这份约 30 行的适配器源码One.js 应用即可获得 nuqs 完整的类型安全查询参数状态管理能力——这也正是 nuqs 适配器架构的价值所在框架接入成本被压缩到一个useAdapter钩子与一个createAdapterProvider调用。赞分享前端状态管理【免费下载链接】next-usequerystateType-safe search params state manager for React frameworks - Like useState, but stored in the URL query string.项目地址https://gitcode.com/gh_mirrors/ne/next-usequerystate点击查看免费下载相关推荐在 json-render 中集成 Redux 状态管理json-render/redux 适配器完全指南在 json render 中集成 Redux 状态管理json render/redux 适配器完全指南 导读 本文介绍 json renderThe人工智能AI 应用前端MCP 服务nuqs 框架适配器Framework Adapters实战指南在 Next.js、React Router、Remix 与 TanStack Router 中正确同步 URL 状态nuqs 框架适配器Framework Adapters实战指南在 Next.js、React Router、Remix 与 TanStack Route后端前端CRM人工智能AI AgentComp AI CRM 中的 nuqs 类型安全 URL 状态管理Next.js 与 React 最佳实践全指南v2.5–v2.9Comp AI CRM 中的 nuqs 类型安全 URL 状态管理Next.js 与 React 最佳实践全指南v2.5–v2.9 本篇技术指南围绕开源仓后端前端CRM人工智能AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
前端状态管理【免费下载链接】next-usequerystateType-safe search params state manager for React frameworks - Like useState, but stored in the URL query string.项目地址https://gitcode.com/gh_mirrors/ne/next-usequerystate点击查看免费下载nuqs 是一个像useState一样、但状态存储在 URL 查询字符串中的类型安全状态管理器。自 v2 起nuqs 通过NuqsAdapter上下文提供器将核心逻辑与具体框架解耦从而可以接入 Next.js、React Router、Remix、TanStack Router 之外的任意 React 框架。One.js 正是这样一个通过社区贡献获得支持的框架本指南将说明为何 One.js 适配器未随核心包内置、如何安装并把它集成进根布局以及透过适配器源码理解 nuqs 自定义适配器nuqs/adapters/custom的工作原理。One.js 适配器社区贡献而非内置One.js基于 React Web 与 React Native 的框架在 nuqs 中的支持来自社区贡献的适配器而不是核心包的一部分。相关注册元数据位于 adapter-onejs.json其描述为Using nuqs in One.js applications作者为 nuqs 维护者 François Best归类为adapter声明依赖one与nuqs。不将其内置的原因在 adapter-onejs.md 中有明确说明One.js 同时基于 React Web 和 React Native会把大量依赖带入 nuqs 的构建过程使依赖安装时间翻倍。也就是说将 One.js 作为硬依赖会显著增加所有 nuqs 使用者的安装成本因此官方选择了社区适配器路线适配器代码保留在 nuqs 生态内但由使用方显式安装。同时文档也给出了明确的演进预期如果 One.js 适配器变得流行且需求足够它可能会被并入核心包。这意味着当前以独立注册项分发只是一种过渡形态你可以在官方 registry 中随时跟踪它的状态变化。安装适配器CLI 或复制粘贴与 registry 中其他条目一样安装 One.js 适配器有两种方式使用 CLI 安装通过 registry 机制拉取 adapter-onejs.source 文件并将其放置到目标路径。手动复制粘贴直接复制adapter-onejs.source的源码内容。从注册表配置可以看到文件的目标位置约定{ type: registry:item, name: adapter-onejs, title: One.js Adapter, description: Using nuqs in One.js applications., author: François Best franky47, categories: [adapter], dependencies: [one, nuqs], files: [ { type: registry:file, path: src/registry/items/adapter-onejs.source, target: ~/app/nuqs-onejs-adapter.tsx } ] }target字段表明适配器源码最终会落在应用的~/app/nuqs-onejs-adapter.tsx其中~指项目根目录这也是后续从根布局导入NuqsAdapter时使用的模块路径。安装前请确保项目已安装one与nuqs两个依赖。集成到根布局包裹Slot组件安装完成后将适配器集成进 One.js 应用的根布局文件app/_layout.tsx用NuqsAdapter包裹框架的Slot组件import { NuqsAdapter } from ./nuqs-one-adapter import { Slot } from one export default function Layout() { return ( {typeof document ! undefined ( meta charSetutf-8 / meta httpEquivX-UA-Compatible contentIEedge / meta nameviewport contentwidthdevice-width, initial-scale1, maximum-scale5 / link relicon href/favicon.svg / / )} NuqsAdapter Slot / /NuqsAdapter / ) }这段代码展示了两个关键点Slot /是 One.js 的页面出口组件等价于 Next.js App Router 的{children}、Remix 的Outlet /NuqsAdapter必须位于其上层才能让子树中的所有useQueryState/useQueryStates钩子拿到适配器上下文typeof document ! undefined的守卫表明这份布局同时参与服务端与客户端渲染meta标签仅在浏览器端输出——这与 One.js 跨 Web / Native 的渲染模型相呼应。与其它框架的集成方式保持一致Next.js App Router 用NuqsAdapter包裹{children}React SPA 在createRoot(...).render()处包裹App /Remix 与 React Router v7/v8 包裹Outlet /详见 adapters.mdx。适配器模式的目标就是让 nuqs 的核心逻辑与框架无关任何框架只要提供适配器即可接入。源码解析One.js 适配器如何工作安装到~/app/nuqs-onejs-adapter.tsx的源码完整内容位于 adapter-onejs.source全文如下import { type unstable_AdapterOptions as AdapterOptions, unstable_createAdapterProvider as createAdapterProvider, renderQueryString } from nuqs/adapters/custom import { useActiveParams, useRouter } from one function useNuqsOneAdapter() { const router useRouter() const searchParams new URLSearchParams(useActiveParams() as {}) const updateUrl (search: URLSearchParams, options: AdapterOptions) { if (options.history push) { router.push(renderQueryString(search), { scroll: options.scroll }) } else { router.replace(renderQueryString(search), { scroll: options.scroll }) } } return { searchParams, updateUrl } } export const NuqsAdapter createAdapterProvider(useNuqsOneAdapter)这段代码可以拆解为三个层面1. 输入读取当前查询参数const searchParams new URLSearchParams(useActiveParams() as {})useActiveParams()是 One.js 提供的钩子返回当前激活的 URL 参数适配器将其转换为标准的URLSearchParams对象作为searchParams暴露给 nuqs。从 nuqs 的角度看适配器只需要回答当前 URL 的查询参数是什么即可。2. 输出更新 URLconst updateUrl (search: URLSearchParams, options: AdapterOptions) { ... }updateUrl是适配器向 nuqs 暴露的回调负责把新的查询参数写回 URL。这里的options类型AdapterOptions在 defs.ts 中定义export type AdapterOptions PickOptions, history | scroll | shallow即从 nuqs 全局选项defs.ts中选取history、scroll、shallow三个字段history: push | replace——决定 URL 更新是入栈可后退还是原地替换scroll: boolean——更新后是否滚动到页面顶部shallow: boolean——是否仅做客户端浅更新。One.js 适配器据此把 push 映射到router.push(...)、其余情况映射到router.replace(...)并把scroll选项透传给路由方法。从源码结构看shallow在 One.js 适配器中未做显式处理其行为取决于 One.js 路由自身的实现——这与 React SPA 适配器文档中没有已知服务器时shallow: false无效的说明见 adapters.mdx属于同类框架约束。3. 组装createAdapterProviderexport const NuqsAdapter createAdapterProvider(useNuqsOneAdapter)unstable_createAdapterProvider从nuqs/adapters/custom导入是 nuqs 提供的工厂函数其实现位于 context.ts它接收一个useAdapter钩子返回一个基于 React Context 的 Provider 组件并把useAdapter、defaultOptions、processUrlSearchParams一并放入 Context value。此后应用内任意位置的useQueryState都会通过useAdapter(watchKeys)拿到该钩子返回的AdapterInterfaceexport type AdapterInterface { searchParams: URLSearchParams pathname?: string updateUrl: UpdateUrlFunction getSearchParamsSnapshot?: () URLSearchParams rateLimitFactor?: number autoResetQueueOnUpdate?: boolean }UpdateUrlFunction的完整签名还允许返回一个 Promise用于在路由加载完成后才结束 React 过渡状态startTransition的isPendingexport type UpdateUrlFunction ( search: URLSearchParams, options: RequiredAdapterOptions ) void | PromisevoidOne.js 适配器未使用pathname、rateLimitFactor等可选字段属于最小可用实现——这恰好是理解自定义适配器 API 的绝佳范例你只需要提供searchParams与updateUrl两样东西nuqs 就能完成其余全部工作。底层原理renderQueryString 与 URL 编码安全适配器中用renderQueryString(search)把URLSearchParams序列化为查询字符串。其实现位于 url-encoding.ts编码规则值得注意export function renderQueryString(search: URLSearchParams): string { if (search.size 0) { return } const query: string[] [] for (const [key, value] of search.entries()) { // Replace disallowed characters in keys const safeKey key .replace(/#/g, %23) .replace(//g, %26) .replace(/\/g, %2B) .replace(//g, %3D) .replace(/\?/g, %3F) query.push(${safeKey}${encodeQueryValue(value)}) } const queryString ? query.join() warnIfURLIsTooLong(queryString) return queryString }几个值得深挖的细节key 需要单独转义#、、、、?在键名中会被替换为百分号编码对应 issue #599 的修复因为它们在查询串中具有语法含义值编码采用encodeQueryValue先转义已有的%%25避免被误读为不完整的转义序列再转义%2B随后把空格编码为 RFC 3986 规定的并处理#、、引号、反引号、尖括号以及不可见的 ASCII 控制字符\x00-\x1F空查询串返回空字符串当所有键都被清除时renderQueryString返回此时router.push()的效果等价于清理查询参数超长 URL 警告warnIfURLIsTooLong在非生产环境且location可用时检查拼接后 URL 是否超过 2000 字符上限并给出警告对应错误码 NUQS-414可参考 errors/NUQS-414.md。这意味着适配器写入的 URL 同样受 nuqs 统一的长 URL 防护约束。横向对比One.js 适配器与 React SPA 适配器One.js 适配器并非孤例nuqs 还内置了nuqs/adapters/reactReact SPA / Vite 等其实现见 react.ts。两者对比可以更清楚地看出适配器边界关注点One.js 适配器社区React SPA 适配器内置读取 URL 参数useActiveParams()One.js 钩子location.searchuseSyncExternalStore更新 URLrouter.push/replacehistory.pushState/replaceState订阅变更依赖 One.js 路由popstate事件 内部 emitter键隔离key isolation未实现透传全部参数filterSearchParams(watchKeys)按需过滤React SPA 适配器中filterSearchParams的使用见 react.ts体现了 nuqs 的键隔离机制useSyncExternalStore的快照只包含被watchKeys监视的键未监视键的变化不会触发重渲染且快照保持引用稳定以满足Object.is的 bail-out 要求。One.js 适配器当前将useActiveParams()全部结果直接转为URLSearchParams从源码结构看尚未做等价的键隔离优化——这是社区适配器与内置适配器在成熟度上的典型差异也是后续演进可能的改进方向。限制与适用前提非内置 APIunstable_createAdapterProvider、unstable_AdapterOptions等带unstable_前缀意味着自定义适配器 API 在 nuqs 未来版本如 v3中可能发生变化升级时需留意 changelog仓库变更历史见 packages/docs/content/blog 相关文章依赖成本使用 One.js 适配器需要在项目中同时安装one与nuqs并将适配器源码纳入应用代码管理~/app/nuqs-onejs-adapter.tsx框架行为差异scroll、history选项依赖 One.js 路由实现shallow等选项的实际效果以 One.js 行为为准社区维护状态One.js 适配器为社区贡献是否并入核心包取决于其流行度与需求若希望长期依赖建议关注官方 registry 的更新。综上借助 adapter-onejs.source 这份约 30 行的适配器源码One.js 应用即可获得 nuqs 完整的类型安全查询参数状态管理能力——这也正是 nuqs 适配器架构的价值所在框架接入成本被压缩到一个useAdapter钩子与一个createAdapterProvider调用。赞分享前端状态管理【免费下载链接】next-usequerystateType-safe search params state manager for React frameworks - Like useState, but stored in the URL query string.项目地址https://gitcode.com/gh_mirrors/ne/next-usequerystate点击查看免费下载相关推荐在 json-render 中集成 Redux 状态管理json-render/redux 适配器完全指南在 json render 中集成 Redux 状态管理json render/redux 适配器完全指南 导读 本文介绍 json renderThe人工智能AI 应用前端MCP 服务nuqs 框架适配器Framework Adapters实战指南在 Next.js、React Router、Remix 与 TanStack Router 中正确同步 URL 状态nuqs 框架适配器Framework Adapters实战指南在 Next.js、React Router、Remix 与 TanStack Route后端前端CRM人工智能AI AgentComp AI CRM 中的 nuqs 类型安全 URL 状态管理Next.js 与 React 最佳实践全指南v2.5–v2.9Comp AI CRM 中的 nuqs 类型安全 URL 状态管理Next.js 与 React 最佳实践全指南v2.5–v2.9 本篇技术指南围绕开源仓后端前端CRM人工智能AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
