数据与集成
先回答三个问题：数据由谁拥有、需要保存多久、是否要跨设备共享。再选择能力。这样可以避免把临时状态、配方、生产记录和外部系统数据塞进同一个位置。
快速选择
| 需求 | 使用能力 | 典型例子 |
|---|---|---|
| 当前运行期间共享一个小值 | App Variable | 当前工单、运行模式、临时结果 |
| Runtime target 重启后仍保留一个小值 | Saved Variable | 标定值、阈值、累计计数 |
| 只在一个 QG 运行实例中使用 | QG state | 循环索引、中间判断 |
| 按名称保存并切换一组参数 | Recipe | 产品型号、温度和压力组合 |
| 在一台目标机上维护轻量多行数据 | TableStore | 点位表、物料表、批次行 |
| 读取或写入外部业务系统 | HTTP Query | MES 工单、ERP 配方、生产报工 |
| 切换运行页语言 | i18n | 按钮、报警和状态文案 |
| 随 App 交付只读文件 | Asset | 图片、视频、3D 模型、只读模板 |
大量历史、复杂检索或多台设备共享的数据，应由外部数据库或业务系统负责，再通过 Query 访问。
Variable：小型状态
| 类型 | 生命周期 | 使用提醒 |
|---|---|---|
| App Variable | 当前运行实例 | 重新启动或重新交付后从定义的初始值开始 |
| Saved Variable | 当前 Runtime target 上的 App 状态 | 重启后保留；切换到另一台目标机不会自动迁移当前值 |
| QG state | 当前 QG 实例 | 顶层 let 适合临时状态；需要保留的值使用 QG.saved |
Page 源码通过 getApp().variables 使用 App Variable。需要改变某个设备或业务对象的状态时，应调用该 Object 的方法，不要再复制一份 Variable 作为第二个真相源。
验收时至少检查：初始值、正常修改、重新启动后的值，以及切换 Runtime target 后是否符合预期。
Recipe：成套参数
Recipe 适合字段固定、需要整体命名、保存和切换的工艺参数组。
- 在 App Settings → Recipes 定义字段和默认值。
- 在 Objects 中确认 App 有可用的
RecipeManager。 - 在 Page 或 QG 中明确“选择、应用、保存”的时机。
- 用测试配方验证缺失字段、非法范围、切换和重新打开。
Recipe 不是历史数据库。批次记录、审计数据或跨设备共享应进入外部系统。
TableStore：目标机上的轻量表格
TableStore 适合一台 Runtime target 上的有限行数据。
- 在 Settings → 功能包安装
Table Store。 - 在 Objects 中添加
TableStore。 - 在 Properties 配置列、主键、格式和最大行数。
- 用 Page 或 QG 验证新增、读取、修改、删除和清空。
主键应稳定且唯一。格式可使用 csv 或现代 Excel .xlsx。如果数据量、查询复杂度或共享范围持续增长，改用外部系统和 Query。
HTTP Query：复用外部调用
在 App Settings → Queries 集中维护 HTTP 调用。Page 和 QG 应复用同一个 Query，不要各自保存 URL 和认证配置。
可配置内容包括：
GET、POST、PUT、DELETE或PATCH；- URL 及
{{parameter}}运行参数； - Headers、URL Params 和 JSON、Form 或 Raw Body；
- None、Bearer 或 Basic Auth；
- Timeout。
Page 事件处理器可调用 getApp().queries.<name>.run(...)；QG 使用对应的 Query 能力。
先用测试环境和无副作用请求执行 Send，再验证超时、认证失败、无效响应和重复提交。生产写入必须定义幂等或防重复策略，并由责任人确认。
Query 中的 token、用户名和密码属于 App 配置。不要把生产凭据提交到不受控 Git、工程副本或普通 AI 对话。交付前按项目的凭据策略检查并替换。
i18n：一份页面，多种语言
- 在 **App Settings → 多语言（I18n）**定义支持语言和默认语言。
- 使用稳定的
lower_snake_case消息 ID，不要在源码中动态拼接 ID。 - Page 和 Component 复用同一套消息，不为每种语言复制源码。
- 在运行页切换语言，检查变量替换、长文本布局和缺失翻译的回退结果。
Page 源码通过 @qx/i18n 使用消息和 locale。翻译文本应在界面渲染时求值，避免在模块加载时缓存成不会更新的字符串。
Asset：随版本交付的只读内容
- 把图片、视频、模型和模板放在
assets/下。 - Page、Component 和 CSS 使用工作区根相对路径
assets/...，统一使用/。 - 不要使用开发机绝对路径，也不要依赖文件名大小写差异。
- Asset 随 Build 交付，是只读内容；报告、上传文件或其他运行时可变数据应由明确的 Object/Provider 能力管理。
在 Design、Preview 和实际运行页中分别检查关键 Asset，尤其是远程 Runtime target。
交付前验收
- 在 Settings 或 Object Properties 确认名称、类型、默认值、字段和参数。
- 保存并执行 Build，处理 Page 或 QG 引用错误。
- 在正确的 Runtime target 上验证重启、失败和恢复路径。
- 对 Query 使用测试账号和可撤销数据完成第一次写入。
- 切换语言并检查长文本；检查远程运行页中的 Asset。
- 记录哪些数据会随项目版本交付，哪些只保留在某台目标机或外部系统。
Build 菜单中的清理只清除本机当前项目的 Build 结果，不会删除项目源码，也不会清除目标机上的 Saved Variable、TableStore、Vision 或其他运行数据。数据重置和迁移必须使用对应能力提供的明确操作。
常见选择错误
| 现象 | 更合适的做法 |
|---|---|
| 用 Variable 保存大量历史 | 外部数据库或 TableStore；跨设备时优先外部系统 |
| 用 TableStore 充当共享业务数据库 | 通过 Query 调用 MES、ERP 或数据库服务 |
| 把生产凭据写进 Page | 放到集中 Query 配置，并按交付流程替换和审查 |
| 用 Asset 保存运行时上传文件 | 由明确的 Object/Provider 能力管理可变数据 |
| 只在编辑器中检查数据能力 | Build 后在正确目标上验证重启、错误和权限 |