Preskočiť na obsah
Overené

@xuda/core

Reaktívny engine bez závislostí, na ktorom stojí platforma, kompilátor aj ukážkové aplikácie.

@xuda/core je reaktívny engine Xuda (signály, plánovač, diff zoznamu s kľúčmi, reaktívny renderer, router) ako balík ESM bez závislostí. Pri importe nečíta ani nezapisuje žiadne globálne premenné: nie func, nie SESSION_OBJ, nie window, nie document.

Jediný verejný balík v tejto časti dokumentácie

package.json balíka @xuda/core obsahuje "private": false. Je to jediný balík spomedzi troch v tejto sekcii (popri @xuda/compiler a @xuda/vite-plugin-xu, oba private: true), ktorý je určený na to, aby sa naň dalo odkazovať mimo tohto repozitára.

Nie je to ani iný engine než ten, ktorý platforma už dodáva: vlastný skript build:globals balíka (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) je spôsob, akým sa zostavuje runtime/js/xuda_core.globals.js, balík reaktívneho renderera dodávaný s platformou.

Reaktívna plocha

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

Pod tým všetkým je jeden graf závislostí, jeden strom vlastníkov, jeden buffer dávok a jeden plánovač: ref prečítaný vnútri effect() sa sleduje a efekt znova spustí, rovnako ako signál prečítaný vnútri watch(). computed tu prijíma getter alebo dvojicu { get, set } pre zapisovateľný computed.

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

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

effectScope() odpovedá na otázku, kto toto uvoľní: pomenovaný vlastník, ktorého môžete odovzdávať, vnárať a zastaviť jedným volaním, namiesto ručného skladania hŕby uvoľňovačov.

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

Komponent vytvorený cez createApp() už jeden takýto rozsah vlastní: jeho <script> beží vo vlastnom oddelenom rozsahu komponentu, takže efekt tam napísaný sa pri odpojení komponentu uvoľní automaticky.

Nízkoúrovňový primitív

signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) a signalComputed sú vlastné bunky enginu pod ref a computed. Sú exportované a plne podporované, neodstránené, pretože na nich stoja renderer a starý most a pretože signal.notify(), opätovné spustenie odberateľov bez zmeny hodnoty, nemá ekvivalent v ref. Kód aplikácie by mal siahať po ref a computed; tieto dva názvy sú zdokumentované ako vrstva pod nimi, nie zastarané za behu (varovanie pri signal() by sa spustilo pri každom rozsahu riadku a každom parametri panela, tisíckrát na obrazovku, pre kód, ktorý na tejto vrstve robí presne to správne).

Vstupný bod aplikácie

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

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

App je skompilovaný modul .xu, ktorý vytvára @xuda/compiler alebo krok zostavenia vite-plugin-xu. createApp zostaví sedem vstrekovaných závislostí, ktoré renderer potrebuje, nad tabuľkou thunkov, ktorú vráti setup() modulu, vytvorí renderer a pripojí strom komponentov. Nie je to druhý renderer: skompilovaná cesta a interpretovaná cesta platformy zdieľajú render.js.

examples/hello je konkrétna, otestovaná verzia tohto: createApp(App).mount('#app') nad skompilovaným App.xu s počítadlom, podmienkou a zoznamom s kľúčmi.

Renderer so vstrekovanými závislosťami

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

create_renderer(deps) je nezávislý od DOM. Všetko prostredie prichádza cez jeden objekt deps a najmenší poctivý hostiteľ potrebuje presne sedem vecí: document (createElement / createTextNode / createComment), evaluate (sledovaný synchrónny vyhodnocovač výrazov), cast_bool (pravdivosť pre xu-render / xu-if), resolve_rows (sledovaný resolver poľa riadkov pre xu-for), row_key (stabilná identita riadku), write_field (zápisy xu-bind) a dispatch_event (handlery xu-on:*). packages/core/demo stavia presne toto nad obyčajným objektom reactive({...}), bez SESSION_OBJ, bez vrstvy zdroja dát a bez starého mosta pod ním.

Dve tiché pasce DOM kontraktu, ak píšete vlastný adaptér

Uzol deps.document bez nodeType sa číta ako objekt jQuery, nie skutočný uzol DOM, čo môže vnoriť každý riadok do predchádzajúceho bez vyhodenej chyby. Uzol bez remove() zmení vyradený riadok na ticho zamietnutý promise: zoznam sa prestane aktualizovať a nič sa nezaloguje. create_adapter v ukážke chráni obe vyhodením chyby pri vytvorení uzla; keď pochopíte, prečo stráž existuje, môžete ju vypnúť cez { guard: false }.

Diagnostika a whenElement

onDiagnostic, getDiagnostics, diagnosticCount a resetDiagnostics menia tiché vzdania sa enginu na jeden pozorovateľný kanál, namiesto roztrúsených volaní console.error, takže sa naň môže v kóde prihlásiť adaptér hostiteľa alebo test. whenElement spustí callback, keď uzol existuje: opýta sa raz a potom sa znova pýta vo fáze commit plánovača (presne vtedy, keď sa DOM ustáli, pred vykreslením), a čakanie, ktoré ostane nesplnené po dvadsiatich ustálených vykresleniach, ohlási samo seba menom, namiesto toho, aby sa ticho vzdalo.

Router

createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter a useRoute prichádzajú z rovnakého balíka. Aktuálna trasa je vlastný reactive balíka @xuda/core a história pochádza z platformy, takže jeho použitie nepridáva žiadnu vlastnú závislosť.

Exporty balíka

Deklarovaná minimálna verzia enginu je Node 18 alebo novší.