Virtuelles DOM (vnode)

Ein leichtgewichtiges virtuelles DOM nach Art von Snabbdom. Es bildet deine Oberfläche als schlichte JavaScript-Objekte ab (die VNodes), vergleicht einen alten Baum mit einem neuen und trägt nur die Unterschiede ins echte DOM ein.

• init() baut den Abgleicher und gibt eine patch-Funktion zurück. Die mitgelieferten Module (class / props / attrs / style / events) tragen sich von selbst ein.
• patch(oldVnode, newVnode) hängt einen Baum ein (wenn oldVnode ein echtes DOM-Element ist) oder vergleicht zwei vnode-Bäume und bessert das DOM an Ort und Stelle nach.
• h(sel, dataOrChildren?, children?) ist der Hyperscript-Helfer, der VNodes baut.

Import

import { init, h, classModule, propsModule, styleModule, eventListenersModule } from 'ranuts/vnode';

Hinweis: In dieser Umsetzung nimmt init() keine Argumente: Der Satz an Modulen liegt fest und wird intern eingetragen, die einzelnen *Module-Exporte müssen init also nicht übergeben werden. Exportiert sind sie zum Nachschlagen und Nachsehen.

Beispiel

Schnellstart

import { init, h } from 'ranuts/vnode';

// init() gibt eine `patch`-Funktion zurück.
// Die mitgelieferten Module (class, props, attrs, style, events) tragen sich von selbst ein.
const patch = init();

const container = document.getElementById('app');

// Einen vnode-Baum bauen
let vnode = h('div#app.container', { style: { color: 'red' } }, [
  h('h1', 'Hello vnode'),
  h('button', { on: { click: () => console.log('clicked') } }, 'Click me'),
]);

// Erstes Zeichnen: als alten vnode ein echtes DOM-Element übergeben, dann wird darin eingehängt
patch(container, vnode);

// Später: den aktualisierten Baum bauen und den vorigen vnode darauf patchen.
// Ins DOM gelangen nur die Unterschiede (Text, Stil, Listener).
const newVnode = h('div#app.container', { style: { color: 'green' } }, [
  h('h1', 'Hello again'),
  h('button', { on: { click: () => console.log('clicked') } }, 'Updated'),
]);

patch(vnode, newVnode);
vnode = newVnode; // den neuesten Baum für das nächste patch behalten

Knoten mit h bauen

// nur das Tag
h('div');

// Tag + data
h('div', { class: { active: true } });

// Tag + ein einzelnes Textkind
h('span', 'hello');

// Tag + Array von Kindern
h('ul', [h('li', 'one'), h('li', 'two')]);

// Tag + data + Kinder
h('a', { attrs: { href: '/home' } }, 'Home');

// Selektoren im CSS-Stil legen id und Klassen fest
h('div#main.card.large', 'content'); // <div id="main" class="card large">content</div>

// Der SVG-Namensraum wird von selbst gesetzt, wenn der Selektor mit "svg" beginnt
h('svg', { attrs: { width: 100, height: 100 } }, [h('circle', { attrs: { cx: 50, cy: 50, r: 40 } })]);

API

init()

Erzeugt den Abgleicher und gibt eine patch-Funktion zurück. Die mitgelieferten Module werden intern eingetragen; Argumente nimmt es keine.

Rückgabe

Wert	Beschreibung	Typ
patch	Hängt vnode-Bäume ins echte DOM ein oder gleicht sie damit ab	(oldVnode: VNode | Element, vnode: VNode) => VNode

patch(oldVnode, vnode)

Kommt von init(). Übergib beim ersten Aufruf als oldVnode ein echtes DOM-Element, dann wird der Baum darin eingehängt. Bei späteren Aufrufen übergib den vorigen VNode, um an Ort und Stelle abzugleichen und nachzubessern. Zurück kommt der neue VNode, den du als „alten“ Wert für den nächsten Aufruf behältst.

Parameter

Parameter	Beschreibung	Typ
oldVnode	Der vorige vnode, oder beim ersten Einhängen ein DOM-Element	VNode | Element
vnode	Der neue vnode-Baum, der gezeichnet werden soll	VNode

h(sel, dataOrChildren?, children?)

Hyperscript-Helfer, der einen VNode baut. Er ist überladen:

Signatur	Beschreibung
h(sel)	Element allein aus einem Selektor
h(sel, data)	Element mit VNodeData (data darf null sein)
h(sel, children)	Element mit Kindern: ein Text oder eine Zahl, ein VNode, oder ein Array
h(sel, data, children)	Element mit Daten und Kindern

Parameter

Parameter	Beschreibung	Typ
sel	Selektor im CSS-Stil: tag, tag#id, tag.class, auch kombiniert (div#id.a.b). Bei svg… kommt der SVG-Namensraum von selbst dazu	string
data	Daten des Knotens: class / props / attrs / style / Listener / key / hook. Darf null sein	VNodeData | null
children	Ein Text oder eine Zahl (wird zum Textknoten), ein einzelner VNode, oder ein Array davon	VNodeChildren

Felder von VNodeData

Feld	Beschreibung	Typ	Angewendet von
props	DOM-Eigenschaften, gesetzt über elm[key] = value	Record<string, any>	propsModule
attrs	HTML-Attribute, gesetzt über setAttribute (true und false schalten das Attribut ein und aus)	Record<string, string | number | boolean>	attributesModule
class	Bedingte Klassen: eine Zuordnung name → boolean	Record<string, boolean>	classModule
style	Inline-Stile: eine Zuordnung name → value (Schlüssel mit --var werden zu CSS-Variablen)	Record<string, any>	styleModule
on	Ereignis-Listener: event → handler (oder ein Array von Handlern)	Record<string, Function | Function[]>	eventListenersModule
key	Beständiges Kennzeichen, mit dem der Abgleich Kinder zuordnet und umsortiert	string | number	(Kern des Abgleichs)
ns	URI des Namensraums (bei SVG-Teilbäumen von selbst gesetzt)	string	(Kern des Abgleichs)
hook	Lebenszyklus-Hooks je vnode (Hooks)	Hooks	(nur als Typ: siehe Hinweis)

Hinweis: hook und der Typ Hooks gehören zur öffentlichen Typfläche. Diese abgespeckte Umsetzung steuert das DOM jedoch über den Lebenszyklus der Module (create / update / destroy); die data.hook-Rückrufe je vnode ruft die derzeitige patch-Schleife nicht auf.

Module

Jedes Modul kümmert sich um ein Stück von VNodeData. init() trägt sie alle ein; einzeln exportiert sind sie außerdem.

Export	Zuständig für	Beschreibung
classModule	data.class	Setzt und entfernt Klassen anhand einer Zuordnung name → boolean
propsModule	data.props	Weist DOM-Eigenschaften unmittelbar zu (elm[key] = value)
attributesModule	data.attrs	Setzt und entfernt HTML-Attribute über setAttribute (auch xml und xlink)
styleModule	data.style	Setzt Inline-Stile und benutzerdefinierte CSS-Eigenschaften
eventListenersModule	data.on	Hängt Ereignis-Listener an und wieder ab
modules	—	Das voreingestellte Registerobjekt, das jeden Modulnamen seinem Modul zuordnet

Exporte tieferer Ebene

Export	Typ	Beschreibung
vnode	(sel, data, children, text, elm) => VNode	Hardwarenahe VNode-Fabrik, die h intern benutzt. Nimm im Anwendungscode lieber h.
addNS	(data, children, sel) => void	Legt den SVG-Namensraum rekursiv über einen Teilbaum. Bei svg…-Selektoren ruft h sie von selbst auf.
htmlDomApi	DOMAPI	Der voreingestellte Browser-DOM-Adapter, den patch intern benutzt (Knoten erzeugen, einfügen, entfernen, Text usw.).
is	{ array, isStr, primitive, isVnode }	Kleine Typprüfer, die überall im Inneren von vnode benutzt werden.
Chain	class Chain	Ein verkettbarer, imperativer DOM-Baumeister (setAttribute, append, setTextContent, …). Mit dem vnode-Abgleich hat er nichts zu tun.
create	(tagName, options?) => Chain	Bequemlichkeitsfabrik, die eine neue Chain liefert.

Typen

Typ	Form und Bedeutung
VNode	{ sel, data, children, elm, text, key, listener? }: ein virtueller Knoten
VNodeData	{ props?, attrs?, class?, style?, on?, key?, ns?, hook? }: siehe die Felder oben
VNodes	VNode[]
VNodeChildElement	VNode | string | number
VNodeChildren	VNodeChildElement | VNodeChildElement[]
ArrayOrElement<T>	T | T[]
Key	string | number
Hooks	{ pre?, init?, create?, insert?, prepatch?, update?, postpatch?, destroy?, remove?, post? }
DOMAPI	Schnittstelle, die die DOM-Operationen beschreibt, die patch benutzt (siehe htmlDomApi)
Fragment	Erweiterung von DocumentFragment für den Umgang mit Fragmenten
Modules	Record<string, Record<string, ModuleHook>>: die Form des Modulregisters
ModuleHook	Ein einzelner Lebenszyklus-Rückruf eines Moduls

Hinweise

1. Nur für den Browser. ranuts/vnode fasst document und die DOM-APIs an; importiere es in Browser-Code, nicht in Node.
2. Behalte den letzten vnode. patch gibt den neuen VNode zurück. Heb ihn auf und übergib ihn bei der nächsten Aktualisierung als oldVnode, damit gegen den aktuellen Baum verglichen wird.
3. In einem VNode schließen sich text und children aus: Ein Knoten ist entweder ein Textknoten oder ein Element mit Kindern.
4. Nimm key für Listen. Gib Geschwistern beim Zeichnen veränderlicher Listen beständige key-Werte, damit der Abgleich Knoten zuordnen und umsortieren kann, statt sie neu zu erzeugen.