UI 元件模式 是做什麼的?
何時使用此技能
- 建立元件庫:建立可重複使用的 UI 元件
- 實作設計系統:應用一致的 UI 模式
- 複雜 UI:需要多種變體的元件(按鈕、模態框、下拉選單)
- 重構:將重複的程式碼萃取成元件
指示
步驟 1:Props API 設計
設計易於使用且可擴展的 Props。
原則:
- 清晰的名稱
- 合理的預設值
- 使用 TypeScript 定義型別
- 可選 Props 使用可選標記 (?)
範例 (Button):
interface ButtonProps {
// 必要
children: React.ReactNode;
// 可選 (有預設值)
variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
size?: 'sm' | 'md' | 'lg';
disabled?: boolean;
isLoading?: boolean;
// 事件處理器
onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
// HTML 屬性繼承
type?: 'button' | 'submit' | 'reset';
className?: string;
}
function Button({
children,
variant = 'primary',
size = 'md',
disabled = false,
isLoading = false,
onClick,
type = 'button',
className = '',
...rest
}: ButtonProps) {
const baseClasses = 'btn';
const variantClasses = `btn-${variant}`;
const sizeClasses = `btn-${size}`;
const classes = `${baseClasses} ${variantClasses} ${sizeClasses} ${className}`;
return (
<button
type={type}
className={classes}
disabled={disabled || isLoading}
onClick={onClick}
{...rest}
>
{isLoading ? <Spinner /> : children}
</button>
);
}
// 使用範例
<Button variant="primary" size="lg" onClick={() => alert('已點擊!')}>
點擊我
</Button>
步驟 2:組合模式
結合小組件以建構複雜 UI。
範例 (Card):
// Card 元件 (容器)
interface CardProps {
children: React.ReactNode;
className?: string;
}
function Card({ children, className = '' }: CardProps) {
return <div className={`card ${className}`}>{children}</div>;
}
// Card.Header
function CardHeader({ children }: { children: React.ReactNode }) {
return <div className="card-header">{children}</div>;
}
// Card.Body
function CardBody({ children }: { children: React.ReactNode }) {
return <div className="card-body">{children}</div>;
}
// Card.Footer
function CardFooter({ children }: { children: React.ReactNode }) {
return <div className="card-footer">{children}</div>;
}
// 複合元件模式
Card.Header = CardHeader;
Card.Body = CardBody;
Card.Footer = CardFooter;
export default Card;
// 使用方式
import Card from './Card';
function ProductCard() {
return (
<Card>
<Card.Header>
<h3>產品名稱</h3>
</Card.Header>
<Card.Body>
<img src="..." alt="產品" />
<p>這裡是產品描述...</p>
</Card.Body>
<Card.Footer>
<button>加入購物車</button>
</Card.Footer>
</Card>
);
}
步驟 3:Render Props / 作為函式的 Children
一種彈性自訂的模式。
範例 (Dropdown):
interface DropdownProps<T> {
items: T[];
renderItem: (item: T, index: number) => React.ReactNode;
onSelect: (item: T) => void;
placeholder?: string;
}
function Dropdown<T>({ items, renderItem, onSelect, placeholder }: DropdownProps<T>) {
const [isOpen, setIsOpen] = useState(false);
const [selected, setSelected] = useState<T | null>(null);
const handleSelect = (item: T) => {
setSelected(item);
onSelect(item);
setIsOpen(false);
};
return (
<div className="dropdown">
<button onClick={() => setIsOpen(!isOpen)}>
{selected ? renderItem(selected, -1) : placeholder || '選擇...'}
</button>
{isOpen && (
<ul className="dropdown-menu">
{items.map((item, index) => (
<li key={index} onClick={() => handleSelect(item)}>
{renderItem(item, index)}
</li>
))}
</ul>
)}
</div>
);
}
// 使用方式
interface User {
id: string;
name: string;
avatar: string;
}
function UserDropdown() {
const users: User[] = [...];
return (
<Dropdown
items={users}
placeholder="選擇一個使用者"
renderItem={(user) => (
<div className="user-item">
<img src={user.avatar} alt={user.name} />
<span>{user.name}</span>
</div>
)}
onSelect={(user) => console.log('已選擇:', user)}
/>
);
}
步驟 4:使用自訂 Hook 分離邏輯
將 UI 與商業邏輯分開。
範例 (Modal):
// hooks/useModal.ts
function useModal(initialOpen = false) {
const [isOpen, setIsOpen] = useState(initialOpen);
const open = useCallback(() => setIsOpen(true), []);
const close = useCallback(() => setIsOpen(false), []);
const toggle = useCallback(() => setIsOpen(prev => !prev), []);
return { isOpen, open, close, toggle };
}
// components/Modal.tsx
interface ModalProps {
isOpen: boolean;
onClose: () => void;
title: string;
children: React.ReactNode;
}
function Modal({ isOpen, onClose, title, children }: ModalProps) {
if (!isOpen) return null;
return (
<div className="modal-overlay" onClick={onClose}>
<div className="modal-content" onClick={(e) => e.stopPropagation()}>
<div className="modal-header">
<h2>{title}</h2>
<button onClick={onClose} aria-label="關閉">×</button>
</div>
<div className="modal-body">{children}</div>
</div>
</div>
);
}
// 使用方式
function App() {
const { isOpen, open, close } = useModal();
return (
<>
<button onClick={open}>開啟模態框</button>
<Modal isOpen={isOpen} onClose={close} title="我的模態框">
<p>這裡是模態框內容...</p>
</Modal>
</>
);
}
步驟 5:效能最佳化
防止不必要的重新渲染。
React.memo:
// ❌ 不好:每當父元件重新渲染,子元件也重新渲染
function ExpensiveComponent({ data }) {
console.log('正在渲染...');
return <div>{/* 複雜 UI */}</div>;
}
// ✅ 好:僅在 props 變更時重新渲染
const ExpensiveComponent = React.memo(({ data }) => {
console.log('正在渲染...');
return <div>{/* 複雜 UI */}</div>;
});
useMemo 與 useCallback:
function ProductList({ products, category }: { products: Product[]; category: string }) {
// ✅ 記憶化過濾結果
const filteredProducts = useMemo(() => {
return products.filter(p => p.category === category);
}, [products, category]);
// ✅ 記憶化回呼函式
const handleAddToCart = useCallback((productId: string) => {
// 加入購物車
console.log('正在加入:', productId);
}, []);
return (
<div>
{filteredProducts.map(product => (
<ProductCard
key={product.id}
product={product}
onAddToCart={handleAddToCart}
/>
))}
</div>
);
}
const ProductCard = React.memo(({ product, onAddToCart }) => {
return (
<div>
<h3>{product.name}</h3>
<button onClick={() => onAddToCart(product.id)}>加入購物車</button>
</div>
);
});
輸出格式
元件檔案結構
components/
├── Button/
│ ├── Button.tsx # 主元件
│ ├── Button.test.tsx # 測試
│ ├── Button.stories.tsx # Storybook
│ ├── Button.module.css # 樣式
│ └── index.ts # 匯出
├── Card/
│ ├── Card.tsx
│ ├── CardHeader.tsx
│ ├── CardBody.tsx
│ ├── CardFooter.tsx
│ └── index.ts
└── Modal/
├── Modal.tsx
├── useModal.ts # 自訂 Hook
└── index.ts
元件範本
import React from 'react';
export interface ComponentProps {
// Props 定義
children: React.ReactNode;
className?: string;
}
/**
* 元件描述
*
* @example
* ```tsx
* <Component>Hello</Component>
* ```
*/
export const Component = React.forwardRef<HTMLDivElement, ComponentProps>(
({ children, className = '', ...rest }, ref) => {
return (
<div ref={ref} className={`component ${className}`} {...rest}>
{children}
</div>
);
}
);
Component.displayName = 'Component';
export default Component;
限制
必須遵守的規則
-
單一職責原則:一個元件只有一個角色
- Button 只處理按鈕,Form 只處理表單
-
Props 型別定義:必須使用 TypeScript 介面
- 啟用自動完成
- 型別安全
-
無障礙性:aria-*、role、tabindex 等
禁止的規則
-
過度的 Props 傳遞:禁止超過 5 層的深度
- 使用 Context 或組合
-
沒有商業邏輯:禁止在 UI 元件中進行 API 呼叫和複雜計算
- 分離到自訂 Hook
-
內聯物件/函式:效能下降
// ❌ 不好的範例 <Component style={{ color: 'red' }} onClick={() => handleClick()} /> // ✅ 好的範例 const style = { color: 'red' }; const handleClick = useCallback(() => {...}, []); <Component style={style} onClick={handleClick} />
範例
範例 1:Accordion (複合元件)
import React, { createContext, useContext, useState } from 'react';
// 使用 Context 共享狀態
const AccordionContext = createContext<{
activeIndex: number | null;
setActiveIndex: (index: number | null) => void;
} | null>(null);
function Accordion({ children }: { children: React.ReactNode }) {
const [activeIndex, setActiveIndex] = useState<number | null>(null);
return (
<AccordionContext.Provider value={{ activeIndex, setActiveIndex }}>
<div className="accordion">{children}</div>
</AccordionContext.Provider>
);
}
function AccordionItem({ index, title, children }: {
index: number;
title: string;
children: React.ReactNode;
}) {
const context = useContext(AccordionContext);
if (!context) throw new Error('AccordionItem 必須在 Accordion 內部使用');
const { activeIndex, setActiveIndex } = context;
const isActive = activeIndex === index;
return (
<div className="accordion-item">
<button
className="accordion-header"
onClick={() => setActiveIndex(isActive ? null : index)}
aria-expanded={isActive}
>
{title}
</button>
{isActive && <div className="accordion-body">{children}</div>}
</div>
);
}
Accordion.Item = AccordionItem;
export default Accordion;
// 使用方式
<Accordion>
<Accordion.Item index={0} title="章節 1">
章節 1 的內容
</Accordion.Item>
<Accordion.Item index={1} title="章節 2">
章節 2 的內容
</Accordion.Item>
</Accordion>
範例 2:多型元件 (as prop)
type PolymorphicComponentProps<C extends React.ElementType> = {
as?: C;
children: React.ReactNode;
} & React.ComponentPropsWithoutRef<C>;
function Text<C extends React.ElementType = 'span'>({
as,
children,
...rest
}: PolymorphicComponentProps<C>) {
const Component = as || 'span';
return <Component {...rest}>{children}</Component>;
}
// 使用方式
<Text>預設 span</Text>
<Text as="h1">標題 1</Text>
<Text as="p" style={{ color: 'blue' }}>段落</Text>
<Text as={Link} href="/about">連結</Text>
最佳實務
- 組合優於 Props:利用 children 代替許多 props
- 受控 vs 非受控:根據情況選擇
- 預設 Props:提供合理的預設值
- Storybook:元件文件與開發
參考資料
- React Patterns
- Compound Components
- Radix UI - 可存取元件
- Chakra UI - 元件庫
- shadcn/ui - 複製貼上元件
後設資料
版本
- 目前版本:1.0.0
- 最後更新:2025-01-01
- 相容平台:Claude、ChatGPT、Gemini
相關技能
- web-accessibility:可存取元件
- state-management:元件狀態管理
標籤
#UI-元件 #React #設計模式 #組合 #TypeScript #前端