ReactNext.js持久化过滤器实现教程

最近发现不少小伙伴都对文章很感兴趣，所以今天继续给大家介绍文章相关的知识，本文《React/Next.js持久化过滤器实现方法》主要内容涉及到等等知识点，希望能帮到你！当然如果阅读本文时存在不同想法，可以在评论中表达，但是请勿使用过激的措辞~

在React/Next.js应用中，高效管理URL查询参数是实现持久化数据过滤的关键。本文将深入探讨如何构建一个健壮的系统，确保用户在应用新过滤器时，旧的过滤器状态得以保留，并实现查询参数的添加、更新与删除。通过利用Next.js App Router的`useRouter`、`usePathname`和`useSearchParams`钩子，结合`URLSearchParams` API，我们将创建一个可复用的查询参数管理工具，从而构建出用户体验流畅、状态一致的过滤功能。

引言：数据过滤中的常见挑战

在现代Web应用中，数据过滤是提升用户体验不可或缺的功能。然而，开发者常遇到的一个问题是，当用户应用一个新的过滤器（例如，输入搜索关键词）时，之前设置的过滤器（例如，标签或价格范围）会被意外清除。这导致URL查询参数无法正确累积，例如从localhost:3000/?tag=food变成localhost:3000/?search=text，而不是期望的localhost:3000/?search=text&tag=food。

其根本原因在于，直接使用router.push('/?search=' + value)会完全替换当前的查询字符串，而非智能地合并或更新。为了解决这一问题，我们需要一种机制来读取现有的URL查询参数，将其与新的参数合并，然后构建一个新的完整URL进行导航。

核心概念：URL查询参数管理

在Next.js App Router环境中，我们利用以下三个核心钩子来管理URL查询参数：

• useRouter：提供程序化导航功能，例如router.push()。
• usePathname：获取当前URL的路径部分（不包含查询参数）。
• useSearchParams：获取当前URL的查询参数，返回一个URLSearchParams对象。

URLSearchParams是一个Web API接口，它提供了便捷的方法来处理URL的查询字符串。我们可以用它来读取、设置、删除和遍历查询参数。

构建可复用的查询参数管理Hook

为了封装查询参数的逻辑，我们创建一个自定义Hook useQueryParamManager。这个Hook将提供一个updateQueryParams函数，用于接收一个包含新参数的对象，并智能地更新URL。

// hooks/useQueryParamManager.js
"use client"; // 确保此Hook在客户端运行

import { useRouter, usePathname, useSearchParams } from 'next/navigation';
import { useCallback } from 'react';

/**
 * 自定义Hook，用于管理Next.js应用中的URL查询参数。
 * 提供了更新、添加和删除查询参数的功能，并自动进行URL导航。
 *
 * @returns {function(Object<string, string | number | null | undefined>): void} updateQueryParams 函数
 */
export function useQueryParamManager() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  /**
   * 更新URL中的查询参数。
   *
   * @param {Object<string, string | number | null | undefined>} newParams 一个对象，键值对表示要更新的参数。
   *   如果值为 null、undefined 或空字符串，则该参数将被从URL中删除。
   */
  const updateQueryParams = useCallback((newParams) => {
    // 基于当前的searchParams创建一个新的URLSearchParams实例
    const currentParams = new URLSearchParams(searchParams.toString());

    // 遍历传入的新参数，更新或删除它们
    Object.entries(newParams).forEach(([key, value]) => {
      if (value === null || value === undefined || String(value).trim() === '') {
        // 如果值为 null/undefined/空字符串，则删除该参数
        currentParams.delete(key);
      } else {
        // 否则，设置或更新该参数
        currentParams.set(key, String(value));
      }
    });

    // 构建新的查询字符串
    const queryString = currentParams.toString();
    // 构建新的完整URL
    const newUrl = queryString ? `${pathname}?${queryString}` : pathname;

    // 使用router.push进行导航，更新URL
    router.push(newUrl);
  }, [router, pathname, searchParams]); // 依赖项确保当router, pathname, searchParams变化时，函数重新创建

  return updateQueryParams;
}

Hook解析：

1. "use client": 声明这是一个客户端组件/Hook，因为它使用了浏览器API（如URLSearchParams）和Next.js客户端钩子。
2. useSearchParams(): 获取当前URL的所有查询参数，并将其转换为一个URLSearchParams对象。
3. new URLSearchParams(searchParams.toString()): 这一步至关重要。它基于当前URL的查询参数创建一个新的URLSearchParams实例。这样做是为了确保我们操作的是当前URL的完整参数集合，而不是从零开始。
4. Object.entries(newParams).forEach(...): 遍历传入的newParams对象。
   • 如果参数值是null、undefined或空字符串，我们调用currentParams.delete(key)来从URL中移除该参数。这对于清除过滤器状态非常有用。
   • 否则，我们使用currentParams.set(key, String(value))来设置或更新参数。set()方法会替换已存在的参数值，如果参数不存在则添加。
5. currentParams.toString(): 将更新后的URLSearchParams对象转换回标准的URL查询字符串格式（例如search=text&tag=food）。
6. router.push(newUrl): 使用Next.js的路由方法导航到新的URL。

在组件中应用查询参数管理Hook

现在，我们将这个Hook集成到我们的过滤组件中。

1. 搜索输入框组件 (Search.js)

// components/common/Search.js
"use client";

import React, { useState, useEffect } from "react";
import { XMarkIcon } from "@heroicons/react/24/outline";
import { useSearchParams } from 'next/navigation';
import { useQueryParamManager } from '../../hooks/useQueryParamManager'; // 引入自定义Hook

export default function Search() {
  const searchParams = useSearchParams();
  // 从URL读取初始搜索值，如果不存在则为空字符串
  const initialSearch = searchParams.get('search') || '';
  const [searchQuery, setSearchQuery] = useState(initialSearch);
  const updateQueryParams = useQueryParamManager(); // 使用自定义Hook

  // 确保组件内部状态与URL参数同步（例如，当用户通过浏览器前进/后退时）
  useEffect(() => {
    setSearchQuery(initialSearch);
  }, [initialSearch]);

  const handleInputChange = (e) => {
    const newValue = e.target.value;
    setSearchQuery(newValue);
    // 调用 updateQueryParams 更新 URL
    // 注意：在实际应用中，对于频繁输入的搜索框，通常会加入防抖（debounce）处理，
    // 以避免每次按键都触发路由更新。
    updateQueryParams({ search: newValue });
  };

  const cleanSearch = (e) => {
    e.preventDefault();
    setSearchQuery("");
    // 传入空字符串，将从URL中删除 'search' 参数
    updateQueryParams({ search: '' });
  };

  return (
    <div className="relative">
      <div className="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
        {/* 搜索图标 */}
        <svg
          className="h-5 w-5 text-gray-500"
          aria-hidden="true"
          fill="currentColor"
          viewBox="0 0 20 20"
          xmlns="http://www.w3.org/2000/svg"
        >
          <path
            fillRule="evenodd"
            d="M8 4a4 4 0 100 8 4 4 0 000-8zM2 8a6 6 0 1110.89 3.476l4.817 4.817a1 1 0 01-1.414 1.414l-4.816-4.816A6 6 0 012 8z"
            clipRule="evenodd"
          ></path>
        </svg>
      </div>
      &lt;input
        type=&quot;search&quot;
        id=&quot;default-search&quot;
        className=&quot;block w-full rounded-lg border border-slate-300 bg-slate-50 p-4 pl-10 text-sm  placeholder-slate-400 focus:border-blue-500 focus:ring-blue-500&quot;
        placeholder=&quot;Search AI tool or category&quot;
        required
        value={searchQuery}
        onChange={handleInputChange}
      /&gt;
      {searchQuery && (
        <button
          type="button"
          onClick={cleanSearch}
          className="absolute inset-y-0 right-0 flex items-center pr-3"
          aria-label="Clear search"
        >
          <XMarkIcon className="h-5 w-5 text-gray-500" aria-hidden="true" />
        </button>
      )}
    </div>
  );
}

2. 选择器组件 (Selector.js)

对于标签（Category）和价格（Price）等选择器，逻辑类似。

// components/common/Selector.js
"use client";

import React from 'react';
import { useSearchParams } from 'next/navigation';
import { useQueryParamManager } from '../../hooks/useQueryParamManager'; // 引入自定义Hook

export default function Selector({ label, data, paramKey }) {
  const updateQueryParams = useQueryParamManager();
  const searchParams = useSearchParams();
  // 从URL读取当前参数值
  const currentValue = searchParams.get(paramKey) || '';

  const handleChange = (e) => {
    const newValue = e.target.value;
    updateQueryParams({ [paramKey]: newValue });
  };

  return (
    <div>
      <label htmlFor={paramKey} className="sr-only">{label}</label>
      &lt;select
        id={paramKey}
        value={currentValue}
        onChange={handleChange}
        className=&quot;block w-full rounded-lg border border-slate-300 bg-slate-50 p-4 text-sm text-slate-700 focus:border-blue-500 focus:ring-blue-500&quot;
      &gt;
        <option value="">All {label}</option> {/* 默认选项，用于清除该过滤器 */}
        {data.map((item) => (
          <option key={item.value} value={item.value}>
            {item.label}
          </option>
        ))}
      &lt;/select&gt;
    </div>
  );
}

3. 过滤器容器组件 (Filters.js)

现在，Filters组件变得更简洁，因为它不再需要传递useRouter或search等props。每个子组件都独立管理自己的查询参数。

// components/Filters.js
"use client";

import React from "react";
import Search from "./common/Search";
import Selector from "./common/Selector";

export default function Filters({ tags, prices }) {
  return (
    <div className="mb-5 flex w-full grid-cols-4 flex-col gap-3 text-center text-base font-medium text-slate-700 md:grid">
      <Search className="col-span-2 w-full" />
      <Selector label="Category" data={tags} paramKey="tag" />
      <Selector label="Price" data={prices} paramKey="price" />
    </div>
  );
}

注意事项与最佳实践

1. 防抖（Debouncing）：对于像搜索输入框这样会频繁触发onChange事件的组件，直接在handleInputChange中调用updateQueryParams可能会导致过多的路由导航和页面重新渲染。强烈建议为搜索输入添加防抖处理，例如，在用户停止输入500毫秒后才更新URL。
2. 多选过滤器：如果某个过滤器允许选择多个值（例如，多个标签），URLSearchParams.set()会替换现有值。为了支持多选，您需要使用URLSearchParams.append()来添加多个同名参数（例如?tag=food&tag=drink），或者将多个值编码成一个参数（例如?tags=food,drink）。useQueryParamManager需要相应地进行调整，可能需要一个updateMultiValueQueryParams函数。
3. URL编码：URLSearchParams会自动处理值的URL编码和解码，因此您无需手动进行encodeURIComponent或decodeURIComponent。
4. 服务器端渲染（SSR）：useSearchParams和usePathname是客户端钩子。在服务器端渲染时，它们在初始渲染时可能为空或不包含最新的URL信息。通常，这不会影响客户端交互，因为一旦组件在客户端水合（hydrate），它们就会获取到正确的URL参数。
5. 清除所有过滤器：可以添加一个“清除所有过滤器”按钮，该按钮会调用router.push(pathname)来导航到不带任何查询参数的原始路径。
6. 错误处理：虽然URLSearchParams

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~