「AI + 低代码引擎」的可视化设计器状态管理

状态管理

简介

本文件面向设计器状态管理系统，系统性阐述状态管理的设计架构、数据流模型、状态同步机制与持久化策略。围绕全局状态、局部状态、项目模型集成、表达式校验与错误恢复等主题，提供可操作的最佳实践、调试技巧与性能优化建议，并给出扩展机制与第三方状态库集成路径。

项目结构

状态管理涉及多个层次：

• 设计器框架层：提供全局状态容器与持久化策略
• 设计器组件层：提供状态数据的可视化编辑与校验
• 解析器层：提供模板与脚本中状态引用的修复与提取
• 渲染器服务层：提供项目与文件的本地持久化与内存缓存
• 项目模型文档：描述项目/区块模型的事件驱动与序列化生命周期

graph TB
subgraph "设计器框架"
F_State["全局状态(State)<br/>packages/designer/src/framework/state.ts"]
end
subgraph "设计器组件"
W_State["状态编辑小组件(state.vue)<br/>packages/designer/src/components/widgets/scripts/state.vue"]
HookProj["项目钩子(useProject)<br/>packages/designer/src/components/hooks/useProject.ts"]
end
subgraph "解析器"
P_State["状态修复工具(state.ts)<br/>packages/parser/src/tools/state.ts"]
P_Scripts["脚本解析(state提取)<br/>packages/parser/src/vue/scripts.ts"]
end
subgraph "渲染器服务"
R_Storage["本地存储服务(storage.ts)<br/>packages/renderer/src/services/storage.ts"]
R_Memory["内存服务(memory.ts)<br/>packages/renderer/src/services/memory.ts"]
end
subgraph "文档与模型"
D_Models["项目/区块模型文档<br/>docs/src/wiki/core/project-and-block-models.md"]
D_Designer["设计器/渲染器架构文档<br/>docs/src/wiki/package/designer-and-renderer.md"]
end
F_State --> W_State
W_State --> P_State
P_State --> P_Scripts
F_State --> R_Storage
F_State --> R_Memory
HookProj --> D_Models
D_Designer --> F_State

核心组件

• 全局状态容器 State：封装设计器偏好与运行态标志，提供持久化与主题联动
• 状态编辑小组件 state.vue：提供状态键值对的增删改与表达式校验
• 状态修复工具 checkAndFixStatePrefix：自动为模板中的状态引用补全 state. 前缀
• 项目模型与事件系统：描述项目/区块的生命周期与事件流
• 渲染器存储服务：提供本地存储与内存缓存的项目/文件持久化能力
• 全局 Pinia Store 注入工具：通过工具链注入全局状态

架构总览

状态管理采用“框架层容器 + 组件层编辑 + 解析层修复 + 服务层持久化”的分层架构。全局状态通过响应式容器与本地存储协同，保证重启后状态恢复；组件层提供可视化编辑与表达式校验；解析层保障模板引用一致性；服务层提供项目级持久化与内存缓存。

sequenceDiagram
participant UI as "状态编辑小组件(state.vue)"
participant Parser as "状态修复工具(state.ts)"
participant Model as "项目/区块模型"
participant Store as "本地存储服务(storage.ts)"
participant Mem as "内存服务(memory.ts)"
UI->>Parser : "提交状态表达式"
Parser-->>UI : "校验结果(含修复建议)"
UI->>Model : "写入状态键值(JSExpression)"
Model->>Store : "持久化项目DSL"
Model->>Mem : "内存缓存(可选)"
Store-->>UI : "保存成功"
Mem-->>UI : "读取缓存(加速)"

详细组件分析

全局状态容器 State

• 职责：集中管理设计器偏好（如网格线、事件响应、自动应用、历史记录、暗色主题、AI 流式输出）与 LLM 列表
• 数据结构：EngineState 接口定义字段；内部以 Vue 响应式对象承载
• 持久化：构造时从本地存储加载默认值，setter 写回本地存储；同时联动 Vue DevTools 主题
• 方法：提供重置、LLM 新增/删除/查询等便捷方法

classDiagram
class State {
-__state : Reactive<EngineState>
-__isDark : Ref<boolean>
+constructor()
-saveDevtoolsTheme()
+reset()
-save(key, value)
+outlineEnabled
+activeEvent
+autoApply
+autoHistory
+llm
+LLMs
+tour
+dark
+streaming
+saveLLM(item)
+removeLLM(item)
+getLLMById(id)
}

状态编辑小组件 state.vue

• 功能：以表格形式展示区块状态键值对，支持新增、删除、编辑；提交前进行表达式校验
• 输入：当前区块模型与渲染上下文
• 表单校验：通过表达式校验函数验证 JSExpression 的合法性
• 交互：提交成功后调用区块模型 setState/removeState 更新状态

flowchart TD
Start(["进入小组件"]) --> Load["读取区块状态entries"]
Load --> Render["渲染表格(名称/初始值)"]
Render --> AddEdit{"新增或编辑?"}
AddEdit --> |新增| ValidateNew["校验名称唯一性"]
AddEdit --> |编辑| ValidateEdit["校验表达式合法性"]
ValidateNew --> Submit["提交JSExpression"]
ValidateEdit --> Submit
Submit --> Save["调用区块模型setState/removeState"]
Save --> Done(["完成"])

状态修复工具 checkAndFixStatePrefix

• 目标：自动为模板中的状态引用补全 state. 前缀，涵盖插值、绑定、指令、事件等场景
• 流程：解析 SFC → 提取 state 属性 → 遍历模板修复 → 重组代码
• 关键点：从脚本 AST 中识别 reactive(state) 的属性集合，再在模板中进行精确替换

flowchart TD
A["输入Vue代码"] --> B["解析SFC与脚本AST"]
B --> C["提取state属性集合"]
C --> D["扫描模板各指令/表达式"]
D --> E{"是否需补全state.前缀?"}
E --> |是| F["生成修复位置与替换文本"]
E --> |否| G["跳过"]
F --> H["逆序应用修复(避免偏移)"]
H --> I["重组完整Vue代码"]
G --> I
I --> J["输出修复结果与变更清单"]

项目模型与事件系统

• 事件驱动：项目/区块模型通过事件系统广播状态变更，便于全局订阅与联动
• 生命周期：包含初始化、变更、发布、生成源码等阶段
• 序列化：导出 DSL 时清理设计期字段，便于版本控制与模板发布

sequenceDiagram
participant Model as "ProjectModel/BlockModel"
participant Emitter as "事件发射器"
participant UI as "设计器组件"
participant Tools as "内置工具"
Model->>Emitter : "触发EVENT_PROJECT_CHANGE"
Emitter-->>UI : "监听回调(刷新UI)"
Tools->>Model : "写入全局Pinia Store/Access/Axios"
Model->>Emitter : "触发发布/生成事件"

渲染器存储服务

• 本地存储：以项目 ID 为键持久化 DSL，支持初始化时合并已有数据
• 内存缓存：在内存中维护项目/材料/文件/历史等映射，提升读写性能
• 适用场景：设计器启动时快速恢复、运行时临时缓存

graph LR
Proj["ProjectModel"] --> S["StorageService(本地)"]
Proj --> M["MemoryService(内存)"]
S --> Local["localStorage"]
M --> InMem["内存对象"]

全局 Pinia Store 注入工具

• 能力：通过工具链注入全局 Pinia Store/Access/Axios 配置，支持 JSFunction 形式的动态配置
• 用途：在设计器中统一管理全局状态与权限、请求配置

依赖分析

• 组件与模型：state.vue 依赖区块模型的 setState/removeState 与渲染上下文进行表达式校验
• 解析与修复：状态修复工具依赖脚本 AST 提取 state 属性，再对模板进行修复
• 持久化：全局状态与项目模型均依赖存储服务进行本地持久化
• 事件与钩子：useProject 钩子从引擎读取项目状态，配合项目模型事件驱动

graph TB
StateComp["state.vue"] --> BlockModel["BlockModel(JSExpression)"]
StateComp --> Parser["checkAndFixStatePrefix"]
Parser --> AST["AST(state属性)"]
State["State(全局状态)"] --> Storage["StorageService"]
State --> Memory["MemoryService"]
Hook["useProject"] --> ProjectModel["ProjectModel"]
ProjectModel --> Events["事件系统"]

性能考虑

• 响应式与存储分离：全局状态使用响应式容器，同时写入本地存储，避免频繁序列化开销
• 逆序修复：模板修复按结束位置逆序应用，减少索引偏移带来的重复计算
• 内存缓存：渲染器内存服务在高频读写场景下显著降低延迟
• 事件节流：项目模型事件广播应结合节流/去抖策略，避免过度重绘
• 表达式校验：在提交前进行轻量校验，失败早返回，减少无效写入

故障排查指南

• 状态未持久化：检查本地存储键与前缀配置，确认构造函数中是否正确合并默认值
• 表达式校验失败：核对 JSExpression 的语法与上下文可用性，必要时使用状态修复工具自动补全
• 模板引用不生效：确认模板中是否遗漏 state. 前缀，使用状态修复工具批量修复
• 项目恢复异常：检查存储服务初始化逻辑与 DSL 序列化清理步骤
• 全局状态注入失败：确认工具链参数类型与 JSFunction 代码格式

结论

本状态管理体系以全局状态容器为核心，结合可视化编辑、模板修复与持久化服务，形成闭环的数据流与同步机制。通过事件驱动与内存缓存，系统在易用性与性能之间取得平衡；通过表达式校验与修复工具，确保状态引用的一致性与安全性。建议在团队协作中统一状态命名规范与校验规则，并利用内置工具链进行全局状态与权限、请求配置的标准化注入。

附录

• 最佳实践
  • 使用统一的状态命名空间，避免与上下文变量冲突
  • 在提交前进行表达式校验，失败即阻断写入
  • 对模板进行定期修复，保持 state. 前缀一致性
  • 利用内存服务加速开发期读写，生产环境依赖本地存储
• 调试技巧
  • 开启 Vue DevTools，观察响应式状态变化
  • 使用事件监听器跟踪项目模型的变更事件
  • 在存储服务中打印 DSL 序列化前后对比
• 性能监控
  • 监控存储写入频率与体积，避免冗余字段
  • 对高频事件进行节流，减少 UI 重绘
• 扩展与集成
  • 自定义状态处理器：在框架层扩展 State 的字段与方法，或新增专用服务
  • 第三方状态库集成：通过全局注入工具将外部状态库桥接至设计器上下文
  • 与项目模型联动：在事件回调中同步外部状态到项目 DSL 或反向拉取

参考资料

VTJ.PRO VTJ.PRO 是一个开源的 AI 低代码引擎，专注解决 “低代码生成代码不可控、难维护” 的痛点。更多信息请访问：

• 📘 官方文档：vtj.pro/
• 🌐 在线平台：app.vtj.pro/
• 📦 开源仓库：gitee.com/newgateway/…