Aller au contenu
Vérifié

Le langage .xu

Le format de blocs dans lequel s'écrit chaque fichier source .xu, et les onze éléments de base dont un projet est fait.

Un fichier .xu est un fichier de blocs, pas un module JavaScript. Chaque bloc correspond à une préoccupation, et les blocs d'objet (<meta>, <params>, <fields>, <actions>, <events>, <datasource>) sont analysés comme des littéraux de style JSON5 : clés sans guillemets, tableaux et objets imbriqués sont tous acceptés.

Onze éléments de base

Le dossier où se trouve un fichier source détermine le type d'unité vers lequel il se compile. Une bonne app Xu se lit généralement plus clairement quand chaque préoccupation a sa propre unité plutôt qu'un seul fichier qui fait tout.

App.xu est le seul fichier réservé : c'est toujours l'app racine et il se compile toujours vers l'identifiant de programme app. Pour un fichier component, l'identifiant se résout dans l'ordre à partir de meta.id, puis mount.id, puis du nom de base du fichier. Tous les autres types d'unité n'ont pas de bloc <mount>, donc leur identifiant se résout à partir de meta.id, puis du nom de base du fichier. Pour les ressources JSON5, l'ordre est id, puis _id, puis le nom de base. Les identifiants en double dans un projet ne sont pas autorisés.

Blocs par type d'unité

App.xu n'a jamais besoin d'un bloc <mount>. Un composant ordinaire n'en a besoin que si vous voulez le monter directement dans une page HTML plutôt que de l'atteindre via <panel program="..."> :

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

Le langage de template

Dans <template>, un petit ensemble d'alias pratiques se compile vers le balisage xu-* propre au runtime.

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 composant, de bout en bout

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> se compile en un module de montage côté client : l'export par défaut reçoit un objet de contexte et peut renvoyer une fonction de nettoyage à exécuter au déchargement. Les blocs <style> sont rassemblés en une seule feuille de style de composant servie.

Format de source de données

Utilisez la forme d'enveloppe lisible dans <datasource lang="json5">. type vaut none, table, array, json ou 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>

Une source de données de type table utilise table, filter, sort, direction, realtime, limit, skip et output. Une source de données de type tableau, JSON ou CSV utilise source.field ou source.url. Pour toute clé de source de données que la forme d'enveloppe n'expose pas, passez à mode="raw" et écrivez les noms de champs qu'utilise le document du runtime lui-même.

Les dix autres blocs, en bref

Des lectures nommées et réutilisables. data/get/LoadStudentClasses.xu associe <params> (champs in/out déclarés) à une <datasource>, donc un composant appelle un chargeur par son nom au lieu de gérer lui-même les détails de la requête.

Des écritures nommées. data/set/SaveStudentProfile.xu ajoute crudMode et allowCreate à <meta> à côté des paramètres et de la source de données, ce qui donne à la persistance un emplacement visible et testable dans la source.

Traitement enregistrement par enregistrement. data/batch/RebuildClassRoster.xu exécute une étape <events> comme before_record sur chaque ligne que résout la <datasource>.

Un bloc <response> transforme les paramètres, les résultats de la source de données et les événements en une charge utile de style JSON :

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

Une transformation nommée et réutilisable. <code> s'exécute comme un corps de fonction sur les paramètres in déclarés et renvoie la valeur out :

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

Une définition de message réutilisable, référencée depuis un workflow au lieu d'être écrite en ligne à chaque fois :

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

Les routes décrivent comment les composants sont présentés sous forme d'app navigable ; elles ne remplacent pas les composants eux-mêmes.

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

Un exemple complet

xuda-studant-app-example est une arborescence source complète qui couvre les onze blocs : un parcours de connexion, un tableau de bord avec routes, des écrans de liste d'étudiants, de tâches et de profil, des lectures et écritures adossées à des tables, et un style Tailwind. Décompressez-la avec :

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
Il existe aussi un second dialecte, à la compilation

Tout ce qui précède est le dialecte interprété que compile xuda-cli : des blocs analysés à l'enregistrement vers des documents de runtime progUi / progFields / progEvents, lus par le moteur de rendu piloté par expressions de la plateforme. Un compilateur distinct et non publié (@xuda/compiler, utilisé par vite-plugin-xu) lit un fichier .xu plus restreint, composé uniquement de <template>, <script> et <style>, ignore les noms de blocs ci-dessus et produit à l'avance un vrai module ES au lieu d'un document JSON. Il cible le moteur de rendu plus récent, à base de signaux, de @xuda/core, le même moteur que la plateforme livre sous runtime/js/xuda_core.globals.js. Voir vite-plugin-xu et @xuda/core pour cette voie.