Orientacja komponentów internetowych

Komponenty internetowe to elementy niestandardowe, model Shadow DOM i szablony HTML: elementy podstawowe platformy do tworzenia komponentów wielokrotnego użytku, niezależnych od platformy, których znaczniki i style są odizolowane od dokumentu. Używaj ich w systemach projektowania, widżetach do umieszczenia i samodzielnych interfejsach.

Poniższe reguły mają charakter przekrojowy. Pobierz konkretny przewodnik dotyczący danego zadania. Każdy z nich zawiera informacje o potrzebnym kontekście oraz dokumentację interfejsów API i potencjalnych problemów.

Zdecyduj, czy potrzebujesz elementu niestandardowego

Używaj elementu niestandardowego tylko wtedy, gdy potrzebujesz hermetyzowanego działania, cyklu życia lub interfejsu API opartego na JS, który można wielokrotnie wykorzystywać w tagu. Nie twórz go, gdy:

• Wystarczy zwykły element HTML z CSS. Stylizowany element <button> lub <details> jest bardziej dostępny i tańszy niż ponowna implementacja.
• Element ma charakter wyłącznie prezentacyjny i nie ma żadnego działania. Klasa w elemencie natywnym jest bardziej wydajna i można ją ograniczyć za pomocą @layer lub @scope.
• Potrzebujesz tylko określania zakresu stylów na serwerze bez interaktywności. Może wystarczyć arkusz stylów z określonym zakresem lub deklaratywny shadow DOM (bez uaktualnienia).

Odtwarzanie semantyki natywnej (niestandardowy element <my-button>, który odtwarza zaznaczenie, aktywację i ARIA) to najczęstsze nadużycie: dziedziczysz ułatwienia dostępu platformy bezpłatnie tylko wtedy, gdy ponownie używasz elementu natywnego. Jeśli uzasadnione jest użycie opakowania w stylu <my-button> (zwykle w przypadku współdzielonych punktów zaczepienia stylów, dodatkowych znaczników lub zachowań, których nie można wyrazić za pomocą elementu natywnego), opakuj rzeczywisty element <button>, zamiast implementować go ponownie (zobacz Styling Web Components, aby dowiedzieć się, jak przekazywać style do wewnętrznego elementu natywnego).

The test is whether you need encapsulated state, a scriptable API, or behavior the native element can't express – not merely a different look. Przełącznik polubienia/ulubionych spełnia te wymagania: zawiera stan domeny, udostępnia ten stan jako element stylizacji dla otaczającej strony i wysyła własne zdarzenie change – żadnej z tych funkcji nie zapewnia stylizowany element <button>. Przycisk, który zmienia kolor tylko po naciśnięciu, nie spełnia tego warunku: użyj <button> + CSS. Gdy go utworzysz, zamodeluj jego stan za pomocą niestandardowego stanu lub atrybutu (patrz Elementy niestandardowe).

Dopasowywanie narzędzia do bazy kodu

To, czy coś powinno być elementem niestandardowym, zależy od tego, co jest już używane w projekcie. Agenci mają tendencję do nadmiernego abstrahowania i zbyt chętnego sięgania po nowy element. W razie wątpliwości lżejsza opcja (element natywny, CSS, szablon serwera) jest zwykle właściwa, a później możesz przejść na element niestandardowy, jeśli wymaga tego ponowne użycie lub zachowanie. Heurystyka, w przybliżonym priorytecie:

• Baza kodu ma już model komponentu (React, Vue, Svelte…). Domyślnie używaj komponentu tej platformy w interfejsie aplikacji. Element niestandardowy należy stosować tylko wtedy, gdy musi on wykraczać poza ramy frameworka lub działać dłużej niż on: prymityw systemu projektowania udostępniany w aplikacjach lub frameworkach, widżet umieszczony w znacznikach, których framework nie kontroluje, lub dane wyjściowe, które muszą działać jako zwykły kod HTML (e-mail, CMS, fragmenty SSR). Nie twórz równoległego systemu komponentów dla zwykłych widoków aplikacji.
• Brak narzędzi, głównie statyczne znaczniki. Prefer plain HTML + CSS, or a server template/partial. Element niestandardowy jest przydatny tylko wtedy, gdy naprawdę potrzebujesz zachowania, cyklu życia lub interfejsu API opartego na JS w tagu – nie tylko do udostępniania znaczników, co robi serwer lub <template> bez wysyłania JS.
• Generator witryn statycznych z wyspami interaktywności. Wyrenderuj znaczniki statycznie, a element niestandardowy zarezerwuj dla części interaktywnej. W przypadku „dużej ilości znaczników i niewielkiej interaktywności” zachowaj znaczniki w Light DOM (lub Declarative Shadow DOM) i pozwól, aby mały element niestandardowy stopniowo je ulepszał, zamiast renderować wszystko od nowa z JS.
• Zamiast tego możesz rozszerzyć wbudowany element. Zwykle lepiej jest wykorzystać element natywny w jak największym stopniu (CSS, kilka detektorów, czasem pseudoelement) niż element niestandardowy, ponieważ dzięki temu zachowujesz dostępność i zachowanie platformy bez dodatkowych kosztów. Przejdź na element niestandardowy, gdy obejścia przestaną być możliwe do utrzymania – gdy będziesz walczyć z wbudowanym zachowaniem elementu lub gdy proces tworzenia stanie się gorszy niż w przypadku czystego interfejsu API komponentu. Potrzeba użycia niewielkiej ilości kodu JS we wbudowanym elemencie nie jest sama w sobie powodem do jego zastąpienia.

Reguły przekrojowe

Te zasady obowiązują we wszystkich poniższych przewodnikach:

• OBOWIĄZKOWO: nazwa tagu musi być w formacie kebab-case i zawierać co najmniej 1 łącznik (np. my-element). To odróżnia elementy niestandardowe od obecnych i przyszłych elementów wbudowanych.
• OBOWIĄZKOWO: wywołaj najpierw super() w konstruktorze, zanim dotkniesz this; wywołanie po dowolnej instrukcji, która odczytuje lub zapisuje this, powoduje błąd.
• OBOWIĄZKOWO: używaj elementów semantycznych (<button>, <nav>, <ul>) w szablonach shadow. Większość błędów ułatwień dostępu w drzewach shadow wynika z niesemantycznych znaczników. Slot nie zmienia roli tego, co wyświetla.
• OBOWIĄZKOWE: odwołania ARIA id (aria-labelledby, aria-describedby, aria-controls) nie mogą przekraczać granicy shadow; element odwołujący się i id, do którego się odwołuje, muszą znajdować się w tym samym drzewie.
• Preferuj attachShadow({ mode: 'open' }), aby narzędzia dla programistów, skrypty strony i hydratacja serwera mogły dotrzeć do element.shadowRoot. Używaj 'closed' tylko wtedy, gdy musisz ukryć strukturę wewnętrzną przed skryptami strony.
• Unikaj dostosowanych elementów wbudowanych (extends HTMLButtonElement z is="…"); Safari trwale odmówiło ich dostarczania.

Tabela przewodników po przypadkach użycia

Zidentyfikuj zadanie i pobierz przewodnik: