在 Next.js 中使用 nuqs createTypedLink 构建类型安全的路径名与搜索参数链接

前端状态管理【免费下载链接】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点击查看免费下载导读本文基于 nuqsnext-usequerystate仓库中的 registry 组件 next-typed-links 展开讲解如何将 Next.js 15.5 的typedRoutes类型安全路径名与 nuqs 的搜索参数描述符search params descriptor连接起来通过一个createTypedLink工具函数生成路径名 查询串完全类型安全的href用于Link与路由跳转。读完本文你将掌握createTypedLink的用法、它的底层实现原理、urlKeys重映射机制以及如何将其接入到自己的 Next.js 应用中。typedRoutes 与 nuqs两条类型安全体系的交汇Next.js 自 15.5 起提供 typed routes 的预览支持开启后next/link的href、router.push()、router.replace()等 API 中的路径名会由编译器推断拼错路径或给动态路由传错参数都会在编译/类型检查阶段直接报错。但 typed routes 只保证路径名pathname的类型安全URL 查询参数search params仍是宽泛的字符串世界。而 nuqs 的核心价值恰恰在于通过parseAsFloat、parseAsString等解析器描述符把查询参数变成带默认值、带序列化/反序列化逻辑的类型安全状态。createTypedLink就是连接这两套体系的桥梁它把 typed routes 的类型安全路径名与 nuqs 的搜索参数描述符组合成一个函数调用它即可得到完整、类型安全的href。该工具最初以Next.js 15.5 typed routes 预览支持的形式出现在 nuqs-2.5 发布说明 中随后被整理为独立的 registry 组件。前提条件Next.js 15.5.0typed routes 支持的最小版本并在next.config.ts中开启const nextConfig { experimental: { typedRoutes: true } }已安装nuqsNPM:npm install nuqsPNPM:pnpm add nuqsYarn:yarn add nuqsBun:bun add nuqs并完成 NuqsAdapter 的接入配置。createTypedLink 的使用该组件在仓库中以 shadcn registry item 形式发布元数据见 next-typed-links.json它声明依赖next15.5.0与nuqs并把 typed-links.ts 作为唯一源文件安装到~/src/lib/typed-links.ts。你也可以直接把该函数复制到自己的代码库中。第一步定义搜索参数描述符与 URL 键重映射在src/app/map/search-params.ts中先定义坐标的解析器描述符与useQueryStates复用同一份定义保证读写两端一致import { createTypedLink } from /src/lib/typed-links import { parseAsFloat, type UrlKeys } from nuqs/server const coordinates { latitude: parseAsFloat.withDefault(0), longitude: parseAsFloat.withDefault(0) } // Optional remapping for shorter keys const urlKeys: UrlKeystypeof coordinates { latitude: lat, longitude: lng }UrlKeys是 nuqs 提供的辅助类型定义见 defs.ts它把代码中的属性名映射为URL 中实际使用的查询参数名。当你不希望?latitude...这种冗长键名暴露在地址栏时可以用UrlKeystypeof coordinates声明映射类型系统会保证映射键名与描述符键完全一致。第二步创建绑定到路由的链接生成函数// [!code word:createTypedLink] export const getMapLink createTypedLink( /map, // The values here are inferred from your apps routes coordinates, { urlKeys } )createTypedLink的第一个参数是RouteNext.js typed routes 导出的路径名联合类型其取值由你应用的实际路由自动推断——如果传了不存在的路径类型检查会直接报错。第二个参数是搜索参数描述符第三个参数是可选的序列化选项此处传入urlKeys重映射。第三步调用生成类型安全的 href// Usage: getMapLink({ latitude: 12.34, longitude: 56.78 }) // /map?lat12.34lng56.78传入的值会被逐个序列化并拼接到路径后latitude序列化为latlongitude序列化为lng且因为两个解析器都声明了withDefault(0)传参时属性名、类型都会被严格校验。在组件中配合next/link使用import Link from next/link function MapLinks() { return ( Link href{getMapLink({ latitude: 48.86, longitude: 2.35 })} Paris, France /Link ) }底层实现一次 bind 完成的函数组合createTypedLink的实现非常精简完整源码见 typed-links.tsimport type { Route } from next import { createSerializer, type CreateSerializerOptions, type ParserMap } from nuqs/server export function createTypedLinkParsers extends ParserMap( route: Route, parsers: Parsers, options: CreateSerializerOptionsParsers {} ) { const serialize createSerializerParsers, Route, Route(parsers, options) return serialize.bind(null, route) }它的本质是对 nuqs 的createSerializer实现见 serializer.ts做了一层柯里化封装用createSerializerParsers, Route, Route基于描述符与选项创建序列化函数用serialize.bind(null, route)把路由路径名预绑定为第一个参数返回一个只接收 values的新函数。因此getMapLink(values)等价于serialize(route, values)。从类型角度看serialize.bind(null, route)恰好把SerializeFunctionParsers, Route, Route的路径名 值双参签名收窄为仅值签名Route类型因此贯穿始终——这正是路径名与查询参数双双类型安全的来源。序列化器的核心行为从 serializer.ts 可以看到createSerializer生成的函数支持两种调用形态仅传值serialize({ latitude: 12.34 })生成纯查询串createTypedLink用的是这种形态自动带上已绑定的路径传 base 值serialize(/map, values)此时会解析 base 中的已有查询参数并追加/修改/删除null值会删除对应参数。序列化循环中的关键逻辑serializer.ts逐键处理值为undefined时跳过该键getOwn只认自有属性见 url-keys.ts值等于解析器默认值且clearOnDefault默认true时从 URL 中删除该参数避免地址栏被无意义参数塞满否则调用parser.serialize(value)序列化并写入。clearOnDefault是CreateSerializerOptions中唯一直接暴露的 nuqs 全局选项另有urlKeys与processUrlSearchParams见 serializer.ts。当你在第三个参数中传入{ clearOnDefault: false }时即使值与默认值相同也会保留在 URL 中便于分享完整状态。urlKeys 重映射的底层机制createTypedLink的{ urlKeys }选项最终会进入createSerializer。序列化时每个键都经过 getUrlKey 解析export function getUrlKey( urlKeys: PartialRecordstring, string, key: string ): string { return getOwn(urlKeys, key) ?? key }即如果urlKeys中为该键配置了别名就用别名否则回退到原键名。这套机制与useQueryStates、createSearchParamsCache、createSerializer完全一致useQueryStates.ts、cache.ts、loader.ts 均消费同一份UrlKeys类型意味着同一份urlKeys定义可以同时复用于读取状态useQueryStates、服务端预取createSearchParamsCache和生成链接createTypedLink保证 URL 键名在应用各处永远一致。这也解释了为什么原文档建议把描述符与urlKeys单独抽成模块导出它们是整条类型安全链路的共享契约。使用注意事项与适用边界typed routes 是前提createTypedLink的第一个参数类型来自next的Route只有在开启experimental.typedRoutes时才有实际约束力未开启时它退化为宽泛的字符串失去路径名层面的类型检查。绑定语义返回的函数已绑定固定路径适合为每个页面/路由创建专用的链接生成器如果需要在多个路径间复用同一组描述符可以保留createSerializer原函数每次传入不同 base。序列化选项按需配置默认clearOnDefault: true会移除与默认值相等的参数processUrlSearchParams可在输出前对URLSearchParams做二次加工如追加全局参数但该选项的最终 URL 展示与读取端行为需要自行保证一致。版本适配当前仓库中该组件面向 Next.js 15.5 设计如果项目使用更早版本或 React Router可参考发布说明中复用同一序列化技巧的思路自行封装React Router 侧同样有基于类型安全href的实践见 nuqs-2.5.mdx。总结createTypedLink用约 15 行代码完成了两件重要的事把 Next.js typed routes 的路径名类型系统与 nuqs 的搜索参数类型系统缝合在一起并通过bind把双参序列化函数变成即调即用的单参 href 工厂。配合UrlKeys重映射与clearOnDefault等选项它让构造链接和读取状态共享同一套类型安全的描述符契约从根源上消除了拼写错误、键名不一致与类型漂移三类常见 bug。赞分享前端状态管理【免费下载链接】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与Elasticsearch集成搜索参数构建查询NuQS与Elasticsearch集成搜索参数构建查询 痛点与解决方案 在Next.js应用中构建搜索功能时开发者常面临URL参数管理与Elasticse前端状态管理Iris 路由宏与链式 RouteBuilder用类型化路径参数构建路由的实战指南Iris 路由宏与链式 RouteBuilder用类型化路径参数构建路由的实战指南 导读 在 Iris Web 框架中路由路径支持一种宏macro语KuGouMusicApi 搜索接口中歌手类型参数的使用注意事项KuGouMusicApi 搜索接口中歌手类型参数的使用注意事项 在使用 KuGouMusicApi 进行音乐搜索时开发者可能会遇到搜索歌手类型 typea后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考