跳到內容
API 參考函式useSearchParams

useSearchParams

useSearchParams 是一個 客戶端元件 Hook，可讓你讀取目前 URL 的查詢字串。

useSearchParams 回傳 URLSearchParams 介面的唯讀版本。

app/dashboard/search-bar.tsx
'use client'
 
import { useSearchParams } from 'next/navigation'
 
export default function SearchBar() {
  const searchParams = useSearchParams()
 
  const search = searchParams.get('search')
 
  // URL -> `/dashboard?search=my-project`
  // `search` -> 'my-project'
  return <>Search: {search}</>
}

參數 

const searchParams = useSearchParams()

useSearchParams 不接受任何參數。

回傳值

useSearchParams 回傳 URLSearchParams 介面的唯讀版本，其中包含用於讀取 URL 查詢字串的實用方法

要知道:

  • useSearchParams 是一個 客戶端元件 Hook，在 伺服器元件 中不支援，以防止在部分渲染期間產生過時的值。
  • 如果應用程式包含 /pages 目錄，useSearchParams 將回傳 ReadonlyURLSearchParams | null。null 值用於遷移期間的相容性，因為在使用 getServerSideProps 的頁面預先渲染期間，搜尋參數是未知的

行為

靜態渲染

如果路由是靜態渲染，呼叫 useSearchParams 將導致客戶端元件樹狀結構向上到最近的 Suspense 邊界 進行客戶端渲染。

這允許路由的一部分進行靜態渲染，而使用 useSearchParams 的動態部分則進行客戶端渲染。

我們建議將使用 useSearchParams 的客戶端元件包裝在 <Suspense/> 邊界中。這將允許其上方的任何客戶端元件進行靜態渲染，並作為初始 HTML 的一部分傳送。範例。

例如

app/dashboard/search-bar.tsx
'use client'
 
import { useSearchParams } from 'next/navigation'
 
export default function SearchBar() {
  const searchParams = useSearchParams()
 
  const search = searchParams.get('search')
 
  // This will not be logged on the server when using static rendering
  console.log(search)
 
  return <>Search: {search}</>
}
app/dashboard/page.tsx
import { Suspense } from 'react'
import SearchBar from './search-bar'
 
// This component passed as a fallback to the Suspense boundary
// will be rendered in place of the search bar in the initial HTML.
// When the value is available during React hydration the fallback
// will be replaced with the `<SearchBar>` component.
function SearchBarFallback() {
  return <>placeholder</>
}
 
export default function Page() {
  return (
    <>
      <nav>
        <Suspense fallback={<SearchBarFallback />}>
          <SearchBar />
        </Suspense>
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

動態渲染

如果路由是動態渲染，useSearchParams 將在客戶端元件的初始伺服器渲染期間在伺服器上可用。

例如

app/dashboard/search-bar.tsx
'use client'
 
import { useSearchParams } from 'next/navigation'
 
export default function SearchBar() {
  const searchParams = useSearchParams()
 
  const search = searchParams.get('search')
 
  // This will be logged on the server during the initial render
  // and on the client on subsequent navigations.
  console.log(search)
 
  return <>Search: {search}</>
}
app/dashboard/page.tsx
import SearchBar from './search-bar'
 
export const dynamic = 'force-dynamic'
 
export default function Page() {
  return (
    <>
      <nav>
        <SearchBar />
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

要知道：設定 dynamic 路由區段設定選項 為 force-dynamic 可用於強制動態渲染。

伺服器元件

頁面

若要在頁面 (伺服器元件) 中存取搜尋參數，請使用 searchParams 屬性。

版面配置

與頁面不同，版面配置 (伺服器元件) 不會接收 searchParams 屬性。這是因為共用版面配置在導航期間不會重新渲染，這可能會導致導航之間產生過時的 searchParams。檢視詳細說明。

相反地，請在客戶端元件中使用頁面的 searchParams 屬性或 useSearchParams Hook，這會在用戶端使用最新的 searchParams 重新渲染。

範例

更新 searchParams

你可以使用 useRouter 或 Link 設定新的 searchParams。執行導航後，目前的 page.js 將收到更新的 searchParams 屬性。

app/example-client-component.tsx
'use client'
 
export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()
 
  // Get a new searchParams string by merging the current
  // searchParams with a provided key/value pair
  const createQueryString = useCallback(
    (name: string, value: string) => {
      const params = new URLSearchParams(searchParams.toString())
      params.set(name, value)
 
      return params.toString()
    },
    [searchParams]
  )
 
  return (
    <>
      <p>Sort By</p>
 
      {/* using useRouter */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>
 
      {/* using <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}

版本歷史

版本變更
v13.0.0引入 useSearchParams。