React 元件:語義化、組合式、標記優先
一個畫面必須能讓人與螢幕閱讀器讀懂它由什麼組成。撰寫或修改任何專案中的 React 元件時,請遵循以下規則。
- 元素說明其身份。 使用
main、header、footer、nav、section、search、ul/li、button、time、form。div或span僅用於為了版面配置或滾動而存在的容器。每個選擇帶來的好處:// 不該這樣:每個容器都是 div,導致螢幕閱讀器聽到一長串連續文字,且「按鈕」無法用 Tab 鍵到達或 Enter 鍵按壓。 <div className="page"> <div className="top"> <span className="updated">10:42</span> <div className="search"><input placeholder="搜尋" /></div> </div> <div className="group"> <div className="group-name">水果</div> <div className="items"> <div className="item" onClick={add}>蘋果</div> </div> </div> </div> // 應該這樣:每個元素說明其身份,因此地標、清單和按鈕自然而來。 <main> <header> <time dateTime="10:42">10:42</time> <search><input type="search" aria-label="搜尋產品" /></search> </header> <section aria-labelledby="fruit"> <h2 id="fruit">水果</h2> <ul> <li><button type="button" onClick={add}>蘋果</button></li> </ul> </section> </main>main和header讓螢幕閱讀器能在頁面各部分之間跳轉;section搭配其h2為區域命名;ul/li表示「清單,5 個項目」;button可用 Tab 鍵到達,並可按下 Enter 和空白鍵,無需額外程式碼;time和search說明了它們的內容是什麼。只有在「沒有特別含義」的情況下才保留div,例如讓清單橫向滾動的容器。 - 畫面是由命名部分組成的組合。 畫面的 JSX 讀起來就像產品自身語言中的畫面大綱:一個命名的元件對應一個人們會指著說「這是 XXX」的部分。每個部分都是一個小型元件,擁有自己的語義元素和 class,因此畫面本身沒有原始 HTML 標籤和 class 字串。閱讀畫面就能知道上面有什麼;打開一個部分就能知道它長怎樣。
當一個人會用某個名稱來稱呼它時(例如「頁首」、「一排產品」、「返回按鈕」),就值得將它命名為一個部分。僅用於間距的包裝器應保留在其所需的部分內部,而非放在畫面中。// 不該這樣:畫面是一棵標籤和 class 的樹,必須費力推敲每個容器是什麼。 <div className="flex h-screen flex-col gap-5 pt-7"> <div className="flex items-center gap-3 px-8"> <span className="text-gray-500">商店</span> <span className="font-semibold">{storeName}</span> </div> <div className="min-h-0 flex-1 overflow-y-auto"> {categories.map((c) => ( <div key={c.name} className="flex flex-col gap-3"> <div className="text-2xl font-semibold">{c.name}</div> <div className="flex gap-6 overflow-x-auto">{/* 產品卡片 */}</div> </div> ))} </div> <button className="absolute bottom-2 left-8 rounded-full" onClick={onBack}>←</button> </div> // 應該這樣:畫面由各部分組成,以其身份命名。 <CatalogLayout heading="產品"> <CatalogHeader> <ShopName /> <StoreName name={storeName} /> </CatalogHeader> <CategoryList categories={categories} onAdd={add} /> <BackButton label="返回商店" onBack={onBack} /> </CatalogLayout> // 每個部分持有自己的元素和 class,僅一次。 function CatalogHeader({ children }: { children: ReactNode }) { return <header className="flex items-center gap-3 px-8">{children}</header>; } - 使用二年級學生就能猜到的命名。 使用事物的簡單詞彙:
Layout、Header、Row、Card、List、Panel、Button、Margin。不要使用隱喻或業界術語(Frame、Rail、Strip、Gutter、Chrome、Shell),除非產品的使用者自己使用該詞彙。測試方法:從未看過程式碼的人是否可以說出<ProductRow>畫的是什麼。// 不該這樣:隱喻和術語讓新人必須解碼。 <PageFrame><TopRail /><ProductStrip gutter={GUTTER} /></PageFrame> // 應該這樣:每個事物使用簡單的詞彙。 <PageLayout><PageHeader /><ProductRow margin={LEFT_MARGIN} /></PageLayout> - 標記優先。 元件的主體就是 JSX。如果
return之前有超過幾行的狀態、副作用或衍伸計算,應將其提取到一個以其所建模的內容命名的 Hook 中(例如useProductSearch),該 Hook 回傳事實與動作。// 不該這樣:在任何人能看到繪製內容之前,先有四十行的狀態與副作用。 function CatalogScreen({ onAdd }: Props) { const [products, setProducts] = useState<Product[] | null>(null); const [query, setQuery] = useState(""); const [adding, setAdding] = useState<string | null>(null); useEffect(() => { /* 擷取產品,防止卸載時的更新 */ }, []); const categories = useMemo(() => /* 篩選,然後分組 */, [products, query]); const add = (p: Product) => { /* 設定 adding,呼叫 onAdd,處理異常 */ }; // ... 另外三十行 ... return <CatalogLayout>...</CatalogLayout>; } // 應該這樣:一個以其建模內容命名的 Hook,接著是 JSX。 function CatalogScreen({ onAdd }: Props) { const search = useProductSearch({ onAdd }); return ( <CatalogLayout> <CategoryList categories={search.categories} onAdd={search.add} /> </CatalogLayout> ); } - 以一個標籤化的狀態來處理互斥的視圖。 當畫面只顯示多種情況中的一種時,使用純函式或 Hook 回傳一個帶有區分標記的聯集(discriminated union),其中攜帶每種情況所需的資料,然後畫面對其進行窮舉的
switch。不要使用巢狀三元運算子或一連串的早期返回。由於// 不該這樣:一連串的條件判斷,順序本身就是邏輯,且容易遺漏某個情況。 if (!loaded) return <Spinner />; if ("error" in loaded) return <Notice title="無法載入訂單" />; if (order.cancelled) return <Notice title="已取消" />; return order.items.length === 0 ? <EmptyBasket /> : order.paid ? <Receipt /> : <Checkout />; // 應該這樣:一個函式決定一切,並回傳每個情況所需的資料。 type OrderView = | { kind: "loading" } | { kind: "failed"; error: string } | { kind: "cancelled" } | { kind: "empty" } | { kind: "checkout"; order: Order } | { kind: "paid"; order: Order; receipt: Receipt }; const view = useOrderView(id); switch (view.kind) { case "loading": return <Spinner />; case "failed": return <Notice title="無法載入訂單" detail={view.error} />; case "cancelled": return <Notice title="已取消" />; case "empty": return <EmptyBasket />; case "checkout": return <Checkout order={view.order} />; case "paid": return <ReceiptPage order={view.order} receipt={view.receipt} />; }kind為窮舉,TypeScript 會在新增一個 case 且未繪製時讓建置失敗。 - 商業邏輯存在於 React 外部。 任何負責決策、檢查、篩選、排序或計算的內容,都是一個不匯入 React 的純函式模組中的純函式,使其可以被重用,並能在不渲染的情況下進行單元測試。Hook 或元件會呼叫它;它不包含在元件內部。此類程式碼的存放位置、分層方式以及如何將其從元件中提取出來,請參考 business-logic 技能。
// productSearch.ts:沒有引入 React,因此可獨立執行與測試。 export function productsMatching(products: readonly Product[], query: string) { const words = query.toLowerCase().split(/\s+/).filter(Boolean); return products.filter((p) => words.every((w) => p.name.toLowerCase().includes(w))); } // Hook 僅呼叫它。 const shown = productsMatching(products, query); - 子元件報告,父元件決定。 Props 是帶有事實的事件(
onAdd(product)),永遠不要傳遞父元件的 setter。// 不該這樣:子元件被賦予父元件的 setter,並自行決定「加入」的意義。 <ProductCard product={p} setBasket={setBasket} setError={setError} /> // 應該這樣:子元件報告發生了什麼事,並附帶事實;父元件決定如何處理。 <ProductCard product={p} onAdd={() => { add(p); }} /> - 第二次撰寫相同的重複標記時,就將其提取為元件。
// 不該這樣:四個畫面中重複撰寫相同的頁面背景和內距。 <div className="relative flex h-screen w-screen flex-col bg-gray-50 p-8">...</div> // 應該這樣:第二次需要時就提取為元件。 <PageLayout>...</PageLayout> - Hook 應該輕薄且負責衍伸,而非儲存。 Hook 只保留無法計算的狀態:使用者做了什麼以及從外部傳入了什麼。其他所有內容都在渲染期間透過規則 6 的純函式從該狀態衍伸而來。不要有映射 prop 或其他狀態的狀態,也不要有僅從其他狀態設定狀態的副作用。副作用僅用於與 React 外部的內容同步(如 fetch、計時器、訂閱、DOM),並且需要進行清理。一個 Hook 只建模一件事。
// 只儲存使用者做了什麼以及從外部傳入了什麼。 const [query, setQuery] = useState(""); const { products } = useProducts(); // 已擷取;其副作用會進行清理 // 每次渲染時,使用純函式模組中的函式衍伸其餘內容。 const shown = productsMatching(products, query); const empty = shown.length === 0; // 不該這樣:一個會漂移的副本,被一個導致兩次渲染的副作用設定。 // const [shown, setShown] = useState(products); // useEffect(() => { setShown(productsMatching(products, query)); }, [products, query]); - 拆分不得改變繪製的內容。 在改動前後記錄渲染的標記並進行比較;通過的測試套件無法顯示移動的包裝器。
# 在改動前記錄每個畫面的渲染標記,進行改動,再次記錄,然後比較。
node record-markup.mjs before/ # 你自己的 Playwright 腳本:打開每個畫面狀態,將 document.body 儲存為 HTML
node record-markup.mjs after/
diff -r before/ after/ # 只有你打算更改的元素應該有差異
在比較之前,先移除每次執行時會變化的內容(ID、時間、產生的程式碼),以便突顯真正的差異。
不要為拆分而拆分:畫面仍然必須整體可讀,而沒有規則的元件則不需要 Hook。