页面源码开发
大多数页面工作可以在 Design、Inspector 和 AI Command Center 中完成，不需要先学习前端框架。只有在需要精确状态逻辑、自定义事件、复杂样式或可复用 Component 时，才需要进入 Source。
源码技术
Page (.qp) 与 Component (.qpc) 使用 Svelte 5 源码，并支持标准 HTML、CSS 和 TypeScript。Design 与 Source 编辑的是同一份页面内容：在任一模式保存后，另一种模式会读取相同结果。
常见源码能力包括：
- 用
$state保存当前 Page 实例的临时界面状态； - 用 TypeScript 函数处理页面事件；
- 用 props、事件或 callback 连接 Page 与 Component；
- 从
.qp或.qpc通过相对路径导入 App Component； - 使用
@theseus/qp-core与已安装功能包公开的 Component。
<script lang="ts">
let running = $state(false);
function toggleRunning() {
running = !running;
}
</script>
<button onclick={toggleRunning}>
{running ? "停止模拟" : "开始模拟"}
</button>
Component 根与权限
App 自定义 .qpc 以 @theseus/qp-core/Widget 作为唯一可测量根，通过 props 接收业务值，通过事件或 callback 把用户动作交给 Page，并转发 class、style、必要的 DOM 属性、requiredRoles 和 unauthorized。
角色列表为空时所有人可见；多个角色按任意匹配，App Admin 始终匹配。未匹配时，hidden 隐藏整个根，disabled 保留显示但禁止交互。原生 HTML 元素不直接拥有这些 Component 权限属性。界面显示规则不能替代 Object、Query、文件或 Safety 能力自己的授权。
从 .qp 或另一个 .qpc 使用相对路径导入 App Component。功能包 Component 使用其公开模块路径；不要复制功能包内部源码。
使用 App 能力
页面源码通过 getApp() 使用 App 级 Query、Variable 和导航。外部服务地址和认证仍应集中放在 Settings → 查询，不要散落到多个 Page。多语言文案通过 @qx/i18n 使用；语言和消息仍在 Settings → 多语言（I18n） 中维护。
需要显示或切换当前操作员时，使用 CurrentUser，并把它放在不会被自身角色规则隐藏的位置：
<script lang="ts">
import CurrentUser from "@theseus/qp-core/CurrentUser";
import { m } from "@qx/i18n";
</script>
<CurrentUser signedOutLabel={m.not_signed_in()} />
CurrentUser 只管理 App user，不会切换 Qixin 账号或运行目标账户。
工程边界
- 页面事件只负责界面协调；设备步骤、等待、超时、恢复和安全联锁应放在 Object、QG 或经过审核的 Provider 中。
$state属于当前页面实例，刷新或重新进入页面后会重置。耐久数据应使用明确的 App 或 Object 存储能力。- App 只能使用已安装功能包公开的模块，不要引入项目未管理的外部依赖或复制功能包内部源码。
- 实时标记跟随当前打开文档；Problems 保存最近一次 Build 对已保存工程文件的诊断。交付前必须保存、Build，并在真实运行页或 Player 中验收。