useSearchParams

useSearchParams は、現在の URL のクエリ文字列を読み取ることができるクライアントコンポーネント用のフックです。

useSearchParams は、URLSearchParams インターフェースの読み取り専用バージョンを返します。

'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 は、URL のクエリ文字列を読み取るためのユーティリティメソッドを含む URLSearchParams インターフェースの読み取り専用バージョンを返します:

URLSearchParams.get(): 検索パラメータに関連付けられた最初の値を返します。例:

URL searchParams.get("a")
/dashboard?a=1 '1'
/dashboard?a= ''
/dashboard?b=3 null
/dashboard?a=1&a=2 '1' - すべての値を取得するには getAll() を使用
URLSearchParams.has(): 指定されたパラメータが存在するかどうかを示すブール値を返します。例:

URL searchParams.has("a")
/dashboard?a=1 true
/dashboard?b=3 false
URLSearchParams の他の読み取り専用メソッドについて詳しく学びましょう。これには getAll()、keys()、values()、entries()、forEach()、toString() が含まれます。

URL	`searchParams.get("a")`
`/dashboard?a=1`	`'1'`
`/dashboard?a=`	`''`
`/dashboard?b=3`	`null`
`/dashboard?a=1&a=2`	`'1'` - すべての値を取得するには `getAll()` を使用

URL	`searchParams.has("a")`
`/dashboard?a=1`	`true`
`/dashboard?b=3`	`false`

知っておくと良いこと:

useSearchParams はクライアントコンポーネント用のフックであり、部分レンダリング中に古い値が表示されるのを防ぐため、サーバーコンポーネントではサポートされていません。

アプリケーションに /pages ディレクトリが含まれている場合、useSearchParams は ReadonlyURLSearchParams | null を返します。null 値は移行時の互換性のためであり、getServerSideProps を使用しないページのプリレンダリング中は検索パラメータが認識できないためです。

動作

静的レンダリング

ルートが静的レンダリングされている場合、useSearchParams を呼び出すと、最も近い Suspense 境界までのクライアントコンポーネントツリーがクライアントサイドでレンダリングされます。

これにより、ルートの一部を静的にレンダリングしながら、useSearchParams を使用する動的な部分をクライアントサイドでレンダリングできます。

useSearchParams を使用するクライアントコンポーネントを <Suspense/> 境界で囲むことを推奨します。これにより、その上のクライアントコンポーネントを静的にレンダリングし、初期 HTML の一部として送信できます。例。

例:

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  // 静的レンダリングを使用している場合、サーバーではログに記録されません
  console.log(search)

  return <>Search: {search}</>
}

動的レンダリング

ルートが動的レンダリングされている場合、useSearchParams はクライアントコンポーネントの初期サーバーレンダリング中にサーバーで利用可能になります。

例:

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  // 初期レンダリング時はサーバーでログに記録され、
  // その後ナビゲーション時はクライアントで記録されます。
  console.log(search)

  return <>Search: {search}</>
}

知っておくと良いこと: dynamic ルートセグメント設定オプションを force-dynamic に設定すると、動的レンダリングを強制できます。

'use client'

export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()

  // 現在の searchParams と提供されたキー/値のペアをマージして、
  // 新しい searchParams 文字列を取得します
  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>

      {/* useRouter を使用 */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>

      {/* <Link> を使用 */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}

バージョン履歴

バージョン	変更点
`v13.0.0`	`useSearchParams` が導入されました。

パラメータ

返り値

動作

静的レンダリング

動的レンダリング

サーバーコンポーネント

ページ

レイアウト

例

`searchParams` の更新

バージョン履歴

On this page