Przejdź do treści
Zweryfikowano

@xuda/core

Reaktywny silnik bez zależności, na którym montują się platforma, kompilator i aplikacje demo.

@xuda/core to reaktywny silnik Xuda (sygnały, planista, różnicowanie list z kluczami, reaktywny renderer, router) jako pakiet ESM bez zależności. Przy imporcie nie czyta ani nie zapisuje żadnych globali: żadnego func, SESSION_OBJ, window ani document.

Jedyny publiczny pakiet w tej części dokumentacji

package.json pakietu @xuda/core ma "private": false. To jedyny pakiet spośród trzech omawianych w tej sekcji (obok @xuda/compiler i @xuda/vite-plugin-xu, oba private: true), zbudowany tak, by można było od niego zależeć poza tym repozytorium.

To także nie jest inny silnik niż ten, który platforma już dostarcza: własny skrypt build:globals pakietu (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) buduje runtime/js/xuda_core.globals.js, czyli pakiet reaktywnego renderera dostarczany przez samą platformę.

Powierzchnia reaktywna

js
import { ref, reactive, computed, effect, watch, effectScope } from '@xuda/core';

Pod spodem jest jeden graf zależności, jedno drzewo właścicieli, jeden bufor wsadowy i jeden planista: odczyt ref wewnątrz effect() śledzi go i uruchamia ponownie, tak samo jak odczyt sygnału wewnątrz watch(). computed przyjmuje tu getter albo parę { get, set } dla zapisywalnego computed.

js
const state = reactive({ count: 0 });
state.count++;             // no .get(), no .set()

const n = ref(0);
n.value++;

effectScope() odpowiada na pytanie „kto to zwalnia”: nazwany właściciel, którego możesz przekazywać, zagnieżdżać i zatrzymywać jednym wywołaniem, zamiast ręcznie budować worek zwalniaczy.

js
const scope = effectScope();
scope.run(() => {
  effect(() => { /* ... */ });
  watch(source, callback);
  onScopeDispose(() => io.disconnect());
});
scope.stop();

Komponent tworzony przez createApp() już ma taki zakres: jego <script> działa wewnątrz własnego, odłączonego zakresu komponentu, więc efekt napisany tam jest zwalniany automatycznie, gdy komponent jest odmontowywany.

Prymityw niskiego poziomu

signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) i signalComputed to własne komórki silnika pod ref i computed. Są eksportowane i w pełni wspierane, nie usunięte, ponieważ renderer i most do starszego kodu są na nich zbudowane, a także dlatego, że signal.notify(), czyli ponowne uruchomienie subskrybentów bez zmiany wartości, nie ma odpowiednika w ref. Kod aplikacji powinien sięgać po ref i computed; te dwie nazwy są udokumentowane jako warstwa niżej, a nie oznaczone jako przestarzałe w czasie działania (ostrzeżenie przy signal() odpalałoby się dla każdego zakresu wiersza i każdego parametru panelu, tysiące razy na ekran, dla kodu, który na tej warstwie robi dokładnie to, co trzeba).

Punkt wejścia aplikacji

js
import { createApp } from '@xuda/core';
import App from './App.xu';

createApp(App).mount('#app');

App to skompilowany moduł .xu, wytworzony przez @xuda/compiler lub krok budowania vite-plugin-xu. createApp buduje siedem wstrzykiwanych zależności, których potrzebuje renderer, na tabeli thunków zwracanej przez setup() modułu, tworzy renderer i montuje drzewo komponentów. To nie jest drugi renderer: ścieżka skompilowana i interpretowana ścieżka platformy współdzielą render.js.

examples/hello to konkretna, przetestowana wersja tego: createApp(App).mount('#app') na skompilowanym App.xu z licznikiem, warunkiem i listą z kluczami.

Renderer ze wstrzykiwanymi zależnościami

js
import { create_renderer } from '@xuda/core';
import { reactive } from '@xuda/core/reactivity';

create_renderer(deps) jest niezależny od DOM. Wszystko środowiskowe przychodzi przez jeden obiekt deps, a najmniejszy uczciwy host potrzebuje dokładnie siedmiu: document (createElement / createTextNode / createComment), evaluate (śledzony, synchroniczny ewaluator wyrażeń), cast_bool (prawdziwość dla xu-render / xu-if), resolve_rows (śledzony resolver tablicy wierszy dla xu-for), row_key (stabilna tożsamość wiersza), write_field (zapisy xu-bind) i dispatch_event (obsługa xu-on:*). packages/core/demo buduje dokładnie to na zwykłym obiekcie reactive({...}), bez SESSION_OBJ, warstwy źródła danych ani mostu do starszego kodu pod spodem.

Dwie ciche pułapki kontraktu DOM, jeśli piszesz własny adapter

Węzeł deps.document bez nodeType jest czytany jako obiekt jQuery, a nie prawdziwy węzeł DOM, co może zagnieździć każdy wiersz wewnątrz poprzedniego bez żadnego zgłoszonego błędu. Węzeł bez remove() zamienia usunięty wiersz w po cichu odrzuconą obietnicę: lista przestaje się aktualizować i nic nie jest logowane. create_adapter w demo zabezpiecza oba przypadki, rzucając błąd przy tworzeniu węzła; przekaż { guard: false }, aby z tego zrezygnować, gdy zrozumiesz, po co jest to zabezpieczenie.

Diagnostyka i whenElement

onDiagnostic, getDiagnostics, diagnosticCount i resetDiagnostics zamieniają ciche poddawanie się silnika w jeden obserwowalny kanał, zamiast rozproszonych wywołań console.error, żeby adapter hosta lub test mógł subskrybować je przez kod. whenElement uruchamia callback, gdy węzeł już istnieje: pyta raz, potem pyta ponownie w fazie zatwierdzenia planisty (dokładnie wtedy, gdy DOM się ustabilizuje, przed malowaniem), a oczekiwanie wciąż niespełnione po dwudziestu ustabilizowanych renderach zgłasza się po nazwie zamiast po cichu się poddać.

Router

createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter i useRoute są dostarczane z tego samego pakietu. Bieżąca trasa to własny reactive z @xuda/core, a historia pochodzi z platformy, więc korzystanie z niego nie dodaje własnej zależności.

Eksporty pakietu

Deklarowane minimum silnika to Node 18 lub nowszy.