自写页 SDK：在受控范围内开发项目页面

1. 自写页 SDK 负责什么

SDK 负责把宿主机中的受控数据能力交给自写 HTML 页面。它提供实时 Tag 快照、Tag 订阅、写入、历史查询、报警查询、报警订阅、多语言和表格辅助方法。SDK 提供数据能力和权限边界，不限定页面形态；项目页面可以按现场需要组织为报表、看板、诊断页、质量页、能耗页或客户专用页面。

• 适合：班次产量报表、能耗日报、设备健康页、质量追溯页、工单看板、客户展示页。
• 页面形式：普通 HTML，可包含独立 CSS、JavaScript、图表库和组件逻辑。
• 数据来源：声明范围内的 Tag、历史数据、报警数据和语言资源。
• 责任边界：HQControl 提供数据和权限边界，页面展示和业务计算由项目代码负责。
• SDK 版本：当前手册按 hq-custom-page.js 的 SDK 1.3.0 能力编写。

2. 运行模型和安全边界

自写页由 HQControl 以 sandbox iframe 方式加载。页面不直接继承主应用内部对象，也不绕过登录、权限、Tag 范围和服务端校验。页面只能等待宿主注入 HQVISU_HOST，再通过 HQVISU_CUSTOM_PAGE.ready() 拿到 SDK API。

• 声明范围是安全边界：未在页面声明的 Tag 不能作为正常读写目标。
• 读取、历史、报警都受 readableTags 范围限制。
• 写入必须同时满足 writableTags 声明和当前用户 tag:write 权限。
• 自写页没有可信内建画面的全部内部能力；导航、弹窗等主应用内部能力不应写成 SDK 承诺。
• 在普通浏览器直接打开自写页文件时没有宿主桥，ready() 会超时失败。

5. ready() 与生命周期

ready() 等待宿主桥就绪，默认超时 5 秒。它返回 Promise，也支持传回调。页面不在 HQControl 运行端打开时，常见错误是 HQVISU_HOST is not available. Open this page from the HQ runtime shell.。

• ready(options)：返回 Promise<api>。
• ready(callback)：宿主就绪后执行回调。
• timeoutMs：等待宿主桥就绪超时，默认 5000ms。
• writeTimeoutMs、historyTimeoutMs、alarmsTimeoutMs：写入、历史和报警请求超时配置。
• destroy()：页面卸载或重建时取消 SDK 订阅，避免旧回调继续运行。

const api = await HQVISU_CUSTOM_PAGE.ready({
  timeoutMs: 5000,
  historyTimeoutMs: 15000,
  alarmsTimeoutMs: 15000
});

window.addEventListener("beforeunload", () => {
  api.destroy();
});

7. 订阅实时变化

subscribe(tags, callback) 会订阅声明范围内的 Tag 变化，并返回取消订阅函数。回调参数是变化项数组，每个 item 包含 tagName、fullCode、value、quality 等字段。只想让快照开始进入页面、暂时不需要回调时，可使用 track(tags)。

• 订阅点位应来自页面声明范围。
• 回调里可以重新调用 readNumber、readBoolean 等方法读取当前快照。
• 离开页面、切换报表或销毁组件时要调用取消订阅函数。
• 高频页面应集中订阅一组 Tag，再统一刷新 UI，避免每个组件重复订阅。

const stopRealtime = api.subscribe([
  "Line1.Temperature",
  "Line1.RunState",
  "Line1.Output"
], (items, host) => {
  updateRealtimeCards({
    temperature: host.readNumber("Line1.Temperature", 0),
    running: host.readBoolean("Line1.RunState", false),
    output: host.readNumber("Line1.Output", 0)
  });
});

// 不再需要实时刷新时
// stopRealtime();

9. 查询历史和趋势

history.query() 用于按时间范围、间隔和聚合方式取历史数据。接口返回历史数据结果，页面可用返回结果绘制趋势图、能耗报表、班次统计或质量分析。

• tags 最多 16 个，且必须在 readableTags 范围内。
• start、end 使用可解析时间，范围最多 366 天。
• interval 可使用 15m、1h、1d、1w 等，最小 1 分钟。
• aggregate 支持 avg、min、max、sum、count、first、last、delta、raw。
• delta 适合电表、水表、产量累积量等报表口径。
• 返回点数默认/最大 20000；超出预算时宿主可能放粗间隔，并通过 effectiveInterval、truncated 表示实际结果。

const weekEnergy = await api.history.query({
  tags: ["Line1.Energy", "Line2.Energy"],
  start: "2026-07-01T00:00:00+08:00",
  end: "2026-07-08T00:00:00+08:00",
  interval: "1d",
  aggregate: "delta",
  points: 20000
});

renderEnergyReport(weekEnergy.items, {
  interval: weekEnergy.effectiveInterval,
  truncated: weekEnergy.truncated
});

10. 查询和订阅报警

报警接口用于查询当前活动报警、分页查询历史报警，以及订阅报警变化。报警范围按页面 readableTags 的整体范围确定；如果页面没有声明可读 Tag，报警查询应返回空范围。

• alarms.getActive()：获取当前活动报警快照。
• alarms.queryHistory(payload)：按时间、等级、状态、来源、分页查询历史报警。
• alarms.subscribe(callback)：订阅报警变化，返回取消订阅函数。
• 历史报警默认可按最近 24 小时查询，单次跨度和分页大小受宿主限制。
• 报警等级通常按 critical、high、medium、low、info 展示；状态通常是 active 或 recovered。

const active = await api.alarms.getActive();
renderAlarmSummary(active.items || []);

const history = await api.alarms.queryHistory({
  start: "2026-07-07T00:00:00+08:00",
  end: "2026-07-08T00:00:00+08:00",
  severity: ["critical", "high"],
  state: ["active", "recovered"],
  limit: 200,
  offset: 0
});

const stopAlarms = api.alarms.subscribe((items) => {
  renderActiveAlarmList(items);
});

12. renderTable 与 bindJsonTable

renderTable(target, rows, options) 是轻量表格辅助，不是报表系统。它会把数组、{ rows: [...] } 或 { items: [...] } 渲染成 HTML table。bindJsonTable(target, tagName, options) 会读取 JSON Tag，并在 Tag 更新时自动重渲染表格。

• target 可以是 CSS 选择器或 DOM 元素。
• options.columns 可传字符串数组，也可传 { key, label } 对象数组。
• 未提供 columns 时，SDK 会根据前 25 行数据推断列。
• options.className 可指定表格 class，页面自行写 CSS。
• 复杂排序、分页、冻结列和导出 Excel 应由项目页面或第三方表格组件实现。

api.renderTable("#quality-table", {
  rows: [
    { tag: "Line1.Temperature", value: "72.4", quality: "good" },
    { tag: "Line1.Pressure", value: "0.68", quality: "good" }
  ]
}, {
  className: "report-table",
  columns: [
    { key: "tag", label: "点位" },
    { key: "value", label: "当前值" },
    { key: "quality", label: "质量" }
  ]
});

// JSON Tag 内容变化时自动刷新表格
const stopTable = api.bindJsonTable("#event-table", "Line1.EventRows", {
  columns: ["time", "type", "message"]
});

13. 多语言

自写页可以跟随 HQControl 当前语言切换。系统翻译包中的 key 可通过 language.translate() 读取；页面内的业务文案，也可以根据 language.current() 自行切换。

• language.current() / getLocale()：读取当前语言码。
• language.translate(key, fallback) / t(key, fallback)：读取系统翻译包。
• language.onChange(callback)：语言变化时重渲染页面，返回取消函数。
• language.setLocale(locale)：切换运行时语言，会影响整个运行时。

function renderTitle() {
  const locale = api.language.current();
  document.getElementById("title").textContent =
    locale === "en" ? "Line A Shift Report" : "A 线班次报表";
}

renderTitle();
const stopLanguage = api.language.onChange(renderTitle);