Tree List: osnove

1. Pregled in namen

Stanje: [Live]. Vir: lib/plugins/wkfluentui/helper/widgets.php, metoda treeList(). Gradi na pogodbi dataGrid(), namesto da bi jo podvajala.

2. Predpogoji

osnovna pogodba dataGrid() že razumljena — Tree List podeduje $columns (key/label/align/mono/width) in konvencijo celic (navadno besedilo ubežano, ['html' => …] ubeže klicatelj) nespremenjeno.

3. Pojmi

Ena mreža, hierarhične vrstice: edina strukturna razlika glede na dataGrid() je v $rows — vrstice lahko nosijo gnezdene podrejene vrstice (rekurzivno, tako kot children pri tree()-u).

4. Prvi koraki

$rows = [
    [
        'id' => 1, 'name' => 'de', 'size' => '', 'children' => [
            ['id' => 2, 'name' => 'wiki', 'size' => ''],
            ['id' => 3, 'name' => 'blog', 'size' => ''],
        ],
    ],
    ['id' => 4, 'name' => 'en', 'size' => ''],
];
 
echo $widgets->treeList($columns, $rows, [
    'rowKey'      => 'id',
    'childrenKey' => 'children',
]);

5. Uporaba

Umešča se med DataGrid (veliko podobnih vrstic, ravno) in TreeView (hierarhija, vendar le en stolpec) — za hierarhične podatke z več stolpci (npr. raziskovalec datotečnega sistema s stolpci velikosti/datuma).

6. API referenca

treeList(array $columns, array $rows, array $opts = []): string v helper_plugin_wkfluentui_widgets. Prazen niz pri praznem $columns; prazen $rows izriše vrstico glave plus vrstico praznega stanja (besedilo empty).

7. Parametri, možnosti in stanja

Ključ	Tip	Pomen
`rowKey`	string	ključ stolpca z enolično vrednostjo vrstice — obvezen za `expanded`/`expandUrl`/`selection`
`childrenKey`	string	ključ v `$rows`, pod katerim ležijo podrejene vrstice (rekurzivno, kot `children` pri `tree()`-u), privzeto `children`
`expanded`	polje vrednosti `rowKey`	začetno razširjene nadrejene vrstice; brez navedbe so vse nadrejene vrstice strnjene
`expandUrl`	callable `(string $key, bool $expand): string`	povezava za preklop brez JS na nadrejeno vrstico; psevdoključa `all`/`none` priskrbita URL-je za orodno vrstico „razširi/strni vse„ — Expand/Collapse
`maxDepthIndent`	int (privzeto 6)	meja zamika — Adaptivity
`selection`	`'none'\|'multi'`	stolpec s potrditvenim poljem (`selection[]` v obrazcu klicatelja, kot `dataGrid()`); zahteva `rowKey`
`rowActions`	callable	celica dejanj na vrstico (kot `dataGrid()`)
`empty`, `ariaLabel`	string	tako kot pri `dataGrid()`

Generiran izris

Ena sama nativna <table role="treegrid"> (ista utemeljitev kot pri dataGrid(): ločena poddrevesa bi razsinhronizirala širine stolpcev) — vsaka vrstica nosi data-wk-depth="<n>" plus aria-level/aria-setsize/aria-posinset, nadrejene vrstice dodatno data-wk-expanded="true|false" in aria-expanded. Zamik prvega stolpca je strežniški vgrajeni slog (15 px na raven, omejen z maxDepthIndent-om).

Meja izrisa (zavezujoče): podrejene vrstice strnjene nadrejene vrstice se ne izrišejo v DOM (ne le hidden) — pri zelo globokih drevesih bi sicer ostala ista meja izrisa kot pri manjkajoči virtualizaciji v DataGridu, le nevidna namesto preprečena.

8. Popolni primeri

Glej odsek 4 plus Expand/Collapse za sodelovanje z expandUrl-om.

9. Omejitve in robni primeri

Brez razvrščanja, brez filtriranja, brez straničenja — hierarhični vrstni red je merodajen; kdor želi ravno razvrščati/filtrirati, uporabi dataGrid().
Podeduje omejitve dataGrid()-a: brez navideznega pomikanja, brez uredljivih celic (za to declarativeTable()).

10. Dostopnost in združljivost

Celoten pregled: Accessibility.

11. Odpravljanje težav

Simptom: nadrejena vrstica ne prikaže preklopnega trikotnika kot povezave.

Vzrok: manjka expandUrl ali vrstica nima vrednosti rowKey — brez obojega se izriše le statični trikotnik.

Rešitev: nastaviti rowKey + expandUrl (odsek 7).

12. Sorodne teme

predstavitveni pregled — vsaka kategorija
DataGrid: osnove — podedovana osnovna pogodba
TreeView: osnove — sorodna ideja hierarhije brez stolpcev