Breadcrumbs

shadow

Breadcrumbs je komponent, ktorý zobrazuje cestu, po ktorej používateľ prešiel v rámci aplikácie alebo webu. Tento element zobrazuje hierarchické usporiadanie stránok, v ktorom každý segment cesty Breadcrumb je hyperlink, umožňujúci rýchly návrat na predchádzajúce úrovne. Breadcrumbs môže obsahovať ikonu.

Základné použitie

Ukážka zobrazuje základný breadcrumb trail s niekoľkými úrovňami, aby bolo jasné, ako sa skladá navigačná cesta a kde je aktívna položka.

Dátové položky

Okrem ručne vložených wje-breadcrumb elementov môžete breadcrumb trail riadiť aj cez property items. Komponent z poľa vytvorí položky a pri ďalšom nastavení porovná nové dáta s existujúcim DOM podľa id, takže upraví iba zmenené položky. Rovnaké dáta môžete odovzdať aj ako JSON string cez atribút items, ak komponent konfigurujete priamo v HTML.

const breadcrumbs = document.querySelector('wje-breadcrumbs');

breadcrumbs.items = [
  { id: 'home', label: 'Home', href: '/', icon: 'home' },
  { id: 'documents', label: 'Documents', href: '/documents' },
  { id: 'invoice', label: 'Invoice', disabled: true, data: { folderId: 10 } },
];

breadcrumbs.addEventListener('wje-breadcrumbs:item-click', (event) => {
  const { item, index, originalEvent } = event.detail;

  if (item.disabled) {
    event.preventDefault();
  }
});

Položka podporuje polia id, label, href, icon, disabled a vlastné data. Klik na dátovo riadenú položku dispatchuje wje-breadcrumbs:item-click; ak listener zavolá event.preventDefault(), pôvodná navigácia sa zastaví.

Použitie s ikonami

Ukážka pridáva ikony priamo k breadcrumb položkám. Hodí sa v prípadoch, keď potrebujete rýchlejšie rozlíšiť sekcie aj vizuálne, nielen textom.

Vlastná ikona oddeľovača

Ukážka mení predvolený oddeľovač breadcrumbov za vlastnú ikonu. Je to vhodné vtedy, keď chcete trail priblížiť vizuálnemu štýlu zvyšku aplikácie.

Zbaľovací breadcrumb

Maximálny počet položiek

Ak je v zozname viac položiek ako hodnota maxItems, zoznam sa zbalí. Hodnota max-items určuje celkový počet viditeľných breadcrumb prvkov vrátane indikátora ....

Ak chcete zbaľovať iba pod konkrétnou šírkou obrazovky, pridajte atribút breakpoint. Podporuje tokeny sm, md, lg, xl, 2xl/xxl aj priamu číselnú hodnotu v pixeloch. Nad breakpointom ostane trail rozbalený aj vtedy, keď má viac položiek ako max-items.

Pre toolbar alebo úzke hlavičky môžete pod breakpointom schovať celý trail do jedného menu pomocou breakpoint-collapse="menu". Nad breakpointom ostáva bežné skrátenie podľa max-items, pod breakpointom ostane v toolbare iba kompaktný indikátor a všetky breadcrumb položky sa presunú do jeho mobilného zobrazenia alebo dropdownu.

Mobilné zobrazenie riadi collapsed-variant. Pôvodná hodnota dropdown ostáva podporovaná. Pre kompaktné hlavičky sú dostupné aj hodnoty text, back, parent-title, menu-title a sheet. Pre disk alebo file manager je odporúčané collapsed-variant="back", ktoré zobrazí parent akciu a aktuálny názov:

<wje-breadcrumbs breakpoint="lg" breakpoint-collapse="menu" collapsed-variant="back">
  <wje-breadcrumb href="/disk">Disk</wje-breadcrumb>
  <wje-breadcrumb href="/disk/personal">Personal</wje-breadcrumb>
  <wje-breadcrumb>TESTS</wje-breadcrumb>
</wje-breadcrumbs>

Predvolený hamburger v tomto režime môžete zmeniť cez breakpoint-collapse-icon, alebo nahradiť celé tlačidlo slotom breakpoint-collapse-trigger. Ak slot nepoužijete, zobrazí sa predvolený wje-button.

<wje-breadcrumbs breakpoint="lg" breakpoint-collapse="menu" breakpoint-collapse-icon="menu-2">
  <wje-breadcrumb href="/home" title="Home" aria-label="Home"><wje-icon slot="start" name="home"></wje-icon></wje-breadcrumb>
  <wje-breadcrumb href="/photography">Photography</wje-breadcrumb>
</wje-breadcrumbs>

<wje-breadcrumbs breakpoint="lg" breakpoint-collapse="menu">
  <wje-button slot="breakpoint-collapse-trigger" fill="outline" aria-label="Breadcrumb menu">
    <wje-icon name="menu-2"></wje-icon>
  </wje-button>

  <wje-breadcrumb href="/home" title="Home" aria-label="Home"><wje-icon slot="start" name="home"></wje-icon></wje-breadcrumb>
  <wje-breadcrumb href="/photography">Photography</wje-breadcrumb>
</wje-breadcrumbs>

Počet položiek pred alebo po zbalení

Keď sú položky zbalené, počet položiek pred a za indikátorom možno riadiť vlastnosťami itemsBeforeCollapse a itemsAfterCollapse. Ak itemsAfterCollapse nenastavíte, dopočíta sa automaticky z max-items.

Rozbaľovacie okno

Zbalené položky je možné zobraziť aj v podobe rozbaľovacieho okna použitím vlastnosti collapsed-variant s hodnotou dropdown.

Rozbalenie po kliknutí

Ak nechcete rozbaľovacie menu, predvolený button variant zobrazí skryté položky priamo v traili po kliknutí na indikátor zbalenia.

Úprava štýlov

Farebné varianty

Farby breadcrumbov sa upravujú cez CSS premenné na wje-breadcrumb, takže si môžete pripraviť aj vlastné významové varianty pre konkrétne trail-y.

CSS vlastné premenné

Ak potrebujete jemnejšie doladiť predvolený vzhľad, upravte CSS premenné pre text a hover stav jednotlivých breadcrumb položiek.

Kedy použiť

Použite wje-breadcrumbs, keď používateľ potrebuje orientáciu v aplikácii alebo prechod medzi stavmi/obrazovkami.

Kedy nepoužiť

Nepoužívajte viac paralelných navigačných vzorov, ktoré si navzájom konkurujú.

Prístupnosť

Zabezpečte jasné active/selected stavy, predvídateľné poradie tabulátora a pomenovanie ovládacích prvkov.

Odporúčané postupy

• Držte URL a UI stav v synchronizácii, aby bola navigácia reprodukovateľná.
• Používajte konzistentné názvoslovie položiek naprieč menu, breadcrumbom a tabmi.
• Pri hlbokých štruktúrach pridajte pomocný kontext (breadcrumb, nadpis, ikony).

Atribúty a vlastnosti

ariaLabel

Popis	Nastavuje ARIA metadáta, ktoré zlepšujú prístupnosť pre asistenčné technológie.
Atribút	aria-label
Typ	any
Predvolené	-

ariaLabelledby

Popis	Nastavuje ARIA metadáta, ktoré zlepšujú prístupnosť pre asistenčné technológie.
Atribút	aria-labelledby
Typ	any
Predvolené	-

breakpoint

Popis	Nastavuje textovú hodnotu uloženú vo voľbe breakpoint.
Atribút	breakpoint
Typ	string
Predvolené	-

breakpointCollapse

Popis	Nastavuje textovú hodnotu uloženú vo voľbe breakpoint-collapse.
Atribút	breakpoint-collapse
Typ	string
Predvolené	-

breakpointCollapseIcon

Popis	Nastavuje textovú hodnotu uloženú vo voľbe breakpoint-collapse-icon.
Atribút	breakpoint-collapse-icon
Typ	string
Predvolené	-

collapsedVariant

Popis	Nastavuje ARIA metadáta, ktoré zlepšujú prístupnosť pre asistenčné technológie.
Atribút	collapsed-variant
Typ	string
Predvolené	-

itemsAfterCollapse

Popis	Nastavuje číselnú hodnotu používanú vo voľbe items-after-collapse.
Atribút	items-after-collapse
Typ	number
Predvolené	1

itemsBeforeCollapse

Popis	Nastavuje číselnú hodnotu používanú vo voľbe items-before-collapse.
Atribút	items-before-collapse
Typ	number
Predvolené	1

maxItems

Popis	Nastavuje číselnú hodnotu používanú vo voľbe max-items.
Atribút	max-items
Typ	number
Predvolené	-

variant

Popis	Nastavuje ARIA metadáta, ktoré zlepšujú prístupnosť pre asistenčné technológie.
Atribút	variant
Typ	string
Predvolené	button

Udalosti

Názov	Popis
wje-breadcrumbs:item-click	Vyvolá sa pri odoslaní udalosti wje-breadcrumbs:item-click.

Metódy

upgradeProperty

Popis	Spustí metódu upgradeProperty na vykonanie logiky komponentu a aktualizáciu jeho stavu.
Signatúra	(property: string) => void

normalizeItems

Popis	Spustí metódu normalizeItems na vykonanie logiky komponentu a aktualizáciu jeho stavu.
Signatúra	(value: Array｜string｜null｜undefined) => Array<object>

normalizeItem

Popis	Spustí metódu normalizeItem na vykonanie logiky komponentu a aktualizáciu jeho stavu.
Signatúra	(item: object｜string｜number, index: number, usedKeys: Set<string>) => object

getItemKey

Popis	Vráti položku key z aktuálneho stavu komponentu.
Signatúra	(item: object, index: number, usedKeys: Set<string>) => string

syncItems

Popis	Synchronizuje položky s externým alebo interným zdrojom stavu.
Signatúra	(records: Array<object>) => void

createItemElement

Popis	Vytvorí položku element a pripojí ho do štruktúry komponentu.
Signatúra	(record: object, index: number) => HTMLElement

updateItemElement

Popis	Aktualizuje položku element podľa najnovších údajov komponentu.
Signatúra	(breadcrumb: HTMLElement, record: object, index: number) => void

syncItemAttribute

Popis	Synchronizuje položku attribute s externým alebo interným zdrojom stavu.
Signatúra	(element: HTMLElement, name: string, value: string｜null｜undefined) => void

syncBooleanItemAttribute

Popis	Synchronizuje boolean položku attribute s externým alebo interným zdrojom stavu.
Signatúra	(element: HTMLElement, name: string, isEnabled: boolean) => void

syncItemContent

Popis	Synchronizuje položku content s externým alebo interným zdrojom stavu.
Signatúra	(breadcrumb: HTMLElement, record: object) => void

getItemStructureSignature

Popis	Vráti položku structure signature z aktuálneho stavu komponentu.
Signatúra	(record: object) => string

dispatchManagedItemClick

Popis	Vyvolá vlastnú udalosť z kontextu komponentu.
Signatúra	(e: MouseEvent) => void

getManagedBreadcrumbFromEvent

Popis	Vráti managed breadcrumb from udalosť z aktuálneho stavu komponentu.
Signatúra	(e: Event) => HTMLElement｜null

updateCollapse

Popis	Aktualizuje collapse podľa najnovších údajov komponentu.
Signatúra	() => void

applyMenuCollapse

Popis	Spustí metódu applyMenuCollapse na vykonanie logiky komponentu a aktualizáciu jeho stavu.
Signatúra	(breadcrumbs: Array<Element>) => void

isBreakpointMenuCollapseActive

Popis	Overí, či je breakpoint menu collapse active aktuálne pravda.
Signatúra	() => boolean

usesMobileCollapsedVariant

Popis	Spustí metódu usesMobileCollapsedVariant na vykonanie logiky komponentu a aktualizáciu jeho stavu.
Signatúra	() => boolean

resetCollapseState

Popis	Obnoví collapse state na počiatočné hodnoty.
Signatúra	(breadcrumbs: Array<Element>) => void

syncManagedAttribute

Popis	Synchronizuje managed attribute s externým alebo interným zdrojom stavu.
Signatúra	(element: Element, name: string, isEnabled: boolean) => void

refreshCollapsedIndicators

Popis	Spustí metódu refreshCollapsedIndicators na vykonanie logiky komponentu a aktualizáciu jeho stavu.
Signatúra	() => void

shouldApplyBreakpointCollapse

Popis	Spustí metódu shouldApplyBreakpointCollapse na vykonanie logiky komponentu a aktualizáciu jeho stavu.
Signatúra	() => boolean

getBreakpointWidth

Popis	Vráti breakpoint width z aktuálneho stavu komponentu.
Signatúra	() => number｜null

getBreakpointCollapseTrigger

Popis	Vráti breakpoint collapse trigger z aktuálneho stavu komponentu.
Signatúra	() => Element｜null

getBreadcrumbs

Popis	Vráti breadcrumbs z aktuálneho stavu komponentu.
Signatúra	() => Array<Element>

getManagedBreadcrumbs

Popis	Vráti managed breadcrumbs z aktuálneho stavu komponentu.
Signatúra	() => Array<Element>

getBreadcrumbsCollapsed

Popis	Vráti breadcrumbs collapsed z aktuálneho stavu komponentu.
Signatúra	() => Array<Element>

CSS tieňové časti

Názov	Popis
container	Štýluje kontajnerovú shadow časť.

CSS vlastné premenné

Pre tento komponent nie sú dostupné žiadne vlastné CSS vlastnosti.

Sloty

Názov	Popis
default	Predvolený slot pre hlavný obsah komponentu.
breakpoint-collapse-trigger	Slot pre vlastný obsah breakpoint-collapse-trigger v komponente.