Next.jsで学ぶReact講座 90日コース | Next.js基礎 - Day 47:検索機能

React Next.jsで学ぶReact講座90日コース
スポンサーリンク

Day 47:URLパラメータを使った検索機能を作る

Day 47では、Next.js App RouterでURLパラメータを使った検索機能を作ります。今日は、/products?keyword=react のようなURLを使って、検索キーワードに応じて商品一覧を絞り込む仕組みを、初心者向けに順番に理解していきます。App Routerでは、Server Componentのページで searchParams を受け取り、Client Componentでは useSearchParams、usePathname、useRouter を使ってURLを書き換えるのが基本です。useSearchParams は読み取り専用で、Client Component専用のHookです。(🔗 nextjs.org)

この機能のよいところは、検索条件がURLに残ることです。つまり、検索した状態のURLをそのまま共有できますし、再読み込みしても同じ検索結果を再現しやすくなります。また、ページ側で searchParams を使ってデータ取得や絞り込みを行うのが、Next.js公式でも推奨される基本パターンです。(🔗 nextjs.org)

スポンサーリンク

まず理解したいこと

検索機能といっても、今回やることはとてもシンプルです。URLの ? 以降にあるクエリ文字列を読み取り、その値で配列データを絞り込みます。たとえば、/products?keyword=react なら、keyword という名前の検索条件に react が入っている、という意味です。ページ側では searchParams からその値を読み、フォーム側ではURLを書き換えます。Next.jsでは、Server Componentのページは searchParams prop を受け取れ、Client Componentでは useSearchParams() で現在のクエリ文字列を読めます。(🔗 nextjs.org)

  • 検索条件を読む場所は、基本的に `page.tsx` です。
  • 入力欄の操作は、基本的に Client Component で行います。
  • 検索条件をURLに反映するには、`useRouter()` や `Link` を使います。
  • 一覧の絞り込み自体は、Server Component側で行うと整理しやすいです。

今日作る完成イメージ

今日は、/products ページに検索フォームを置き、入力したキーワードをURLに反映して一覧を絞り込みます。完成後のURLは、たとえば次のようになります。

/products
/products?keyword=react
/products?keyword=next
/products?keyword=typescript

今回のファイル構成は次のようにします。

src/
├── app/
│   ├── products/
│   │   ├── SearchForm.tsx
│   │   └── page.tsx
│   └── layout.tsx
└── data/
    └── products.ts

Step 1:検索対象のデータを用意する

まずは検索対象となる商品データを用意します。今回は学習用なので、データベースではなく配列で十分です。

src/data/products.ts

// 商品1件分の型です
export type Product = {
  id: number;
  name: string;
  description: string;
};

// 学習用の商品データです
export const products: Product[] = [
  {
    id: 1,
    name: "React入門書",
    description: "Reactの基本を学べる初心者向けの書籍です。",
  },
  {
    id: 2,
    name: "Next.js実践ガイド",
    description: "App Routerやデータ取得を学べる実践向けの書籍です。",
  },
  {
    id: 3,
    name: "TypeScriptハンドブック",
    description: "型安全な開発を学びたい方向けの書籍です。",
  },
  {
    id: 4,
    name: "React Tシャツ",
    description: "Reactロゴ入りの学習用Tシャツです。",
  },
  {
    id: 5,
    name: "JavaScriptノート",
    description: "フロントエンド学習メモに便利なノートです。",
  },
];
TypeScript

ここでは、name だけでなく description も持たせています。こうしておくと、「商品名だけでなく説明文も検索対象にする」という実践的な練習ができます。

Step 2:searchParams を使って検索するページを作る

次に、/products ページを作ります。App Routerのページでは、searchParams prop を受け取れます。現在のNext.js公式では、searchParams はPromiseとして受け取る形が案内されており、Server Componentのページで検索条件を使ってデータ取得や絞り込みを行うのに向いています。また、searchParams を使うとそのページは動的レンダリングになります。(🔗 nextjs.org)

src/app/products/page.tsx

// 商品データを読み込みます
import { products } from "../../data/products";

// 検索フォームを読み込みます
import SearchForm from "./SearchForm";

// searchParamsの型です
type ProductsPageProps = {
  searchParams: Promise<{
    keyword?: string;
  }>;
};

// 商品一覧ページです
export default async function ProductsPage({
  searchParams,
}: ProductsPageProps) {
  // URLからkeywordを取得します
  const { keyword = "" } = await searchParams;

  // 比較しやすいように小文字へ変換します
  const normalizedKeyword = keyword.trim().toLowerCase();

  // 商品一覧をキーワードで絞り込みます
  const filteredProducts = products.filter((product) => {
    // 商品名と説明文をまとめて小文字化します
    const targetText =
      `${product.name} ${product.description}`.toLowerCase();

    // キーワードが空なら全件表示し、入っていれば部分一致検索します
    return normalizedKeyword === ""
      ? true
      : targetText.includes(normalizedKeyword);
  });

  return (
    <main>
      <h1>商品一覧</h1>
      <p>
        URLパラメータを使って商品を検索します。
      </p>

      {/* 現在の検索キーワードをフォームへ渡します */}
      <SearchForm defaultKeyword={keyword} />

      <p>
        検索キーワード:
        <strong>{keyword === "" ? "未入力" : keyword}</strong>
      </p>

      {filteredProducts.length === 0 ? (
        <p>該当する商品は見つかりませんでした。</p>
      ) : (
        <ul>
          {filteredProducts.map((product) => (
            // 商品一覧を表示します
            <li key={product.id}>
              <h2>{product.name}</h2>
              <p>{product.description}</p>
            </li>
          ))}
        </ul>
      )}
    </main>
  );
}
TSX

このコードで重要なのは、検索条件をURLから読むことと、検索結果をその値で決めることです。searchParams はページで使う検索条件向けの仕組みであり、Client Componentの useSearchParams はあくまでクライアント側で読むためのHookです。公式でも、ページデータの読み込みやフィルタリングにはPageの searchParams prop を使うことが勧められています。(🔗 nextjs.org)

Step 3:検索フォームをClient Componentで作る

次に、検索キーワードを入力してURLを更新するフォームを作ります。ここはブラウザー操作が必要なのでClient Componentにします。useRouter() はClient Component内でプログラム的にルート遷移するためのHookで、App Routerでは next/navigation から読み込みます。useSearchParams() は読み取り専用の URLSearchParams を返し、現在のクエリ文字列を参照できます。(🔗 nextjs.org)

src/app/products/SearchForm.tsx

// このファイルはClient Componentです
"use client";

// フォーム入力を管理するためにuseStateを使います
import { useState } from "react";

// URL操作に使うHookを読み込みます
import { usePathname, useRouter, useSearchParams } from "next/navigation";

// Propsの型です
type SearchFormProps = {
  defaultKeyword: string;
};

// 検索フォームです
export default function SearchForm({
  defaultKeyword,
}: SearchFormProps) {
  // 入力欄の値を管理します
  const [keyword, setKeyword] = useState(defaultKeyword);

  // 現在のURL情報を取得します
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  // フォーム送信時の処理です
  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    // 通常のフォーム送信を止めます
    event.preventDefault();

    // 現在の検索パラメータを複製します
    const params = new URLSearchParams(searchParams.toString());

    // 前後の空白を取り除きます
    const trimmedKeyword = keyword.trim();

    // キーワードが空ならURLから削除します
    if (trimmedKeyword === "") {
      params.delete("keyword");
    } else {
      // キーワードがあるならURLへ設定します
      params.set("keyword", trimmedKeyword);
    }

    // 新しいURLへ移動します
    router.push(`${pathname}?${params.toString()}`);
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={keyword}
        placeholder="キーワードを入力してください"
        // 入力値をstateへ保存します
        onChange={(event) => setKeyword(event.target.value)}
      />
      <button type="submit">検索</button>
    </form>
  );
}
TSX

この実装の考え方はとても大切です。useSearchParams() は読み取り専用なので、そのまま書き換えるのではなく、new URLSearchParams(searchParams.toString()) で新しいものを作ってから更新します。Next.js公式でも、現在の検索条件を複製し、set() で値を変更してから router.push() や Link で遷移する例が紹介されています。(🔗 nextjs.org)

Step 4:なぜServer Component側で絞り込むのか

ここは初心者が迷いやすいポイントです。検索フォームはClient Componentですが、一覧の絞り込みはServer Componentのページ側で行っています。これは、検索条件を使ってページデータを決める処理はPageの searchParams prop で行うのが基本だからです。公式ドキュメントでも、データベースのフィルタリングやページ読み込みに関わる検索条件には searchParams prop を使い、Client側だけで使う値には useSearchParams を使うと整理されています。(🔗 nextjs.org)

つまり、役割は次のように分けると分かりやすいです。

  • 入力するのはClient Componentです。
  • URLを書き換えるのもClient Componentです。
  • そのURLをもとに一覧を決めるのはServer Componentです。

この設計にしておくと、あとで本物のデータベース検索や外部API検索へ発展させやすくなります。

Step 5:/products?keyword=react がどう動くのかを追いかける

ここで、実際の流れを頭の中で整理します。

  • 利用者が検索欄に `react` と入力します。
  • 送信すると、Client Componentが `router.push(“/products?keyword=react”)` を実行します。`useRouter()` はClient Componentでプログラム的なナビゲーションを行うためのHookです。
  • Next.jsがそのURLへ遷移します。
  • ページの `searchParams` に `keyword=react` が渡されます。ページは `searchParams` prop を受け取れます。
  • Server Component側で商品一覧を `react` で絞り込みます。
  • 絞り込まれた結果が表示されます。

この流れが理解できると、検索だけでなく、並び替え、絞り込み、ページネーションにも応用できます。

Step 6:検索条件を消したときの設計も重要

検索機能では、「入力したとき」だけでなく「消したとき」も大切です。今回のコードでは、キーワードが空文字なら params.delete("keyword") を使っています。これにより、/products?keyword= のような中途半端なURLではなく、/products に近い自然な形へ戻しやすくなります。

// キーワードが空ならURLから削除します
if (trimmedKeyword === "") {
  params.delete("keyword");
} else {
  // キーワードがあるならURLへ設定します
  params.set("keyword", trimmedKeyword);
}
TSX

このようにしておくと、URLが読みやすくなり、検索条件がない状態も扱いやすくなります。

Step 7:router.push と router.replace の違いも知っておく

今回の例では router.push() を使いました。useRouter() の push は新しい履歴を追加し、replace は履歴を追加せず現在の履歴を置き換えます。どちらもClient Componentで使えます。(🔗 nextjs.org)

検索機能では、次のように考えると分かりやすいです。

  • 検索のたびに履歴を残したいなら `push` を使います。
  • 細かい入力変更で履歴を増やしすぎたくないなら `replace` を使います。

たとえばリアルタイム検索では replace のほうが向くことが多いですが、今回は「送信して検索する」学習用なので push で十分です。

Step 8:部分一致検索をどう実装しているか

今回の検索は、includes() を使った部分一致検索です。さらに、検索時は大文字・小文字の違いで結果が変わりにくいように、小文字へそろえています。

// 比較しやすいように小文字へ変換します
const normalizedKeyword = keyword.trim().toLowerCase();

// 商品名と説明文をまとめて小文字化します
const targetText =
  `${product.name} ${product.description}`.toLowerCase();

// キーワードが含まれているか確認します
return normalizedKeyword === ""
  ? true
  : targetText.includes(normalizedKeyword);
TSX

このように、検索条件と対象文字列の両方を同じ形にそろえて比較すると、初心者でも安定した検索を作りやすくなります。

Step 9:検索結果が0件のときも必ず考える

検索機能では、結果がある場合だけでなく、見つからない場合の表示も重要です。今回のコードでは、filteredProducts.length === 0 のときに専用メッセージを出しています。

{filteredProducts.length === 0 ? (
  <p>該当する商品は見つかりませんでした。</p>
) : (
  <ul>
    {filteredProducts.map((product) => (
      <li key={product.id}>
        <h2>{product.name}</h2>
        <p>{product.description}</p>
      </li>
    ))}
  </ul>
)}
TSX

この処理がないと、利用者には「何も表示されないだけ」に見えてしまいます。検索機能では、失敗ではなく「該当なし」も普通の状態として丁寧に扱うことが大切です。

Step 10:実務で特に大事な注意点

検索機能は簡単そうに見えますが、実務では注意点があります。

  • URLパラメータは利用者が自由に変更できるので、受け取った値をそのまま信用しないことが大切です。
  • 空文字、長すぎる文字列、想定外の値も来る前提で考えます。
  • 表示用の検索と、データベース問い合わせ用の検索は分けて考えるべきです。

今回の例は配列フィルタなので比較的安全ですが、将来データベース検索へつなぐなら、検索文字列の長さ制限、サニタイズ、バリデーション、必要に応じたレート制限も重要になります。URLパラメータは、フォーム入力と同じく「外部から来る値」として扱う癖をつけると安全です。

Step 11:リアルタイム検索に発展させる考え方

今回は送信ボタン付きの検索フォームでしたが、発展として「入力するたびにURLを更新して検索する」こともできます。その場合も、URL操作には useRouter()、現在値の確認には useSearchParams() が使えます。useSearchParams() はClient Component Hookで、現在のクエリ文字列を読むためのものです。(🔗 nextjs.org)

ただし、初心者向けにはまず送信型の検索をおすすめします。理由は、次の3つです。

  • 処理の流れを追いやすいです。
  • URLの変化を理解しやすいです。
  • 不要な再検索を減らしやすいです。

Step 12:初心者向けテンプレート

最後に、最小テンプレートを載せておきます。

検索ページの最小テンプレート

// searchParamsを受け取るページです
export default async function Page({
  searchParams,
}: {
  // 現在の検索条件を受け取ります
  searchParams: Promise<{ keyword?: string }>;
}) {
  // URLからkeywordを取り出します
  const { keyword = "" } = await searchParams;

  return (
    <main>
      <h1>検索ページ</h1>
      <p>現在のキーワード: {keyword}</p>
    </main>
  );
}
TSX

検索フォームの最小テンプレート

// Client Componentとして使います
"use client";

// 必要なHookを読み込みます
import { useState } from "react";
import { usePathname, useRouter, useSearchParams } from "next/navigation";

// 検索フォームです
export default function SearchForm() {
  // 入力値を管理します
  const [keyword, setKeyword] = useState("");

  // URL操作用のHookです
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  // フォーム送信時の処理です
  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    // 通常送信を止めます
    event.preventDefault();

    // 現在の検索条件を複製します
    const params = new URLSearchParams(searchParams.toString());

    // キーワードを設定します
    params.set("keyword", keyword);

    // URLを更新します
    router.push(`${pathname}?${params.toString()}`);
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={keyword}
        onChange={(event) => setKeyword(event.target.value)}
      />
      <button type="submit">検索</button>
    </form>
  );
}
TSX

Day 47のチェックリスト

  • URLパラメータを使った検索の基本が説明できます。
  • ページで `searchParams` を受け取り、検索条件を読めます。`searchParams` はPageで使うための仕組みです。
  • Client Componentで `useSearchParams()` を使って現在の検索条件を読めます。`useSearchParams` は読み取り専用です。
  • `useRouter()` でURLを書き換えられます。`useRouter` はClient Componentでのプログラム的な遷移に使います。
  • `/products?keyword=react` のようなURLで商品一覧を絞り込めます。
  • 検索結果が0件のときの表示も実装できます。
  • URLパラメータを外部入力として扱う意識を持てます。

まとめ

Day 47では、Next.js App RouterでURLパラメータを使った検索機能を作りました。検索条件はURLのクエリ文字列に持たせ、Server Componentのページでは searchParams prop でその値を受け取り、Client Componentのフォームでは useSearchParams、usePathname、useRouter を使ってURLを更新する、という流れが基本です。公式でも、ページのデータ読み込みに関わる検索条件は searchParams prop を使い、クライアント専用の読み取りには useSearchParams を使う形が案内されています。(🔗 nextjs.org)

この仕組みが理解できると、検索だけでなく、並び替え、カテゴリーフィルター、ページネーションにも発展させやすくなります。つまりDay 47は、ただの検索機能ではなく、URLと画面状態を一致させるNext.jsらしい設計を学ぶ回でもあります。

タイトルとURLをコピーしました