WebBuilder 组件— viewport 视口容器

组件类名：Wb.Viewport　所属分组：General　继承链：Component → Container → Panel → Viewport

1. 组件概述

viewport 是全屏 Panel 组件，是一个模块（xwl 文件）的界面根容器。每个需要显示界面的模块通常包含且仅需一个 viewport，直接添加到 module 根节点下，代表模块内的全屏容器。它继承 Panel 的全部能力（标题栏、tbar/bbar 工具栏等），但典型用途是作为整个页面的布局骨架，通过 layout 属性组织子组件。

2. 常用属性

布局的实现机制：layout 属性最终在容器 bodyEl 元素上设置 cls 样式类，完全由 CSS 完成，性能开销极低。

3. 典型布局模式（IDE 实用配置）

• 全屏型：viewport layout=fit，子组件（如 grid）自动填满整个视口；
• 左侧栏 + 客户区：layout=row，左侧 tree 设 width=20em，右侧 grid 设 flex=1；
• 底部栏 + 客户区：layout=column，上部 grid 设 flex=1，底部 panel 设 height=20em；
• 表单型：layout=form1，直接放置多个编辑控件，自动形成规范的单列表单；
• 组合嵌套：容器可无限嵌套，实现上述模式的任意组合。

4. 常用方法与事件

JAVASCRIPT复制

// 向 viewport 动态添加子组件（注意：必须扁平配置，不能嵌套 properties）
app.viewport1.add({cname: 'grid', url: 'myapp/select-staff.xwl'});

// 获取子组件、切换可见性
const grid = app.viewport1.findItem(true, 'grid1');
grid.visible = false;

// 工具栏按钮的 click 事件中刷新数据
app.grid1.reload();

组件就绪后执行的初始化代码放在 ready 事件中；事件处理函数中通过 app.<组件 cid> 访问模块内任意组件。

5. 注意事项

1. viewport 必须挂在 module 根节点，不能嵌套在其他容器内；
2. 依赖容器尺寸的操作（如画布 zoomToFit、图表 resize）必须在容器完成布局后执行——在 finalize 阶段容器可能仍是 0×0，需要延迟或轮询等待；
3. 动态 add() 时使用扁平配置对象（{cname, text, value...}），XWL 源码中的 properties:/events: 嵌套块是解析期专用语法，运行时传入会被丢弃；
4. 工具栏属性键名固定为 tbar/bbar，使用自定义键名整个工具栏不会被创建。

6. 示例参考

平台示例：example/basic/layout.xwl（布局）、example/crud/staff.xwl（viewport + grid 标准 CRUD 页面结构）。