Composants React : sémantiques, composés, centrés sur le balisage
Un écran doit être lisible tel qu'il est constitué, par une personne et par un lecteur d'écran. Appliquez ces règles lors de l'écriture ou de la modification de composants React, dans n'importe quel projet.
- Les éléments disent ce qu'ils sont. Utilisez
main,header,footer,nav,section,search,ul/li,button,time,form. Undivou unspann'est que pour une boîte qui existe pour la mise en page ou le défilement.Ce que chaque choix apporte :// Pas ça : chaque boîte est un div, donc un lecteur d'écran entend un long texte continu, et // le "bouton" ne peut pas être atteint avec Tab ni activé avec Entrée. <div className="page"> <div className="top"> <span className="updated">10:42</span> <div className="search"><input placeholder="Rechercher" /></div> </div> <div className="group"> <div className="group-name">Fruit</div> <div className="items"> <div className="item" onClick={add}>Pommes</div> </div> </div> </div> // Ceci : chaque élément dit ce qu'il est, donc les points de repère, les listes et les boutons viennent gratuitement. <main> <header> <time dateTime="10:42">10:42</time> <search><input type="search" aria-label="Rechercher des produits" /></search> </header> <section aria-labelledby="fruit"> <h2 id="fruit">Fruit</h2> <ul> <li><button type="button" onClick={add}>Pommes</button></li> </ul> </section> </main>mainetheaderpermettent à un lecteur d'écran de naviguer entre les parties de la page ;sectionavec sonh2nomme la région ;ul/lidit "liste, 5 éléments" ;buttonest accessible par Tab et activé par Entrée et Espace sans code supplémentaire ;timeetsearchdisent ce que leur contenu est. Gardez undivlà où rien n'est signifié, comme la boîte qui fait défiler une liste horizontalement. - Un écran est une composition de parties nommées. Le JSX d'un écran se lit comme un plan de l'écran dans les propres mots du produit : un composant nommé pour chaque partie qu'une personne pointerait. Chaque partie est un petit composant qui possède son élément sémantique et ses classes, de sorte que l'écran lui-même n'a pas de balises HTML brutes ni de chaînes de classes. Lire l'écran vous dit ce qu'il contient ; ouvrir une partie vous dit à quoi elle ressemble.
Une partie mérite d'être nommée quand une personne l'appellerait quelque chose ("l'en-tête", "une rangée de produits", "le bouton retour"). Un wrapper qui n'existe que pour l'espacement reste à l'intérieur de la partie qui en a besoin, pas dans l'écran.// Pas ça : l'écran est un arbre de balises et de classes, et ce qu'est chaque boîte doit être déduit. <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">Boutique</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">{/* cartes produit */}</div> </div> ))} </div> <button className="absolute bottom-2 left-8 rounded-full" onClick={onBack}>←</button> </div> // Ceci : l'écran est ses parties, nommées pour ce qu'elles sont. <CatalogLayout heading="Produits"> <CatalogHeader> <ShopName /> <StoreName name={storeName} /> </CatalogHeader> <CategoryList categories={categories} onAdd={add} /> <BackButton label="Retour à la boutique" onBack={onBack} /> </CatalogLayout> // Chaque partie possède son propre élément et ses classes, une fois. function CatalogHeader({ children }: { children: ReactNode }) { return <header className="flex items-center gap-3 px-8">{children}</header>; } - Noms qu'un étudiant de deuxième année devinerait. Utilisez le mot simple pour la chose :
Layout,Header,Row,Card,List,Panel,Button,Margin. Pas de métaphore et pas de jargon professionnel (Frame,Rail,Strip,Gutter,Chrome,Shell) sauf si les propres utilisateurs du produit disent ce mot. Test : quelqu'un qui n'a jamais vu le code peut dire ce que<ProductRow>dessine.// Pas ça : métaphore et jargon qu'un nouveau venu doit décoder. <PageFrame><TopRail /><ProductStrip gutter={GUTTER} /></PageFrame> // Ceci : le mot simple pour chaque chose. <PageLayout><PageHeader /><ProductRow margin={LEFT_MARGIN} /></PageLayout> - Balisage d'abord. Le corps d'un composant est son JSX. Plus de quelques lignes d'état, d'effets ou de dérivation avant le
returnvont dans un hook nommé pour ce qu'il modélise (useProductSearch), qui retourne des faits et des actions.// Pas ça : quarante lignes d'état et d'effets avant que quiconque puisse voir ce qui est dessiné. function CatalogScreen({ onAdd }: Props) { const [products, setProducts] = useState<Product[] | null>(null); const [query, setQuery] = useState(""); const [adding, setAdding] = useState<string | null>(null); useEffect(() => { /* récupérer les produits, se protéger contre le démontage */ }, []); const categories = useMemo(() => /* filtrer, puis grouper */, [products, query]); const add = (p: Product) => { /* définir adding, appeler onAdd, attraper */ }; // ... trente lignes de plus ... return <CatalogLayout>...</CatalogLayout>; } // Ceci : un hook nommé pour ce qu'il modélise, puis le JSX. function CatalogScreen({ onAdd }: Props) { const search = useProductSearch({ onAdd }); return ( <CatalogLayout> <CategoryList categories={search.categories} onAdd={search.add} /> </CatalogLayout> ); } - Un état étiqueté pour les vues exclusives. Lorsqu'un écran affiche exactement une chose parmi plusieurs, une fonction pure ou un hook retourne une union discriminée qui porte les données de chaque état, et l'écran est un
switchexhaustif dessus. Pas de ternaires imbriqués et pas de chaîne de retours anticipés.Avec// Pas ça : une chaîne de conditions, où l'ordre est la logique et un cas est facile à manquer. if (!loaded) return <Spinner />; if ("error" in loaded) return <Notice title="Impossible de charger la commande" />; if (order.cancelled) return <Notice title="Annulée" />; return order.items.length === 0 ? <EmptyBasket /> : order.paid ? <Receipt /> : <Checkout />; // Ceci : une fonction décide et retourne les données dont chaque cas a besoin. 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="Impossible de charger la commande" detail={view.error} />; case "cancelled": return <Notice title="Annulée" />; case "empty": return <EmptyBasket />; case "checkout": return <Checkout order={view.order} />; case "paid": return <ReceiptPage order={view.order} receipt={view.receipt} />; }kindexhaustif, TypeScript échoue la construction lorsqu'un nouveau cas est ajouté et non dessiné. - La logique métier vit en dehors de React. Tout ce qui décide, vérifie, filtre, trie ou calcule est une fonction pure dans un module simple qui n'importe pas React, afin qu'elle puisse être réutilisée et testée unitairement sans rendu. Un hook ou un composant l'appelle ; il ne la contient pas. Où va ce code, comment le superposer et comment le sortir d'un composant sont dans la compétence business-logic.
// productSearch.ts : pas d'import React, donc il s'exécute et est testé tout seul. 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))); } // Le hook ne fait que l'appeler. const shown = productsMatching(products, query); - Les enfants rapportent, les parents décident. Les props sont des événements avec des faits (
onAdd(product)), jamais un setter du parent.// Pas ça : l'enfant reçoit les setters du parent et décide ce que signifie ajouter. <ProductCard product={p} setBasket={setBasket} setError={setError} /> // Ceci : l'enfant rapporte ce qui s'est passé, avec les faits ; le parent décide. <ProductCard product={p} onAdd={() => { add(p); }} /> - Un balisage répété devient un composant la deuxième fois qu'il est écrit.
// Pas ça : le même fond de page et le même remplissage écrits dans quatre écrans. <div className="relative flex h-screen w-screen flex-col bg-gray-50 p-8">...</div> // Ceci : écrit une fois, la deuxième fois qu'il était nécessaire. <PageLayout>...</PageLayout> - Les hooks sont fins et dérivent, ne stockent pas. Un hook ne garde que l'état qui ne peut pas être calculé : ce que l'utilisateur a fait et ce qui est arrivé de l'extérieur. Tout le reste est dérivé pendant le rendu à partir de cet état, par les fonctions pures de la règle 6. Pas d'état qui reflète une prop ou un autre état, et pas d'effet qui ne fait que définir un état à partir d'un autre état. Un effet est pour se synchroniser avec quelque chose en dehors de React (un fetch, un minuteur, un abonnement, le DOM), et se nettoie après lui-même. Un hook modélise une chose.
// Stockez seulement ce que l'utilisateur a fait et ce qui est arrivé de l'extérieur. const [query, setQuery] = useState(""); const { products } = useProducts(); // récupéré ; son effet se nettoie // Dérivez le reste à chaque rendu, avec des fonctions pures d'un module simple. const shown = productsMatching(products, query); const empty = shown.length === 0; // Pas ça : une copie qui dérive, définie par un effet qui rend deux fois. // const [shown, setShown] = useState(products); // useEffect(() => { setShown(productsMatching(products, query)); }, [products, query]); - Une scission ne doit pas changer ce qui est dessiné. Enregistrez le balisage rendu avant et après et comparez ; une suite de tests réussie ne montre pas un wrapper déplacé.
# Enregistrez le balisage rendu de chaque écran avant le changement, faites le changement, enregistrez à nouveau, et comparez.
node record-markup.mjs before/ # votre propre script Playwright : ouvre chaque état d'écran, sauvegarde document.body sous forme de HTML
node record-markup.mjs after/
diff -r before/ after/ # seuls les éléments que vous vouliez changer doivent différer
Supprimez ce qui change d'une exécution à l'autre (ids, heures, codes générés) avant de comparer, afin qu'une vraie différence se démarque.
Ne scindez pas pour le plaisir : un écran doit toujours être lisible dans son ensemble, et un composant sans règles n'a besoin d'aucun hook.