# 参考文档总路由（按任务形状命中，不要通读）

先在下表命中一行，按「先读」开工；只有先读不够时才打开「按需再读」。示例检索一律走 [examples/catalog.md](../examples/catalog.md)（按意图标签找可导入工程）。

## 任务形 quick routes

| 任务形状 | 先读 | 按需再读 | 抄哪个示例 |
|---|---|---|---|
| 从零做大屏（**默认产出路径：写 .vp.tsx → 编译成 JSON**） | [vptsx.md](vptsx.md)（写法权威：API/映射规则/配方） | SKILL.md 主流程 | `scripts/vptsx/examples/energy-mini.vp.tsx` + 各示例 `.vp.tsx` 配对 |
| 固定 1920×1080 大屏（演示/LED）的视觉与铺满 | [visual-style.md](visual-style.md)（token+铺满配方） | [envelope.md](envelope.md)、[widgets/index.md](widgets/index.md) | 科技风 01/02 |
| 任意窗口比例自适应（百分比） | [visual-style.md](visual-style.md) §3 第二行配方 | [envelope.md](envelope.md) §4.1 | 科技风 03、布局示例 12 |
| 流式自适应仪表盘（内容回流） | [visual-style.md](visual-style.md) §3 第三行 + [gotchas.md](gotchas.md) #3 | [widgets/layouts.md](widgets/layouts.md)（流式容器预置与子项 `fluid-*`） | 科技风 04、布局示例 03/04/05 |
| 编辑器已打开、改现有页面 | [page-live-loop](page-live-loop.md)（模式 C） | 本技能作写法依据 | — |
| 设计数据源 / mock 实时演示 | [data.md](data.md) | [gotchas.md](gotchas.md) #6/#7 | 科技风 02（mock）、minimal-bar |
| 数据交互（筛选/选中/联动/条件样式/动态数据项/属性数据源） | [widgets/data-interactions.md](widgets/data-interactions.md) | [gotchas.md](gotchas.md) #9~#11 | examples/ 最小版 + `data/数据交互/*` 成屏版 |
| 事件交互（点击/切页/弹窗/轮询/多状态） | [interactions.md](interactions.md) | [gotchas.md](gotchas.md) #19/#20 | `data/数据交互/事件交互`、`示例-多状态切换`、`示例-定时器与接口` |
| 卡片墙 / 设备墙（数据驱动重复） | [widgets/containers.md](widgets/containers.md) §5b + [visual-style.md](visual-style.md) §4 | [gotchas.md](gotchas.md) #17/#18 | 组件示例 25/26、科技风 02 |
| 2D 地图页（标绘/服务/CAD） | [widgets/map-2d.md](widgets/map-2d.md) | [interactions.md](interactions.md) 地图触发器/动作 | `data/地图/图层与源/`（catalog 有分类） |
| 组态页（工艺流程图） | [widgets/scada-2d.md](widgets/scada-2d.md) | [interactions.md](interactions.md) | `data/组态/01`（全功能） |
| 三维场景页（数字孪生） | [widgets/scene-3d.md](widgets/scene-3d.md) | [gotchas.md](gotchas.md) #14/#15 | `data/三维/元素/`（逐元素）→ `data/三维/场景/`（综合） |
| 多页 + 窗口（弹窗/抽屉/画面复用） | [envelope.md](envelope.md) §2b + [widgets/containers.md](widgets/containers.md) §5e | [interactions.md](interactions.md) switchWindow | `data/数据交互/窗口交互-*`、`示例-画面组件-*` |
| 组合组件（母版-实例） | [widgets/containers.md](widgets/containers.md) §5bb | — | `data/组件/组合/04` |
| 设备差异化（大屏/平板/手机） | [envelope.md](envelope.md)（sizeModeOverrides） | [widgets/base-options.md](widgets/base-options.md) device-visible | 组件示例 28、复杂示例 08 |
| 平台怎么用 / SDK 嵌入 / 部署 / MCP | [platform/sdk.md](platform/sdk.md) | — | — |

## 主题文档一览

- [envelope.md](envelope.md)：顶层结构与序列化规则（project/screens/windows/节点形状/铺满 8 值）
- [widgets/index.md](widgets/index.md)：组件参考索引（14 个家族分文件 + 绑定字段速查）
- [data.md](data.md)：连接 / 连接数据 / 数据规则（含 mock 模拟数据源）
- [interactions.md](interactions.md)：事件交互（触发器→动作）与多状态
- [visual-style.md](visual-style.md)：科技感视觉规范（配色 token / 装饰语言 / 铺满守则）
- [gotchas.md](gotchas.md)：常见陷阱 26 条（生成前扫一遍）
- [vptsx.md](vptsx.md)：VP-TSX 写法权威（默认产出路径）——runtime API、JSON→TSX 映射规则、非平凡配方、产出链与校验层次
- [widgets/index.md](widgets/index.md)：14 个组件家族 options 速查
- [widget-schema.generated.json](widget-schema.generated.json)：全量选项字典（机器可读，最权威）