DataGrid: osnove

Nazaj: predstavitveni pregled

Stanje: [Live], preverjeno glede na wkfluentui@a477094.

dataGrid() izriše namizno tabelo, ki zapolni podokno in je odporna na spremembo velikosti, z izbirnim razvrščanjem, izbiro vrstic in množičnimi dejanji — osrednji gradnik za „veliko podobnih zapisov kot tabela„ v tej knjižnici. Ta stran dokumentira osnovno pogodbo (stolpci, vrstice, ustvarjene oznake, videz tabele, obstojnost širine stolpcev); podrobnosti, specifične za funkcije (razvrščanje, izbira, množična dejanja, filtriranje, straničenje, izvoz, dostopnost), so na pripadajočih podstraneh predstavitvenega pregleda.

Ciljna publika: vsak vtičnik DokuWiki, ki želi prikazati seznam podobnih zapisov (vrstice podatkovne baze, seznam datotek, konfiguracijske vnose …) kot tabelo, namesto da bi gradil lastno logiko izrisovanja tabele.

• DokuWiki z omogočenim vtičnikom wkfluentui.
• helper_plugin_wkfluentui_widgets naložen prek plugin_load('helper', 'wkfluentui_widgets') — ne plugin_load('helper', 'wkfluentui') (vrne null, glej api → odsek „odpravljanje težav").
• Za sortUrl/bulkActions s končnimi točkami strežnika: obravnavalec POST obrazca s preverjanjem sectok na strani klicatelja (gradnik zagotavlja le oznake, brez logike strežnika).

Nativna <table>, ne ponovna izvedba z div. Namerna arhitekturna odločitev: ločeni tabeli glave/telesa ali mreža div desinhronizirata širine stolpcev brez JavaScripta; nativna <table> ohranja glavo in telo poravnana ter brezplačno prinaša pravilno implicitno tabelarično semantiko. role=„grid“ (poleg aria-multiselectable pri multi) je nastavljen šele, ko je aktiven model izbire — čista prikazovalna tabela brez izbire ostane semantično tabela, ne gradnik „grid“.

Navadno besedilo proti HTML, ki mu je mogoče zaupati: vrednosti celic v $rows so privzeto navadno besedilo (gradnik jih ubeži prek hsc()); vrednost oblike ['html' => string] namesto tega izriše nespremenjen HTML, ki ga je že ubežal klicatelj — enaka konvencija kot povsod v tem API-ju (glej api → odsek „koncepti", konvencija ubežanja).

Z vsebnikom vodena prilagodljivost: brez prelomne točke vidnega polja, mreža sledi širini svojega podokna — podrobnosti: adaptivity.

/** @var helper_plugin_wkfluentui_widgets $widgets */
$widgets = plugin_load('helper', 'wkfluentui_widgets');
 
$columns = [
    ['key' => 'id',     'label' => 'ID',     'align' => 'right', 'mono' => true, 'width' => '4rem'],
    ['key' => 'name',   'label' => 'Ime'],
    ['key' => 'status', 'label' => 'Stanje', 'sortable' => false],
];
 
$rows = [
    ['id' => 1, 'name' => 'Preveri pravilo požarnega zidu', 'status' => 'odprto'],
    ['id' => 2, 'name' => 'Preveri opravilo varnostne kopije', 'status' => 'opravljeno'],
];
 
echo $widgets->dataGrid($columns, $rows, [
    'ariaLabel' => 'Seznam opravil',
    'empty'     => 'Ni vnosov.',
]);

Napačno: posredovati $rows kot navaden nabor vrednosti brez ključev stolpcev ([1, 'Preveri pravilo požarnega zidu', 'odprto']). dataGrid() prebere vrednosti celic prek $row[$col['key']] — brez ujemajočih ključev vsaka celica ostane prazna, brez sporočila o napaki (glej odsek 11, odpravljanje težav).

public function dataGrid(array $columns, array $rows, array $opts = []): string

Povzetek: izriše namizno podatkovno tabelo iz definicij stolpcev in podatkov vrstic, izbirno z razvrščanjem, izbiro vrstic in orodno vrstico množičnih dejanj.

Povratna vrednost: string — popoln fragment HTML (<div class="wk-datagrid">…</div>). Prazen niz, kadar je $columns prazen (brez tabele brez stolpcev) — ne glede na to, ali $rows vsebuje vnose.

Seznam asociativnih polj ključ => vrednost celice. Niz se ubeži kot navadno besedilo; ['html' => string] izriše HTML, ki mu je mogoče zaupati in ga je ubežal klicatelj, brez preverjanja.

<div class="wk-datagrid" data-wk-selection="…" data-wk-persist="…"> → izbirno <div class="wk-datagrid__bulkbar"> → nativna <div class="wk-datagrid__body"><table>…</table></div> z lepljivim <thead class="wk-datagrid__head">. Vsaka celica glave nosi scope="col" (izrecna semantika glave stolpca — skladno z odločitvijo za uporabo nativne tabelarične semantike namesto ponovne izvedbe ARIA, glej odsek 3).

Tabela, ki jo je mogoče razvrščati in večkratno izbrati, z množičnim dejanjem (združuje osnove + razvrščanje + izbiro + množična dejanja):

$columns = [
    ['key' => 'id', 'label' => 'ID', 'align' => 'right', 'mono' => true, 'width' => '4rem'],
    ['key' => 'name', 'label' => 'Ime'],
    ['key' => 'status', 'label' => 'Stanje'],
];
 
echo $widgets->dataGrid($columns, $rows, [
    'sort'        => ['name', 'asc'],
    'persistKey'  => 'opravila:seznam',
    'selection'   => 'multi',
    'rowKey'      => 'id',
    'bulkActions' => [
        ['label' => 'Označi kot opravljeno', 'element' =>
            '<button type="submit" name="do" value="done" class="wk-btn">Označi kot opravljeno</button>'],
    ],
    'ariaLabel' => 'Seznam opravil',
    'empty'     => 'Ni opravil.',
]);

• Brez navideznega drsenja — glej Data Paging and Scrolling.
• Brez urejljivih celic na tej stopnji — glej Data Editing (množična dejanja), odsek urejanja mreže.
• Brez filtra glave stolpca — glej filtering.
• Brez razvrščanja po več stolpcih — glej sorting → omejitve.
• persistKey mora biti stabilen med ogledi strani in edinstven na primerek mreže — dve mreži z enakim persistKey si po nesreči delita isto stanje localStorage.

• Popoln pregled ARIA/tipkovnice: accessibility (konsolidirano, tu ni podvojeno).
• Brez JavaScripta tabela ostane povsem uporabna; razvrščanje brez JS zahteva sortUrl (nadomestilo na strani strežnika), sicer glave ostanejo tiho nerazvrstljive.
• Združljivost brskalnikov: brez zahtev, ki bi presegale osnovno podporo CSS Grid/Flexbox (enako preostanku knjižnice).

Simptom: celice ostanejo prazne, čeprav $rows vsebuje podatke.

Vzrok: ključi vrstic v $rows se ne ujemajo z $columns[]['key'] (tipkarska napaka ali navaden nabor vrednosti namesto asociativnega polja).

Rešitev: preverite vsak $columns[]['key'] glede na dejanske array_keys() vrstice v $rows.

Simptom: stolpec s potrditvenimi polji manjka kljub selection => 'multi'.

Vzrok: rowKey manjka v $opts — gradnik tiho degradira na none (glej odsek 7, obnašanje ob napaki).

Rešitev: nastavite $opts['rowKey'] na edinstven ključ stolpca.

• predstavitveni pregled — vse kategorije
• FluentUI: javni API pomočnika — popolna pogodba metod vseh pomočnikov
• FluentUI: osnovni katalog gradnikov — DeclarativeTable (katalog Tier 2)
• SQLite Data Studio: Admin-Oberfläche — prvi porabnik (SQL Workbench)