Community程式設計與開發github.com

react-components

撰寫語義化、組合式且以標記優先的 React 元件 — 使用語義化的 HTML 元素、將畫面視為由命名明確的元件組合而成的簡短陳述、將狀態與副作用置於只儲存事實並衍伸其他資訊的輕薄 Hook 中,並將商業邏輯保留在 React 外部(請參閱 business-logic 技能)。適用於撰寫、審查或重構任何 React 元件、Hook 或畫面,當 JSX 充滿了 div 和 class 字串、元件在 return 之前有一長串狀態與副作用、或邏輯與元件糾纏不清時。

react-components 是什麼?

此技能定義了一套撰寫 React 元件的準則,強調語義化 HTML、組合式架構與標記優先。它確保畫面無論對於開發人員或螢幕閱讀器都可讀,透過使用如`main`、`header`、`nav`和`button`等語義元素取代泛用的`div`與`span`,從而無需額外程式碼即可提供無障礙功能。畫面被拆解為以產品詞彙命名的元件(例如 `CatalogHeader`、`ProductRow`),其 JSX 如同大綱般清晰,且不包含原始 HTML 標籤或 class 字串。商業邏輯被封裝在純函式模組中(不依賴 React),元件僅透過呼叫這些模組來使用邏輯,這使得邏輯可被單獨重用與測試。Hook 被限定於管理無法從外部推導的狀態(如使用者輸入或 API 回傳資料),所有其他資料在渲染期間透過純函式衍生,從而減少不必要的重新渲染與副作用。此技能與 Claude Code、Coder 或 Cursor 等 AI 代理工具相容,為撰寫、審查或重構 React 元件提供結構化指南,確保程式碼品質、可維護性與無障礙性。

相容平台~Claude Code~Codex CLI~Cursor
Part ofReact
npx skills add https://github.com/tosinamuda/skills/tree/main/react-components

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

React 元件:語義化、組合式、標記優先

一個畫面必須能讓人與螢幕閱讀器讀懂它由什麼組成。撰寫或修改任何專案中的 React 元件時,請遵循以下規則。

  1. 元素說明其身份。 使用 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,例如讓清單橫向滾動的容器。
  2. 畫面是由命名部分組成的組合。 畫面的 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>;
    }
    
    當一個人會用某個名稱來稱呼它時(例如「頁首」、「一排產品」、「返回按鈕」),就值得將它命名為一個部分。僅用於間距的包裝器應保留在其所需的部分內部,而非放在畫面中。
  3. 使用二年級學生就能猜到的命名。 使用事物的簡單詞彙: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>
    
  4. 標記優先。 元件的主體就是 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>
      );
    }
    
  5. 以一個標籤化的狀態來處理互斥的視圖。 當畫面只顯示多種情況中的一種時,使用純函式或 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 且未繪製時讓建置失敗。
  6. 商業邏輯存在於 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);
    
  7. 子元件報告,父元件決定。 Props 是帶有事實的事件(onAdd(product)),永遠不要傳遞父元件的 setter。
    // 不該這樣:子元件被賦予父元件的 setter,並自行決定「加入」的意義。
    <ProductCard product={p} setBasket={setBasket} setError={setError} />
    
    // 應該這樣:子元件報告發生了什麼事,並附帶事實;父元件決定如何處理。
    <ProductCard product={p} onAdd={() => { add(p); }} />
    
  8. 第二次撰寫相同的重複標記時,就將其提取為元件。
    // 不該這樣:四個畫面中重複撰寫相同的頁面背景和內距。
    <div className="relative flex h-screen w-screen flex-col bg-gray-50 p-8">...</div>
    
    // 應該這樣:第二次需要時就提取為元件。
    <PageLayout>...</PageLayout>
    
  9. 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]);
    
  10. 拆分不得改變繪製的內容。 在改動前後記錄渲染的標記並進行比較;通過的測試套件無法顯示移動的包裝器。
# 在改動前記錄每個畫面的渲染標記,進行改動,再次記錄,然後比較。
node record-markup.mjs before/   # 你自己的 Playwright 腳本:打開每個畫面狀態,將 document.body 儲存為 HTML
node record-markup.mjs after/
diff -r before/ after/           # 只有你打算更改的元素應該有差異

在比較之前,先移除每次執行時會變化的內容(ID、時間、產生的程式碼),以便突顯真正的差異。

不要為拆分而拆分:畫面仍然必須整體可讀,而沒有規則的元件則不需要 Hook。

相關技能