创建 Page 与 Component
Page 是操作员最终看到的 HMI 画面，文件扩展名为 .qp。Component 是 App 内可复用的视觉模块，文件扩展名为 .qpc。两者都可以在 Design / Preview / Source 之间切换。
什么时候使用哪一种
| 需求 | 使用 |
|---|---|
| 登录后首先打开的首页、设备总览、报警或配方画面 | Page (.qp) |
| 多个 Page 都要复用的状态卡、按钮组或工位区域 | Component (.qpc) |
| 已由功能包提供的通用视觉能力 | Package Component |
| 只在某个 Page 中出现的一小段布局 | 直接放在该 Page 中 |
Component 不会单独成为运行入口；Page 可以在 Resources → Pages 中设为首页或通过导航打开。
从哪里开始
- 在左侧 Resources → Pages 的右键菜单中选择新建页面。
- 输入清晰、稳定且不重复的名称，例如
overview或station-detail。 - 需要复用内容时，在 Components 分组中新建 Component。
- 在 Design 中组合视觉元素，在 Source 中处理精确逻辑和样式。
- 保存后先用 Preview 检查页面，再执行 Build 和完整运行验收。
在 Page 的右键菜单中选择设为首页，可决定 Runtime 根页面和 Player 默认打开哪个 Page。
Design、Preview 和 Source 的区别
| 模式 | 适合做什么 | 不会做什么 |
|---|---|---|
| Design | 拖入 Component、调整几何、属性、样式和事件，查看不同内容尺寸 | 不会执行真实 Object 调用，也不会替代运行验收 |
| Preview | 在编辑器内检查布局、输入、导航、动画和真实数据绑定 | 不会 Build、Deploy 或 Start，也不会采用未保存草稿 |
| Source | 编辑页面结构、样式、状态和复杂事件逻辑 | 不会自动更新已部署版本 |
Preview 使用当前绑定 Runtime target 上已部署的 App。目标已有同一 App 的 Previewing 实例时会复用；否则从 Stopped 按需进入 Previewing。Running 或 Debugging 不会被 Preview 复用，必须先 Stop。目标上没有当前 App 的部署时，Preview 会要求先 Build。
Preview 中的真实 Object 调用会到达当前 Runtime target。连接设备后，Preview 不是无副作用的静态画布；输出、运动和生产动作必须按现场测试流程授权和验收。
设计一个 Page
1. 先确定信息层级
先回答操作员最常问的三件事：现在是什么状态、下一步能做什么、失败后怎么恢复。把主状态和主要动作放在首屏；诊断细节和低频设置放在次级区域或独立 Page。
2. 用 Design 完成视觉结构
- 从 Palette 拖入已安装功能包提供的 Component，或 App 自己的
.qpc； - 选中元素后在右侧 Inspector 调整 Geometry、Layout、Spacing、Typography、Appearance、事件和绑定；
- 使用多选、对齐和分布工具保持间距一致；
- 双击 App Component 实例可进入对应
.qpc，嵌套 Component 也可以继续打开； - 用撤销 / 重做检查每次可视修改；保存后再切换 Preview。
Page 只有一个顶层视觉根。普通画布通常让根拥有页面尺寸和背景，再由根组织内部元素。不要依赖编辑器缩放判断真实尺寸；Design、Preview 和运行页都会按页面自己的 CSS 布局。
3. 用 Component 复用一致行为
把重复出现并且需要统一维护的视觉单元提取为 Component。为它定义清晰的输入、用户动作和默认样式，再在多个 Page 中复用。角色控制位于 Inspector 的权限分组；账号切换入口应保持可访问，界面隐藏也不能替代敏感操作的实际授权。
普通复用工作可以在 Design 和 Inspector 中完成。需要直接编写 Component 输入、事件、根元素或权限转发时，再进入高级：页面源码开发。
连接 App 能力
Object 与 QG
Page 可以调用当前 App 已配置的 Object。使用 Source 补全选择精确实例和方法，不要在页面里复制设备地址或协议细节。设备步骤、等待、超时和恢复分支应由 QG 或业务能力负责；Page 只发起意图并显示结果。
Design 不执行真实 Object 调用。Preview、Start 和 Debug 的调用取决于当前运行目标及其状态，所以至少要验收正常返回、超时 / 故障和重复操作三条路径。
Query、Variable 与导航
在 Settings 中集中维护 App 级 Query、Variable 和导航，再通过页面绑定或已配置的能力使用它们。外部服务地址和认证不要在多个 Page 中重复配置；需要跨重启保存的业务值应使用项目认可的持久能力，而不是页面临时状态。
多语言
在 Settings → 多语言（I18n） 中维护语言和消息，并在 Page 中使用对应文案。交付前至少检查默认语言、切换后的布局、长文案截断和缺失消息。
图片与 3D 模型
把图片、字体、GLB / GLTF 和其他只读素材放入 assets/**，并使用工作区根相对路径，例如 assets/logo.png 或 assets/models/cell.glb。同一条路径可在 Design、Preview 和 Runtime 中使用。运行期可变数据不能写回 assets/**。
当前 App user
页面中受角色控制内容的操作员身份由 App user 表示。需要显示当前操作员或提供账号切换时，加入 CurrentUser Component，并确保它不被放进自身可能隐藏的受限区域。完整配置见应用用户、角色与运行页登录；源码用法放在高级：页面源码开发。
从编辑到运行的推荐顺序
- 在 Design 和 Source 中完成修改并保存。
- 查看当前文件的实时标记，修复明显的页面源码和类型问题。
- 打开 Preview，检查视觉、输入、导航和无设备副作用的交互。
- Stop 当前运行实例，再执行 Build；在 Problems 中修复本次构建错误。
- 用 Start 验收正常运行，或用 Debug 验收断点和故障路径。
- 从 Runtime 根页面或 Player 检查首页、登录、分辨率和长时间运行行为。
实时编辑器标记与 Problems 不是同一份结果：前者跟随当前打开文档，Problems 只保留最近一次 Build 对已保存工程文件的诊断。
验收清单
- Page 名称唯一，首页指向存在的
.qp； - Design、Preview 和 Runtime 的尺寸、文字、颜色和交互一致；
.qpc在不同 Page 中复用时，props、事件和样式都符合预期；- 键盘操作、焦点、对比度、触控尺寸和不同语言已检查；
- 素材使用
assets/...路径，在目标环境没有缺失； - Object 调用显示加载、成功、失败和恢复状态，不会把故障伪装成正常结果；
CurrentUser显示的是 App user，角色分支在真实运行页中验收；- Build 成功后，Start / Debug 和 Player 使用的是同一已部署版本。
常见问题
在线文档或旧工程仍出现其他页面扩展名
当前 Page 只使用 .qp，可复用 Component 只使用 .qpc。不要创建兼容副本或按旧格式继续编写；应把内容迁移到当前文件并更新所有引用。
Preview 提示需要 Build
当前 Runtime target 没有这个 App 的可用部署。保存修改，确认运行实例已停止，再执行 Build。Preview 不会自行 Build 或 Deploy。
Preview 与运行页显示的还是旧内容
先确认编辑器标签没有未保存标记，再检查 Build 是否成功以及当前选中的 Runtime target。Preview、Start 和 Debug 都不会读取未保存草稿。
Design 能看到内容，但 Object 操作没有反应
Design 不执行真实 Object 调用。切换 Preview，并确认目标已部署当前 App、Object 配置有效且调用不会造成未授权的现场动作。
Component 在画布中无法正确缩放或套用样式
先检查 Component 根布局、宽高约束和外部样式是否冲突。需要检查源码根元素或属性转发时，参见高级：页面源码开发。
图片或模型在目标上缺失
确认文件位于 assets/**，源码使用 assets/... 正斜杠路径，并重新 Build。不要引用开发机绝对路径或编辑器临时 URL。