React Router v6：
SPA 路由完整指南

// pages/BlogPost.tsx
// 對應路由：<Route path="/blog/:id" element={<BlogPost />} />
import { useParams } from 'react-router-dom';
import { useState, useEffect } from 'react';

type Post = {
  id: string;
  title: string;
  content: string;
  author: string;
};

function BlogPost() {
  // useParams 回傳一個物件，key 對應路由中的 :參數名稱
  const { id } = useParams<{ id: string }>();
  const [post, setPost] = useState<Post | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    if (!id) return;

    setLoading(true);
    fetch(`/api/posts/${id}`)
      .then(r => {
        if (!r.ok) throw new Error('文章不存在');
        return r.json();
      })
      .then(data => {
        setPost(data);
        setLoading(false);
      })
      .catch(err => {
        setError(err.message);
        setLoading(false);
      });
  }, [id]);  // id 改變時重新 fetch（例如從 /blog/1 navigate 到 /blog/2）

  if (loading) return <div className="p-8 text-center">載入中...</div>;
  if (error) return <div className="p-8 text-center text-red-500">{error}</div>;
  if (!post) return null;

  return (
    <article className="max-w-2xl mx-auto p-8">
      <h1 className="text-3xl font-bold mb-4">{post.title}</h1>
      <p className="text-gray-500 mb-6">作者：{post.author}</p>
      <div className="prose">{post.content}</div>
    </article>
  );
}

// 路由定義
<Route path="/users/:userId/posts/:postId" element={<UserPost />} />

// 元件中取得多個參數
function UserPost() {
  const { userId, postId } = useParams<{ userId: string; postId: string }>();

  // URL: /users/42/posts/100
  // userId = "42"
  // postId = "100"

  // 注意：useParams 回傳的值永遠是 string
  // 如果需要數字，需要自行轉換：
  const numericId = Number(postId);

  return (
    <div>
      <h1>使用者 {userId} 的文章 #{postId}</h1>
    </div>
  );
}

// 更多動態路由範例：
// /products/:category/:productId
// /dashboard/:orgId/settings/:settingId
// /files/:folderId/:fileId/preview

// v6.4+ 語法：? 表示可選參數
<Route path="/blog/:id?" element={<BlogPost />} />
// 匹配 /blog 和 /blog/123

// * 萬用路由：匹配剩餘所有路徑段
<Route path="/files/*" element={<FileExplorer />} />

function FileExplorer() {
  // URL: /files/documents/2026/report.pdf
  // * 匹配到 "documents/2026/report.pdf"
  const params = useParams();
  const filePath = params['*'];  // "documents/2026/report.pdf"
  return <div>檔案路徑：{filePath}</div>;
}

// pages/Login.tsx
import { useNavigate } from 'react-router-dom';
import { useState } from 'react';

function LoginForm() {
  const navigate = useNavigate();
  const [loading, setLoading] = useState(false);

  const handleLogin = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    setLoading(true);

    try {
      const formData = new FormData(e.currentTarget);
      await login({
        email: formData.get('email') as string,
        password: formData.get('password') as string,
      });

      // 登入成功：導向 dashboard
      // replace: true → 不留下登入頁的歷史記錄（避免按上一頁回到登入頁）
      navigate('/dashboard', { replace: true });
    } catch (err) {
      setLoading(false);
      // 顯示錯誤訊息
    }
  };

  return (
    <form onSubmit={handleLogin}>
      <input name="email" type="email" placeholder="Email" />
      <input name="password" type="password" placeholder="密碼" />
      <button type="submit" disabled={loading}>
        {loading ? '登入中...' : '登入'}
      </button>
    </form>
  );
}

import { useNavigate } from 'react-router-dom';

function SomeComponent() {
  const navigate = useNavigate();

  // 基本導航
  navigate('/dashboard');

  // replace：不加歷史記錄（按上一頁不會回到這頁）
  navigate('/login', { replace: true });

  // 相對導航：-1 是上一頁，1 是下一頁（就像 history.go()）
  navigate(-1);  // 上一頁
  navigate(1);   // 下一頁（如果有的話）

  // 傳遞 state（不出現在 URL 中，適合暫時性資料）
  navigate('/checkout', {
    state: {
      from: 'cart',
      items: selectedItems,  // 可以傳複雜物件
    }
  });

  return null;
}

// 在目標頁面讀取 state
import { useLocation } from 'react-router-dom';

function CheckoutPage() {
  const location = useLocation();
  const state = location.state as { from: string; items: CartItem[] } | null;

  console.log(state?.from);   // 'cart'
  console.log(state?.items);  // 購物車商品

  // 注意：state 在重新整理後會消失
  // 如果需要持久化，改用 useSearchParams 或 localStorage

  return <div>結帳頁</div>;
}

// components/ProtectedRoute.tsx
import { Navigate, Outlet } from 'react-router-dom';
import { useAuthStore } from '@/store/useAuthStore';

function ProtectedRoute() {
  const isLoggedIn = useAuthStore((state) => state.isLoggedIn);

  if (!isLoggedIn) {
    // 用 <Navigate> 組件做宣告式重定向
    // replace 確保不留歷史記錄
    return <Navigate to="/login" replace />;
  }

  return <Outlet />;  // 已登入：正常渲染子路由
}

// 在路由定義中使用
function App() {
  return (
    <Routes>
      <Route path="/login" element={<Login />} />
      <Route path="/blog" element={<BlogList />} />

      {/* 用 ProtectedRoute 包住需要保護的路由 */}
      <Route element={<ProtectedRoute />}>
        <Route path="/dashboard" element={<DashboardLayout />}>
          <Route index element={<DashboardHome />} />
          <Route path="profile" element={<Profile />} />
        </Route>
        <Route path="/admin" element={<Admin />} />
      </Route>
    </Routes>
  );
}

// pages/ProductList.tsx
import { useSearchParams } from 'react-router-dom';

function ProductList() {
  // useSearchParams 類似 useState，但 state 儲存在 URL 的查詢字串中
  const [searchParams, setSearchParams] = useSearchParams();

  // 讀取查詢字串（型別都是 string | null）
  const category = searchParams.get('category') ?? 'all';
  const page = Number(searchParams.get('page') ?? '1');
  const sortBy = searchParams.get('sort') ?? 'newest';

  // 更新查詢字串（會改變 URL，但不觸發頁面刷新）
  const handleCategoryChange = (cat: string) => {
    setSearchParams({
      category: cat,
      page: '1',     // 切換分類時重置頁數
      sort: sortBy,  // 保留其他現有參數
    });
    // URL 變成 /products?category=electronics&page=1&sort=newest
  };

  const handlePageChange = (newPage: number) => {
    // 更新單一參數，保留其他參數
    setSearchParams(prev => {
      prev.set('page', String(newPage));
      return prev;
    });
  };

  return (
    <div>
      <div className="flex gap-4 mb-6">
        {/* 分類篩選 */}
        <select
          value={category}
          onChange={(e) => handleCategoryChange(e.target.value)}
          className="border rounded p-2"
        >
          <option value="all">全部分類</option>
          <option value="electronics">電子產品</option>
          <option value="clothing">服飾</option>
          <option value="books">書籍</option>
        </select>

        {/* 排序 */}
        <select
          value={sortBy}
          onChange={(e) => setSearchParams(prev => {
            prev.set('sort', e.target.value);
            return prev;
          })}
          className="border rounded p-2"
        >
          <option value="newest">最新</option>
          <option value="price-asc">價格由低到高</option>
          <option value="price-desc">價格由高到低</option>
        </select>
      </div>

      {/* 商品列表（根據 category 和 sortBy 篩選/排序）*/}
      <ProductGrid category={category} sortBy={sortBy} page={page} />

      {/* 分頁 */}
      <Pagination
        currentPage={page}
        onPageChange={handlePageChange}
      />

      {/* 目前的 URL：/products?category=electronics&page=2&sort=price-asc */}
      {/* 使用者可以書籤、分享這個 URL，下次打開還是同樣的篩選狀態 */}
    </div>
  );
}

// 搜尋列：即時更新 URL 的查詢字串
import { useSearchParams, useNavigate } from 'react-router-dom';
import { useState, useCallback } from 'react';

function SearchBar() {
  const [searchParams, setSearchParams] = useSearchParams();
  const query = searchParams.get('q') ?? '';
  const [inputValue, setInputValue] = useState(query);

  const handleSearch = (e: React.FormEvent) => {
    e.preventDefault();
    if (inputValue.trim()) {
      setSearchParams({ q: inputValue.trim(), page: '1' });
    } else {
      // 清空搜尋：移除 q 參數
      setSearchParams(prev => {
        prev.delete('q');
        prev.delete('page');
        return prev;
      });
    }
  };

  return (
    <form onSubmit={handleSearch} className="flex gap-2">
      <input
        type="search"
        value={inputValue}
        onChange={(e) => setInputValue(e.target.value)}
        placeholder="搜尋商品..."
        className="flex-1 border rounded p-2"
      />
      <button type="submit" className="btn-primary px-6">搜尋</button>
    </form>
  );
}

// 在列表元件中讀取搜尋條件
function ProductGrid() {
  const [searchParams] = useSearchParams();
  const query = searchParams.get('q');
  const category = searchParams.get('category') ?? 'all';
  const page = Number(searchParams.get('page') ?? '1');

  // 用 searchParams 作為 useEffect 的依賴
  // URL 改變時自動重新 fetch
  useEffect(() => {
    fetchProducts({ query, category, page });
  }, [query, category, page]);

  return <div>{/* 商品列表 */}</div>;
}