Vai al contenuto
Verificata

Il linguaggio .xu

Il formato a blocchi in cui è scritto ogni file sorgente .xu, e gli undici elementi di base di cui è fatto un progetto.

Un file .xu è un file a blocchi, non un modulo JavaScript. Ogni blocco è un singolo aspetto, e i blocchi oggetto (<meta>, <params>, <fields>, <actions>, <events>, <datasource>) vengono interpretati come letterali in stile JSON5: chiavi senza virgolette, array e oggetti annidati vanno tutti bene.

Undici elementi di base

La cartella in cui si trova un file sorgente decide in quale tipo di unità si compila. Un'app Xu ben fatta di solito è più chiara quando ogni aspetto ha la propria unità invece di un solo file che fa tutto.

App.xu è l'unico file riservato: è sempre l'app radice e si compila sempre nell'id di programma app. Per un file component l'id viene risolto in ordine da meta.id, poi da mount.id, poi dal nome base del file stesso. Ogni altro tipo di unità non ha un blocco <mount>, quindi il suo id viene risolto da meta.id, poi dal nome base del file stesso. Per le risorse JSON5 l'ordine è id, poi _id, poi il nome base. Gli id duplicati in un progetto non sono ammessi.

Blocchi per tipo di unità

App.xu non ha mai bisogno di un blocco <mount>. Un componente normale ne ha bisogno solo quando vuoi montarlo direttamente in una pagina HTML invece di raggiungerlo tramite <panel program="...">:

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

Il linguaggio dei template

Dentro <template>, un piccolo insieme di alias semplici si compila nel markup xu-* del runtime stesso.

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>

Un componente, dall'inizio alla fine

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> si compila in un modulo di montaggio lato client: l'export predefinito riceve un oggetto di contesto e può restituire una funzione di rimozione da eseguire allo scaricamento. I blocchi <style> vengono raccolti in un unico foglio di stile del componente che viene servito.

Formato del datasource

Usa la forma con wrapper leggibile dentro <datasource lang="json5">. type è uno tra none, table, array, json o 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>

Un datasource di tipo table usa table, filter, sort, direction, realtime, limit, skip e output. Un datasource di tipo array, JSON o CSV usa source.field o source.url. Per qualsiasi chiave del datasource che la forma con wrapper non espone, passa a mode="raw" e scrivi i nomi dei campi usati dal documento di runtime stesso.

Gli altri dieci blocchi, in breve

Letture con nome e riutilizzabili. data/get/LoadStudentClasses.xu abbina <params> (campi in/out dichiarati) a un <datasource>, così un componente chiama un loader per nome invece di occuparsi lui stesso dei dettagli della query.

Scritture con nome. data/set/SaveStudentProfile.xu aggiunge crudMode e allowCreate a <meta> insieme ai parametri e al datasource, dando alla persistenza una casa visibile e testabile nel sorgente.

Elaborazione record per record. data/batch/RebuildClassRoster.xu esegue un passaggio di <events> come before_record su ogni riga che il <datasource> risolve.

Un blocco <response> trasforma parametri, risultati del datasource ed eventi in un payload in stile JSON:

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

Una trasformazione con nome e riutilizzabile. <code> viene eseguito come corpo di funzione sui parametri in dichiarati e restituisce il valore out:

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

Una definizione di messaggio riutilizzabile, richiamata da un flusso di lavoro invece di essere scritta inline ogni volta:

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" }
  ]
}

Le route descrivono come i componenti vengono presentati come app navigabile; non sostituiscono i componenti stessi.

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

Un esempio completo

xuda-studant-app-example è un albero di sorgenti completo che copre tutti gli undici blocchi: un flusso di login, una dashboard con route, schermate di elenco studenti, attività e profilo, letture e scritture su tabelle e stile Tailwind. Estrailo con:

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
Esiste anche un secondo dialetto, in fase di build

Tutto quanto sopra è il dialetto interpretato che xuda-cli compila: blocchi analizzati al salvataggio in documenti di runtime progUi / progFields / progEvents, letti dal renderer della piattaforma guidato dalle espressioni. Un compilatore separato e non pubblicato (@xuda/compiler, usato da vite-plugin-xu) legge un file .xu più ristretto composto solo da <template>, <script> e <style>, ignora i nomi dei blocchi sopra e produce in anticipo un vero modulo ES invece di un documento JSON. Ha come obiettivo il renderer più recente basato sui signal in @xuda/core, lo stesso motore che la piattaforma distribuisce come runtime/js/xuda_core.globals.js. Vedi vite-plugin-xu e @xuda/core per quel percorso.