alang.ai

006 搜索与分页，searchParams ​

目录

本文对应 Next.js Learn 入门教程的第 11 章。

Learn how to use the Next.js APIs: searchParams, usePathname, and useRouter.

Implement search and pagination using URL search params.

准备 ​

为什么使用URL查询参数？ ​

Why use URL search params?

As mentioned above, you'll be using URL search params to manage the search state. This pattern may be new if you're used to doing it with client side state.

There are a couple of benefits of implementing search with URL params:

  • Bookmarkable and Shareable URLs: Since the search parameters are in the URL, users can bookmark the current state of the application, including their search queries and filters, for future reference or sharing.
  • Server-Side Rendering and Initial Load: URL parameters can be directly consumed on the server to render the initial state, making it easier to handle server rendering.
  • Analytics and Tracking: Having search queries and filters directly in the URL makes it easier to track user behavior without requiring additional client-side logic.

为什么使用URL查询参数？

如上所述，你将使用URL查询参数来管理搜索状态。如果你习惯了使用客户端状态来处理搜索，那么这种模式可能对你来说是新的。

使用URL参数实现搜索有几个好处：

  • 可书签和可共享的URL：因为搜索参数在URL中，用户可以将应用程序的当前状态（包括他们的搜索查询和过滤器）加入书签，以供将来参考或分享。
  • 服务端渲染和初始加载：在服务器上可以直接消费URL参数以渲染初始状态，这使得处理服务器渲染变得更加容易。
  • 分析和追踪：将搜索查询和过滤器直接放在URL中，可以更轻松地跟踪用户行为，而无需额外的客户端逻辑。

invoices 代码 ​

/dashboard/invoices/page.tsx

tsx
import Pagination from '@/app/ui/invoices/pagination';
import Search from '@/app/ui/search';
import Table from '@/app/ui/invoices/table';
import { CreateInvoice } from '@/app/ui/invoices/buttons';
import { lusitana } from '@/app/ui/fonts';
import { InvoicesTableSkeleton } from '@/app/ui/skeletons';
import { Suspense } from 'react';

export default async function Page() {
  return (
    <div className="w-full">
      <div className="flex w-full items-center justify-between">
        <h1 className={`${lusitana.className} text-2xl`}>Invoices</h1>
      </div>
      <div className="mt-4 flex items-center justify-between gap-2 md:mt-8">
        <Search placeholder="Search invoices..." />
        <CreateInvoice />
      </div>
      {/*  <Suspense key={query + currentPage} fallback={<InvoicesTableSkeleton />}>
        <Table query={query} currentPage={currentPage} />
      </Suspense> */}
      <div className="mt-5 flex w-full justify-center">
        {/* <Pagination totalPages={totalPages} /> */}
      </div>
    </div>
  );
}

实现：添加搜索功能 ​

useSearchParams usePathname useRouter ​

Adding the search functionality

These are the Next.js client hooks that you'll use to implement the search functionality:

  • useSearchParams- Allows you to access the parameters of the current URL. For example, the search params for this URL /dashboard/invoices?page=1&query=pending would look like this: {page: '1', query: 'pending'}.
  • usePathname - Lets you read the current URL's pathname. For example, for the route /dashboard/invoices, usePathname would return '/dashboard/invoices'.
  • useRouter - Enables navigation between routes within client components programmatically. There are multiple methods you can use.

Here's a quick overview of the implementation steps:

  1. Capture the user's input.
  2. Update the URL with the search params.
  3. Keep the URL in sync with the input field.
  4. Update the table to reflect the search query.

以下是你将用于实现搜索功能的Next.js 的 Client Hook：

  • useSearchParams - 允许你访问当前URL的参数。例如，这个URL /dashboard/invoices?page=1&query=pending 的搜索参数将是这样的：{page: '1', query: 'pending'}。

  • usePathname - 允许你读取当前URL的路径名（pathname）。例如，对于路由 /dashboard/invoices，usePathname 将返回 '/dashboard/invoices'。

  • useRouter - 可以在客户端组件中以编程方式实现路由之间的导航。你可以使用多个方法。

以下是实现步骤的简要概述：

  1. 捕获用户的输入。
  2. 使用搜索参数更新URL。
  3. 保持URL与输入字段同步。
  4. 更新表格以反映搜索查询。

1. 捕获用户的输入 ​

<Search> 组件

tsx
'use client';

import { MagnifyingGlassIcon } from '@heroicons/react/24/outline';

export default function Search({ placeholder }: { placeholder: string }) {
  function handleSearch(term: string) {
    console.log(term);
  }

  return (
    <div className="relative flex flex-1 flex-shrink-0">
      <label htmlFor="search" className="sr-only">
        Search
      </label>
      <input
        className="peer block w-full rounded-md border border-gray-200 py-[9px] pl-10 text-sm outline-2 placeholder:text-gray-500"
        placeholder={placeholder}
        onChange={(e) => {
          handleSearch(e.target.value);
        }}
      />
      <MagnifyingGlassIcon className="absolute left-3 top-1/2 h-[18px] w-[18px] -translate-y-1/2 text-gray-500 peer-focus:text-gray-900" />
    </div>
  );
}

2. 使用搜索参数更新URL ​

Import the useSearchParams hook from 'next/navigation', and assign it to a variable:

tsx
'use client';

import { MagnifyingGlassIcon } from '@heroicons/react/24/outline';
import { useSearchParams } from 'next/navigation';

export default function Search() {
  const searchParams = useSearchParams();

  function handleSearch(term: string) {
    console.log(term);
  }
  // ...
}

Inside handleSearch, create a new URLSearchParams instance using your new searchParams variable.

tsx
'use client';

import { MagnifyingGlassIcon } from '@heroicons/react/24/outline';
import { useSearchParams } from 'next/navigation';

export default function Search() {
  const searchParams = useSearchParams();

  function handleSearch(term: string) {
    const params = new URLSearchParams(searchParams);
  }
  // ...
}

URLSearchParams is a Web API that provides utility methods for manipulating the URL query parameters. Instead of creating a complex string literal, you can use it to get the params string like ?page=1&query=a.

Next, set the params string based on the user’s input. If the input is empty, you want to delete it:

tsx
'use client';

import { MagnifyingGlassIcon } from '@heroicons/react/24/outline';
import { useSearchParams } from 'next/navigation';

export default function Search() {
  const searchParams = useSearchParams();

  function handleSearch(term: string) {
    const params = new URLSearchParams(searchParams);
    if (term) {
      params.set('query', term);
    } else {
      params.delete('query');
    }
  }
  // ...
}

Now that you have the query string. You can use Next.js's useRouter and usePathname hooks to update the URL.

Import useRouter and usePathname from 'next/navigation', and use the replace method from useRouter() inside handleSearch:

tsx
'use client';

import { MagnifyingGlassIcon } from '@heroicons/react/24/outline';
import { useSearchParams, usePathname, useRouter } from 'next/navigation';

export default function Search() {
  const searchParams = useSearchParams();
  const pathname = usePathname();
  const { replace } = useRouter();

  function handleSearch(term: string) {
    const params = new URLSearchParams(searchParams);
    if (term) {
      params.set('query', term);
    } else {
      params.delete('query');
    }
    replace(`${pathname}?${params.toString()}`);
  }
}

Here's a breakdown of what's happening:

  • ${pathname} is the current path, in your case, "/dashboard/invoices".
  • As the user types into the search bar, params.toString() translates this input into a URL-friendly format.
  • replace(${pathname}?${params.toString()}) updates the URL with the user's search data. For example, /dashboard/invoices?query=lee if the user searches for "Lee".
  • The URL is updated without reloading the page, thanks to Next.js's client-side navigation (which you learned about in the chapter on navigating between pages.

以下是详细解释：

  • ${pathname} 是当前路径，在你的例子中，为 "/dashboard/invoices"。
  • 当用户在搜索栏中输入时，params.toString() 将这些输入转换为友好的URL格式。
  • replace(${pathname}?${params.toString()}) 使用用户的搜索数据更新URL。例如，如果用户搜索 "Lee"，则为 /dashboard/invoices?query=lee。
  • 多亏了 Next.js 的客户端导航（你在页面间导航的章节中了解过），页面不会重新加载即可更新 URL。

3. 保持URL与输入字段同步 ​

To ensure the input field is in sync with the URL and will be populated when sharing, you can pass a defaultValue to input by reading from searchParams:

tsx
<input
  className="peer block w-full rounded-md border border-gray-200 py-[9px] pl-10 text-sm outline-2 placeholder:text-gray-500"
  placeholder={placeholder}
  onChange={(e) => {
    handleSearch(e.target.value);
  }}
  defaultValue={searchParams.get('query')?.toString()}
/>

INFO

defaultValue vs. value / Controlled vs. Uncontrolled

If you're using state to manage the value of an input, you'd use the value attribute to make it a controlled component. This means React would manage the input's state.

However, since you're not using state, you can use defaultValue. This means the native input will manage its own state. This is okay since you're saving the search query to the URL instead of state.

如果你正在使用状态(state)来管理输入框(input)的值，那么你应该使用 value 属性将其变为受控组件(controlled component)。这意味着React将管理输入框的状态(state)。

然而，由于你没有使用状态(state)，你可以使用 defaultValue。这意味着原生输入框(native input)将管理自身的状态(state)。既然你是将搜索查询保存到URL中，而非状态(state)，这样做是可行的。

4. 更新表格以反映搜索查询 ​

函数对比
tsx
export default async function Page() {
tsx
export default async function Page({
  searchParams,
}: {
  searchParams?: {
    query?: string;
    page?: string;
  };
}) {
tsx
import Pagination from '@/app/ui/invoices/pagination';
import Search from '@/app/ui/search';
import Table from '@/app/ui/invoices/table';
import { CreateInvoice } from '@/app/ui/invoices/buttons';
import { lusitana } from '@/app/ui/fonts';
import { Suspense } from 'react';
import { InvoicesTableSkeleton } from '@/app/ui/skeletons';

export default async function Page({
  searchParams,
}: {
  searchParams?: {
    query?: string;
    page?: string;
  };
}) {
  const query = searchParams?.query || '';
  const currentPage = Number(searchParams?.page) || 1;

  return (
    <div className="w-full">
      <div className="flex w-full items-center justify-between">
        <h1 className={`${lusitana.className} text-2xl`}>Invoices</h1>
      </div>
      <div className="mt-4 flex items-center justify-between gap-2 md:mt-8">
        <Search placeholder="Search invoices..." />
        <CreateInvoice />
      </div>
      <Suspense key={query + currentPage} fallback={<InvoicesTableSkeleton />}>
        <Table query={query} currentPage={currentPage} />
      </Suspense>
      <div className="mt-5 flex w-full justify-center">
        {/* <Pagination totalPages={totalPages} /> */}
      </div>
    </div>
  );
}

INFO

When to use the useSearchParams() hook vs. the searchParams prop?

You might have noticed you used two different ways to extract search params. Whether you use one or the other depends on whether you're working on the client or the server.

  • <Search> is a Client Component, so you used the useSearchParams() hook to access the params from the client.
  • <Table> is a Server Component that fetches its own data, so you can pass the searchParams prop from the page to the component.

As a general rule, if you want to read the params from the client, use the useSearchParams() hook as this avoids having to go back to the server.

当何时使用 useSearchParams() Hook vs searchParams 属性？

你可能已经注意到，在提取搜索参数时使用了两种不同的方式。选择使用哪一个取决于你是在客户端还是服务器端进行工作。

  • <Search> 是一个客户端组件，因此你通过 useSearchParams() 钩子来从客户端访问参数。
  • <Table> 是一个在服务器端获取数据的服务端组件，因此你可以从页面向组件传递 searchParams 属性。

作为一个基本原则，如果你希望从客户端读取参数，请使用 useSearchParams() 钩子，因为这样可以避免不必要的回到服务器端。

没太看懂，需要再次细看

最佳实践: Debouncing 防抖 ​

https://nextjs.org/learn/dashboard-app/adding-search-and-pagination#best-practice-debouncing

概念解释 ​

Debouncing 解释

Debouncing 是一种编程实践，用于限制函数的执行频率。这在处理一些高频触发的事件（如键盘输入、滚动、窗口大小调整等）时非常有用。

Debouncing 的工作原理如下：

  1. 触发事件：当一个需要被防抖的事件（如搜索框中的按键输入）发生时，启动一个定时器。
  2. 等待：如果在定时器到期之前发生了新的事件，那么定时器就会被重置。
  3. 执行：如果定时器到达了倒计时的结束，那么防抖函数就会被执行。

在 JavaScript 中，你可以使用 setTimeout 和 clearTimeout 函数来实现防抖。以下是一个简单的防抖函数的实现：

javascript
function debounce(func, wait) {
  let timeout;
  return function(...args) {
    clearTimeout(timeout);
    timeout = setTimeout(() => func.apply(this, args), wait);
  };
}

在这个函数中，func 是需要被防抖的函数，wait 是等待的时间（以毫秒为单位）。这个函数返回一个新的函数，这个新的函数在被连续调用时，只有在最后一次调用后的 wait 毫秒后才会执行 func 函数。

You're updating the URL on every keystroke, and therefore querying your database on every keystroke! This isn't a problem as our application is small, but imagine if your application had thousands of users, each sending a new request to your database on each keystroke.

Debouncing is a programming practice that limits the rate at which a function can fire. In our case, you only want to query the database when the user has stopped typing.

How Debouncing Works:

  1. Trigger Event: When an event that should be debounced (like a keystroke in the search box) occurs, a timer starts.
  2. Wait: If a new event occurs before the timer expires, the timer is reset.
  3. Execution: If the timer reaches the end of its countdown, the debounced function is executed.

You can implement debouncing in a few ways, including manually creating your own debounce function. To keep things simple, we'll use a library called use-debounce.

你正在每次键入时更新URL，并因此在每次键入时都会查询数据库！鉴于我们的应用程序规模较小，这不成问题，但如果想象一下，你的应用程序拥有成千上万的用户，每个用户在每次键入时都向数据库发送新的请求。

防抖是一种编程实践，旨在限制函数触发的频率。在我们的案例中，你只想在用户停止键入时查询数据库。

如何实现防抖:

  1. 触发事件: 当需要被防抖的事件发生时（如搜索框中的键入），一个计时器就开始运行。
  2. 等待: 如果在计时器结束之前发生新事件，计时器将重置。
  3. 执行: 如果计时器倒计时结束，那么防抖后的函数就会被执行。

你可以通过几种方式实现防抖，包括手动创建自己的防抖函数。为了简单起见，我们将使用一个名为use-debounce的库来实现。

use-debounce ​

安装：

bash
npm i use-debounce

使用：

tsx
// ...
import { useDebouncedCallback } from 'use-debounce';

// Inside the Search Component...
const handleSearch = useDebouncedCallback((term) => {
  console.log(`Searching... ${term}`);

  const params = new URLSearchParams(searchParams);
  if (term) {
    params.set('query', term);
  } else {
    params.delete('query');
  }
  replace(`${pathname}?${params.toString()}`);
}, 300);

useDebouncedCallback 接受一个函数作为参数，这个函数是需要被防抖的函数。在这个例子中，这个函数是 (term) =>

This function will wrap the contents of handleSearch, and only run the code after a specific time once the user has stopped typing (300ms).

该函数将封装 handleSearch 的内容，并且只有在用户停止输入后的特定时间（300毫秒）才会执行代码。

添加分页 ​

Navigate to the <Pagination/> component and you'll notice that it's a Client Component. You don't want to fetch data on the client as this would expose your database secrets (remember, you're not using an API layer). Instead, you can fetch the data on the server, and pass it to the component as a prop.

In /dashboard/invoices/page.tsx, import a new function called fetchInvoicesPages and pass the query from searchParams as an argument:

查看 <Pagination/> 组件，你会注意到这是一个客户端组件。你不希望在客户端请求数据，因为这将暴露你的数据库秘钥（记住，你并未使用 API 层）。相反，你可以在服务器端请求数据，并将其作为属性传递至组件。

在 /dashboard/invoices/page.tsx 中，导入一个名为 fetchInvoicesPages 的新函数，并将来自 searchParams 的 query 作为参数传递给它：

……

此处查看详细细节：https://nextjs.org/learn/dashboard-app/adding-search-and-pagination#adding-pagination

同时值得看 Pagenation 的具体实现。

重要待补

Alang.AI - Make Great AI Applications

Copyright © 2025