Nuqs：解锁URL状态管理

nuqs是一个强大的库，旨在使用URL查询字符串管理React应用程序的状态。这样做的好处是将应用程序状态与浏览器的地址栏同步，为浏览复杂界面的用户提供无缝体验。无论您是构建单页应用程序还是多路由平台，nuqs都提供了一个强大的框架，可用于直接在URL中处理状态。

例子：https://nuqs.47ng.com/playground/basic-counter

官网介绍：https://nuqs.47ng.com/

Nuqs的关键特性

Nuqs提供了一系列引人注目的特性，使其成为React开发者的必备工具：

• 框架兼容性：支持Next.js（包括app和pages路由器）、纯React（SPA）、Remix和React Router。
• URL作为真相之源：确保URL反映了当前应用程序状态，便于分享和收藏。
• 历史管理：允许替换或追加历史条目，以启用或禁用通过状态变化的后退导航。
• 内置解析器：为常见数据类型（如整数、浮点数、布尔值和日期）提供解析器，并提供创建自定义解析器的选项。
• 服务器端支持：在服务器组件中提供类型安全的搜索参数访问。

开始使用Nuqs

要开始使用Nuqs，您需要通过npm或yarn安装它：

npm install nuqs

yarn add nuqs

安装完成后，您可以通过根据您的框架选择适当的适配器，将Nuqs集成到您的React应用程序中。

Nuqs的基本使用

使用useQueryState管理状态

useQueryState钩子是Nuqs的核心，允许您将单个查询参数作为状态变量进行管理。

import { useQueryState } from 'nuqs';

const GreetingComponent = () => {
  const [name, setName] = useQueryState('name');

  return (
    <>
      <h1>Hello, {name || '匿名访客'}!</h1>
      <input value={name || ''} onChange={e => setName(e.target.value)} />
      <button onClick={() => setName(null)}>清除</button>
    </>
  );
};

在这个示例中，name参数与输入字段同步，并反映在URL中。

解析非字符串类型

默认情况下，搜索参数是字符串，但管理URL中存在更复杂的类型（例如数字、布尔值、日期），这时候就需要类型安全的解析器。

nuqs提供内置解析器，如parseAsInteger、parseAsBoolean和parseAsIsoDateTime，确保查询参数经过验证和类型检查。例如，parseAsInteger将字符串转换为整数，而parseAsBoolean解释true或false。

这些解析器有助于管理和强制执行搜索参数中的正确类型，从而提高应用程序的安全性和可靠性。

import { useQueryState, parseAsInteger } from 'nuqs';

const CounterComponent = () => {
  const [count, setCount] = useQueryState('count', parseAsInteger.withDefault(0));

  return (
    <>
      <pre>count: {count}</pre>
      <button onClick={() => setCount(c => c + 1)}>+</button>
      <button onClick={() => setCount(c => c - 1)}>-</button>
    </>
  );
};

这种设置确保count始终被视为整数。

与transitions处理加载状态

您可以将useQueryState与React的useTransition中的startTransition函数相结合，在服务器重新渲染组件时通过显示加载状态来提供更流畅的用户体验。

// lib/hooks/useProductParams.ts
import { useTransition } from 'react';

export function useProductParams() {
  const [isPending, startTransition] = useTransition();

  const [search, setSearch] = useQueryState('search',
      parseAsString.withDefault('').withOptions({
        // rest of the code
          startTransition
      })
  );
  const [{ category, sort, page }, setParams] = useQueryStates({
    // rest of the code
  }, {
      // rest of the code
      startTransition
  });
  return {
// rest of the code
    isPending
  };
}

我们现在可以导入useProductParam Hook，并在我们的组件中使用它：

'use client'
import { useProductParams } from '@/lib/hooks/useProductParams';
import LoadingSpinner from './LoadingSpinner';

export default function SearchBar() {
  const { search, setSearch, isPending } = useProductParams();
// rest of the code
  return (
    <div className="relative">
    // rest of the code
      {isPending && (
        <div className="absolute right-2 top-2">
          <LoadingSpinner />
        </div>
      )}
    </div>
  );
}

高级技术

使用多个查询状态

对于一起管理相关的查询参数，useQueryStates是理想的选择：

import { useQueryStates, parseAsFloat } from 'nuqs';

const LocationComponent = () => {
  const [coordinates, setCoordinates] = useQueryStates({
    lat: parseAsFloat.withDefault(45.18),
    lng: parseAsFloat.withDefault(5.72)
  });

  return (
    <div>
      纬度：{coordinates.lat}, 经度：{coordinates.lng}
    </div>
  );
};

服务器端解析

Nuqs还可以管理服务器端的搜索参数，这对深度嵌套的服务器组件特别有用。

nuqs提供了一个名为createSearchParamsCache的实用函数，允许您为特定搜索参数（例如字符串、整数）定义解析器，并在服务器组件中安全访问它们。解析值在当前渲染周期期间保持，并且可以与客户端组件共享，以确保整个应用程序的类型安全。让我们看看如何使用nuqs来正确实现这一点。

import { createSearchParamsCache, parseAsInteger } from 'nuqs/server';

export const searchParamsCache = createSearchParamsCache({
  maxResults: parseAsInteger.withDefault(10)
});

function ResultsPage({ searchParams }) {
  const { maxResults } = searchParamsCache.parse(searchParams);

  return <span>显示最多 {maxResults} 个结果</span>;
}

总结

Nuqs库是管理React应用程序中URL查询字符串状态的变革者。它通过将URL作为可靠的数据来，简化了复杂的状态管理场景。通过集成Nuqs，开发者可以构建更直观、用户友好的应用程序。

本文由mdnice多平台发布