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は、製品の言葉で書かれた画面のアウトラインとして読めるようにします。つまり、人が指さす各部分に対して、1つの名前付きコンポーネントを用意します。各部分は、自身のセマンティック要素とクラスを保持する小さなコンポーネントであり、画面自体には生の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>; } - 名前は、2年生が推測できるものにする。 物事には平易な言葉を使用します:
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の前に数行を超える状態、副作用、または導出がある場合は、それがモデル化するものにちなんだ名前のフック(useProductSearch)にまとめ、そのフックはファクトとアクションを返します。// 良くない例: 何が描画されるかを誰もが見られるようになる前に、40行の状態と副作用がある。 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を呼び出し、catch */ }; // ... さらに30行 ... return <CatalogLayout>...</CatalogLayout>; } // 良い例: モデル化するものにちなんだ1つのフック、そしてJSX。 function CatalogScreen({ onAdd }: Props) { const search = useProductSearch({ onAdd }); return ( <CatalogLayout> <CategoryList categories={search.categories} onAdd={search.add} /> </CatalogLayout> ); } - 排他的なビューには1つのタグ付き状態を使用する。 画面が複数のうちの正確に1つを表示する場合、純粋関数またはフックは各状態のデータを保持する識別共用体を返し、画面はそれを網羅的に
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 />; // 良い例: 1つの関数が決定し、各ケースが必要とするデータを返す。 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をインポートしないプレーンなモジュール内の純粋関数とします。これにより、レンダリングなしで再利用および単体テストが可能になります。フックまたはコンポーネントがそれを呼び出します。それを含みません。そのコードの配置場所、レイヤー化の方法、コンポーネントからの取り出し方については、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))); } // フックはそれを呼び出すだけ。 const shown = productsMatching(products, query); - 子は報告し、親が決定する。 Propsは、イベントとファクト(
onAdd(product))であり、親のセッターであってはなりません。// 良くない例: 子に親のセッターが渡され、追加の意味を子が決定する。 <ProductCard product={p} setBasket={setBasket} setError={setError} /> // 良い例: 子は何が起こったかをファクトと共に報告し、親が決定する。 <ProductCard product={p} onAdd={() => { add(p); }} /> - 繰り返されるマークアップは、2回目に記述された時点でコンポーネントにする。
// 良くない例: 同じページ背景とパディングが4つの画面に記述されている。 <div className="relative flex h-screen w-screen flex-col bg-gray-50 p-8">...</div> // 良い例: 2回目に必要になった時点で1回だけ記述される。 <PageLayout>...</PageLayout> - フックは薄く、導出し、保存しない。 フックは、計算できない状態のみを保持します:ユーザーが行ったことと、外部から到着したものです。その他はすべて、ルール6の純粋関数によって、その状態からレンダリング中に導出されます。プロップや別の状態をミラーリングする状態はなく、別の状態からのみ状態を設定する副作用もありません。副作用は、Reactの外部(フェッチ、タイマー、サブスクリプション、DOM)と同期するためのものであり、自身のクリーンアップを行います。1つのフックは1つのことをモデル化します。
// ユーザーが行ったことと、外部から到着したもののみを保存する。 const [query, setQuery] = useState(""); const { products } = useProducts(); // フェッチされたもの。その副作用はクリーンアップを行う。 // 残りは、プレーンなモジュールの純粋関数を使って、レンダリングのたびに導出する。 const shown = productsMatching(products, query); const empty = shown.length === 0; // 良くない例: ずれてしまうコピー。2回レンダリングする副作用によって設定される。 // 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、時刻、生成コード)を取り除き、実際の差異が際立つようにします。
分割自体を目的にしないでください。画面は全体として読み取れる必要があり、ルールのないコンポーネントにはフックは必要ありません。