所属产品: Mingcedar CONTROL

页面 SDK：快速上手 | Mingcedar

将 HTML 上传到“画面文件”并从运行菜单打开，Runtime 会自动加载 SDK，无需安装 npm 包或添加 script。调用一次 ready()，后续复用返回的 api。

首次发布 2026-10-25T12:48:42.546388866Z 最近更新 2026-10-26T19:56:55.577167925Z

使用页面 SDK 读取 Tag、写入设定值并查询报警和趋势。示例适用于原生 HTML 和 Vue；发布前须替换项目点位并核对权限。

将 HTML 上传到“画面文件”并从运行菜单打开，Runtime 会自动加载 SDK，无需安装 npm 包或添加 script。调用一次 ready()，后续复用返回的 api。

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>HQVISU_CUSTOM_PAGE.ready().then(async (api) => {

// Use the examples below here. Reuse this api object.

}).catch(error => console.error(error.message));</code></pre></div>

完成标志 原生 HTML 将代码放在 body 末尾的 <script> 中，页面元素放在前面。按需选取下文片段放进同一 async 回调，复用 api。独立 Vite 服务器、file:// 和其它网站不提供此运行环境。

</ul>

</article>

<h3 id="sdk-expand">声明页面使用的 Tag</h3>

把这段声明放进入口 HTML 的 head。将 <device-code>.<tag-code> 替换成实际完整编码；只读页面把 writableTags 改成 []。Vue 也写在 index.html 中。

<div class="manual-code" data-code-language="html"><div class="manual-code-toolbar">HTMLHTML<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: HTML">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><script>window.HQVISU_PAGE_META = { layoutMode: "native" };</script>

{

"readableTags": ["<device-code>.<tag-code>"],

"writableTags": ["<device-code>.<tag-code>"]

}

</script></code></pre></div>

完成标志 layoutMode: "native" 让普通 HTML/Vue 按窗口自适应布局。readableTags 是读范围，writableTags 是写范围；声明不会授予账号原本没有的控制权限。

</article>

添加 <output id="value"></output>，用 ReadTagDouble 读数值，null 指定不可用时的返回值。整数、布尔和文本分别用 ReadTagInteger、ReadTagBoolean、ReadTagString。

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const value = api.ReadTagDouble("<device-code>.<tag-code>", null);

document.getElementById("value").textContent = value ?? "—";</code></pre></div>

完成标志 读取同步返回已采集的当前值，不会每次调用都去读 PLC。null 显示为“—”，不能当成真实 0。

</article>

<h3 id="sdk-first-value">值变化时自动刷新</h3>

在 HTML 放一个 <output id="value"></output>，用 subscribe 通知页面刷新。无需 setInterval 反复查询。

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const tag = "<device-code>.<tag-code>";

function renderValue() {

document.getElementById("value").textContent = value ?? "—";

}

renderValue();

const stop = api.subscribe([tag], renderValue);

// Call stop() when this view is removed.</code></pre></div>

完成标志 首次进入立即显示当前值，后续变化自动更新。组件退出时调用 stop()。

</article>

<h3 id="custom-page-tutorial-item-5">点击按钮写入一次 Tag</h3>

添加 <button id="write" disabled>写入</button> 和 <pre id="result"></pre>。下面写入一次 12.5；换成项目允许的目标值。目标需声明为可写、启用 Tag 控制，并由具有 tag:write 权限的账号操作。

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const button = document.getElementById("write");

const output = document.getElementById("result");

button.disabled = !(api.supports("tag.write") && await api.auth.hasPermission("tag:write"));

button.onclick = async () => {

if (button.disabled) return;

const tag = "<device-code>.<tag-code>";

if (!api.ReadTagQualityGood(tag)) { output.textContent = "Tag unavailable"; return; }

if (!confirm("Write 12.5?")) return;

button.disabled = true;

try {

const result = await api.WriteTagDouble(tag, 12.5, { reason: "Operator setpoint update" });

const done = result?.accepted === true && result?.status === "done"

&& result?.outcomeUncertain !== true && result?.operatorVerificationRequired !== true

&& result?.transportOnly !== true;

output.textContent = (done ? "Command completed; verify collected value: " : "Result unconfirmed; verify before another write: ")

+ JSON.stringify(result ?? null);

} catch (error) {

output.textContent = "Result unconfirmed: " + error.message + " " + (error.commandId || error.result?.commandId || "");

}

// Reconcile the result before another write. Never retry automatically.

};</code></pre></div>

完成标志 整数、布尔用 WriteTagInteger、WriteTagBoolean。本例每页实例仅提交一次，随后禁用按钮；done 仍须核对后续正常采集值。刷新会重置按钮，下次操作前须核对上次结果；需跨刷新阻断时，保存待核对状态。

<li><a href="/hqserver/manual/custom-page-sdk/#custom-page-sdk-item-14">写入结果核对</a></li>

</ul>

</article>

<h3 id="custom-page-tutorial-item-6">查询当前报警（一次）</h3>

在 HTML 添加 <div id="alarms"></div> 和 。getActive 查询当前报警，renderTable 把 items 显示成表格。

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const alarms = await api.alarms.getActive({ limit: 100 });

api.renderTable("#alarms", alarms.items);

document.getElementById("alarm-status").textContent = alarms.hasMore ? "More records available" : "";</code></pre></div>

完成标志 本例仅查询一次。实时列表用 alarms.subscribe 通知重新查询，不直接追加回调数据；退出时取消订阅。空 items 表示当前范围无报警，hasMore=true 表示仍有记录。其它设备或分组须配置报警范围。

<li><a href="/hqserver/manual/custom-page-sdk/#custom-page-sdk-item-17">报警范围声明</a></li>

</ul>

</article>

<h3 id="custom-page-tutorial-item-9">查看最近一小时的历史报警</h3>

添加 <div id="alarm-history"></div> 和 。历史报警用 alarms.queryHistory 查询，显示在独立表格中。

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const alarmEnd = new Date();

const alarmHistory = await api.alarms.queryHistory({

start: new Date(alarmEnd.getTime() - 3600000).toISOString(),

end: alarmEnd.toISOString(),

limit: 100

});

api.renderTable("#alarm-history", alarmHistory.items);

document.getElementById("history-status").textContent = alarmHistory.hasMore ? "More records available" : "";</code></pre></div>

</article>

<h3 id="custom-page-tutorial-item-7">查询趋势数据</h3>

先为 Tag 启用趋势归档，添加 <div id="trend"></div> 和 。下面把最近一小时的分钟平均值显示成表格；将同一份 points 交给图表组件即可画曲线。

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const trendEnd = new Date();

const trend = await api.history.query({

tags: ["<device-code>.<tag-code>"],

start: new Date(trendEnd.getTime() - 3600000).toISOString(),

end: trendEnd.toISOString(), interval: "1m", aggregate: "avg"

});

const points = (trend.items[0]?.points || []).map(point => ({

time: point.t, value: point.quality === "good" ? point.value : null

}));

api.renderTable("#trend", points);

完成标志 无归档时返回空数据；异常质量用 null 保留曲线缺口。effectiveInterval 是实际采样间隔。

</article>

<h3 id="sdk-scenario-popup">打开设备弹窗</h3>

先在“弹窗模板”保存模板，添加 <button id="open-popup">打开设备</button>，再绑定点击。替换设备编码、模板编码和已声明的 Tag。

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>document.getElementById("open-popup").onclick = () => {

try {

api.dialog.openDevicePopup({

plc: "<device-code>",

templateCode: "<popup-template-code>",

focusTagNames: ["<device-code>.<tag-code>"]

});

} catch (error) { console.error(error.message); }

};</code></pre></div>

完成标志 弹窗中的显示、读写、报警和趋势由模板配置决定。调用返回不代表弹窗内写入已完成；实际核对弹窗与目标值。

</article>

<h3 id="sdk-scenario-navigation">跳转到其它页面</h3>

按目标选择下面一个调用，放在按钮的点击处理函数中。相对路径以当前画面为起点；在 assets 根内可以跳到上级、下级和其它目录。

api.navigation.gotoPage("details/equipment.html"); // Child page

api.navigation.gotoPage("../overview.html"); // Parent page

api.navigation.gotoPage("/assets/<folder>/index.html"); // Another folder

api.navigation.openUrl("https://<server-host>/manual", { openInNewWindow: true });</code></pre></div>

</article>

<h3 id="sdk-scenario-language">跟随系统切换中英文</h3>

系统顶栏 LANG 已负责切换，不必再加语言按钮。给标题加 id="title"，读取当前语言并订阅变化。

const zh = api.language.current().startsWith("zh");

document.getElementById("title").textContent = zh ? "设备总览" : "Equipment overview";

}

renderText();

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

// Call stopLanguage() when this view is removed.</code></pre></div>

</article>

<h3 id="tutorial-sdk-vue-component">在 Vue 中使用同一套 API</h3>

Vue 3 项目在 index.html 中添加布局和 Tag 声明，再保存并挂载以下完整只读组件。onMounted 后取得 api；发布到 Runtime 后自动加载 SDK。

<div class="manual-code" data-code-language="vue"><div class="manual-code-toolbar">VueVue<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: Vue">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><script setup>

import { ref, onMounted, onUnmounted } from "vue";

const value = ref(null), error = ref("");

let stop, disposed = false;

onMounted(async () => {

try {

const api = await window.HQVISU_CUSTOM_PAGE.ready();

if (disposed) return;

const refresh = () => { value.value = api.ReadTagDouble(tag, null); };

refresh();

stop = api.subscribe([tag], refresh);

} catch (err) { if (!disposed) error.value = err.message; }

});

onUnmounted(() => { disposed = true; stop?.(); });

</script>

<p v-if="error">{{ error }}</p>

<output v-else>{{ value ?? "—" }}</output>

</template></code></pre></div>

完成标志 设置 Vite base: "./"，按原目录上传 dist 内容。卸载只取消组件订阅，不调用 api.destroy()。本例 api 位于 onMounted 内；按钮调用须在组件作用域保存 api，见完整 Vue 写入示例。

</ul>

</article>

<h3 id="custom-page-tutorial-item-2">完整 HTML：替换点位后发布</h3>

需要从零开始时复制这个完整只读页，替换两处 Tag 编码。它使用 Runtime 自动提供的 SDK。

<details class="manual-code-disclosure"><summary>展开完整源代码</summary><div class="manual-code" data-code-language="html"><div class="manual-code-toolbar">HTMLHTML<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: HTML">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><!doctype html>

<title>Mingcedar live value</title>

{"readableTags":["<device-code>.<process-tag-code>"],"writableTags":[]}

</script>

<h1>Live value</h1>

<p id="status" role="status">Connecting…</p>

<output id="value">Waiting for data</output>

(async () => {

const tag = "<device-code>.<process-tag-code>";

const status = document.getElementById("status");

const output = document.getElementById("value");

const api = await HQVISU_CUSTOM_PAGE.ready({timeoutMs: 10000});

function refresh() {

const quality = api.ReadTagQuality(tag);

status.textContent = "Connected — quality: " + quality;

output.textContent = quality === "good" && value !== null

? String(value) : "Unavailable";

}

const stop = api.subscribe([tag], refresh);

refresh();

window.addEventListener("pagehide", event => {

if (!event.persisted) { stop(); api.destroy(); }

});

})().catch(error => {

});

</script>

</html></code></pre></div></details>

</article>

<h3 id="custom-page-tutorial-item-3">发布到运行页面</h3>

<ol>

<li>配置中心 → 画面文件：上传 HTML；Vue 上传构建后 dist 的内容并保留目录。</li>

<li>配置中心 → 菜单：选择“页面（直接打开 HTML）”，把入口指向刚上传的 HTML。</li>

<li>从运行菜单打开。先确认 Tag 值，再验证需要的操作；修改后覆盖发布并刷新。</li>

</ol>

</article>

<h3 id="custom-page-tutorial-item-11">常见问题与排查</h3>

<ul>

<li>HQVISU_CUSTOM_PAGE 未定义：确认从当前 Runtime 的运行菜单打开；独立网页不会自动提供 SDK。</li>

<li>读到 null：核对静态声明、完整 Tag 编码及数据质量。</li>

<li>写入不可用：核对 writableTags、账号权限和 Tag 控制标志；未知结果先核对，不重发。</li>

<li>其他数据类型和选项见 API 参考。</li>

</ul>

</ul>

</article>

<h3 id="sdk-development-brief">页面交付信息</h3>

开发和验收自写页面时，准备实际 Tag 编码与类型、允许的写入值、页面功能及目标运行菜单。入口 HTML 中的声明须与页面代码一致。

<ul>

<li>记录页面使用的 Tag、报警和历史范围；写入点同时明确账号权限、控制许可和设备允许值。</li>

<li>从运行菜单打开页面，核对 SDK 初始化、GOOD 质量、系统 LANG 切换和组件卸载后的订阅清理。</li>

<li>验证写入回执与后续正常采集值；结果未确认时保留命令标识，下一次操作前先核对。</li>

<li>缺少实际编码、类型或授权范围时，先补全配置再发布。</li>

</ul>

</ul>

</article>

</div>