דילוג לתוכן
אומת

@xuda/core

המנוע הריאקטיבי בלי תלויות, שהפלטפורמה, המהדר ואפליקציות ההדגמה נטענים עליו.

@xuda/core הוא המנוע הריאקטיבי של Xuda (signals, מתזמן, השוואת רשימות עם מפתחות, מנגנון הצגה ריאקטיבי, נתב) כחבילת ESM בלי תלויות. הוא לא קורא ולא כותב גלובליים בייבוא: אין func, אין SESSION_OBJ, אין window, אין document.

החבילה הציבורית היחידה בחלק הזה של התיעוד

ה-package.json של @xuda/core נושא "private": false. זו החבילה היחידה מבין השלוש שמכוסות בקטע הזה (לצד @xuda/compiler ו-@xuda/vite-plugin-xu, שתיהן private: true) שנבנתה כדי להיות תלות מחוץ למאגר הזה.

הוא גם לא מנוע נפרד מזה שהפלטפורמה כבר משלבת: סקריפט build:globals של החבילה עצמה (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) הוא הדרך שבה נבנית runtime/js/xuda_core.globals.js, חבילת מנגנון ההצגה הריאקטיבי של הפלטפורמה עצמה.

המשטח הריאקטיבי

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

יש גרף תלויות אחד, עץ בעלים אחד, מאגר אצווה אחד ומתזמן אחד מתחת לכל זה: קריאת ref בתוך effect() עוקבת ומריצה אותו מחדש, בדיוק כמו קריאת signal בתוך watch(). computed כאן מקבל getter, או זוג { get, set } ל-computed שניתן לכתיבה.

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

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

effectScope() עונה על "מי משחרר את זה": בעלים עם שם שאפשר להעביר, לקנן ולעצור בקריאה אחת, במקום להרכיב ביד שקית של משחררים.

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

רכיב שנוצר דרך createApp() כבר מחזיק אחד כזה: ה-<script> שלו רץ בתוך ההיקף המנותק של הרכיב עצמו, ולכן effect שנכתב שם משוחרר אוטומטית כשהרכיב נפרק.

הרכיב ברמה הנמוכה

signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) ו-signalComputed הם התאים של המנוע עצמו מתחת ל-ref ול-computed. הם מיוצאים ונתמכים במלואם, לא הוסרו, כי מנגנון ההצגה והגשר הישן בנויים עליהם, ובגלל ש-signal.notify(), שמריץ מחדש מנויים בלי שינוי ערך, אין לו מקבילה ב-ref. קוד אפליקציה צריך לפנות במקום זה ל-ref ול-computed; שני השמות האלה מתועדים כשכבה שמתחת, לא כמיושנים בזמן ריצה (אזהרה על signal() הייתה נורית לכל היקף שורה ולכל פרמטר של פאנל, אלפי פעמים במסך, עבור קוד שעושה בדיוק את הדבר הנכון בשכבה הזו).

נקודת הכניסה של האפליקציה

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

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

App הוא מודול .xu מקומפל, שנוצר על ידי @xuda/compiler או על ידי שלב הבנייה של vite-plugin-xu. createApp בונה את שבע התלויות המוזרקות שמנגנון ההצגה צריך מעל טבלת ה-thunks ש-setup() של המודול מחזיר, יוצר את מנגנון ההצגה, וטוען את עץ הרכיבים. זה לא מנגנון הצגה שני: הנתיב המקומפל והנתיב המפורש של הפלטפורמה חולקים את render.js.

examples/hello הוא הגרסה הקונקרטית והנבדקת של זה: createApp(App).mount('#app') מעל App.xu מקומפל עם מונה, תנאי ורשימה עם מפתחות.

מנגנון ההצגה, עם הזרקת תלויות

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

create_renderer(deps) אינו קשור ל-DOM. כל מה שסביבתי מגיע דרך אובייקט deps אחד, והמארח הכנה הקטן ביותר צריך בדיוק שבעה מהם: document (createElement / createTextNode / createComment), evaluate (מעריך ביטויים סינכרוני שעוקב), cast_bool (אמת או שקר עבור xu-render / xu-if), resolve_rows (פותר מערך שורות שעוקב עבור xu-for), row_key (זהות יציבה של שורה), write_field (כתיבות של xu-bind) ו-dispatch_event (מטפלי xu-on:*). packages/core/demo בונה בדיוק את זה מעל אובייקט reactive({...}) רגיל, בלי SESSION_OBJ, בלי שכבת מקור נתונים ובלי גשר ישן בשום מקום מתחת.

שתי מלכודות שקטות בחוזה ה-DOM, אם כותבים מתאם משלכם

צומת deps.document בלי nodeType נקרא כאובייקט jQuery ולא כצומת DOM אמיתי, וזה יכול לקנן כל שורה בתוך קודמתה בלי שום שגיאה שנזרקת. צומת בלי remove() הופך שורה שנשמטה להבטחה שנדחית בשקט: הרשימה מפסיקה להתעדכן ושום דבר לא נרשם ביומן. create_adapter בהדגמה שומר מפני שתיהן בכך שהוא זורק בזמן יצירת הצומת; מעבירים { guard: false } כדי לוותר על זה אחרי שמבינים למה השומר קיים.

אבחון ו-whenElement

onDiagnostic, getDiagnostics, diagnosticCount ו-resetDiagnostics הופכים את הכניעות השקטות של המנוע לערוץ אחד שאפשר לצפות בו, במקום קריאות console.error מפוזרות, כך שמתאם מארח או בדיקה יכולים להירשם אליהן מקוד. whenElement מריץ callback ברגע שצומת קיים: הוא שואל פעם אחת, ואז שואל שוב בשלב ה-commit של המתזמן (בדיוק כש-ה-DOM מתייצב, לפני הציור), והמתנה שעדיין לא התמלאה אחרי עשרים רינדורים מיוצבים מדווחת על עצמה בשמה במקום לוותר בשקט.

הנתב

createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter ו-useRoute נשלחים מאותה חבילה. הנתיב הנוכחי הוא reactive של @xuda/core עצמו, וההיסטוריה מגיעה מהפלטפורמה, ולכן השימוש בו לא מוסיף תלות משלו.

ייצואי החבילה

Node 18 ומעלה היא רצפת המנוע המוצהרת.