画布系统

2026年7月8日大约 23 分钟

画布系统

画布就是页面的可视区域。本章解决一个反复困扰新手的问题：大屏怎么在各种屏幕 / 窗口下正确地铺满、不变形、内容不丢。

一句话决策

投屏 / 像素稿还原 → 新建选「固定大屏」，全屏适配用「等比缩放」。
地图 / 组态 / 三维再配侧栏或底栏 → 新建选「示例 · CAD 图纸 / 互联网地图 / 组态监控台 / 三维巡检」（不变形铺满，主视觉自动吃剩余空间）；只要骨架选「示例 · 等比铺满」。
任意窗口都铺满、又要自由摆放 → 选「自适应画布 · 百分比」。
卡片墙 / 报表长页、内容随窗口回流 → 选「流式」。

三条互不替代的轴

大屏「看起来怎么适配窗口」由三组各管各的设置共同决定。把它们混为一谈，是布局踩坑的头号原因。

轴	在哪里设	管什么
轴 A · 全屏适配	页面 → `fullscreen-mode`	整张画布如何放进浏览器窗口
轴 B · 内部布局	页面 / 分组面板 → `container-layout`	子组件之间怎么排
轴 C · 设备断点	工程设置 + 尺寸模式条	大屏 / 平板 / 手机各存一份差量

轴 A 决定「画布与窗口的关系」，轴 B 决定「画布里面怎么排」，轴 C 是叠加在前两者之上的「按设备改一改」。三轴常用的组合已被预置成页面布局画像，新建时选画像即可。

布局画像（layout-profile）：新建时选它

每个页面有一个布局画像，是页面整体行为的「主声明」。新建工程选模板，本质就是选画像。

画像	机制	适用
固定大屏（`canvas-scale`）	固定设计尺寸（如 1920×1080），播放时整张画布等比缩放进窗口	指挥中心投屏、固定比例 LED、像素稿还原
百分比自适应（`canvas-percent`）	画布=窗口，组件仍绝对定位但按百分比随窗口等比改尺寸	任意窗口比例都要铺满、又想保留自由摆放（地图为底 + 悬浮面板）
流式（`flow-fluid`）	画布=窗口，组件按「流」自动排布（可换行 / 等分 / 填充剩余空间）	卡片墙、运营长页、移动端友好

新建时选对最省事

画像决定「这一页的根本性质」。从「固定大屏」改成「流式」往往要重排所有组件。同一工程的不同页面可以用不同画像。

轴 A · 全屏适配（fullscreen-mode）

设计稿是固定比例，播放窗口比例千变万化，所以「全屏 + 不变形 + 内容完整」三者不可兼得。每个取值就是一种取舍。

取值	界面名	行为	取舍
`scaling`	等比缩放	整页等比缩进窗口（contain）	不变形、完整，可能留黑边（内核缺省：工程 JSON 没写该键时按此播放）
`fill-uniform`	等比铺满 · 不变形(背景填满)	等比取 min 缩放（不变形）、内容锚定左上；画布逻辑尺寸撑到视口，右 / 下空白由页面背景填满	不变形、无黑边（新建固定大屏模板的默认起手式，配合锚点 / 自动填充吃掉扩展区，见下）
`adaptive`	铺满裁切	等比放大铺满（cover）	不变形、铺满，贴边内容被裁
`stretch`	拉伸	横纵独立缩放	铺满、完整，会变形
`responsive`	响应式	不缩放，画布=窗口，组件按轴 B 回流	真随窗口改尺寸（百分比 / 流式靠它）
`fit-width`	宽度铺满	按宽等比铺满，超高纵向滚动	竖屏门户、长卷海报
`fit-height`	高度铺满	按高等比铺满，超宽横向滚动	LED 横带、拼接条屏
`original`	原始	1:1 不缩放、居中	调试、小画布预览

黑边从哪来、怎么处理

scaling 要保证「不变形 + 完整」，当窗口比例与设计稿不一致时只能在四周留空白——这是物理必然，不是 bug。处理办法：

把填充颜色（fullscreen-fill-color，代码默认 #000000 纯黑）设成品牌深色（推荐示例 #04111d），黑边就「隐形」了（最稳妥）；
或改用 fill-uniform（不变形、空白由页面背景补满，代价内容靠左上不居中）、adaptive（代价裁边）、stretch（代价变形）、fit-* / responsive（代价按会变的尺寸设计）。

既不变形、又不留空：让内容吃掉扩展出来的画布

fill-uniform 与 scaling 的内容倍率完全相同，区别只在留白是「黑边」还是「真实画布」：前者把画布撑到视口 ÷ 缩放系数，多出来的右 / 下是可以摆内容的区域。所以只要有人去占用它，「等比不变形」和「铺满不留空」就能同时成立。两种占用方式，优先用第一种：

锚点（精确、推荐）：给该长大的组件设 responsive-x: left-right / responsive-y: top-bottom（地图、表格四边贴边），侧栏设 right / top-bottom。原来只在「响应式」下生效的锚点，现在 fill-uniform 下同样生效。
自动填充（兜底、零配置）：页面开 fill-auto-expand（界面「自动填充剩余空间」），把没有显式锚点的地图 / 三维 / 组态 / 表格 / 列表 / 布局容器，以及够大的卡片 / 图表（宽 ≥ 画布 15%、高 ≥ 10%）拉到剩余空间，并夹在包裹它的外框、同宽顶栏、右侧与下方邻居之内。外框若也是填充候选，会先撑开，再让内部主视觉跟到新内缘（组态套装饰边框时才能铺满）。前景 / 背景层上的装饰边框也当作外框约束，避免业务页表格撕出叠层边框。框内的二次填充只给近满宽的说明块 / 状态条与本身就是主视觉的类型分增量：文本卡片这类固定盒会停在设计尺寸（否则标注了精确坐标尺寸的示意盒会被撑成整框大小），框内组件的锚点与 canvas-grow: scale 在这一轮同样生效。贴着设计稿右缘的窄栏（距右约 96px 内的状态卡）会随画布变宽右移，避免放大后被主视觉盖住或右侧留空；与贴边栏水平重叠的同侧小控件（坐标 / 缩放 / 指南针）作为侧栏簇一起走。横排 KPI 墙的末卡不搬（不依赖是否有装饰边框），避免最后一张被撕出边框。装饰边框撑开后，框内横排与近满宽说明块会再分一次增量，避免外框铺满、里面仍留空。适合老工程一键改善。侧栏也可显式写 responsive-x: right。
四条构图规则（自动生效）：叠在主视觉之上的浮层（图例、工具条、悬浮卡）不当成右 / 下邻居，主视觉照常扩展并从它下面穿过；设计稿上左右（或上下）边距对称的居中盒（两侧留白都 ≥ 96px 且基本相等）扩展时保留原边距，不会被只向右下的拉伸带偏；并排的多列 / 多行填充候选（首尾相接的带）按设计尺寸比例分配增量、后续列平移（三列看板均匀长大，不再是右列独吞；增量不足 48px 不挪列），叠在后续列上的浮层随宿主一起平移；被撑大的分组面板 / 固定面板（static + 内容适应=none）内部子项按同一套锚点 + 填充跟到新盒，贴原点且尺寸≈面板的「铺满子项」直接跟满（递归三层；栅格 / 流式容器由 CSS 轨道自己回流，停靠 / 侧栏的槽位有专门的运行态同步）。比主视觉宽的说明顶栏若右侧还有更靠外的贴边控件，不再把主视觉钉在顶栏右缘（否则地图停在标题条、中间留空）。

在编辑器里把「适配方式」切到等比铺满时，若你从未配置过「自动填充剩余空间」，会替你自动开启（显式关过则尊重你的选择）——避免「选了铺满、预览里右侧仍是一片空背景」。

两者可共存：显式锚点优先，自动填充只管剩下的组件。容器若不想被撑大（希望卡片数不变、整体等比放大），把它的 canvas-grow 设为 scale——分组面板与行 / 列 / 网格 / 流式行 / 固定面板在属性面板里有这一项；停靠、侧栏这类整页骨架默认吃满（工程 JSON 里同样可写该键）。

各子布局在铺满下的表现

布局容器都是填充候选，都会被撑大；区别在里面的子组件怎么跟。所以「行式 / 列式 / 流式」可以放心用在等比铺满里，只要知道各自的分配引擎：

子布局	内部引擎	容器被撑大后子项的行为
行布局 `layout-row`	栅格（12 列 × 1 行，`minmax(0,1fr)`）	两轴都自动按轨道比例回流，无需任何设置
网格布局 `layout-grid`	栅格分割树（分数轨道）	同上；格子按 `grid-tree` 比例一起长大
列布局 `layout-column`	流式纵向、不换行	横向铺满；纵向增量分给子项——固定大屏页里新拖入的子项默认「宽/高都自适应」即可分到增量；老工程若子项高度是「固定」，增量会堆在末尾，手动改成自适应
流式行 `layout-flow-row`	流式横向、换行	按可用宽度重新换行排布。子项保持固定尺寸（这是刻意的：换行容器里主轴自适应会让每项独占一行而塌掉）。要让它们均分宽度，把容器的「换行」设为不换行
固定面板 `layout-fixed-panel`、分组面板 `group-panel`	静态绝对定位	内部子项按锚点 + 自动填充跟到新盒（递归三层）；贴原点且尺寸≈面板的「铺满子项」直接跟满
停靠 / 侧栏 `layout-dock`、`layout-sidebar`	外壳槽位（flex）	槽位盒随外壳变化，面板与铺满子项跟到新槽位

一句话选型

要规整均分用行 / 网格布局（栅格轨道最省心）；要纵向堆叠且一起长高用列布局；要卡片墙自然换行用流式行（子项保持尺寸）；要自由摆放用分组 / 固定面板（内部走锚点或百分比）。

scale 只管尺寸，不管位置

把 canvas-grow: scale 的容器摆在画布增长的那一侧（比如贴着右缘的侧栏），撑开出来的区域既没人吃、容器也不会挪过去，就会留一块背景空白。两种正确摆法：让它靠里、由主视觉吸收增量（见 data/布局/适配/18），或者改用锚点 responsive-x: right 贴边——那样它同样保持宽度，但会跟着右缘走。

只改播放几何，不改工程

锚点与自动填充都只写运行态几何（playing），不改 options、不进撤销栈；编辑器画布仍按设计尺寸呈现。

自动填充的边界（要精确控制就用锚点）

列带间隙里躺着非成员（分隔装饰、钉死的小组件）时放弃按比例重排，回退为「带尾吃满」的保守结果。
组件平移只发生在两处：右缘窄栏 / 侧栏簇贴边、并排带的后续列（连同叠在其上的浮层）。其它组件只向右 / 向下变大。要「贴着某条边走」必须用锚点。
嵌套回流只进分组面板 / 固定面板（static、内容适应=none、限三层）；panel-content-fit 非 none 时由 CSS 缩放接管，锚点 / 百分比子项仍按各自规则。

拉伸的配套铁律

切到 stretch 时，记得把背景的「填充方式」（background-fill-type）也设为 stretch，并让画布尺寸贴合目标屏比例，否则会「背景错位、圆被拉成椭圆」。

轴 B · 内部布局（container-layout）

容器用 container-layout 决定其直接子组件如何排布。可选值按容器类型不同：页面只有 static 绝对定位 / fluid 流式两种；组件容器（分组面板、布局容器）另有第三种 grid 栅格。

静态布局（static，默认）

每个子组件用 position（左上角 [x, y]）和 size（[宽, 高]）摆放，坐标相对父容器左上角。
组件可重叠，图层数组靠前 = 先绘制 = 在底层。
配合固定大屏缩放时，所有组件随整页一起缩放，相对位置不变（和 PPT 投屏一样）。

注意

静态布局下组件必须显式写 position 和 size，否则会叠在 [0,0]。

在「响应式」全屏适配下，静态组件默认钉死在设计坐标。要让它随窗口变化，用下面两种之一（两者互斥：组件设了 percent 单位后锚点重算会被跳过，percent 生效、不报错）：

① 响应式锚点（responsive-x / responsive-y）：让组件相对容器边缘固定或拉伸。

横向 `responsive-x`	含义
`left` / `right`	左 / 右边距固定
`left-right`	左贴边，宽度随容器拉满
`center`	水平居中
`scale`	位置与宽度按比例缩放

纵向 responsive-y 同理（top / bottom / top-bottom / middle / scale）。典型「地图为底 + 左右悬浮面板」：地图 left-right × top-bottom（四边贴边铺满），左右面板 left/right × top-bottom（永远贴边）。

② 百分比单位（geometry-unit: percent）：渲染时把位置 / 尺寸换算成相对父容器的百分比，父盒一变就等比自适应。选了「自适应画布 · 百分比」模板后新拖入的静态组件会自动默认 percent；拖入的若是设计容器（分组面板 / 布局容器），插入时还会自动补 panel-content-fit: contain（补缺不覆盖，避免百分比盒变化时内部被裁）。

高频坑：盒子缩了，里面的内容没缩

百分比 / 锚点只适配「这一层盒子」，不缩盒子里按像素摆放的子内容。给分组面板开「内容自适应缩放」（panel-content-fit：默认 none 不缩放，可选 contain 等比适应 / cover 等比铺满 / stretch 拉伸铺满），或整页改用固定大屏缩放即可解决。

流式布局（fluid）

流式下子组件不写绝对坐标，按顺序自动排布，靠「流式选项」决定占多大、是否换行。

容器侧（写在流式容器身上）：flex-direction（row/column 主轴；页面默认 column，组件容器默认 row）、fluid-wrap（wrap/nowrap，默认换行）、fluid-gap-type（fixed/adaptive，默认 fixed；adaptive 等价 space-between 且忽略间隔值）、fluid-gap-value（页面默认 10）、fluid-justify-content / fluid-align-items（主 / 交叉轴对齐）、padding（[上,下,左,右]，页面流式默认 [2,2,2,2]）。

子项侧（写在子组件身上）：宽高各有三态 fluid-width-type / fluid-height-type（默认宽 adaptive、高 px）：

adaptive 自适应：撑满交叉轴；若在主轴上则多个子项等分或单个吃满剩余空间，可用 *-minmax:[min,max] 约束。
px 固定：固定像素（fluid-width-px / fluid-height-px，默认 100），配合换行做卡片墙。
auto：由内容自身撑开。

作用域差异：同一套键，不同容器露出的 UI 不同

完整的流式设置面板（间隔类型 / 间隔值 / 主 / 交叉轴对齐 / 内边距）在页面上；布局容器（列布局、流式行）另有「排布对齐」组（主轴对齐含 space-between 等 6 档 + 间隙）；普通分组面板切到流式后面板上只有 flex-direction + fluid-wrap。渲染层对所有流式容器读同一套键，手写 JSON 给分组面板加 fluid-justify-content、padding 等同样生效。

流式最易踩的坑

根页面用「流式 + 竖排」时，务必显式把 fluid-wrap 设为 nowrap。容器默认换行（wrap），内容一旦超高就会「横向换列、跑到最右边」。

栅格布局（grid，仅组件容器）

分组面板 / 布局容器设 container-layout: 'grid' 后，直接子组件按栅格轨道落位（行布局 layout-row 就是预置的 12 列 × 1 行栅格）。

容器侧：grid-columns（列数，默认 12）、grid-rows（行数，默认 1）、grid-col-gap / grid-row-gap（列 / 行间隔，默认 8）、grid-padding（内边距 [上,下,左,右]，注意不是 padding——那是流式的键，两者独立）、grid-col-weights / grid-row-weights（逗号分隔的轨道权重字符串，如 "1,2,1"；留空 = 等分）。

子项侧：grid-col-span / grid-row-span（跨列 / 跨行，默认 1）、grid-col-start / grid-row-start（1 起算的起始线；默认 0 = 不指定起始线，自动流式填充）。

提示

「网格布局」组件（layout-grid）不用这套扁平轨道键——它走树形分割树 grid-tree（九宫格占位、拖分隔条调相邻比例），两套模型不要混写。

轴 A × 轴 B 怎么配对

全屏适配	static（绝对定位）	fluid（流式）
等比缩放 / 铺满裁切 / 拉伸	✅ 经典固定大屏	⚠️ 设计尺寸内排好后再整体缩放（放大镜，非真回流）
等比铺满	✅ 固定大屏；配锚点 / `fill-auto-expand` 可让内容吃满扩展区	⚠️ 同上（子项按流排好后整体缩放）
响应式	⚠️ 必须配锚点或百分比单位，否则钉死	✅ 真回流：随窗口改尺寸 / 换行

记住：选了「响应式」，绝对定位的组件不会自动动——要么改流式，要么加锚点 / 百分比单位。

行 / 列 / 流式 / 网格这些布局容器在「等比铺满 + 内容吃满」下最省事：容器盒被撑大后，子项由容器自己重排，不必逐个配锚点。注意两点差异——fluid-*-type: px 的子项固定不变（只有间距变），fluid-wrap: wrap 会重新换行导致每行卡片数变化。要保持设计稿的卡片数，把容器 canvas-grow 设为 scale。

轴 C · 设备断点（大 / 平板 / 手机）

「一套工程，三档屏宽各存一份差量」。任何画像都按视口宽切档（固定大屏也切），差别只在能改什么，见下方「固定画布下的设备差量」。

档位	默认条件	用途
大屏 LARGE	窗口宽 > 1279	基线：所有配置的本体
平板 MEDIUM	768 ~ 1279	相对大屏的差量覆盖
手机 SMALL	≤ 767	相对大屏的差量覆盖

大屏是基线：你在大屏档改的配置是「本体」（写进 options）；
中 / 小屏只存差量（sizeModeOverrides.MEDIUM/SMALL）：切到平板 / 手机档改某项，只记录「相对大屏的不同」；
编辑器顶部「尺寸模式条」切换当前编辑档位；
device-visible 配合断点做按设备显隐（被某档隐藏的组件仍留在图层树，方便恢复）；
断点可在工程级改：project.settings.sizeModes.breakpoints（默认 { small: 767, medium: 1279 }）；
settings.sizeModes.widths / heights 是编辑态预览画布尺寸（widths 默认 LARGE 0=用设计尺寸、MEDIUM 1024、SMALL 375；heights 缺省 = 自动沿用基线高），只影响编辑器里的模拟视口，不是断点；
settings.layoutDefaults.geometryUnit 决定新拖入组件的默认几何单位（选「百分比自适应」画像时自动写为 percent）。

页面的「结构性」设置恒走基线、不能只在手机变：fullscreen-mode、fill-auto-expand、layout-profile、screen-overflow、size。（fill-auto-expand 与 fullscreen-mode 是一组：若它按设备存差量，在窄窗口下打开自动填充、窗口一变宽档位回到大屏就会失效。）

设备差量只在编辑态产生

按设备存差量是编辑器里「切到手机档、改出一份差量」的产物。运行态的写入——SDK 句柄 setOption / setOptions、代码面板脚本、交互动作——语义是「把当前值改成这个」，一律写基线，因此不会随视口跨档失效。

否则会出现这种现象：在窄窗口（手机档）里脚本改好了文案和样式，窗口一拉宽档位回到大屏，组件整批退回创建时的样子。发布页 / SDK 内嵌下，运行态写入还会顺手清掉同路径的旧设备差量，保证脚本写的值当场生效；编辑器（含预览）不清，避免抹掉你配好的差量。

固定画布下的设备差量

固定大屏（等比缩放 / 等比铺满 / 裁切…）在手机上同样需要「藏掉次要面板、放大字号、三列变一列」，所以设备档位对它照常生效，但组件自身的 position / size 恒走基线：几何由「整屏缩放 + 锚点 / 自动填充」独占，不再叠加一份每设备的 px 盒。可以按设备改的例如：device-visible、字号与配色、容器的 grid-columns / fluid-wrap / container-layout、文案、数据筛选条件。

两种模式下的差别：

	响应式页面	固定画布页面
档位切换	按视口宽	按视口宽（同样生效）
编辑器画布	按该档预览宽 × 高收窄回流	保持设计尺寸（画布尺寸就是设计基准，不收窄）
可存差量	任意属性，含 position / size	除 `position` / `size` 之外的属性

手机上要完全另一套排布怎么办

固定画布下改不了每设备的位置尺寸。真要做一套独立的手机版，新建一个「百分比自适应」或「流式 · 长页」的页面，再按需跳转——那类画像本来就是为随窗口改尺寸设计的。

在线演示

① 静态布局（绝对定位）：每个组件用 position / size 钉在画布坐标上，可重叠：

② 流式布局（fluid）：子组件不写坐标，按流自动排布、放不下换行（卡片墙）：

③ 停靠骨架（layout-dock）：顶栏 + 左右侧栏 + 底栏 + 主区，拖分隔条可调（运行态 resizable）：

场景 → 配方速查

你要的效果	画像	全屏适配	内部布局	关键设置
指挥中心投屏（不变形、完整）	固定大屏	等比缩放	静态	填充色设品牌深色；内容排满画布
铺满且不变形（接受内容靠左上）	固定大屏	等比铺满	静态	空白由页面背景补满；背景设深色 / 图
铺满、不变形、还不留空	固定大屏	等比铺满	静态 / 布局容器	新建选「示例 · CAD 图纸 / 互联网地图 / 组态监控台 / 三维巡检」或骨架「示例 · 等比铺满」；或主视觉配 `left-right` × `top-bottom` 锚点 / 开 `fill-auto-expand`
单屏必须铺满（接受变形）	固定大屏	拉伸	静态	画布按目标屏比例；背景填充也设拉伸
背景 / 地图铺满（接受裁边）	固定大屏	铺满裁切	静态	地图放最底层、覆盖整屏
竖屏长页门户	固定大屏	宽度铺满	静态 / 流式	画布竖长（1080×1920）
地图为底 + 悬浮面板（自适应）	百分比自适应	响应式	静态	锚点或百分比单位
自由摆放、任意窗口铺满	百分比自适应	响应式	静态	顶层组件单位设 percent；面板开内容自适应缩放
卡片墙（窄屏换行）	流式	响应式	流式	横排 + 换行；卡片宽 `px`
报表 / 运营长页	流式	响应式	流式	竖排 + `nowrap`；页面溢出 `scroll-y`

工程 JSON 字段速查

面向直接读写工程文件或二次开发者。日常在编辑器里调即可，无需手写。

// 页面 screen.options
{
  "layout-profile": "canvas-scale",     // canvas-scale | canvas-percent | flow-fluid
  "size": [1920, 1080],
  "fullscreen-mode": "scaling",         // scaling|fill-uniform|adaptive|stretch|responsive|fit-width|fit-height|original
  "fullscreen-fill-color": "#04111d",   // 留边填充色（代码默认 #000000，此处为品牌深色示例）
  "fill-auto-expand": false,            // 仅 fill-uniform / responsive：把无锚点的主视觉拉满剩余画布
  "container-layout": "static",         // 页面：static | fluid（组件容器另有 grid）
  "screen-overflow": "hidden"           // 响应式长页用 scroll-y / scroll-x
}

// 组件 widget.options（静态子项 + 外壳通用几何）
{ "position": [100, 80], "size": [400, 300],
  "geometry-unit": "px",                // px | percent
  "responsive-x": "left", "responsive-y": "top",
  "canvas-grow": "reflow",              // 仅容器：reflow 吃满剩余空间(子项重排) | scale 保持设计比例
  "device-visible": true,
  "rotate": [0, 0, 15],                 // [x,y,z] 三轴角度（°）
  "opacity": 80,                        // 不透明度 0-100
  "no-events": false }                  // 鼠标穿透，仅播放态生效；节点级另有 enabled / locked（与 options 平级）
                                        // 注：组件基类无通用阴影 / 混合模式 / 进出场动画键

// 组件 widget.options（流式子项）
{ "fluid-width-type": "adaptive", "fluid-width-minmax": [320, 0],
  "fluid-height-type": "px", "fluid-height-px": 120 }

// 组件容器 options（栅格容器）与其子项
{ "container-layout": "grid",
  "grid-columns": 12, "grid-rows": 2, "grid-col-gap": 8, "grid-row-gap": 8,
  "grid-padding": [0, 0, 0, 0],         // 栅格内边距（注意不是 padding）
  "grid-col-weights": "1,2,1" }         // 逗号权重；空 = 等分
{ "grid-col-span": 4, "grid-row-span": 1,
  "grid-col-start": 0 }                 // 0 = 自动流式；填 1 起算的起始线

// 节点上的设备差量（与 options 平级）
// 固定画布页里 position / size 不进这些桶（写了也不生效），几何走整屏缩放 + 锚点
{ "sizeModeOverrides": {
    "MEDIUM": { "grid-columns": 6 },
    "SMALL":  { "container-layout": "fluid", "device-visible": false } } }

延伸阅读：架构原理（画布如何被加载渲染）· 组件手册 · 容器布局（行 / 列 / 网格 / 侧边栏等布局控件）· 窗口系统（浮层画布）。