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

שפת .xu

פורמט הבלוקים שבו כתוב כל קובץ מקור `.xu`, ואחד עשר אבני הבניין שפרויקט עשוי מהן.

קובץ .xu הוא קובץ בלוקים, לא מודול JavaScript. כל בלוק הוא עניין אחד, ובלוקי האובייקטים (<meta>, <params>, <fields>, <actions>, <events>, <datasource>) מנותחים כליטרלים בסגנון JSON5: מפתחות בלי מרכאות, מערכים ואובייקטים מקוננים כולם תקינים.

אחד עשר אבני בניין

התיקייה שבה נמצא קובץ מקור קובעת לאיזה סוג יחידה הוא מתקמפל. אפליקציית Xu טובה נקראת בדרך כלל ברור יותר כשלכל עניין יש יחידה משלו, במקום קובץ אחד שעושה הכול.

App.xu הוא הקובץ השמור היחיד: הוא תמיד האפליקציה הראשית ותמיד מתקמפל למזהה התוכנית app. בקובץ component המזהה נקבע לפי הסדר מ-meta.id, אחר כך מ-mount.id, ואז משם הבסיס של הקובץ עצמו. לכל סוג יחידה אחר אין בלוק <mount>, ולכן המזהה שלו נקבע מ-meta.id, ואז משם הבסיס של הקובץ עצמו. במשאבי ה-JSON5 הסדר הוא id, אחר כך _id, ואז שם הבסיס. מזהים כפולים בפרויקט אסורים.

בלוקים לפי סוג יחידה

App.xu אף פעם לא צריך בלוק <mount>. רכיב רגיל צריך אותו רק כשרוצים שהוא ייטען ישירות לתוך דף HTML ולא יושג דרך <panel program="...">:

xml
<mount>
{
  id: "marketing_hero",
  file: "landing.html",
  selector: "#hero"
}
</mount>

שפת התבניות

בתוך <template>, קבוצה קטנה של כינויים ידידותיים מתקמפלת לסימון ה-xu-* של סביבת הריצה עצמה.

xml
<template>
  <single-view>
    <section class="screen">
      <input bind="search_v" placeholder="Search students">
      <button @click="togglePanel">Toggle panel</button>

      <div if="@show_panel_v">
        <panel program="student_details" />
      </div>
    </section>
  </single-view>
</template>

רכיב, מההתחלה ועד הסוף

xml
<meta lang="json5">
{
  id: "student_list",
  menuTitle: "Student List",
  uiFramework: "@xuda.io/xuda-framework-plugin-tailwind"
}
</meta>

<fields lang="json5">
{
  show_panel_v: { type: "boolean", value: false },
  student_count_v: { type: "number", value: 3 }
}
</fields>

<actions lang="json5">
{
  togglePanel: [
    { action: "update", name: { value: "@show_panel_v: !@show_panel_v" } }
  ]
}
</actions>

<template>
  <single-view>
    <section class="p-6 space-y-4">
      <h1>Students</h1>
      <p :content="'Count: ' + @student_count_v"></p>
      <button class="rounded-full px-4 py-2 bg-sky-600 text-white" @click="togglePanel">
        Toggle details
      </button>
      <div if="@show_panel_v">
        <panel program="student_details" />
      </div>
    </section>
  </single-view>
</template>

<script> מתקמפל למודול טעינה בצד הלקוח: ייצוא ברירת המחדל מקבל אובייקט הקשר ויכול להחזיר פונקציית ניקוי שתרוץ בעת הפריקה. בלוקי <style> נאספים לגיליון סגנונות אחד של הרכיב שמוגש.

פורמט מקור הנתונים

משתמשים בצורת העטיפה הקריאה בתוך <datasource lang="json5">. type הוא אחד מ-none, table, array, json או csv.

xml
<datasource lang="json5">
{
  type: "table",
  table: "student_profiles_table",
  filter: {
    mode: "index",
    activeIndex: "campus_idx",
    indexes: {
      campus_idx: { campus: { from: "@campus_in", to: "@campus_in" } }
    }
  },
  output: "students_out",
  direction: "asc",
  realtime: true,
  limit: 25
}
</datasource>
xml
<datasource lang="json5">
{
  type: "table",
  table: "student_tasks_table",
  filter: {
    mode: "query",
    query: { $and: [{ status: "Open" }, { campus: "Boston Campus" }] }
  },
  output: "tasks_out"
}
</datasource>
xml
<datasource lang="json5">
{
  type: "json",
  source: { url: "https://example.com/students.json" },
  output: "students_out"
}
</datasource>
xml
<datasource lang="json5" mode="raw">
{
  "dataSourceType": "table",
  "dataSourceTableId": "student_profiles_table"
}
</datasource>

מקור נתונים של טבלה משתמש ב-table, filter, sort, direction, realtime, limit, skip ו-output. מקור נתונים של מערך, JSON או CSV משתמש ב-source.field או ב-source.url. לכל מפתח של מקור נתונים שצורת העטיפה לא חושפת, עוברים ל-mode="raw" וכותבים את שמות השדות שמסמך סביבת הריצה עצמו משתמש בהם.

עשרת הבלוקים האחרים, בקצרה

קריאות עם שם, לשימוש חוזר. data/get/LoadStudentClasses.xu מצמיד את <params> (שדות in/out מוצהרים) ל-<datasource>, כך שרכיב קורא לטוען בשמו במקום להחזיק בעצמו את פרטי השאילתה.

כתיבות עם שם. data/set/SaveStudentProfile.xu מוסיף crudMode ו-allowCreate ל-<meta> לצד הפרמטרים ומקור הנתונים, ונותן לשמירה בית גלוי ובר בדיקה במקור.

עיבוד רשומה אחר רשומה. data/batch/RebuildClassRoster.xu מריץ שלב של <events> כמו before_record על כל שורה ש-<datasource> מחזיר.

בלוק <response> הופך פרמטרים, תוצאות של מקור נתונים ואירועים למטען בסגנון JSON:

xml
<response>
({ ok: true, count: (@students_out || []).length, rows: @students_out })
</response>

המרה עם שם, לשימוש חוזר. <code> רץ כגוף פונקציה על פרמטרי ה-in המוצהרים ומחזיר את ערך ה-out:

xml
<code>
return (@raw_name_in || "")
  .trim()
  .toLowerCase()
  .replace(/\b\w/g, (letter) => letter.toUpperCase());
</code>

הגדרת הודעה לשימוש חוזר, שאליה מפנים מתהליך עבודה במקום לכתוב אותה בתוך השורה בכל פעם:

xml
<alert lang="json5">
{
  alertDisplay: "toast",
  alertType: "success",
  alertTitle: "Student saved",
  createLog: false
}
</alert>
json5
{
  id: "student_profiles_table",
  menuTitle: "Student Profiles Table",
  fields: [
    { field_id: "student_id", type: "string" },
    { field_id: "full_name", type: "string" }
  ],
  indexes: [{ id: "campus_idx", name: "Campus", keys: ["campus"] }]
}
json5
{
  id: "app_route",
  menuTitle: "App Route",
  menu: [
    { title: "Overview", prog: "app" },
    { title: "Students", prog: "student_list" }
  ]
}

נתיבים מתארים איך רכיבים מוצגים כאפליקציה שאפשר לנווט בה; הם לא מחליפים את הרכיבים עצמם.

json5
{
  id: "class_helper",
  menuTitle: "Class Helper",
  config: { provider: "openai", model: "gpt-5" }
}

דוגמה מלאה

xuda-studant-app-example הוא עץ מקור שלם שמכסה את כל אחד עשר הבלוקים: זרימת התחברות, לוח בקרה עם ניתוב, רשימת תלמידים, משימות ומסכי פרופיל, קריאות וכתיבות שמבוססות על טבלאות, ועיצוב Tailwind. פורקים אותו עם:

bash
mkdir xuda-studant-app-example
cd xuda-studant-app-example
npm pack xuda-studant-app-example
tar -xzf xuda-studant-app-example-*.tgz --strip-components=1 package
rm xuda-studant-app-example-*.tgz
npm install
npm run dev
קיימת גם דיאלקט שני, בזמן בנייה

כל מה שלמעלה הוא הדיאלקט המפורש ש-xuda-cli מקמפל: בלוקים שמנותחים בזמן שמירה למסמכי סביבת ריצה progUi / progFields / progEvents, שנקראים על ידי מנגנון ההצגה של הפלטפורמה שמונע ביטויים. מהדר נפרד שלא פורסם (@xuda/compiler, שבו משתמש vite-plugin-xu) קורא קובץ .xu צר יותר שעשוי רק מ-<template>, <script> ו-<style>, מתעלם משמות הבלוקים שלמעלה, ופולט מראש מודול ES אמיתי במקום מסמך JSON. הוא מכוון למנגנון ההצגה החדש יותר שמבוסס על signals ב-@xuda/core, אותו מנוע שהפלטפורמה משלבת כ-runtime/js/xuda_core.globals.js. ראו vite-plugin-xu ו-@xuda/core לנתיב הזה.