Item

Anatomia#

Instalacja#

$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/item.json

Użycie#

import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@/components/ui/item"

<Item variant="outline">
  <ItemMedia variant="icon">
    <GitBranchIcon />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Connect a repository</ItemTitle>
    <ItemDescription>Deploy on every push to main.</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button size="sm" variant="outline">Connect</Button>
  </ItemActions>
</Item>

Przykłady#

Warianty#

default wtapia się w powierzchnię, na której leży, outline to wyniesiony kafelek, a muted — wpuszczona w tło wnęka.

Rozmiary#

default, sm i xs skalują jednocześnie odstępy wewnętrzne, odstępy między częściami i grafikę. Używaj sm w listach wewnątrz kart, a xs w menu.

Grafika#

ItemMedia mieści kafelek z ikoną (variant="icon"), obraz (variant="image") albo cokolwiek innego — Avatar, oznaczenie typu pliku. Gdy element ma opis, grafika wyrównuje się do góry.

Lista#

ItemGroup zamienia elementy w listę: grupa dostaje role="list", a każdy zwykły element automatycznie staje się elementem listy. ItemSeparator rysuje cienkie linie między wierszami, a czytniki ekranu go pomijają.

Jako link#

Gdy cały wiersz prowadzi w inne miejsce, wyrenderuj element jako link przez render. Style najechania i fokusu działają automatycznie. Zestaw linków owiń w <nav> z etykietą, a nie w ItemGroup — link nie może być jednocześnie elementem listy.

<Item variant="outline" render={<a href="/docs" />}>
  …
</Item>

Nagłówek i stopka#

ItemHeader i ItemFooter zajmują całą szerokość nad wierszem i pod nim — na postęp, metadane lub akcje drugorzędne.

Wytyczne#

Kiedy używać#

• W wierszach, które opisują jeden obiekt z opcjonalną akcją: członka zespołu, plik, integrację, ustawienie.
• W krótkich listach, w których każdy wiersz łączy grafikę, tekst i kontrolki.

Kiedy nie używać#

• Przy wielu wierszach porównywanych w tych samych kolumnach — użyj komponentu Table.
• Przy pojedynczym, rozbudowanym obiekcie — wybierz Card.
• W menu nawigacyjnych z samymi ikonami — sięgnij po Sidebar lub Dropdown Menu.

Jedna główna akcja na wiersz#

Treść#

• Tytuły mieść w jednej linii, a opisy w dwóch — dłuższe zostaną przycięte.
• W tytule umieść informację, która najlepiej odróżnia element od innych. Na liście osób to imię i nazwisko, na liście plików — nazwa pliku.

Dostępność#

• Semantyka listy jest automatyczna. Wewnątrz ItemGroup zwykłe elementy są udostępniane jako elementy listy. Elementy wyrenderowane jako coś innego (linki, przyciski) zachowują własne role.
• Link jest odczytywany jako całość. Dostępną nazwą elementu-linku jest cała jego treść tekstowa. Pisz zwięzłe tytuły i opisy, żeby ta nazwa pozostała użyteczna.
• Nazywaj akcje z samą ikoną. Przyciski menu „Więcej” potrzebują etykiety, która wskazuje wiersz: „Zarządzaj: Maya Chen”.
• Grafika dekoracyjna. Ikony w ItemMedia są dekoracyjne — znaczenie niesie tytuł. Obrazy, które przekazują informację, potrzebują tekstu alt albo role="img" z etykietą.

Dokumentacja API#

Item#

Zbudowany na useRender z Base UI, więc przyjmuje prop render.

ItemMedia#

ItemGroup#

<div role="list">, który układa elementy jeden pod drugim i informuje je, że są elementami listy. Przy mniejszych elementach odstępy się zmniejszają.

ItemContent, ItemTitle, ItemDescription#

Kolumna tekstu. Tytuły są przycinane do jednej linii, a opisy do dwóch.

ItemActions#

Kontrolki na końcu wiersza.

ItemHeader, ItemFooter#

Wiersze na całą szerokość nad głównym wierszem i pod nim.

ItemSeparator#

Pozioma linia między elementami; wewnątrz grupy ukryta przed technologiami wspomagającymi.