Saltar al contenido
Verificada

El lenguaje .xu

El formato de bloques en el que se escribe cada archivo fuente .xu, y los once bloques de construcción de que se compone un proyecto.

Un archivo .xu es un archivo de bloques, no un módulo de JavaScript. Cada bloque es una responsabilidad, y los bloques de objeto (<meta>, <params>, <fields>, <actions>, <events>, <datasource>) se analizan como literales de estilo JSON5: las claves sin comillas, los arrays y los objetos anidados son todos válidos.

Once bloques de construcción

La carpeta en la que está un archivo fuente decide a qué tipo de unidad se compila. Una buena app Xu suele leerse con más claridad cuando cada responsabilidad tiene su propia unidad en lugar de que un solo archivo lo haga todo.

App.xu es el único archivo reservado: siempre es la app raíz y siempre se compila con el id de programa app. Para un archivo component, el id se resuelve por orden desde meta.id, después mount.id y después el nombre base del propio archivo. Cualquier otro tipo de unidad no lleva bloque <mount>, así que su id se resuelve desde meta.id y después desde el nombre base del propio archivo. Para los recursos JSON5 el orden es id, después _id y después el nombre base. No se permiten ids duplicados dentro de un proyecto.

Bloques por tipo de unidad

App.xu nunca necesita un bloque <mount>. Un componente normal solo lo necesita cuando quieres montarlo directamente en una página HTML en lugar de llegar a él mediante <panel program="...">:

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

El lenguaje de plantillas

Dentro de <template>, un pequeño conjunto de alias cómodos se compila hasta el marcado xu-* propio del 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 componente, de principio a fin

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 compila en un módulo de montaje del lado del cliente: la exportación por defecto recibe un objeto de contexto y puede devolver una función de limpieza que se ejecuta al descargar. Los bloques <style> se reúnen en una única hoja de estilos de componente que se sirve.

Formato de datasource

Usa la forma de envoltorio legible dentro de <datasource lang="json5">. type es uno de 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 de tabla usa table, filter, sort, direction, realtime, limit, skip y output. Un datasource de array, JSON o CSV usa source.field o source.url. Para cualquier clave de datasource que la forma de envoltorio no exponga, pasa a mode="raw" y escribe los nombres de campo que usa el propio documento del runtime.

Los otros diez bloques, brevemente

Lecturas con nombre y reutilizables. data/get/LoadStudentClasses.xu combina <params> (campos in/out declarados) con un <datasource>, de modo que un componente llama a un cargador por su nombre en lugar de ocuparse él mismo de los detalles de la consulta.

Escrituras con nombre. data/set/SaveStudentProfile.xu añade crudMode y allowCreate a <meta> junto con los params y el datasource, dando a la persistencia un lugar visible y comprobable en el código fuente.

Procesamiento registro a registro. data/batch/RebuildClassRoster.xu ejecuta un paso de <events> como before_record sobre cada fila que resuelve el <datasource>.

Un bloque <response> convierte los params, los resultados del datasource y los eventos en una carga de estilo JSON:

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

Una transformación con nombre y reutilizable. <code> se ejecuta como el cuerpo de una función sobre los params in declarados y devuelve el valor out:

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

Una definición de mensaje reutilizable, a la que se hace referencia desde un flujo de trabajo en lugar de escribirla en línea cada vez:

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

Las rutas describen cómo se presentan los componentes como una app navegable; no sustituyen a los propios componentes.

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

Un ejemplo completo

xuda-studant-app-example es un árbol de código fuente completo que cubre los once bloques: un flujo de inicio de sesión, un panel de control con rutas, lista de estudiantes, pantallas de tareas y de perfil, lecturas y escrituras respaldadas por tablas y estilos con Tailwind. Desempaquétalo 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
También existe un segundo dialecto, en tiempo de compilación

Todo lo anterior es el dialecto interpretado que compila xuda-cli: bloques analizados al guardar en documentos de runtime progUi / progFields / progEvents, leídos por el renderizador de la plataforma guiado por expresiones. Un compilador distinto y no publicado (@xuda/compiler, usado por vite-plugin-xu) lee un archivo .xu más reducido, formado solo por <template>, <script> y <style>, ignora los nombres de bloque anteriores y emite por adelantado un módulo ES real en lugar de un documento JSON. Está dirigido al renderizador más nuevo basado en signals de @xuda/core, el mismo motor que la plataforma distribuye como runtime/js/xuda_core.globals.js. Consulta vite-plugin-xu y @xuda/core para ese camino.