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 和 Space 触发,无需额外代码;time和search表明其内容含义。只在没有具体含义的地方保留div,例如用于横向滚动的列表容器。 - 页面由命名清晰的组成部分 组成。页面的 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>; } - 名称要让二年级学生也能猜出来。 使用描述事物本身的最直白的词:
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 返回一个能携带每种状态数据的可区分联合,页面则对其进行穷举的
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 会在构建时失败。 - 业务逻辑存在于 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); - 子组件报告,父组件决策。 属性是携带事实的事件(
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)从这些状态推导得出。不要有镜像属性或其他状态的状态,也不要有仅从其他状态设置状态的副作用。副作用用于与 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]); - 拆分组件不能改变绘制的内容。 在拆分前后记录渲染出的标记并进行比较;一个通过的测试套件并不能证明移除了一个包装器没有改变内容。
# 在修改前记录每个页面渲染出的标记,进行修改,再次记录,然后比较。
node record-markup.mjs before/ # 您自己的 Playwright 脚本:打开每个页面状态,将 document.body 保存为 HTML
node record-markup.mjs after/
diff -r before/ after/ # 只有您打算改变的元素才应该有差异
在比较之前,剔除每次运行会变化的内容(如 ID、时间、生成的代码),这样真实的差异才会凸显出来。
不要为了拆分而拆分:页面仍然需要整体可读,没有规则的组件不需要 Hook。