Zum Inhalt springen
Geprüft

Globale Variablen

Das eine Programm, aus dem jedes andere Programm lesen kann, für Zustand und Logik, die zur ganzen App gehören statt zu einem Bildschirm.

Jedes Xuda-Projekt hat genau ein Programm für Globale Variablen. Es enthält die Konstanten, gemeinsamen Variablen und Startlogik, die jede Komponente und jedes Get-Data-, Set-Data-, Batch-, JavaScript- oder API-Programm im Projekt lesen kann. So hat ein Wert, der überall dasselbe bedeutet (der angemeldete Nutzer, ein Feature-Flag, der aktive Campus), genau ein Zuhause, statt in jeden Bildschirm kopiert zu werden, der ihn braucht.

Globale Variablen laufen immer auf dem Client

Was runAt anderswo auch sagt: Die Laufzeit erzwingt für Globale Variablen client. Es ist der eine Programmtyp, der nie auf dem Server läuft, und damit der falsche Ort für alles, was dem Gerät fernbleiben muss (Geheimnisse, privilegierte Lesezugriffe). Nutze dafür ein serverseitiges Get-Data- oder Set-Data-Programm.

Wann du sie nutzt

Greife zu den Globalen Variablen, wenn ein Wert oder ein Stück Startlogik von mehr als einer Komponente gebraucht wird und du ihn nicht bei jeder davon als Parameter durchreichen willst: den Namen des angemeldeten Nutzers, einen gewählten Campus oder Mandanten, ein Dark-Mode-Flag, eine Support-E-Mail-Adresse, einen raise_event-Hub, auf den mehrere voneinander unabhängige Bildschirme hören können.

Nutze sie nicht für etwas, das zu einem einzelnen Bildschirm gehört (das ist ein Komponentenfeld), oder für etwas, das serverseitig laufen muss.

Eigenschaften

Das Dokument liegt bei studio_meta.parentId: "globals", der Wurzel eines eigenen Zweigs im Baum, getrennt von programs, database und routes. Das Dokument der Globalen Variablen eines Projekts und die Baumwurzel können nicht gelöscht werden.

progFields

Jeder Eintrag deklariert eine Variable, überall als @field_id lesbar.

Systemglobale sind immer neben deinen eigenen verfügbar: @SYS_GLOBAL_OBJ_LOGIN_USER_INFO (das Objekt des angemeldeten Nutzers) und @SYS_GLOBAL_OBJ_REFS (mit xu-ref registrierte Elemente, genutzt für Lade- und Leerzustände).

progEvents

Globale Variablen unterstützen dieselbe Form progEvents wie jedes andere Programm, aber nicht jeder Ereignistyp der Plattform gilt für sie. Der Prüfer beschränkt screen_ready, on_refresh, on_unload und client_interval auf Komponenten; einen davon bei einem Programm für Globale Variablen zu deklarieren, ist ein harter Validierungsfehler. Was die Globalen Variablen tatsächlich unterstützen:

Kein client_interval oder server_cron bei den Globalen Variablen

Eine ältere Beschreibung dieser Einheit behauptete, die Globalen Variablen könnten in einem Intervall (client_interval) oder nach einem Server-Cron-Zeitplan (server_cron) pollen. Beides hält dem aktuellen Prüfer nicht stand: client_interval wird als nur für Komponenten validiert, und server_cron ist überhaupt kein bekannter Ereignistyp, seine einzige Spur in der Laufzeit ist ein auskommentierter Handler. Wenn ein Projekt heute wiederkehrendes Polling braucht, setze den Timer auf eine Komponente (client_interval ist dort echt und aktiv), nicht auf die Globalen Variablen.

Praxisbeispiel

Den gemeinsamen Zustand deklarieren

Füge Felder für die Werte hinzu, die jeder Bildschirm braucht: selected_campus_v, signed_in_user_v, dark_mode_v.

Von überall lesen

Jede Komponente, jedes Programm und jeder Ausdruck im Projekt liest sie auf dieselbe Weise, mit @: @selected_campus_v.

Ein übergreifendes Ereignis auslösen

Gib den Globalen Variablen ein user_defined-Ereignis (zum Beispiel campus_changed) und rufe es mit raise_event aus der Komponente auf, die den Campus ändert. Jede andere geöffnete Komponente, die ebenfalls einen raise_event-Listener für diesen Namen registriert hat, reagiert, ohne direkten Bezug zwischen den beiden Bildschirmen.

Im Studio-Baum sind die Globalen Variablen der einzelne Knoten an der Wurzel eines eigenen Zweigs (nicht unter Programme verschachtelt). Öffne ihn, füge der Tabelle Felder für jede gemeinsame Variable Zeilen mit Typ und Standardwert hinzu und füge unter Ereignisse Zeilen für on_load / on_exit / jedes benannte Ereignis hinzu, jeweils mit eigenem Workflow.

xml
<meta lang="json5">
{
  id: "school_globals",
  menuTitle: "School Globals"
}
</meta>

<fields lang="json5">
{
  selected_campus_v: { type: "string", value: "Boston Campus" },
  signed_in_user_v: { type: "string", value: "Avery Walker" },
  support_email_v: { type: "string", value: "[email protected]" },
  dark_mode_v: { type: "boolean", value: false }
}
</fields>
json
{
  "properties": {
    "menuType": "globals",
    "menuName": "School Globals",
    "progDescription": "Campus and operator state shared across the app."
  },
  "progFields": [
    {
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "data": { "field_id": "selected_campus_v", "type": "virtual" },
      "props": { "fieldType": "string", "fieldValue": "Boston Campus" }
    }
  ],
  "progEvents": [
    { "id": "d4e5f6a7-b8c9-4d0e-af1a-3b4c5d6e7f8a", "data": { "type": "on_load", "parameters": [], "condition": "" }, "workflow": [] }
  ],
  "progDataSource": {}
}