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

1. 界面导览

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

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——删了重建连接会失效（用「替换连接」迁移），改别名不影响。

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

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。

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 / scada-2d.md / 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 §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。