Part i exportparts do stylizacji zewnętrznej

Ścisła hermetyzacja stylów Shadow DOM uniemożliwia użytkownikom ponowne stylowanie pojedynczych elementów wewnątrz komponentu. Zmienne CSS sprawdzają się w przypadku globalnych właściwości, ale nie można na przykład nadać wewnętrznemu przyciskowi "close" niestandardowego border-radius. Rozwiązaniem są parts.

Element wewnętrzny shadow DOM należy oznaczyć za pomocą part="name". Użytkownicy mogą następnie wskazywać go za pomocą pseudoelementu ::part(name): my-dialog::part(close-button) { color: red; }. Nazwany element staje się punktem stylowania, podczas gdy reszta shadow DOM pozostaje hermetyczna.

Aby udostępnić jeden element jako wiele parts, należy rozdzielić ich nazwy spacjami: part="button primary". ::part(button) wskazuje go ogólnie, a ::part(primary) — jako element w stylu głównym. Każda nazwa jest dopasowywana niezależnie.

::part pozwala używać tylko niektórych pseudoklas (:hover, :focus, :disabled) — nie pozwala natomiast używać kombinatorów potomstwa ani dalszego wyboru strukturalnego. ::part(card) p jest nieprawidłowe; nie można dostać się do wnętrza part za pomocą selektorów potomstwa.

Gdy element niestandardowy umieszcza wewnątrz własnego shadow DOM inny element niestandardowy, parts elementu wewnętrznego nie są normalnie udostępniane stronie zewnętrznej. Atrybut exportparts="close-button" na zagnieżdżonym elemencie przekazuje te parts do zewnętrznego hosta.

exportparts="close-button: dismiss" eksportuje wewnętrzny part pod nową nazwą na elemencie zewnętrznym. Dzięki temu komponent zewnętrzny może udostępniać przejrzysty interfejs nazw niezależny od tego, które elementy wewnętrzne składają się na jego implementację.

Niestandardowe właściwości CSS udostępniają wartości (kolory, odstępy, czcionki). Parts udostępniają elementy (pełny zakres możliwości CSS — obramowania, transformacje, animacje). Niestandardowych właściwości CSS należy używać dla globalnych tokenów, a parts dla jednorazowej personalizacji na poziomie elementu. Oba mechanizmy mogą współistnieć w tym samym komponencie.

Praktyka stosowana w systemach projektowych: należy udostępnić niewielki zestaw parts dla elementów najczęściej personalizowanych (przycisków, nagłówków, wskaźników) oraz obszerny zestaw niestandardowych właściwości CSS dotyczących kolorów, odstępów i typografii. Użytkownicy mogą tworzyć motywy na poziomie wartości albo elementów, zależnie od potrzeb.

Nazwy parts stają się częścią publicznego API komponentu — ich zmiana powoduje uszkodzenie CSS użytkowników. Należy wybierać nazwy opisujące rolę elementu ("close-button", "header", "track"), a nie jego pozycję ("first-button"), aby API pozostało zrozumiałe w miarę rozwoju implementacji.

W pliku readme komponentu należy wymienić wszystkie dostępne parts (oraz parts eksportowane). Bez dokumentacji użytkownicy muszą sprawdzać DOM, aby je odkryć, co wiąże ich z tym, co akurat znajdą. Listę parts należy traktować jak listę props komponentu frameworka.

::part i exportparts są dostępne we wszystkich nowoczesnych przeglądarkach. Nawet starsze wersje Safari obsługują już ::part. Można ich swobodnie używać; w bardzo starych przeglądarkach (w większości już nieużywanych) obejściem jest zastosowanie dodatkowych niestandardowych właściwości CSS.

Do czego służy atrybut exportparts?

Atrybut part udostępnia pojedyncze elementy shadow DOM do zewnętrznego stylowania za pomocą ::part(name) — zapewniając pełne możliwości CSS bez naruszania hermetyzacji. exportparts przekazuje parts z zagnieżdżonych elementów niestandardowych do zewnętrznego hosta i opcjonalnie zmienia ich nazwy. Parts należy łączyć z niestandardowymi właściwościami CSS, aby uzyskać kompletny interfejs tworzenia motywów, a listę parts dokumentować jako część API komponentu.