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

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

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

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

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

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

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

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

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

基本用法

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

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

const [searchParams, setSearchParams] = useSearchParams()

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

讀取參數(shù)

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

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

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

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

寫(xiě)入?yún)?shù)

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

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

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

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

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

需求分析

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

代碼實(shí)現(xiàn)

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

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

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

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

    if (value) {
      // 設(shè)置參數(shù)，URL 會(huì)變?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="請(qǐng)輸入搜索內(nèi)容..."
        style={{ padding: "8px", width: "300px" }}
      />

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

export default SearchPage

代碼解析

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

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

進(jìn)階細(xì)節(jié)

在使用 useSearchParams 時(shí)，還有兩個(gè)細(xì)節(jié)值得注意。

防抖（Debounce）

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

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

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

設(shè)置 replace: true 會(huì)替換當(dāng)前的歷史記錄項(xiàng)，而不是新增一條，這樣用戶點(diǎn)擊“后退”時(shí)會(huì)直接回到進(jìn)入搜索頁(yè)之前的頁(yè)面。

處理復(fù)雜對(duì)象

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

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

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

最新評(píng)論