使用 useSearchParams 同步 URL 和查詢參數(shù)

在開發(fā) React 應(yīng)用時，我們經(jīng)常遇到一種場景：用戶在搜索框輸入關(guān)鍵詞，篩選出一個列表，然后希望把這個結(jié)果分享給同事。

如果我們將篩選條件僅僅保存在組件的 useState 中，一旦刷新頁面或復(fù)制鏈接，這些狀態(tài)就會丟失，用戶看到的只能是初始頁面。

為了解決這個問題，我們需要將狀態(tài)“提升”到 URL 的查詢參數(shù)（Query Params）中。在 React Router v6 中，useSearchParams 這個 Hook 就是專門用來處理這個問題的。

本文將介紹如何使用它來實現(xiàn) URL 與應(yīng)用狀態(tài)的同步。

為什么要同步狀態(tài)到 URL

在單頁應(yīng)用（SPA）中，URL 不僅僅是頁面的地址，它還應(yīng)該承載頁面的狀態(tài)。

將查詢參數(shù)（如 ?q=react&page=1）綁定到 URL 有以下幾個顯而易見的好處：

1. 可分享性：用戶直接復(fù)制 URL 發(fā)送給他人，對方打開后看到的內(nèi)容與發(fā)送者完全一致。
2. 持久性：刷新頁面后，搜索條件和頁碼不會丟失。
3. 瀏覽器歷史：用戶可以使用瀏覽器的“后退”按鈕回到上一次的搜索結(jié)果。

基本用法

useSearchParams 的用法與 React 原生的 useState 非常相似。它返回一個數(shù)組，包含兩個元素：當前的查詢參數(shù)對象和一個更新查詢參數(shù)的函數(shù)。

import { useSearchParams } from "react-router-dom"

const [searchParams, setSearchParams] = useSearchParams()

• searchParams：這是一個 URLSearchParams 對象，用于讀取當前的 URL 參數(shù)。
• setSearchParams：這是一個函數(shù)，用于設(shè)置新的 URL 參數(shù)，并觸發(fā)組件重新渲染。

讀取參數(shù)

假設(shè)當前的 URL 是 http://localhost:3000/search?q=javascript。

要獲取 q 參數(shù)的值，我們使用 standard URLSearchParams API 中的 .get() 方法。

const query = searchParams.get("q") // 返回 "javascript"

注意：URLSearchParams 獲取到的值默認都是字符串。如果你在處理頁碼（如 ?page=1），獲取到的將是字符串 "1"，在使用前可能需要通過 parseInt 或 Number 進行轉(zhuǎn)換。

寫入?yún)?shù)

要更新 URL 上的參數(shù)，我們調(diào)用 setSearchParams。這會更新 URL 的查詢字符串，并自動將新的記錄添加到瀏覽器的歷史堆棧中。

// 將 URL 更新為 /search?q=react
setSearchParams({ q: "react" })

如果你想保留現(xiàn)有的其他參數(shù)（例如在切換頁碼時保留搜索關(guān)鍵詞），你需要手動合并對象，或者傳入一個回調(diào)函數(shù)（取決于 React Router 的具體版本行為，通常直接傳入新對象會替換舊對象，因此建議顯式構(gòu)建新對象）。

構(gòu)建一個可分享的搜索組件

下面我們通過一個完整的示例，來實現(xiàn)一個“輸入即搜索”且狀態(tài)同步到 URL 的功能。

需求分析

• 有一個輸入框，用于輸入搜索關(guān)鍵詞。
• 輸入框的值（Value）應(yīng)該受控于 URL 中的 q 參數(shù)。
• 當用戶輸入時，更新 URL 參數(shù)。
• 頁面根據(jù) URL 參數(shù)展示結(jié)果。

代碼實現(xiàn)

import React from "react"
import { useSearchParams } from "react-router-dom"

function SearchPage() {
  // 1. 初始化 hook
  const [searchParams, setSearchParams] = useSearchParams()

  // 2. 讀取參數(shù)：獲取 URL 中的 'q'，如果沒有則默認為空字符串
  const query = searchParams.get("q") || ""

  // 3. 事件處理：當 input 變化時，更新 URL
  const handleInputChange = (event) => {
    const value = event.target.value

    if (value) {
      // 設(shè)置參數(shù)，URL 會變?yōu)??q=輸入值
      setSearchParams({ q: value })
    } else {
      // 如果清空了輸入，最好也移除參數(shù)，保持 URL 干凈
      setSearchParams({})
    }
  }

  return (
    <div style={{ padding: "20px" }}>
      <h2>搜索示例</h2>

      {/* 輸入框綁定 */}
      <input
        type="text"
        value={query}
        onChange={handleInputChange}
        placeholder="請輸入搜索內(nèi)容..."
        style={{ padding: "8px", width: "300px" }}
      />

      {/* 模擬展示結(jié)果 */}
      <div style={{ marginTop: "20px" }}>
        <p>
          當前的搜索關(guān)鍵詞是：<strong>{query}</strong>
        </p>
        <p style={{ color: "#666", fontSize: "14px" }}>
          試著復(fù)制現(xiàn)在的瀏覽器地址欄 URL 分享給別人，他們將看到同樣的關(guān)鍵詞。
        </p>
      </div>
    </div>
  )
}

export default SearchPage

代碼解析

這個組件的核心邏輯在于：輸入框的狀態(tài)不再由 useState 管理，而是直接由 searchParams 驅(qū)動。

• 讀取階段：組件渲染時，直接從 URL 讀取 q 賦值給 input 的 value。這意味著，如果用戶是通過帶有參數(shù)的鏈接進來的（例如 /search?q=hello），輸入框里會自動填充 "hello"。
• 寫入階段：用戶輸入時，調(diào)用 setSearchParams。這會修改 URL，URL 變化導(dǎo)致組件重新渲染，輸入框的值隨之更新。這是一個完美的閉環(huán)。

進階細節(jié)

在使用 useSearchParams 時，還有兩個細節(jié)值得注意。

防抖（Debounce）

上面的例子中，用戶每輸入一個字母，URL 就會更新一次，瀏覽器的歷史記錄也會增加一條。這在實際體驗中可能不僅對性能有影響，也會讓用戶的“后退”操作變得困難（需要按很多次后退才能回到上一個頁面）。

通常，我們會配合“防抖”技術(shù)，在用戶停止輸入 300ms 或 500ms 后再更新 URL?；蛘?，使用 setSearchParams 的 replace 選項：

setSearchParams({ q: value }, { replace: true })

設(shè)置 replace: true 會替換當前的歷史記錄項，而不是新增一條，這樣用戶點擊“后退”時會直接回到進入搜索頁之前的頁面。

處理復(fù)雜對象

URL 參數(shù)本質(zhì)上是字符串。如果你需要存儲復(fù)雜的篩選對象（例如多選標簽、日期范圍），通常需要自行序列化。

• 寫入時：將數(shù)組或?qū)ο筠D(zhuǎn)換為字符串（如逗號分隔 tags=vue,react）。
• 讀取時：將字符串拆解回數(shù)組。

以上就是React使用useSearchParams同步URL和查詢參數(shù)的方法的詳細內(nèi)容，更多關(guān)于React useSearchParams同步URL和查詢參數(shù)的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論