Community编程与开发github.com

react-components

编写语义化、组合式、标记优先的 React 组件 — 使用语义化 HTML 元素,将页面拆分为命名清晰的小组件,状态和副作用放在精简的 Hook 中(仅存储事实,其余推导得出),业务逻辑保持在 React 外部。适用于编写、审查或重构任何 React 组件、Hook 或页面,当 JSX 充满 div 和 class 字符串时,当组件在 return 之前有长串的状态和副作用时,或当逻辑与组件纠缠不清时。

react-components 是什么?

此技能提供了一套清晰的 React 组件编写规范,强调语义化、组合式和标记优先。它指导开发者使用语义化 HTML 元素(如 main、header、nav、button)来构建可访问的页面,避免过度使用 div。技能要求将页面拆分为命名清晰的小型组件,使 JSX 结构像产品页面的大纲一样易于理解。通过将状态和副作用提取到专门的 Hook 中,并使业务逻辑与 React 分离,组件变得精简且易于测试。该技能适用于所有 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 和 Space 触发,无需额外代码;time 和 search 表明其内容含义。只在没有具体含义的地方保留 div,例如用于横向滚动的列表容器。
  2. 页面由命名清晰的组成部分 组成。页面的 JSX 读起来就像是产品自身语言对页面的概述:页面上人能指出的每个部分都有一个命名的组件。每个部分是一个小组件,拥有自己的语义元素和样式类,因此页面本身没有原始的 HTML 标签和类字符串。阅读页面就知道上面有什么;打开一个部分就知道它长什么样。
    // 错误的做法:页面是一棵由标签和类组成的树,每个盒子是什么需要仔细推敲。
    <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>
    
    // 每个部分持有自己的元素和样式类,只需定义一次。
    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 返回一个能携带每种状态数据的可区分联合,页面则对其进行穷举的 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 会在构建时失败。
  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. 子组件报告,父组件决策。 属性是携带事实的事件(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)从这些状态推导得出。不要有镜像属性或其他状态的状态,也不要有仅从其他状态设置状态的副作用。副作用用于与 React 外部的对象同步(如 fetch、定时器、订阅、DOM),并且必须进行清理。一个 Hook 模拟一件事。
    // 只存储用户做了什么以及从外部传来了什么。
    const [query, setQuery] = useState("");
    const { products } = useProducts();                 // 通过 fetch 获取;其副作用会进行清理
    
    // 其余内容在每次渲染时推导,使用普通模块中的纯函数。
    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。

相关技能