前端元件技能
目的:指導如何根據伺服器/用戶端元件模式以及現有元件結構,建立 Next.js 元件。
概覽
Next.js 16+ 預設使用 App Router 與伺服器元件(Server Components)。僅在需要互動性時(如 Hook、事件處理器、瀏覽器 API)才使用用戶端元件(Client Components)。
伺服器 vs 用戶端元件
伺服器元件(預設)
使用時機:
- 頁面與佈局
- 靜態內容
- 從 API 取得資料(盡可能)
- SEO 最佳化內容
模式:
// 不需要 "use client" 指示詞
import { Metadata } from "next";
export const metadata: Metadata = {
title: "頁面標題",
};
export default function PageComponent() {
return <div>靜態內容</div>;
}
範例:frontend/app/layout.tsx、frontend/app/page.tsx
用戶端元件(需要時使用)
使用時機:
- 互動元素(按鈕、表單、輸入框)
- 事件處理器(onClick、onChange 等)
- React Hook(useState、useEffect、useRouter 等)
- 瀏覽器 API(localStorage、window、document 等)
- 即時更新
- 拖放功能
模式:
"use client"; // 必須是第一行
import { useState, useEffect } from "react";
import { useRouter } from "next/navigation";
interface ComponentProps {
prop1: string;
prop2?: number;
}
export default function ComponentName({ prop1, prop2 }: ComponentProps) {
const router = useRouter();
const [state, setState] = useState("");
useEffect(() => {
// 副作用
}, []);
return <div>{/* 元件 JSX */}</div>;
}
範例:frontend/components/ProtectedRoute.tsx、frontend/app/signup/page.tsx
元件結構模板
"use client"; // 僅限用戶端元件
/**
* 元件名稱
*
* 簡短說明此元件的功能
*/
import { useState, useEffect } from "react";
import { ComponentType } from "@/types";
import { cn } from "@/lib/utils";
interface ComponentProps {
prop1: string;
prop2?: number;
className?: string;
}
export default function ComponentName({ prop1, prop2, className }: ComponentProps) {
// 狀態
const [state, setState] = useState("");
// 副作用
useEffect(() => {
// 副作用邏輯
}, []);
// 處理器
const handleClick = () => {
// 處理器邏輯
};
// 渲染
return (
<div className={cn("base-classes", className)}>
{/* 元件內容 */}
</div>
);
}
特定元件模式
1. ProtectedRoute 模式
來源:frontend/components/ProtectedRoute.tsx
"use client";
import { useEffect, useState } from "react";
import { useRouter } from "next/navigation";
import { isAuthenticated } from "@/lib/auth";
import LoadingSpinner from "./LoadingSpinner";
interface ProtectedRouteProps {
children: React.ReactNode;
}
export default function ProtectedRoute({ children }: ProtectedRouteProps) {
const router = useRouter();
const [isAuthorized, setIsAuthorized] = useState(false);
const [isChecking, setIsChecking] = useState(true);
useEffect(() => {
async function checkAuth() {
try {
const authenticated = await isAuthenticated();
if (!authenticated) {
const currentPath = window.location.pathname;
if (currentPath !== "/signin") {
sessionStorage.setItem("redirectAfterLogin", currentPath);
}
router.push("/signin");
} else {
setIsAuthorized(true);
}
} catch (error) {
console.error("身份驗證檢查失敗:", error);
router.push("/signin");
} finally {
setIsChecking(false);
}
}
checkAuth();
}, [router]);
if (isChecking) {
return (
<div className="min-h-screen flex items-center justify-center">
<LoadingSpinner size="large" />
</div>
);
}
if (!isAuthorized) {
return null;
}
return <>{children}</>;
}
模式:
- 在元件掛載時檢查身份驗證
- 檢查期間顯示載入指示器
- 將預期目的地儲存在 sessionStorage 中
- 若未通過驗證,重新導向至
/signin - 僅在授權通過時渲染 children
2. LoadingSpinner 模式
來源:frontend/components/LoadingSpinner.tsx
interface LoadingSpinnerProps {
size?: "small" | "medium" | "large";
color?: string;
label?: string;
}
export default function LoadingSpinner({
size = "medium",
color = "blue",
label = "載入中...",
}: LoadingSpinnerProps) {
const sizeClasses = {
small: "w-4 h-4 border-2",
medium: "w-8 h-8 border-3",
large: "w-12 h-12 border-4",
};
const colorClasses = {
blue: "border-blue-600 border-t-transparent",
gray: "border-gray-600 border-t-transparent",
white: "border-white border-t-transparent",
};
const spinnerClass = `${sizeClasses[size]} ${
colorClasses[color as keyof typeof colorClasses] || colorClasses.blue
} rounded-full animate-spin`;
return (
<div
className="flex items-center justify-center"
role="status"
aria-label={label}
aria-live="polite"
>
<div className={spinnerClass}></div>
<span className="sr-only">{label}</span>
</div>
);
}
模式:
- 多種尺寸(small、medium、large)
- 多種顏色(blue、gray、white)
- 無障礙標籤(
role="status"、aria-label、aria-live) - 使用
sr-only類別的螢幕閱讀器文字
3. 表單處理模式
來源:frontend/app/signup/page.tsx
"use client";
import { useState } from "react";
import { useRouter } from "next/navigation";
import { api } from "@/lib/api";
import { isValidEmail, getPasswordStrength } from "@/lib/utils";
export default function SignupPage() {
const router = useRouter();
const [formData, setFormData] = useState({
name: "",
email: "",
password: "",
});
const [errors, setErrors] = useState<Record<string, string>>({});
const [isLoading, setIsLoading] = useState(false);
const [apiError, setApiError] = useState("");
const validateForm = (): boolean => {
const newErrors: Record<string, string> = {};
if (!formData.name.trim()) {
newErrors.name = "名稱為必填";
}
if (!formData.email.trim()) {
newErrors.email = "電子郵件為必填";
} else if (!isValidEmail(formData.email)) {
newErrors.email = "請輸入有效的電子郵件地址";
}
// 更多驗證...
setErrors(newErrors);
return Object.keys(newErrors).length === 0;
};
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();
setApiError("");
if (!validateForm()) {
return;
}
setIsLoading(true);
try {
const response = await api.signup(formData);
if (response.success) {
router.push("/dashboard");
} else {
setApiError(response.message || "註冊失敗");
}
} catch (error: any) {
setApiError(error.message || "發生錯誤");
} finally {
setIsLoading(false);
}
};
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
const { name, value } = e.target;
setFormData((prev) => ({ ...prev, [name]: value }));
// 使用者開始輸入時清除該欄位的錯誤
if (errors[name]) {
setErrors((prev) => ({ ...prev, [name]: "" }));
}
};
return (
<form onSubmit={handleSubmit}>
{/* 表單欄位 */}
</form>
);
}
模式:
- 分別為表單資料、錯誤、載入狀態和 API 錯誤建立獨立狀態
- 回傳布林值的驗證函數
- 輸入變更時清除錯誤
- 提交期間的載入狀態
- 用 try-catch 進行錯誤處理
- 成功時重新導向
4. ToastNotification 模式
來源:frontend/components/ToastNotification.tsx
"use client";
import { useEffect, useState } from "react";
import { ToastMessage, ToastType } from "@/types";
export function useToast() {
const [toasts, setToasts] = useState<ToastMessage[]>([]);
const showToast = (type: ToastType, message: string, duration?: number) => {
const id = `toast-${Date.now()}-${Math.random()}`;
const newToast: ToastMessage = {
id,
type,
message,
duration,
};
setToasts((prev) => [...prev, newToast]);
};
const dismissToast = (id: string) => {
setToasts((prev) => prev.filter((toast) => toast.id !== id));
};
return {
toasts,
showToast,
dismissToast,
success: (message: string, duration?: number) => showToast("success", message, duration),
error: (message: string, duration?: number) => showToast("error", message, duration),
// ...
};
}
模式:
- 用於 Toast 管理的自訂 Hook
- 可設定持續時間的自動關閉功能
- 支援疊加多條 Toast
- 輔助方法(success、error、warning、info)
Tailwind CSS 模式
1. 僅使用實用程式類別
<div className="flex items-center justify-center gap-4 p-6 bg-white rounded-lg shadow-md">
模式:使用 Tailwind 實用程式類別,不要使用內聯樣式
2. 使用 cn() 實用程式的條件式類別
import { cn } from "@/lib/utils";
<div className={cn(
"base-classes",
condition && "conditional-classes",
className // 允許透過 prop 覆寫
)}>
模式:使用來自 @/lib/utils 的 cn() 來處理條件式類別
3. 深色模式支援
<div className="bg-white dark:bg-gray-800 text-gray-900 dark:text-white">
模式:使用 dark: 前綴來設定深色模式樣式
4. 響應式設計
<div className="w-full sm:w-1/2 md:w-1/3 lg:w-1/4">
模式:使用斷點前綴(sm:、md:、lg:、xl:)
無障礙模式(符合 WCAG 2.1 AA)
1. ARIA 標籤
<button aria-label="關閉對話框">×</button>
<div role="status" aria-live="polite" aria-label="載入中...">
模式:始終為純圖示按鈕提供 aria-label
2. 語意化 HTML
<nav>
<ul>
<li><a href="/">首頁</a></li>
</ul>
</nav>
模式:使用語意化 HTML 元素(nav、main、section、article 等)
3. 鍵盤導航
<button
onClick={handleClick}
onKeyDown={(e) => {
if (e.key === "Enter" || e.key === " ") {
handleClick();
}
}}
>
模式:確保所有互動元素都支援鍵盤操作
4. 螢幕閱讀器文字
<span className="sr-only">正在載入內容</span>
模式:使用 sr-only 類別來提供僅供螢幕閱讀器讀取的文字
5. 焦點管理
<input
autoFocus
className="focus:outline-none focus:ring-2 focus:ring-blue-500"
/>
模式:始終提供可見的焦點指示器
檔案命名慣例
- 頁面:kebab-case(例如
signup.tsx、signin.tsx) - 元件:PascalCase(例如
TaskList.tsx、TaskItem.tsx) - 佈局:
layout.tsx - 錯誤頁面:
error.tsx、not-found.tsx
憲法要求
- FR-033:Next.js 16+ App Router 結構 ✅
- FR-034:預設伺服器元件,需要時使用用戶端元件 ✅
- FR-035:錯誤邊界 ✅
- FR-036:符合 WCAG 2.1 AA ✅
- FR-037:TypeScript 嚴格模式 ✅
- FR-038:Prettier 格式化 ✅
- FR-039:ESLint 規則 ✅
參考資料
- 規範文件:
specs/002-frontend-todo-app/spec.md- 元件規格 - 現有元件:
frontend/components/*.tsx- 元件範例 - 現有頁面:
frontend/app/*.tsx- 頁面範例
進階元件模式
1. 拖放模式(第 7 階段 - T065)
函式庫:@dnd-kit/core
"use client";
import { DndContext, closestCenter, KeyboardSensor, PointerSensor, useSensor, useSensors } from "@dnd-kit/core";
import { SortableContext, sortableKeyboardCoordinates, useSortable, verticalListSortingStrategy } from "@dnd-kit/sortable";
export default function SortableTaskList({ tasks, onReorder }: Props) {
const sensors = useSensors(
useSensor(PointerSensor),
useSensor(KeyboardSensor, {
coordinateGetter: sortableKeyboardCoordinates,
})
);
const handleDragEnd = (event: DragEndEvent) => {
const { active, over } = event;
if (over && active.id !== over.id) {
onReorder(active.id, over.id);
}
};
return (
<DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
<SortableContext items={tasks.map(t => t.id)} strategy={verticalListSortingStrategy}>
{tasks.map(task => (
<SortableTaskItem key={task.id} task={task} />
))}
</SortableContext>
</DndContext>
);
}
模式:使用 @dnd-kit/core 進行拖放,在拖曳結束時處理重新排序
2. 復原/重做模式(第 7 階段 - T066)
"use client";
import { useReducer } from "react";
interface HistoryState<T> {
past: T[];
present: T;
future: T[];
}
function historyReducer<T>(state: HistoryState<T>, action: { type: string; newPresent?: T }): HistoryState<T> {
const { past, present, future } = state;
switch (action.type) {
case "UNDO":
if (past.length === 0) return state;
return {
past: past.slice(0, past.length - 1),
present: past[past.length - 1],
future: [present, ...future],
};
case "REDO":
if (future.length === 0) return state;
return {
past: [...past, present],
present: future[0],
future: future.slice(1),
};
case "SET":
if (action.newPresent === present) return state;
return {
past: [...past, present],
present: action.newPresent!,
future: [],
};
default:
return state;
}
}
export function useHistory<T>(initialPresent: T) {
const [state, dispatch] = useReducer(historyReducer, {
past: [],
present: initialPresent,
future: [],
});
const undo = () => dispatch({ type: "UNDO" });
const redo = () => dispatch({ type: "REDO" });
const set = (newPresent: T) => dispatch({ type: "SET", newPresent });
return { state: state.present, undo, redo, set, canUndo: state.past.length > 0, canRedo: state.future.length > 0 };
}
模式:使用 useReducer 管理歷史狀態(past、present、future),透過「UNDO」、「REDO」和「SET」動作來支援復原和重做