React-Komponenten: semantisch, komponiert, markup-zentriert
Ein Bildschirm muss lesbar sein als das, woraus er besteht – für einen Menschen und für einen Screenreader. Wende diese Regeln an, wenn du in einem beliebigen Projekt React-Komponenten schreibst oder änderst.
- Elemente sagen, was sie sind. Verwende
main,header,footer,nav,section,search,ul/li,button,time,form. Eindivoderspanist nur für eine Box, die für Layout oder Scrollen existiert.Was jede Wahl bringt:// Nicht so: Jede Box ist ein div, daher hört ein Screenreader einen langen Textblock, // und der "Button" kann weder mit Tab erreicht noch mit Enter gedrückt werden. <div className="page"> <div className="top"> <span className="updated">10:42</span> <div className="search"><input placeholder="Suche" /></div> </div> <div className="group"> <div className="group-name">Obst</div> <div className="items"> <div className="item" onClick={add}>Äpfel</div> </div> </div> </div> // So: Jedes Element sagt, was es ist – Landmarken, Listen und Buttons sind automatisch. <main> <header> <time dateTime="10:42">10:42</time> <search><input type="search" aria-label="Produkte durchsuchen" /></search> </header> <section aria-labelledby="obst"> <h2 id="obst">Obst</h2> <ul> <li><button type="button" onClick={add}>Äpfel</button></li> </ul> </section> </main>mainundheaderermöglichen einem Screenreader, zwischen Teilen der Seite zu springen;sectionmit seinemh2benennt die Region;ul/lisagt "Liste, 5 Elemente";buttonist mit Tab erreichbar und kann ohne zusätzlichen Code mit Enter und Space gedrückt werden;timeundsearchsagen, was ihr Inhalt ist. Behalte eindivdort, wo nichts Gemeintes ist, z. B. die Box, die eine Liste seitlich scrollt. - Ein Bildschirm ist eine Komposition benannter Teile. Das JSX eines Bildschirms liest sich wie eine Gliederung des Bildschirms in den eigenen Worten des Produkts: eine benannte Komponente für jeden Teil, auf den eine Person zeigen würde. Jeder Teil ist eine kleine Komponente, die ihr eigenes semantisches Element und ihre eigenen Klassen besitzt, sodass der Bildschirm selbst keine rohen HTML-Tags und keine class-Strings enthält. Das Lesen des Bildschirms sagt dir, was darauf ist; das Öffnen eines Teils sagt dir, wie er aussieht.
Ein Teil ist es wert, benannt zu werden, wenn eine Person ihn als etwas bezeichnen würde ("der Header", "eine Produktzeile", "der Zurück-Button"). Ein Wrapper, der nur für Abstände existiert, bleibt innerhalb des Teils, der ihn braucht, nicht im Bildschirm.// Nicht so: Der Bildschirm ist ein Baum aus Tags und Klassen, und was jede Box ist, muss erschlossen werden. <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">Shop</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">{/* Produktkarten */}</div> </div> ))} </div> <button className="absolute bottom-2 left-8 rounded-full" onClick={onBack}>←</button> </div> // So: Der Bildschirm ist seine Teile, benannt nach dem, was sie sind. <CatalogLayout heading="Produkte"> <CatalogHeader> <ShopName /> <StoreName name={storeName} /> </CatalogHeader> <CategoryList categories={categories} onAdd={add} /> <BackButton label="Zurück zum Shop" onBack={onBack} /> </CatalogLayout> // Jeder Teil hält sein eigenes Element und seine eigenen Klassen, einmal. function CatalogHeader({ children }: { children: ReactNode }) { return <header className="flex items-center gap-3 px-8">{children}</header>; } - Namen, die ein Zweitsemester erraten würde. Verwende das einfache Wort für das Ding:
Layout,Header,Row,Card,List,Panel,Button,Margin. Keine Metaphern und keine Fachjargon (Frame,Rail,Strip,Gutter,Chrome,Shell), es sei denn, die eigenen Benutzer des Produkts sagen dieses Wort. Test: Jemand, der den Code noch nie gesehen hat, kann sagen, was<ProductRow>zeichnet.// Nicht so: Metaphern und Jargon, die ein Neuling erst entschlüsseln muss. <PageFrame><TopRail /><ProductStrip gutter={GUTTER} /></PageFrame> // So: Das einfache Wort für jedes Ding. <PageLayout><PageHeader /><ProductRow margin={LEFT_MARGIN} /></PageLayout> - Markup zuerst. Der Hauptteil einer Komponente ist ihr JSX. Mehr als ein paar Zeilen Zustand, Effekte oder Ableitungen vor dem
returnkommen in einen Hook, der nach dem benannt ist, was er modelliert (useProductSearch), und der Fakten und Aktionen zurückgibt.// Nicht so: Vierzig Zeilen Zustand und Effekte, bevor jemand sehen kann, was gezeichnet wird. function CatalogScreen({ onAdd }: Props) { const [products, setProducts] = useState<Product[] | null>(null); const [query, setQuery] = useState(""); const [adding, setAdding] = useState<string | null>(null); useEffect(() => { /* Produkte abrufen, gegen Unmount sichern */ }, []); const categories = useMemo(() => /* filtern, dann gruppieren */, [products, query]); const add = (p: Product) => { /* adding setzen, onAdd aufrufen, Fehler abfangen */ }; // ... dreißig weitere Zeilen ... return <CatalogLayout>...</CatalogLayout>; } // So: Ein Hook, benannt nach dem, was er modelliert, dann das JSX. function CatalogScreen({ onAdd }: Props) { const search = useProductSearch({ onAdd }); return ( <CatalogLayout> <CategoryList categories={search.categories} onAdd={search.add} /> </CatalogLayout> ); } - Ein getaggter Zustand für exklusive Ansichten. Wenn ein Bildschirm genau eines von mehreren Dingen zeigt, gibt eine reine Funktion oder ein Hook eine diskriminierte Union zurück, die die Daten jedes Zustands trägt, und der Bildschirm ist ein erschöpfendes
switchdarüber. Keine verschachtelten ternären Operatoren und keine Kette von frühen Returns.Mit erschöpfender// Nicht so: Eine Kette von Bedingungen, bei der die Reihenfolge die Logik ist und ein Fall leicht übersehen wird. if (!loaded) return <Spinner />; if ("error" in loaded) return <Notice title="Bestellung konnte nicht geladen werden" />; if (order.cancelled) return <Notice title="Storniert" />; return order.items.length === 0 ? <EmptyBasket /> : order.paid ? <Receipt /> : <Checkout />; // So: Eine Funktion entscheidet und gibt die Daten zurück, die jeder Fall benötigt. 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="Bestellung konnte nicht geladen werden" detail={view.error} />; case "cancelled": return <Notice title="Storniert" />; case "empty": return <EmptyBasket />; case "checkout": return <Checkout order={view.order} />; case "paid": return <ReceiptPage order={view.order} receipt={view.receipt} />; }kind-Prüfung schlägt TypeScript den Build fehl, wenn ein neuer Fall hinzugefügt und nicht gezeichnet wird. - Geschäftslogik lebt außerhalb von React. Alles, was entscheidet, prüft, filtert, sortiert oder berechnet, ist eine reine Funktion in einem einfachen Modul, das React nicht importiert, sodass es ohne Rendern wiederverwendet und unit-getestet werden kann. Ein Hook oder eine Komponente ruft es auf; es enthält sie nicht. Wo dieser Code hingehört, wie man ihn schichtet und wie man ihn aus einer Komponente herausholt, steht im business-logic-Skill.
// productSearch.ts: Kein React-Import, also läuft es und wird eigenständig getestet. 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))); } // Der Hook ruft es nur auf. const shown = productsMatching(products, query); - Kinder melden, Eltern entscheiden. Props sind Ereignisse mit Fakten (
onAdd(product)), niemals ein Setter des Eltern-Elements.// Nicht so: Dem Kind werden die Setter des Elternteils übergeben, und es entscheidet, was Hinzufügen bedeutet. <ProductCard product={p} setBasket={setBasket} setError={setError} /> // So: Das Kind meldet, was passiert ist, mit den Fakten; das Elternteil entscheidet. <ProductCard product={p} onAdd={() => { add(p); }} /> - Wiederholtes Markup wird beim zweiten Mal zur Komponente.
// Nicht so: Derselbe Seitenhintergrund und -abstand in vier Bildschirmen ausgeschrieben. <div className="relative flex h-screen w-screen flex-col bg-gray-50 p-8">...</div> // So: Einmal geschrieben, beim zweiten Mal, als es gebraucht wurde. <PageLayout>...</PageLayout> - Hooks sind dünn und leiten ab, nicht speichern. Ein Hook behält nur den Zustand, der nicht berechnet werden kann: was der Benutzer getan hat und was von außen gekommen ist. Alles andere wird während des Renderings aus diesem Zustand abgeleitet, durch die reinen Funktionen von Regel 6. Kein Zustand, der ein Prop oder einen anderen Zustand spiegelt, und kein Effekt, der nur einen Zustand aus einem anderen Zustand setzt. Ein Effekt dient der Synchronisation mit etwas außerhalb von React (einem Fetch, einem Timer, einem Abonnement, dem DOM) und räumt nach sich auf. Ein Hook modelliert eine Sache.
// Speichere nur, was der Benutzer getan hat und was von außen gekommen ist. const [query, setQuery] = useState(""); const { products } = useProducts(); // abgerufen; sein Effekt räumt auf // Leite den Rest jedes Renderns mit reinen Funktionen aus einem einfachen Modul ab. const shown = productsMatching(products, query); const empty = shown.length === 0; // Nicht so: Eine Kopie, die abweicht, gesetzt durch einen Effekt, der zweimal rendert. // const [shown, setShown] = useState(products); // useEffect(() => { setShown(productsMatching(products, query)); }, [products, query]); - Eine Aufteilung darf nicht ändern, was gezeichnet wird. Zeichne das gerenderte Markup vorher und nachher auf und vergleiche; eine bestehende Testsuite zeigt keinen verschobenen Wrapper an.
# Zeichne das gerenderte Markup jedes Bildschirms vor der Änderung auf, nimm die Änderung vor,
# zeichne es erneut auf und vergleiche.
node record-markup.mjs before/ # eigenes Playwright-Skript: öffnet jeden Bildschirmzustand, speichert document.body als HTML
node record-markup.mjs after/
diff -r before/ after/ # nur die Elemente, die du ändern wolltest, sollten sich unterscheiden
Entferne, was sich von Lauf zu Lauf ändert (IDs, Zeiten, generierte Codes), bevor du vergleichst, damit ein echter Unterschied auffällt.
Teile nicht um des Teilens willen auf: Ein Bildschirm muss immer noch als Ganzes lesbar sein, und eine Komponente ohne Regeln braucht keinen Hook.