85 lines
3.2 KiB
TypeScript
85 lines
3.2 KiB
TypeScript
import type { Entity, JsonValue } from '../shared';
|
||
import type { Interaction } from '../interaction';
|
||
|
||
/**
|
||
* 全局变量
|
||
*
|
||
* 【架构定位】：
|
||
*
|
||
* 1. 它是低代码平台的“响应式状态中枢（Reactive State Hub）”。
|
||
* 2. 它是连接组件（Component）的输入/输出、驱动查询（Query）动态刷新的核心媒介。
|
||
*
|
||
* 【引擎实现指引】：
|
||
*
|
||
* 渲染引擎启动时，必须扫描所有 Variable 节点，提取其 `key` 和初始 `value`，
|
||
* 并在内存中构建一个支持深度订阅的全局 Store（如 Zustand）。
|
||
*
|
||
* 当任何 Action（如 `setVariable`）修改了该 Store 中的值时，
|
||
* 引擎的响应式机制会自动触发所有绑定了该变量的组件重绘或 Query 重新请求。
|
||
*/
|
||
export interface Variable extends Entity {
|
||
/**
|
||
* 变量的键名，用于在表达式中作为变量名来引用
|
||
*
|
||
* 核心架构边界：
|
||
*
|
||
* 与仅用于 UI 展示的 `label` (如："当前选中用户") 不同，`key` 是供 JIT 编译器在代码块中求值的真实引用名。
|
||
* (例如：在代码式的配置中通过 `context.variables.currentUser` 来访问它)
|
||
*
|
||
* 引擎约束：
|
||
*
|
||
* 1. 必须严格符合 JavaScript 变量命名规范（正则：/^[a-zA-Z_$][a-zA-Z0-9_$]*$/）。
|
||
* 2. 在当前应用 (Application) 的所有 Variables 列表中必须全局唯一。
|
||
* 3. 它是不可变的“主键”级数据，修改它可能导致海量已绑定的组件或查询报错（引用失效）。
|
||
*/
|
||
key: string;
|
||
/**
|
||
* 变量的类型，运行时类型守卫
|
||
*
|
||
* 决定了该变量在内存中允许存储的合法数据类型。
|
||
*
|
||
* 引擎在执行 `setVariable` Action 时，必须先根据此字段进行运行时类型校验 (Runtime Type Checking)，
|
||
* 以防止用户将一个对象强行赋给一个声明为 'number' 的变量，从而引发灾难性的级联崩溃。
|
||
*/
|
||
type: 'string' | 'number' | 'boolean' | 'object' | 'array';
|
||
/**
|
||
* 是否为可选变量，默认false
|
||
*/
|
||
optional: boolean;
|
||
/**
|
||
* 是否允许变量为null，默认false
|
||
*/
|
||
nullable: boolean;
|
||
/**
|
||
* 变量保存的值（初始值）
|
||
*
|
||
* 在 Schema 中，它仅仅代表应用首次加载时（或变量被重置时）的一个“静态快照”。
|
||
*
|
||
* 引擎约束：
|
||
*
|
||
* 为确保该初始快照可以被安全地序列化存入数据库，它必须是一个合法的纯净 JSON 结构，
|
||
* 坚决抵制在此处使用 Function, Date 等无法被 `JSON.stringify` 转换的类型。
|
||
*/
|
||
value: JsonValue;
|
||
/**
|
||
* 交互
|
||
*
|
||
* 变量级生命周期与状态监听
|
||
*
|
||
* 挂载于状态节点本身的高阶控制流。
|
||
*
|
||
* 引擎实现指引：
|
||
*
|
||
* 这是低代码中最强大的“连锁反应触发器（Chain Reaction Trigger）”。
|
||
* 当变量的值发生突变时触发（如 `event: 'onChange'`）。
|
||
*
|
||
* 典型场景：
|
||
*
|
||
* 1. 表单联动：当 `selectedProvince` 变量改变时，触发 Action 去清空 `selectedCity` 变量。
|
||
* 2. 异常监控：当 `errorCount` 变量突破阈值时，触发 Action 弹出一个警告对话框 (Modal)。
|
||
*
|
||
* 如果该变量无任何监听逻辑，必须为一个显式的空数组 `[]`。
|
||
*/
|
||
interactions: Interaction[];
|
||
}
|