# 编辑器使用指南（搭建 / 数据 / 交互 / 布局 / 发布）

## 1. 界面导览

| 区域 | 作用 |
|---|---|
| 组件库（左侧） | 拖拽内置组件到画布（图表/表格/容器/地图控件/布局骨架…） |
| 画布（中央） | 所见即所得摆放/选中/调整；双击容器/地图/组态进入内部编辑 |
| 图层树 | 层级与顺序（数组靠前=底层）、显隐、锁定、进入内部 |
| 属性面板（右侧） | 样式 / 数据 / 交互 / 悬浮弹层 / 多状态 页签 |
| 数据面板 | 新建/编辑连接与连接数据、给组件绑字段 |
| 尺寸模式条（顶部） | 响应式页切 大屏/平板/手机 档编辑 |
| 窗口管理 | 创建/编辑工程级窗口（一次只编辑一个窗口） |
| 代码面板 | 组件/页面的二次开发脚本（Extension） |
| 预览 / 保存 / 历史 / 发布（顶部） | 预览运行态；主动保存草稿（不同则归档上一份，同内容不重复归档）；历史版本还原/管理；发布生成线上快照 |

搭建流程：拖组件 → 调参数（未接数据显示内置示例）→ 数据面板建连接 → 绑字段 → 配交互 → 预览 → 发布/导出。

## 2. 画布与布局（三条互不替代的轴）

**轴 A 全屏适配**（页面 `fullscreen-mode`，管整张画布怎么放进窗口）：`scaling` 等比缩放(默认,可能留黑边→把 `fullscreen-fill-color` 设品牌深色) / `fill-uniform` 等比铺满(不变形,画布撑到视口,右下是真实画布区) / `adaptive` 铺满裁切 / `stretch` 拉伸(背景 `background-fill-type` 也要 stretch) / `responsive` 响应式(画布=窗口,组件按轴 B 回流) / `fit-width`/`fit-height`(超出滚动) / `original`。

**既不变形又不留空**：选 `fill-uniform`（**新建固定大屏模板/新增子页已默认**；在属性面板「布局画像 · 适配方式」里切，从未配过时会自动替你开启「自动填充剩余空间」），再让内容占用撑大出来的画布——优先给主视觉配锚点（地图/表格 `responsive-x:"left-right"`+`responsive-y:"top-bottom"`，侧栏 `right`+`top-bottom`；锚点现在在 `fill-uniform` 下也生效）；老工程可直接开页面 `fill-auto-expand`「自动填充剩余空间」兜底（自动拉伸无锚点的地图/三维/组态/表格/列表/布局容器，以及够大的卡片/图表，夹在外框与邻居之内；外框先撑开，内部主视觉跟到新内缘；前景/背景层上的装饰边框也当外框，避免业务页表格撕出叠层边框；框内二次填充只给近满宽说明块与主视觉类型分增量，文本卡片停在设计尺寸，框内锚点/`canvas-grow:"scale"` 同样生效；叠在主视觉上的图例不挡扩展、居中盒保持对称边距、并排多列按设计宽比例均分增量、被撑大的分组面板/固定面板内部子项跟到新盒；说明顶栏不把地图钉死在标题条、右缘栏不拆横排 KPI 末卡、同侧小控件作为侧栏簇一起贴边）。要「贴着某条边走」或精确控制仍用锚点/百分比。

**子布局在铺满下的分配引擎**（行/列/流式都能用在铺满里，容器都会被撑大，区别是子项怎么跟）：行布局`layout-row`(12 列栅格)/网格`layout-grid`(分割树) 两轴自动按轨道比例回流，最省心；列布局`layout-column`(纵向不换行) 子项设「宽/高自适应」才分到纵向增量（固定大屏页拖入即此默认，老工程里「固定」高度会把增量堆在末尾）；流式行`layout-flow-row`(换行) 子项保持尺寸、按宽度重新换行（换行容器主轴不能自适应，会每项独占一行而塌），要均分就改成不换行；固定面板/分组面板(static) 内部子项走嵌套回流+锚点/百分比；停靠/侧栏由槽位同步。容器不想被撑大就设 `canvas-grow:"scale"`（注意它只管尺寸不管位置：这种容器别贴着增长的那一侧摆，否则右/下会留背景空白——放靠里让主视觉吸收增量，或改用 `responsive-x:"right"` 锚点贴边）。只改运行态几何，不写 options。

**轴 B 内部布局**（页面/容器 `container-layout`，管子组件怎么排）：

- `static` 绝对定位（默认）：子组件必须写 `position`+`size`；响应式适配下要配**锚点**（`responsive-x/y`: left/right/left-right/center/scale…）或**百分比单位**（`geometry-unit:"percent"`），二者不要同用。盒子缩了内容没缩→分组面板开 `panel-content-fit`(contain/cover/stretch)。
- `fluid` 流式：子组件不写坐标；容器侧 `flex-direction`/`fluid-wrap`/`fluid-gap-*`/对齐/`padding`，子项侧 `fluid-width/height-type`(adaptive 等分或吃满/px 固定/auto 内容撑开)。⚠️根页面竖排必须显式 `fluid-wrap:"nowrap"`，否则超高会横向换列。
- `grid` 栅格：`grid-columns/rows` + 子项 `grid-col-span`/`grid-row-span`；布局控件（layout-row/column/grid/dock/sidebar/accordion…）就是预置好布局的容器。

**轴 C 设备断点**：大屏 LARGE(>1279)=基线写 `options`；平板 MEDIUM(768~1279)/手机 SMALL(≤767)只存差量 `sizeModeOverrides`；`device-visible` 按设备显隐。**任何画像都按视口宽切档（固定大屏也生效）**，但固定画布下组件 `position`/`size` 恒走基线（几何由整屏缩放+锚点独占，编辑器画布也不随设备收窄——那只对 responsive 页生效）；能按设备改的是显隐/字号/配色/容器列数(`grid-columns`)/`fluid-wrap`/文案等。手机要完全另一套排布 → 另建 `canvas-percent`/`flow-fluid` 页面再跳转。页面的结构性设置（fullscreen-mode/fill-auto-expand/layout-profile/screen-overflow/size）恒走基线——`fill-auto-expand` 跟 `fullscreen-mode` 同组，否则在窄窗口下开启、窗口变宽切回大屏档就会失效。**设备差量只在编辑态产生**：运行态写入（SDK 句柄 setOption/setOptions、代码面板脚本、交互动作）一律写基线，不会随视口跨档失效；发布页/SDK 内嵌下还会清掉同路径旧差量让写入当场生效，编辑器（含预览）不清。

**新建选布局画像**（`layout-profile`，页面根本性质，改画像≈重排）：固定大屏 `canvas-scale`（投屏/像素稿）/ 百分比自适应 `canvas-percent`（任意窗口铺满+自由摆放）/ 流式 `flow-fluid`（卡片墙/长页）。地图、组态、三维再配侧栏或底栏时选「示例 · CAD 图纸 / 互联网地图 / 组态监控台 / 三维巡检」（`fill-uniform` + `fill-auto-expand`，中间已是对应主视觉）；只要四周栏骨架选「示例 · 等比铺满」。

## 3. 数据接入（数据面板）

三层结构：**连接 connection →表 table → 字段 field**；组件用三元组 `[连接uid, 表uid, 字段uid]` 绑定（属性面板「数据」页签点选即可，无须手写）。绑定认 uid——删了重建连接会失效（用「替换连接」迁移），改别名不影响。

| 连接器 | 用途 | 要点 |
|---|---|---|
| `json`/`csv`/`excel` | 静态/文件数据 | 数据内联，运行时不取数；json/csv 有「编辑」铅笔可就地改数 |
| `api` | HTTP 接口 | `dataPath` 定位响应数组；`refreshInterval` 秒级轮询 |
| `websocket`/`webhook`/`postMessage` | 实时推送 | postMessage=iframe 场景宿主喂数（按 `linkId` 匹配）；接口类只更新连接的**第一张表** |
| `mock` | 模拟数据 | 字段 kind：wave/walk/sequence/int/float/enum…；无后端做实时演示首选 |
| `pocketbase` | 平台数据 | 编辑器「平台数据」里建表（后端 PocketBase 集合），实时订阅 SSE |

在此之上的数据能力（组件属性面板配置）：**筛选 filter**（组件级先筛后用）、**选中传递/联动**（发起方 emit + 接收方 receive；页面开关只在编辑器内预览生效）、**数据规则 dataRules**（可复用条件，供条件样式/多状态/conditionMeet 触发器引用）、**条件样式**（满足规则→改样式）、**动态数据项**（数据驱动任意样式项）。持久化形态细节查本技能 references/（[envelope](../envelope.md) · [data](../data.md) · [interactions](../interactions.md) · [visual-style](../visual-style.md)）。

## 4. 事件交互（属性面板「交互」页签）

模型：**触发器 → 动作**（一个触发器下可挂多条动作，`start` 同时/顺序、`delay`、`duration`）。

- 高频触发器：点击/移入移出/入场离场（组件）、点击某项 itemClicked（数据组件）、行点击（表格）、viewChanged（视图容器）、地图/组态点击、数据规则满足 conditionMeet / 页面入场 screenAppear / 定时器 timer（页面；⚠️ 页面/窗口级触发器只在编辑器内预览生效，发布 /view 与 SDK 静默不跑）。
- 高频动作：修改设置 changeOption（支持公式 `{:字段}` 取 payload）、切换页面/打开链接、开关弹窗 switchPopup / 开关窗口 switchWindow、调用接口 requestApi（结果可写参数/写数据源/派发事件；配页面 timer=轮询仅编辑器内预览有效，运行态轮询用 api 连接 refreshInterval）、发送/接收行为事件（与宿主互通）、切换状态 switchState、执行脚本 executeScript（由宿主 onScript 接管）。
- **多状态**：属性面板「多状态」页签声明状态 + 每状态覆盖若干选项；切换方式=动作主动切/数据驱动/跟随页面态。

完整清单与 JSON 形态：[interactions.md](../interactions.md)。

## 5. 窗口（工程级浮层）

窗口管理面板创建；两类：**固定**（中央/上下左右，可模态 `block-page`+遮罩，可拖标题栏）与**锚定**（贴触发元素，自动翻转避让带箭头；地图点击要素时跟随要素）。打开方式：交互 `switchWindow` / 页面 `open-with-window`（进页自动开，一次会话一次）/ 工程 `splashWindowUid` 启动闪屏 / SDK `ctx.openWindow(uid)`。关闭：遮罩外点击、右上 ×、Esc、`switchWindow(close)`。任意组件还可配「悬浮弹层」（tooltip/悬停卡片/点击 popover，内容可指向窗口）。与页面内轻弹层 `group-popup` 并存：工程级复用选窗口，页面内简单弹层选 group-popup。

## 6. 地图 / 组态 / 三维（双击进入内部编辑）

- **2D 地图 map-2d**：内部=本体（坐标系/底图）+ 数据源 + 图层；支持 CAD 图纸（vjmap 服务）与地理底图互叠。图层点击可配弹锚定窗口（`feature-panel-uid`）。
- **组态 scada-2d**：图元库拖拽 + 端口拉线 + 测点长表驱动（键/值两列，图元填 `data-key`）；主题切换整屏协调。图元库五页签：**工业图元**（含「导入SVG」）、**行业图片**（2.5D/序列帧，按行业/静态·序列帧/分类筛选，精灵图插入时写 `sprite-*`）、**我的图片**（素材库，双击/拖入即成 `shape:"image"` 图片图元，可接线/按值换图）、**我的图元**（框选一组右键「另存为图元…」入库，跨工程复用）、**通用组件**。图片文件可直接从桌面拖进画布或 Ctrl+V 粘贴，自动上传素材库后落成图元。
- **三维场景 scene-3d**：双击进入后左栏变 **3D 组件库**（50 张预设卡：基础/场景/灯光/形状/模型/标注/组态/特效），拖拽插入；右侧场景树按七组分层，视口有选中描边、平移/旋转/缩放 gizmo、「测量」工具与「保存当前视角」。41 种元素（楼群/管网/光柱/看板/液位罐/瓦片底图/倾斜摄影……）+ 测点长表驱动 + 播放态五触发器十六动作。
- 组件级用法与图层/图元/元素清单：本技能 [widgets/map-2d.md](../widgets/map-2d.md) / [scada-2d.md](../widgets/scada-2d.md) / [scene-3d.md](../widgets/scene-3d.md)。

## 7. 代码面板（组件内嵌脚本）

选中组件/页面 → 「代码」页签 → 写 `export default class`，生命周期 `created/mounted/ready/update/destroy/onEnable/onDisable`；`this.element`（本组件：getOption/setOption/addEventListener/emit/getData/寻址）与 `this.project`（跨组件：getElement/setData/setParams/emit）。**编辑态不执行，预览/发布态自动实例化**。跨脚本协作：`getElement(uid).getExtensionInstance()`。详见 [sdk.md](sdk.md) §7。

## 8. 预览 / 保存 / 发布 / 导入导出

- **预览**：编辑器内实时运行态（含交互与取数）。
- **保存（Ctrl+S）= 草稿**；**发布 = 运行态快照**，观看者始终看最近一次发布，草稿可继续改。
- **素材库**：菜单「项目 → 素材库...」，账号级图片资源（跨工程复用），支持多选/整文件夹导入（文件夹名自动成分组）、拖拽与 Ctrl+V 粘贴上传、拼音搜索、批量移动分组/删除；同内容重复上传按散列自动合并。属性面板所有图片类选项都有「素材库」入口。
- **导出工程**：菜单「另存为」→ 选格式：`*.vpproj.json` 工程文件（纯数据，可版本管理/脚本生成）、`*.vpproj.zip` **工程包**（project.json + `assets/` 素材实体，**跨服务器搬家用**：本服务器图片引用会被打包并在导入时自动回传重连）、`*.vp.tsx` **整工程代码**（单文件 AI 可读可改，经 VP-TSX 编译或 `page_apply_project` 回导）、**TSX 工程包 `.zip`**（代码 + 自包含编译环境：runtime/编译器/校验器/schema，解压 `npm i && npm run build` 独立编译出 `.vpproj.json`，`npm run typecheck` 类型检查）；**导入**：首页「导入工程」（吃 `.vpproj.json` 与 `.vpproj.zip`）。导入后打开编辑器会自动截取与「保存」相同的页面预览图（首页卡片缩略图；工程已有手动封面则不覆盖）。部署包/二开包导出时素材自动随包（包内 `data/assets/`）。
- 交付方式对比与二开工程包见 [deploy-and-integrate.md](deploy-and-integrate.md)。