工程文件结构

工程文件（文件名多为 *.vpproj.json）是唯杰AI可视化平台的唯一数据真源：编辑器导出它、运行时加载它。它是纯数据（JSON），因此可版本管理，也可用脚本 / 程序生成。本页速览其顶层结构与节点形状；深入细节见架构原理、数据系统、事件交互。

顶层信封

{
  "project": {
    "name": "工程名",
    "screen": {
      "uid": "screen_main",
      "type": "screen",
      "name": "主页面",
      "options": {
        "layout-profile": "canvas-scale",
        "fullscreen-mode": "stretch",
        "size": [1920, 1080],
        "background-color": "#0c0d0e"
      },
      "widgets": []
    },
    "screens": [],
    "params": {},
    "settings": {}
  },
  "connections": [],
  "connectionData": {},
  "dataRules": []
}

字段	说明
project.screen	必填，主页面。多页放 project.screens[]，前 / 背景层放 foregroundScreen / backgroundScreen
connections	数据源定义（连接 + 表 + 字段，不含行数据）
connectionData	行数据桶：connUid → [{ tableId, rows }]
dataRules	工程级可复用筛选规则（组间 OR、组内 AND）

节点通用形状

页面、组件、子元素（piece）都是同一种节点，靠 type 区分：

{
  "uid": "唯一ID",
  "type": "类型串",         // 页面恒为 "screen"；组件见组件手册；piece 见地图 / 三维 / 组态
  "name": "可选显示名",
  "options": { /* 扁平 KV，只写要改的，其余走默认 */ },
  "stateOverrides": {},      // 多状态覆盖，不用则省略
  "sizeModeOverrides": {},   // 设备差异覆盖（响应式页生效）
  "widgets": [],             // 仅容器型（分组面板 / 页面）有
  "pieces": []               // 仅 builder 型（2D 地图 / 三维场景 / 组态）有
}

options 是稀疏的

只写你要改的项，未写项运行时回落组件默认值。但静态布局下每个组件必须显式写 position 和 size，否则会叠在 [0,0]。

UID 规则

• 形如 前缀 + 随机串（运行期由 vpUid(prefix) 生成）。手写时只需全局唯一且各处引用一致。
• 习惯前缀：页面 screen_、连接 conn_、表 tbl_、字段 f_、数据规则 dc_。组件 uid 一般无前缀。

数据绑定三元组

组件用 field(...) 类型的 option 绑定数据，值是三元组数组 [连接uid, 表uid, 字段uid]：

"metric-fields": [["conn_sales", "tbl_sales", "f_amount"]]

字段 uid 必须是该表 fields[].uid，也是 connectionData 行对象里的键名。详见数据系统。

布局与全屏（速记）

• 每个 screen 节点 options 建议显式写 layout-profile（canvas-scale 固定 / canvas-percent 百分比 / flow-fluid 流式）。
• 铺满屏幕写 fullscreen-mode（示例常用 stretch）。

详见画布系统。

校验

仓库内置校验脚本，可核对 uid 一致性、绑定三元组、必填项等：

node .cursor/skills/generate-vp-project/scripts/validate-project-json.mjs <你的工程.json>