Tree
De Tree component organiseert gegevens als een hiërarchie van knooppunten. Elk knooppunt bevat een unieke sleutel en een label. Knopen zijn met elkaar verbonden om ouder-kind relaties te vormen. Je kunt knooppunten uitbreiden of inkrimpen om hun kinderen te tonen of te verbergen. Iconen verduidelijken welk type knooppunt je bekijkt en of het is geselecteerd. Selectie ondersteunt het kiezen van één knooppunt of meerdere tegelijk.
Knooppuntmodel en boomstructuur
De rol van TreeNode dwc-tree-node
Elk gegevenselement in de boom is verpakt in een TreeNode. Dit object bevat de sleutel, het tekstlabel en links naar de ouder- en kindknopen. De wortelknoop is speciaal: hij bestaat in elke boom maar is niet zichtbaar. Hij dient als de container voor alle knooppunten op het hoogste niveau, waardoor de boomstructuur intern gemakkelijker te beheren is.
Omdat knopen referenties naar hun ouders en kinderen behouden, is het doorlopen van de boom eenvoudig. Of je nu naar boven, naar beneden wilt bewegen of een specifiek knooppunt op sleutel wilt vinden, de verbindingen zijn altijd toegankelijk.
Het maken en beheren van knopen
Knooppunten worden gemaakt met eenvoudige fabrieksmethoden, hetzij door een sleutel en tekst te bieden, of alleen tekst (die ook als sleutel dient). Dit garandeert dat elk knooppunt geldig en uniek identificeerbaar is.
Knooppunten aan de boom toevoegen houdt in dat je add() of insert() op een ouderknoop aanroept. Deze methoden zorgen voor het toewijzen van de ouderreferentie en informeren de boom om zijn UI bij te werken.
Voorbeeld:
TreeNode parent = Tree.node("Parent");
TreeNode child = Tree.node("Child");
parent.add(child);
tree.add(parent);
Proberen dezelfde knoop aan meer dan één ouder toe te wijzen, resulteert in een uitzondering. Deze beveiliging zorgt ervoor dat de boom een goede hiërarchie behoudt door te voorkomen dat knopen meerdere ouders hebben, wat de integriteit van de structuur zou breken en onverwacht gedrag zou veroorzaken.
Het wijzigen van knopen
Je kunt het label van een knoop bijwerken door setText(String text) aan te roepen. Deze methode verandert de tekst die voor de knoop in de boom wordt weergegeven.
Om een specifiek kindknoop te verwijderen, gebruik je remove(TreeNode child). Dit ontkoppelt het kind van zijn ouder en verwijdert het uit de boomstructuur. Het wist ook de ouderreferentie.
Als je alle kinderen van een knoop wilt wissen, roep je removeAll() aan. Dit verwijdert elk kindknoop, wist hun ouderreferenties en leeg de lijst met kinderen.
Elke knoop ondersteunt het opslaan van aanvullende informatie aan de serverzijde met setUserData(Object key, Object data). Dit stelt je in staat om willekeurige metadata of referenties aan de knoop te associëren, zonder deze gegevens aan de client of de UI bloot te stellen.
In de demo, dubbelklik op een knoop om een editor te openen voor de tekst. Voer de nieuwe tekst in en sla op om het label van de knoop in de boom bij te werken.
Iconen
Iconen bieden visuele aanwijzingen over wat knopen vertegenwoordigen en hun status. Ze verbeteren de leesbaarheid door knooptypen en selectiestatus in één oogopslag te onderscheiden. De Tree component ondersteunt het globaal instellen van standaardiconen, het aanpassen van iconen per knoop en het wisselen van iconzichtbaarheid.
Globale iconen
De boom staat je toe standaardiconen in te stellen voor ingeklapte groepen, uitgebreide groepen, bladknopen en geselecteerde bladeren.
Voorbeeld:
tree.setCollapsedIcon(TablerIcon.create("folder"));
tree.setExpandedIcon(TablerIcon.create("folder-opened"));
tree.setLeafIcon(TablerIcon.create("file"));
tree.setLeafSelectedIcon(TablerIcon.create("file-checked"));
Een icoon kan elke geldige webforJ icoon definitie zijn of een bronbestand dat is geladen via een webforJ ondersteunde middelenprotocollen.
Per-knoop iconen
Je kunt globale standaardinstellingen overschrijven door iconen aan individuele knopen toe te wijzen. Dit is nuttig wanneer bepaalde knopen verschillende concepten vertegenwoordigen, zoals “project” mappen of speciale bestanden.
Voorbeeld:
node.setIcon(TablerIcon.create("project"));
node.setSelectedIcon(TablerIcon.create("project-selected"));
Iconzichtbaarheid
Soms wil je misschien iconen voor groepen of bladeren verbergen om rommel te verminderen. De component laat je toe om de zichtbaarheid globaal voor deze categorieën te schakelen, waardoor je de weergave van de boom kunt vereenvoudigen zonder de structuur te verliezen.
Voorbeeld:
tree.setGroupIconsVisible(false);
tree.setLeafIconsVisible(false);
Knooppuntuitbreiding en -samenklap
Knooppunten kunnen worden uitgebreid of samengeklapt om te beheersen welke delen van de boom zichtbaar zijn. Dit stelt je in staat om je te concentreren op relevante secties en ondersteunt scenario's zoals lazy loading of dynamische gegevensupdates.
Uitbreidings- en samenvouwoperaties
De boom ondersteunt het uitbreiden en samenvouwen van individuele knopen, hetzij via hun sleutel of directe referentie. Je kunt ook alle nakomelingen van een knoop in één keer uitbreiden of samenvouwen.
Deze operaties stellen je in staat om te controleren hoeveel van de boom zichtbaar is en ondersteunen lazy loading van gegevens of focus op gebieden van belang.
Voorbeeld:
tree.expand(node);
tree.collapse(key);
// samenvouwen subbomen
tree.expandFrom(node);
tree.collapseFrom(node);
De wortelknoop verankert de boom maar blijft verborgen. Het samenvouwen van de wortel zou normaal gesproken alles verbergen, waardoor de boom leeg lijkt. Om dit te voorkomen, verkleint het samenvouwen van de wortel eigenlijk alle kinderen maar houdt de wortel intern uitgebreid, zodat de boom zijn inhoud correct blijft tonen.
Lazy loading van knopen
De boom ondersteunt lazy loading van kindknopen door te reageren op uitbreidingsgebeurtenissen. Wanneer een gebruiker een knoop uitbreidt, kan je app die knoopkinderen dynamisch laden of genereren. Dit verbetert de prestaties door alleen zichtbare delen van de boom op aanvraag te laden.
Gebruik het onExpand evenement om te detecteren wanneer een knoop wordt uitgebreid. Controleer binnen de handler of de kinderen van de knoop tijdelijke aanduidingen zijn (bijvoorbeeld een spinner of lege knoop) en vervang deze door daadwerkelijke gegevens zodra ze zijn geladen.
Selectie
Selectie controleert welke knopen door de gebruiker zijn gekozen. De Tree component ondersteunt flexibele modi en API's om knopen te selecteren, te deselecteren en op te vragen.
Selectiemodi
Je kunt kiezen of de boom het selecteren van één knoop tegelijk of meerdere knopen tegelijkertijd toestaat. Overschakelen van meerdere naar enkele selectie deselecteert automatisch alles behalve de eerste geselecteerde knoop.
Voorbeeld:
tree.setSelectionMode(Tree.SelectionMode.SINGLE);
Wanneer de boom is ingesteld op de modus voor meerdere selecties, kunnen gebruikers meer dan één knoop tegelijkertijd selecteren. De manier waarop dit werkt, hangt af van het apparaat:
- Desktop (muis en toetsenbord): Gebruikers houden de Ctrl toets (of Cmd toets op macOS) ingedrukt en klikken op knopen om ze toe te voegen of te verwijderen van de huidige selectie. Hierdoor kunnen gebruikers meerdere individuele knopen selecteren zonder andere te deselecteren.
- Mobiele en touch-apparaten: Aangezien modifier-toetsen niet beschikbaar zijn, tikken gebruikers eenvoudig op knopen om ze te selecteren of deselecteren. Elke tik schakelt de selectiestatus van die knoop om, waardoor eenvoudige multi-selectie mogelijk is via eenvoudige tikken.
Selecteren en deselecteren
Knooppunten kunnen worden geselecteerd of gedeselecteerd op referentie, sleutel, individueel of in batches. Je kunt ook alle kinderen van een knoop in één keer selecteren of deselecteren.
Voorbeeld:
// selecteer knoop op referentie of sleutel
tree.select(node);
tree.selectKey(key);
// deselecteer knoop op referentie of sleutel
tree.deselect(node);
tree.deselectAll();
// geselecteerde of gedeselecteerde kinderen van knopen
tree.selectChildren(parentNode);
tree.deselectChildren(parentNode);
Opvragen van de selectiestatus
Je kunt de huidige selectie krijgen door de onderstaande code te gebruiken:
// krijg de referentie van de geselecteerde knoop
TreeNode selected = tree.getSelected();
List<TreeNode> selectedItems = tree.getSelectedItems();
// krijg de sleutel van de geselecteerde knoop
Object selectedKey = tree.getSelectedKey();
List<Object> selectedKeys = tree.getSelectedKeys();
