Saltar para o conteúdo
Verificado

A linguagem .xu

O formato de blocos em que cada ficheiro-fonte .xu é escrito e os onze blocos de construção de que um projeto é feito.

Um ficheiro .xu é um ficheiro de blocos, não um módulo JavaScript. Cada bloco é uma só preocupação, e os blocos de objeto (<meta>, <params>, <fields>, <actions>, <events>, <datasource>) são analisados como literais ao estilo JSON5: chaves sem aspas, arrays e objetos aninhados são todos aceites.

Onze blocos de construção

A pasta em que um ficheiro-fonte está decide a que tipo de unidade é compilado. Uma boa aplicação Xu costuma ler-se com mais clareza quando cada preocupação tem a sua própria unidade, em vez de um só ficheiro fazer tudo.

O App.xu é o único ficheiro reservado: é sempre a aplicação de raiz e compila sempre para o id de programa app. Para um ficheiro component, o id resolve-se por ordem a partir de meta.id, depois mount.id e depois o nome-base do próprio ficheiro. Todos os outros tipos de unidade não levam bloco <mount>, por isso o seu id resolve-se a partir de meta.id e depois do nome-base do próprio ficheiro. Para os recursos JSON5 a ordem é id, depois _id e depois o nome-base. Não são permitidos ids duplicados num projeto.

Blocos por tipo de unidade

O App.xu nunca precisa de um bloco <mount>. Um componente normal só precisa de um quando quer que seja montado diretamente numa página HTML em vez de ser alcançado através de <panel program="...">:

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

A linguagem de modelos

Dentro de <template>, um pequeno conjunto de alias amigáveis compila para a própria marcação xu-* do 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>

Um componente, de ponta a ponta

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>

O <script> compila para um módulo de montagem do lado do cliente: a exportação predefinida recebe um objeto de contexto e pode devolver uma função de descarte a executar ao descarregar. Os blocos <style> são reunidos numa única folha de estilos do componente que é servida.

Formato do datasource

Use a forma de invólucro legível dentro de <datasource lang="json5">. type é um de 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>

Um datasource de tabela usa table, filter, sort, direction, realtime, limit, skip e output. Um datasource de array, JSON ou CSV usa source.field ou source.url. Para qualquer chave de datasource que a forma de invólucro não exponha, passe para mode="raw" e escreva os nomes de campos que o próprio documento de runtime usa.

Os outros dez blocos, em resumo

Leituras com nome e reutilizáveis. data/get/LoadStudentClasses.xu junta <params> (campos in/out declarados) com um <datasource>, para que um componente chame um carregador pelo nome em vez de ter ele próprio os detalhes da consulta.

Escritas com nome. data/set/SaveStudentProfile.xu acrescenta crudMode e allowCreate a <meta> juntamente com os parâmetros e o datasource, dando à persistência um lugar visível e testável na fonte.

Processamento registo a registo. data/batch/RebuildClassRoster.xu executa um passo de <events>, como before_record, para cada linha que o <datasource> resolve.

Um bloco <response> transforma parâmetros, resultados do datasource e eventos numa carga ao estilo JSON:

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

Uma transformação com nome e reutilizável. <code> executa-se como o corpo de uma função sobre os parâmetros in declarados e devolve o valor out:

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

Uma definição de mensagem reutilizável, referenciada a partir de um fluxo de trabalho em vez de ser escrita no próprio local de 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" }
  ]
}

As rotas descrevem como os componentes são apresentados como uma aplicação navegável; não substituem os próprios componentes.

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

Um exemplo completo

O xuda-studant-app-example é uma árvore de fontes completa que cobre os onze blocos: um fluxo de início de sessão, um dashboard com rotas, ecrãs de lista de alunos, tarefas e perfil, leituras e escritas apoiadas em tabelas e estilos Tailwind. Descompacte-o com:

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
Existe também um segundo dialeto, em tempo de compilação

Tudo o que está acima é o dialeto interpretado que o xuda-cli compila: blocos analisados ao guardar para documentos de runtime progUi / progFields / progEvents, lidos pelo renderizador da plataforma orientado por expressões. Um compilador separado e não publicado (@xuda/compiler, usado pelo vite-plugin-xu) lê um ficheiro .xu mais estreito, feito apenas de <template>, <script> e <style>, ignora os nomes de blocos acima e emite antecipadamente um verdadeiro módulo ES em vez de um documento JSON. Tem como alvo o renderizador mais recente baseado em signals do @xuda/core, o mesmo motor que a plataforma disponibiliza como runtime/js/xuda_core.globals.js. Veja vite-plugin-xu e @xuda/core para esse caminho.