跳到主要内容

创建 Page 与 Component

Page 是操作员最终看到的 HMI 画面，文件扩展名为 .qp。Component 是 App 内可复用的视觉模块，文件扩展名为 .qpc。两者都可以在 Design / Preview / Source 之间切换。

什么时候使用哪一种​

需求使用
登录后首先打开的首页、设备总览、报警或工艺参数画面Page (.qp)
多个 Page 都要复用的状态卡、按钮组或工位区域Component (.qpc)
已由功能包提供的通用视觉能力Package Component
只在某个 Page 中出现的一小段布局直接放在该 Page 中

Component 不会单独成为运行入口；Page 可以在 Resources → Pages 中设为首页或通过导航打开。

从哪里开始​

  1. 在左侧 Resources → Pages 的右键菜单中选择新建页面。
  2. 输入清晰、稳定且不重复的名称，例如 overview 或 station-detail。
  3. 需要复用内容时，在 Components 分组中新建 Component。
  4. 在 Design 中组合视觉元素，在 Source 中处理精确逻辑和样式。
  5. 保存后先用 Design 检查页面，再执行 Build 和完整运行验收。

新建 Page 时可以同时选择画布尺寸和背景色。背景默认是白色；启用跟随主题后，模板不会写入背景样式，页面将使用当前主题或宿主表面的背景。

在 Page 的右键菜单中选择设为首页，可决定 Runtime 根页面和 Player 默认打开哪个 Page。

更快找到 Component​

Design 左侧 Palette 会把 App 自定义 Component 和所有已安装功能包的 Component 放在同一个目录中，并默认按用途分类。每个条目同时显示来源；点击筛选按钮后，可按类别、来源和 tag 组合筛选。搜索不仅匹配 Component 名称，也匹配简介、类别、tag、功能包 id 和目录，因此可以直接搜索“表单”“日期”“grid”或“Fluent UI”。输入搜索词或启用筛选后，Palette 会切换为一层结果列表，避免在多层目录中反复展开。

类别和 tag 来自各 Component 的声明，不根据名称猜测。未声明类别的 App Component 会明确出现在“未分类”中；如需为自定义 Component 添加分类和 tag，请参阅高级：页面源码开发。

使用 Siemens iX 完整组件​

需要完整的工业应用外壳、导航、表单、日期时间、反馈、数据展示、Chat、Upload 和 Grid 时，安装主包；需要图表时再安装独立图表包：

theseus package add theseus.ix@1.0.0
theseus package add theseus.ix-charts@1.0.1

theseus.ix 公开 iX 5.2.1 的全部 121 个 Web Component、完整 iX Icons 和 iX 风格的 AG Grid Community。theseus.ix-charts 提供通用 ECharts 入口以及折线、面积、趋势、柱状、饼图、环图、仪表盘和散点图。两者都把浏览器依赖编译进功能包，App 不需要 npm 或 node_modules。

<script lang="ts">
  import IxApplication from "@theseus/ix/IxApplication";
  import IxApplicationHeader from "@theseus/ix/IxApplicationHeader";
  import IxContent from "@theseus/ix/IxContent";
  import IxDatePicker from "@theseus/ix/IxDatePicker";
  import IxMenu from "@theseus/ix/IxMenu";
  import IxTheme from "@theseus/ix/IxTheme";
</script>

<IxTheme colorSchema="light">
  <IxApplication theme="classic" colorSchema="light">
    <IxApplicationHeader slot="application-header" name="Production" />
    <IxMenu slot="menu" />
    <IxContent><IxDatePicker singleSelection /></IxContent>
  </IxApplication>
</IxTheme>

每个 iX tag 使用对应的 PascalCase 导出，例如 ix-date-picker 对应 IxDatePicker。默认文字、内部元素和命名 slot 都可在 Inspector 的内容分组中直接编写；命名 slot 通过子元素的 slot 属性传入。需要调用 iX 元素的公开方法时使用 bind:element={引用}；element 是底层元素实例句柄，不是可填写的字符串属性。发布包只带上游 iX Classic light/dark 及其中内嵌的资源，不另带 Siemens Corporate Brand Theme 或专有字体文件；Siemens 名称和商标的使用仍须遵守相应权利要求。

使用 Fluent UI Web Components​

需要 Fluent 2 风格的基础控件时，安装 Fluent UI 包：

theseus package add theseus.fluent-ui@1.0.0

theseus.fluent-ui 覆盖 @fluentui/web-components 3.1.3 实际发布的全部 42 个 Custom Element，并提供用于浅色、深色、跟随系统和自定义 token 的 FluentTheme。浏览器运行依赖已全部编译进功能包，App 不需要 npm 或 node_modules。这个包不包含 React 组件、独立 Fluent 图标库，以及上游该版本尚未发布的 Combobox 和 SplitButton。

<script lang="ts">
  import FluentButton from "@theseus/fluent-ui/FluentButton";
  import FluentTextInput from "@theseus/fluent-ui/FluentTextInput";
  import FluentTheme from "@theseus/fluent-ui/FluentTheme";

  let name = $state("");
</script>

<FluentTheme appearance="system">
  <FluentTextInput bind:value={name} placeholder="Name" />
  <FluentButton appearance="primary" onclick={() => console.log(name)}>
    Submit
  </FluentButton>
</FluentTheme>

每个 Fluent tag 使用对应的 PascalCase 导出，例如 fluent-text-input 对应 FluentTextInput。默认内容和命名 slot 都可以直接组合，命名 slot 通过子元素的 slot 属性传入；常用输入事件可直接使用 oninput、onchange、onclick 等属性。需要调用底层 Custom Element 的公开方法时，使用 bind:element={引用}。

Design、Preview 和 Source​

模式用途
Design编辑几何、属性、样式和事件；按住 Alt 可操作页面内的本地控件
Preview直接操作页面；真实调用需要 Run / Debug，失败写入 Console
Source编辑页面结构、样式、本地状态和事件逻辑

Design 不执行 Runtime Object 或 Query。Object 方法返回明确的类型化设计值，Query 返回状态 0（未执行），不输出跳过调用日志。预览可直接操作页面；Stopped 时 Object / Query 调用被拒绝并在 Console 报错，Run / Debug 初始化完成后才可真实调用。预览不会自动 Build、Deploy 或启动 Runtime。完整设备行为仍需在运行页验收。

应用中心的 Design 可直接操作本地控件，并支持缩放、平移和适应视图；编辑器 Design 默认保留选择与编辑。两者使用本地工程资源，不依赖目标部署。页面在挂载并完成首次适配后显示。

设计一个 Page​

1. 先确定信息层级​

先回答操作员最常问的三件事：现在是什么状态、下一步能做什么、失败后怎么恢复。把主状态和主要动作放在首屏；诊断细节和低频设置放在次级区域或独立 Page。

2. 用 Design 完成视觉结构​

  • 从 Palette 拖入已安装功能包提供的 Component，或 App 自己的 .qpc；
  • 选中元素后在右侧 Inspector 调整 Geometry、Layout、Spacing、Typography、Appearance、事件和绑定；
  • 使用多选、对齐和分布工具保持间距一致；
  • 双击 App Component 实例可进入对应 .qpc，嵌套 Component 也可以继续打开；
  • 用撤销 / 重做检查每次可视修改；保存后继续验证本地交互。

数组生成的重复元素也可以分别悬停、点击选择，按住 Shift、Cmd（macOS）或 Ctrl（Windows / Linux）追加或取消选择，也可以框选多个。它们仍共享同一份模板：属性修改和删除会影响这组重复元素；不能通过多选给同一模板写入互相冲突的位置或尺寸。

Page 只有一个顶层视觉根。普通画布通常让根拥有页面尺寸和背景，再由根组织内部元素。不要依赖编辑器缩放判断真实尺寸；Design 和运行页都会按页面自己的 CSS 布局。

运行页和 Player 会将完整页面等比缩放到窗口内的最大尺寸，不额外留边：至少一组对边贴合窗口，另一方向居中，不裁切或拉伸。窗口大小变化后会自动重新适配。页面尺寸由根元素决定，内部滚动区域仍按页面自己的布局工作；Design 的手动缩放比例不会带入运行页。

3. 用 Component 复用一致行为​

把重复出现并且需要统一维护的视觉单元提取为 Component。为它定义清晰的输入、用户动作和默认样式，再在多个 Page 中复用。角色控制位于 Inspector 的权限分组；账号切换入口应保持可访问，界面隐藏也不能替代敏感操作的实际授权。

普通复用工作可以在 Design 和 Inspector 中完成。需要直接编写 Component 输入、事件、根元素或权限转发时，再进入高级：页面源码开发。

连接 App 能力​

Object 与 QG​

Page 可以调用当前 App 已配置的 Object。使用 Source 补全选择精确实例和方法，不要在页面里复制设备地址或协议细节。设备步骤、等待、超时和恢复分支应由 QG 或业务能力负责；Page 只发起意图并显示结果。

Design 不执行真实 Object 调用。Start 和 Debug 的调用取决于当前运行目标及其状态，所以至少要验收正常返回、超时 / 故障和重复操作三条路径。

Query、Variable 与导航​

在 Settings 中集中维护 App 级 Query、Variable 和导航，再通过页面绑定或已配置的能力使用它们。外部服务地址和认证不要在多个 Page 中重复配置；需要跨重启保存的业务值应使用项目认可的持久能力，而不是页面临时状态。

多语言​

在 Settings → 多语言（I18n） 中维护语言和消息，并在 Page 中使用对应文案。交付前至少检查默认语言、切换后的布局、长文案截断和缺失消息。

图片与 3D 模型​

把图片、字体、GLB / GLTF 和其他只读素材放入 assets/**，并使用工作区根相对路径，例如 assets/logo.png 或 assets/models/cell.glb。同一条路径可在 Design 和 Runtime 中使用。运行期可变数据不能写回 assets/**。

当前 App user​

页面中受角色控制内容的操作员身份由 App user 表示。需要显示当前操作员或提供账号切换时，加入 CurrentUser Component，并确保它不被放进自身可能隐藏的受限区域。完整配置见应用用户、角色与运行页登录；源码用法放在高级：页面源码开发。

从编辑到运行的推荐顺序​

  1. 在 Design 和 Source 中完成修改并保存。
  2. 查看当前文件的实时标记，修复明显的页面源码和类型问题。
  3. 打开 Design，检查视觉、输入、导航和无设备副作用的交互。
  4. Stop 当前运行实例，再执行 Build；在 Problems 中修复本次构建错误。
  5. 用 Start 验收正常运行，或用 Debug 验收断点和故障路径。
  6. 从 Runtime 根页面或 Player 检查首页、登录、分辨率和长时间运行行为。

实时编辑器标记与 Problems 不是同一份结果：前者跟随当前打开文档，Problems 只保留最近一次 Build 对已保存工程文件的诊断。

某个 Object 类型不可用时，相关引用会显示错误，但不影响其他 Page 的设计与编辑。Design 中组件渲染失败会在该组件位置显示错误，其余布局仍可编辑；如果失败发生在页面初始化中，则显示页面错误。修复所有 Object 错误后才能通过 Build。

验收清单​

  • Page 名称唯一，首页指向存在的 .qp；
  • Design 和 Runtime 的尺寸、文字、颜色和交互一致；
  • .qpc 在不同 Page 中复用时，props、事件和样式都符合预期；
  • 键盘操作、焦点、对比度、触控尺寸和不同语言已检查；
  • 素材使用 assets/... 路径，在目标环境没有缺失；
  • Object 调用显示加载、成功、失败和恢复状态，不会把故障伪装成正常结果；
  • CurrentUser 显示的是 App user，角色分支在真实运行页中验收；
  • Build 成功后，Start / Debug 和 Player 使用的是同一已部署版本。

常见问题​

在线文档或旧工程仍出现其他页面扩展名​

当前 Page 只使用 .qp，可复用 Component 只使用 .qpc。不要创建兼容副本或按旧格式继续编写；应把内容迁移到当前文件并更新所有引用。

运行页内容旧或提示需要 Build​

保存源码，核对当前目标，Stop 后 Build，再 Start / Debug。Design 使用 工程源码，运行页使用已部署版本。

Design 中 Object 方法没有执行​

这是预期行为。Design 不执行 Object / Query，也不输出跳过调用日志。需要真实业务验证时，明确 Start / Debug 后使用预览或运行页。