Product: Mingcedar CONTROL

Custom-page SDK API reference | Mingcedar

The SDK provides project HTML with realtime Tags, typed reads and writes, history, alarms, user, permissions, language, navigation, device popups, and table helpers. Project code handles layout and business calculations.

Published 2026-10-25T12:48:42.626899431Z Updated 2026-10-26T19:56:55.63461996Z

New to the SDK? <a href="/en/hqserver/manual/custom-page-tutorial/">Start with the step-by-step tutorial</a>. Use this page to look up parameters and return values.<div class="manual-doc-article manual-doc-article-section"><h2 id="custom-page-sdk">SDK: Custom-page SDK API reference</h2>

Native HTML/Vue integration and public API reference. Tag reads and writes use the PPT ReadTag*/WriteTag* names; the system LANG control switches languages.

The SDK provides project HTML with realtime Tags, typed reads and writes, history, alarms, user, permissions, language, navigation, device popups, and table helpers. Project code handles layout and business calculations.

<ul>

<li>Good fits: shift production reports, daily energy reports, equipment health pages, quality trace pages, work-order boards, and customer views.</li>

<li>Page forms: plain HTML, native ES modules, or built Vue pages; ship CSS, charts and components with the project.</li>

<li>Data sources: declared tags, history data, alarm data, and language resources.</li>

<li>Responsibility boundary: Mingcedar provides data and permission boundaries; the project page owns presentation and business calculations.</li>

<li>SDK version: 1.5.0.</li>

</ul>

Expected result Start with SDK quick start. Except for complete pages/components, snippets assume api, the required DOM elements, and project renderers are ready.

<li><a href="/en/hqserver/manual/custom-page-tutorial/">Start by reading one Tag</a></li>

</ul>

</article>

<h3 id="custom-page-sdk-item-2">Runtime origin and permission boundaries</h3>

Project pages run in an iframe on a separate Screen Origin, isolated from the Portal. The bridge validates origin, window, session, and document identity. Pages may use their own origin’s cookies, storage, URL parameters, and ordinary Web Workers, but not Service Workers. They cannot access Portal cookies, administration DOM, or configuration APIs. Data and writes remain subject to page declarations and server authorization.

</article>

<h3 id="custom-page-sdk-item-3">What page-owned JavaScript can do</h3>

Custom pages may use DOM, CSS, components, chart libraries, and interactions allowed by the browser and iframe sandbox. The SDK governs Mingcedar Host capabilities.

<ul>

<li>Supported: DOM/component logic and <code>alert</code>, <code>confirm</code>, and <code>prompt</code>.</li>

<li>Supported: <code>window.open</code>, form submission, browser navigation, and user-initiated downloads; browser popup and user-activation rules still apply.</li>

<li>Clipboard API is supported only when secure-context, user activation, browser permission, and enterprise-policy requirements are met.</li>

<li>Service Worker registration is unsupported. The page does not receive Portal cookies, login tokens, Admin DOM, configuration APIs, or raw Host service objects.</li>

<li>The page cannot poll a PLC directly; the SDK does not provide alarm acknowledge, shelve, or close operations.</li>

<li><code>api.supports()</code> checks Host Bridge capabilities, not browser API availability or permission.</li>

</ul>

</article>

<h3 id="custom-page-sdk-item-4">SDK loading is automatic; module imports are optional</h3>

Runtime loads the SDK for published HTML/Vue pages. Call await HQVISU_CUSTOM_PAGE.ready(); no extra script tags are needed.

<ul>

<li>An ES module can import { ready } from "/runtime/hqVisuDesigner/hq-custom-page.mjs"; it reuses the installed SDK.</li>

<li>Only non-injected environments such as a custom Mock need hq-common.js followed by hq-custom-page.js. Loading files does not create runtime permissions.</li>

<li>Static Tag declarations remain in entry HTML. No SDK npm package is required. A Vite dev server or file:// is not the runtime environment.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</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>

</article>

<h3 id="custom-page-sdk-item-5">How to declare tag scope</h3>

The server grants page capabilities from supported HTML JSON and data declarations. Use full dotted Tag codes, such as <code><device-code>.<temperature-tag-code></code>, and canonical bit references <code>[0]</code>–<code>[31]</code>. Invalid or over-limit declarations affect capability grants.

<ul>

<li>Supported config block ids: <code>hqvisu-custom-page</code>, <code>hqvisu-custom-page-config</code>, <code>hqvisu-page-config</code>, and <code>hqvisu-dependencies</code>.</li>

<li>Readable aliases: <code>readableTags</code>, <code>tags</code>, <code>tagNames</code>, <code>readTags</code>, and <code>watchTags</code>.</li>

<li>Writable aliases: <code>writableTags</code> and <code>writeTags</code>; matching declarations under <code>outputs</code> are also collected.</li>

<li>Under <code>dependencies</code>, supported fields are <code>tags</code>, <code>tagNames</code>, <code>readableTags</code>, <code>readTags</code>, <code>writableTags</code>, and <code>writeTags</code>.</li>

<li>Values may be arrays or strings separated by newline, comma, or semicolon.</li>

<li>Bit references such as <code><device-code>.<status-word-tag-code>[3]</code> are read-only, for example ReadTagBoolean(name, null). Write a bit with WriteTagBit("<device-code>.<status-word-tag-code>", 3, "set") and declare the parent Tag readable and writable. No write method accepts [3] in its target. History also queries the parent Tag.</li>

<li><code><device-code></code> and <code><tag-code></code> in this manual are placeholders. Replace them with actual project codes before publishing.</li>

<li>ready({ tags }) requests tracking; it does not enlarge server write, history, alarm or Popup scope. Put a controlled Tag that needs readback in both readableTags and writableTags.</li>

</ul>

<div class="manual-code" data-code-language="html"><div class="manual-code-toolbar">HTMLHTML<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: HTML">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><script type="application/json" id="hqvisu-custom-page">

{

"readableTags": [

"<device-code>.<temperature-tag-code>",

"<device-code>.<pressure-tag-code>",

"<device-code>.<run-state-tag-code>",

"<device-code>.<output-tag-code>",

"<device-code>.<energy-tag-code>",

"<device-code>.<setpoint-tag-code>"

],

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

}

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

</article>

<h3 id="custom-page-sdk-item-6">Dynamic exact-on-use Tags from parameters, loops, and composition</h3>

Use <code>exact-on-use</code> for full Tag codes built from runtime parameters, loops, or functions. Each exact Tag is checked for format, existence, enabled state, page session, and read/write rules. Wildcards, catalog enumeration, and unlimited access are unsupported.

<ul>

<li>liveTagRead.maxActiveTags accepts 1–8000. This small-page example budgets 64 read Tags and 16 write Tags. Size it for actual use; quotas are not a performance guarantee.</li>

<li>The formal <code>liveTagWrite.maxActiveTags</code> limit is 2000.</li>

<li>Good fits: select a device from page parameters, loop over a known device list, build a full Tag in a function, or bind a component to a business object.</li>

<li>Unsupported: <code><device-code>.*</code> search, Tag catalog reads, device enumeration, or bypassing per-Tag Host validation.</li>

<li>Dynamic declaration expands exact live read/write only. History, alarms, device popups, and prefetch retain their own scopes.</li>

<li>Use static declarations for fixed Tags to support initial prefetch, subscriptions, and scope management.</li>

</ul>

{

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

"dependencies": {

"runtimeAccess": {

"liveTagRead": { "mode": "exact-on-use", "maxActiveTags": 64 },

"liveTagWrite": { "mode": "exact-on-use", "maxActiveTags": 16 }

}

}

</script>

const deviceCode = new URLSearchParams(location.search).get("device");

const temperatureTag = `${deviceCode}.<temperature-tag-code>`;

api.track(temperatureTag);</code></pre></div>

</article>

<h3 id="custom-page-sdk-item-7">ready() and resource lifetime</h3>

HQVISU_CUSTOM_PAGE.ready(options?), ready(callback), and ESM ready(options?) return Promise<PageApi>. Initialization confirms the bridge, not GOOD values for every Tag. One SDK belongs to the HTML document and is reused across Vue mounts.

<ul>

<li>tags: string[] adds tracked Tags; prefer static declarations. Display initialization errors with try/catch; do not loop ready retries.</li>

<li>subscribe, alarms.subscribe, language.onChange and bindJsonTable return cleanup functions. Call each component-owned cleanup on unmount.</li>

<li>destroy() permanently ends the document. A later ready() in that document rejects with RUNTIME_PAGE_DESTROYED. Do not destroy on ordinary Vue unmount; only end the whole document.</li>

<li>pagehide with persisted=true means BFCache retention, not permanent destruction. An unmounted component must not register subscriptions after async setup resolves.</li>

<li>timeoutMs controls the host wait (10000 ms in the examples), not PLC read/write timeouts. Check each Tag quality after ready resolves.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const api = await HQVISU_CUSTOM_PAGE.ready();

const stop = api.subscribe(["<device-code>.<tag-code>"], renderValue);

// renderValue is your UI renderer.

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

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

</article>

<h3 id="custom-page-sdk-item-8">SDK global-object API</h3>

The global object is <code>HQVISU_CUSTOM_PAGE</code>, with compatibility alias <code>HQVisuCustomPage</code>. These members are available before <code>ready()</code>; page data requires a ready Host connection.

<ul>

<li><code>version</code>: string <code>1.5.0</code>.</li>

<li><code>ready(options | callback)</code>: returns <code>Promise<PageApi></code>.</li>

<li><code>whenVisualReady({ timeoutMs? })</code>: waits for the first authorized visual snapshot and returns <code>Promise<void></code>; ordinary pages use <code>ready()</code> to obtain the api.</li>

<li><code>destroy()</code>: permanently ends this document's SDK connection. On component unmount, cancel only subscriptions owned by that component.</li>

<li><code>normalizeTagName(value)</code>: stringifies, trims, and removes one matching outer quote pair; returns a string.</li>

<li><code>tagList(value)</code>: accepts strings, nested arrays, or a scalar; splits newline/comma/semicolon text, normalizes, drops empty values and legacy placeholders shaped like <code><TagName></code>, and deduplicates; returns <code>string[]</code>.</li>

<li><code>renderTable(target, rows, options)</code>: renders a lightweight HTML table and returns <code>{ rowCount, columnCount }</code>.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</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>";

const normalized = HQVISU_CUSTOM_PAGE.normalizeTagName(tag);

const tags = HQVISU_CUSTOM_PAGE.tagList([tag, tag]);</code></pre></div>

</article>

<h3 id="custom-page-sdk-item-9">PageApi root object and capability matrix</h3>

Use the root methods returned by <code>ready()</code> and stable namespaces such as <code>api.auth</code>, <code>api.permissions</code>, <code>api.history</code>, and <code>api.alarms</code>. Low-level <code>api.host</code> interfaces vary by transport.

<ul>

<li>Properties: <code>version</code>, <code>bridgeVersion</code>, <code>schemaRevision</code>, frozen <code>capabilities</code>, and low-level <code>host</code>.</li>

<li>Discovery: <code>getCapabilities()</code> returns a mutable copy; <code>supports(name)</code> returns a boolean and false for an unknown capability.</li>

<li>Namespaces: <code>auth</code>, <code>permissions</code>, <code>language</code>, <code>history</code>, <code>alarms</code>, <code>navigation</code>, and <code>dialog</code>.</li>

<li>Root methods: <code>track</code>, <code>subscribe</code>, all read/write methods, <code>queryHistory</code>, <code>translate</code> / <code>t</code>, <code>renderTable</code>, <code>bindJsonTable</code>, and <code>destroy</code>.</li>

<li>Capability names: <code>page.parameters</code>, <code>tag.read</code>, <code>tag.write</code>, <code>history.read</code>, <code>user.read</code>, <code>navigation</code>, <code>popup</code>, <code>alarm.read</code>, and <code>log.write</code>.</li>

<li><code>supports()</code> indicates transport exposure only; it is not user permission and does not enlarge page scope.</li>

<li>log.write is optional: when supports("log.write") is false, do not call it or report logging success. PageApi exposes no standalone root log.write API.</li>

</ul>

</article>

<h3 id="custom-page-sdk-item-10">Current-user and permission API</h3>

The stable session result is <code>{ user, permissions }</code>. For an authenticated user, <code>user</code> contains <code>username</code>, <code>displayName</code>, and <code>permissions</code>. An anonymous direct Screen Gateway returns <code>user: null</code> and an empty permission array. Tokens, cookies, roles, and page-capability secrets are never exposed.

<ul>

<li><code>api.auth.getSession()</code>: session snapshot. Use <code>await api.auth.getSession()</code> for both synchronous and asynchronous Hosts.</li>

<li>api.auth.getCurrentUser() / getUser() → user snapshot or null; getUsername() → username; getDisplayName() → display name, falling back to username.</li>

<li><code>api.auth.hasPermission(code)</code> / <code>api.permissions.has(code)</code>: returns <code>Promise<boolean></code>.</li>

<li><code>api.auth.requirePermission(code)</code> / <code>api.permissions.require(code)</code>: resolves true when allowed and rejects when denied.</li>

<li>These methods belong to PageApi.auth. Prefer this public wrapper over transport-specific objects under api.host.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const api = await HQVISU_CUSTOM_PAGE.ready();

const session = await api.auth.getSession();

const canWrite = api.supports("tag.write")

&& await api.permissions.has("tag:write");

renderCurrentUser(session.user);

setWriteControlsEnabled(canWrite);</code></pre></div>

</article>

<h3 id="custom-page-sdk-item-11">Read API: the same names as PPT</h3>

Reads synchronously return the current collected snapshot without polling a PLC. Typed reads with explicit fallback return it for non-GOOD/missing quality or conversion failure; omitting fallback is not a quality check. ReadTag returns raw values without typed conversion or quality filtering. Use ReadTagDouble(name, null) and show quality to distinguish a real zero from unavailable data.

<ul>

<li><code>ReadTag(name, fallback?)</code> → raw snapshot value, without typed conversion.</li>

<li><code>ReadTagBoolean(name, fallback?)</code> → boolean; recognizes booleans, finite numbers and true/false, 1/0, on/off, yes/no text; default false.</li>

<li><code>ReadTagInteger(name, fallback?)</code> → safe integer truncated toward zero; default 0. Preserve large integers as raw/text instead of coercing to Number.</li>

<li><code>ReadTagDouble(name, fallback?)</code> → finite number; default 0.</li>

<li><code>ReadTagString(name, fallback?)</code> → display text, preferring displayValue and numeric precision/round rules; default empty string. GOOD empty strings are valid.</li>

<li><code>ReadTagJson(name, fallback?)</code> → parsed JSON value; default null. It may be an object, array or scalar.</li>

<li><code>ReadTagDateTime(name, fallback?)</code> → valid Date or fallback; default null. See the UTC-field rule for PLC calendars below.</li>

<li><code>ReadCalculatedTag(name, fallback?)</code> → calculated number/boolean with calculated-source and GOOD checks; default null. Use the calculated Tag code and declare its read scope.</li>

<li><code>ReadTagQuality(name, fallback?)</code> → <code>"good" | "bad"</code>; <code>ReadTagQualityGood(name)</code> → <code>boolean</code>. Missing quality defaults to bad; do not pass good to conceal missing quality.</li>

<li><code>getMeta(name)</code> → metadata object. dataType, qualityDetail, timestamp, source, and other fields depend on the supplied snapshot; stale/pending diagnostics do not add a third ReadTagQuality result.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const name = "<device-code>.<tag-code>";

const raw = api.ReadTag(name);

const quality = api.ReadTagQuality(name); // "good" | "bad"

const usable = api.ReadTagQualityGood(name);

document.getElementById("value").textContent = usable && value !== null ? String(value) : "—";

const meta = api.getMeta(name); // source, dataType, ts/persistenceVersion when supplied

// Choose the reader matching each Tag's type; do not cast one Tag to every type.

const running = api.ReadTagBoolean("<device-code>.<run-state-tag-code>", null);

const count = api.ReadTagInteger("<device-code>.<count-tag-code>", null);

const label = api.ReadTagString("<device-code>.<text-tag-code>", "—");

const date = api.ReadTagDateTime("<device-code>.<datetime-tag-code>", null);

const calculated = api.ReadCalculatedTag("<calculated-tag-code>", null);</code></pre></div>

</article>

<h3 id="custom-page-sdk-item-12">Subscribe to realtime changes</h3>

<code>track(tags)</code> normalizes and tracks Tags, returning deduplicated names. <code>subscribe(tags, callback)</code> returns an idempotent unsubscribe function and calls <code>(items, api)</code>. Read the snapshot for initial rendering, then subscribe to changes.

<ul>

<li>Each change includes <code>tagName</code> and <code>value</code>; <code>fullCode</code>, <code>quality</code>, <code>timestamp</code>, <code>source</code>, and other metadata are provided when available.</li>

<li>A page may hold at most 8000 active unique Tags. Invalid, missing, disabled, or rejected candidates do not permanently consume the budget.</li>

<li>The wire boundary carries at most 256 Tags per batch and the SDK runs up to four batches concurrently; a large page still uses one logical realtime subscription and one WebSocket.</li>

<li>Use the callback's second argument to read a consistent current snapshot; group high-frequency Tags and update UI in one pass.</li>

<li>Unsubscribe when scope changes or the component exits. <code>destroy()</code> cleans up remaining Tag and alarm subscriptions.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</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>.<process-tag-code>";

function renderValue() {

api.ReadTagQualityGood(tag) && value !== null ? String(value) : "—";

}

renderValue();

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

// stopRealtime() when this view no longer needs the subscription.</code></pre></div>

</article>

<h3 id="custom-page-sdk-item-13">Write API: parameters, prerequisites and returns</h3>

Typed writes use (name, value, options?). Always await the result: a Host may return synchronously, a Promise, or undefined; do not assume .then() exists. Writes require tag.write capability, admitted scope, user tag:write permission, Tag control permission and valid quality; execution rechecks Owner and user action.

<ul>

<li><code>WriteTagBoolean(name, value, options?)</code>: use boolean, 0/1 or explicit boolean text; "false" means false, not JavaScript truthiness.</li>

<li><code>WriteTagInteger(name, value, options?)</code>: number must be a safe integer; BigInt or decimal integer text preserves precision. The service checks the actual device range.</li>

<li><code>WriteTagDouble(name, value, options?)</code>: finite numeric value or valid numeric text; reject NaN, Infinity and blank form input.</li>

<li><code>WriteTagString(name, value, options?)</code>: text; empty string is an intentional value, still subject to PLC encoding and length limits.</li>

<li><code>WriteTagJson(name, value, options?)</code>: pass the actual JSON object/array/value, without JSON.stringify on an object. Restore original empty text with WriteTagString.</li>

<li><code>WriteTagDateTime(name, value, options?)</code>: Date or date text; PLC calendar metadata selects serialization, as explained below.</li>

<li><code>WriteTag(name, value, options?)</code> / <code>WriteTag({ TagName, Value, ValueType, ... })</code>: generic entry, also accepting a camelCase payload; false, 0, empty text and JSON values are retained.</li>

<li><code>WriteTagBit(name, bitIndex, bitAction, options?)</code>: name is the parent Tag, with GOOD quality and a supported 8/16/32-bit integer type. The index must fit that type and be within 0–31; actions are set/reset/toggle. Blank indexes are invalid. Protocol support varies; Modbus requires confirmed FC22 support, with no toggle or full-word read/modify/write fallback.</li>

<li>options.reason supplies an operation reason; typed helpers fix their type and caller source. Precheck with await api.auth.hasPermission("tag:write"); capability tag.write is not the permission code.</li>

<li>Initiate from a user click handler. Page confirmation does not replace configured Host confirmation. Do not write automatically from timers, loading or subscriptions.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">Bind a write button inside ready (id="write", result id="result")JavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: Bind a write button inside ready (id="write", result id="result")">Copy code</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 (!confirm("Write 12.5?")) return;

button.disabled = true;

try {

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

&& 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>

</article>

<h3 id="custom-page-sdk-item-14">Classify the command, then verify normal collected readback</h3>

accepted=true means admitted. Inspect status, commandId, journalId and uncertainty fields. currentValue may be a runtime-write echo and is not proof of later normal collection. In this fragment nextValue and reason come from validated page inputs.

<ul>

<li>done: command completed; verify normal collected source, newer timestamp/version and quality before confirming the device value. Do not overwrite live display with the target.</li>

<li>proxied: inspect actual completion evidence after forwarding. sent or transportOnly=true proves transport only, not PLC execution.</li>

<li>readback_failed/readback_mismatch/latest_superseded: show reconciliation required, not a confirmed collected value.</li>

<li>pending_verification/outcome_uncertain, timeout, disconnect, undefined or unknown status: keep operations blocked, retain commandId, reconcile records and actual values, without automatic retry.</li>

<li>accepted=false, cancelled, failed or page_changed: no confirmed completion; show the actual result.</li>

</ul>

try {

const result = await api.WriteTagDouble("<device-code>.<setpoint-tag-code>", nextValue, { reason });

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

(confirmed ? "Command completed; verify normal collected state: " : "Verify before another write: ")

// Do not overwrite the live value with nextValue or result.currentValue.

// Reconcile the command record and a later GOOD collected sample before another operation.

} catch (error) {

"Result unconfirmed; do not retry automatically. " + error.message;

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

Expected result PageApi has no public command-journal query method. Retain commandId from the receipt or error for an authorized administration/operations integration to reconcile. Use subscribe and getMeta to inspect later GOOD normal collection. Keep controls disabled while unconfirmed; allow a new operator action only after reconciliation, never based solely on a delay, refresh or value equality.

</article>

<h3 id="custom-page-sdk-item-15">Query history and trends</h3>

<code>api.history.query(request)</code> and root alias <code>api.queryHistory(request)</code> both return <code>Promise<HistoryQueryResult></code>. The request reads the history store and does not poll a PLC. Every Tag must be inside the page history-read scope.

<ul>

<li>Request fields: <code>tags</code>, <code>start</code>, <code>end</code>, <code>interval</code>, and <code>aggregate</code>, with optional <code>points</code>.</li>

<li><code>tags</code> is required. The submitted array accepts at most 16 entries, including duplicates; the server then deduplicates them. History does not accept <code>[0]</code> through <code>[31]</code> bit references; query the parent Tag.</li>

<li><code>start</code> and <code>end</code> must be RFC 3339 timestamps, with a maximum range of 366 days.</li>

<li><code>interval</code> supports <code>m</code>, <code>h</code>, <code>d</code>, and <code>w</code>, for example <code>15m</code>, <code>1h</code>, <code>1d</code>, or <code>1w</code>; minimum 1 minute.</li>

<li><code>aggregate</code> supports <code>avg</code>, <code>min</code>, <code>max</code>, <code>sum</code>, <code>count</code>, <code>first</code>, <code>last</code>, <code>delta</code>, and <code>raw</code>.</li>

<li><code>delta</code> fits meters and accumulating counters such as energy, water, or production total.</li>

<li>The example queries the last seven days. The target Tags need recorded history for data to appear.</li>

<li>Omitted or zero <code>points</code> defaults to 20000. Maximum is 20000 and it cannot be smaller than the deduplicated Tag count.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const weekEnd = new Date();

const weekStart = new Date(weekEnd.getTime() - 7 * 24 * 60 * 60 * 1000);

const weekEnergy = await api.history.query({

tags: [

"<primary-device-code>.<energy-tag-code>",

"<secondary-device-code>.<energy-tag-code>"

],

start: weekStart.toISOString(),

end: weekEnd.toISOString(),

interval: "1d",

aggregate: "delta",

points: 20000

});

renderEnergyReport(weekEnergy.items, {

interval: weekEnergy.effectiveInterval,

truncated: weekEnergy.truncated

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

</article>

<h3 id="custom-page-sdk-item-16">How to consume a history result</h3>

The result is <code>{ items, effectiveInterval, rangeStart, rangeEnd, truncated }</code>. <code>items</code> contains one series per requested Tag. A series is <code>{ tag, tagId, displayName, points }</code>; every point is <code>{ t, value, quality }</code>.

<ul>

<li><code>tag</code> is the full Tag code, <code>tagId</code> is the server identifier, and <code>displayName</code> may be empty.</li>

<li><code>points[].t</code> is RFC 3339, <code>value</code> is raw or aggregated, and <code>quality</code> is that point's quality.</li>

<li><code>effectiveInterval</code> is the interval actually used and may be coarser than requested when the point budget is tight.</li>

<li><code>rangeStart</code> and <code>rangeEnd</code> are the actual UTC/RFC 3339 range.</li>

<li><code>truncated: true</code> means the aggregation interval was coarsened or raw records were cut off by the point budget. Show the effective interval and an incomplete-result notice. To retrieve complete raw records, query smaller time windows.</li>

<li>Read each series with <code>series.points || []</code> to handle missing data. Render an empty state instead of treating absent records as zero.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>for (const series of weekEnergy.items || []) {

const chartPoints = (series.points || []).map((point) => ({

time: new Date(point.t),

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

quality: point.quality

}));

drawEnergySeries(series.displayName || series.tag, chartPoints);

}

showActualInterval(weekEnergy.effectiveInterval, weekEnergy.truncated === true);</code></pre></div>

</article>

<h3 id="custom-page-sdk-item-17">Alarm-scope declaration</h3>

The server mints alarm scope from page declarations; client query fields cannot enlarge it. Declare dimensions under <code>alarm</code>, <code>alarmScope</code>, or <code>pageAlarm</code> in the JSON configuration. Readable Tags are also added automatically to the alarm Tag scope.

<ul>

<li>Supported dimensions: <code>tags</code>, <code>plcCodes</code>, <code>functionGroupCodes</code>, <code>deviceGroupCodes</code>, and <code>signalGroupCodes</code>.</li>

<li>With no alarm scope, active and historical alarm queries return an empty scope.</li>

<li>Dynamic <code>liveTagRead</code> does not enlarge alarms. Statically declare required alarm Tags or groups.</li>

<li>The server overwrites any client scope fields with the minted capability; additive JSON cannot reveal more alarms.</li>

<li>Group codes need the device prefix. Empty scope means unbound, not all alarms. showWindow controls the page alarm rail, separately from the equipment Popup.</li>

</ul>

{

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

"alarmScope": {

"plcCodes": ["<device-code>"],

"functionGroupCodes": ["<device-code>.<function-group-code>"],

"deviceGroupCodes": [],

"signalGroupCodes": []

}

}

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

</article>

<h3 id="custom-page-sdk-item-18">Query and subscribe to alarms</h3>

Alarm APIs provide synchronous snapshots, asynchronous queries, and change subscriptions. <code>getActive()</code>, <code>getActiveAlarms()</code>, and <code>queryHistory(request)</code> return paged <code>Promise<AlarmQueryResult></code> results.

<ul>

<li><code>getSnapshot()</code> returns the current Host snapshot synchronously. A Host may return an array or a wrapper such as <code>{ alarms }</code> or <code>{ activeAlarms }</code>.</li>

<li>Query fields: <code>start</code>, <code>end</code>, <code>severity</code>, <code>state</code>, <code>source</code> / <code>q</code>, <code>limit</code>, <code>offset</code>, <code>cursorTs</code>, and <code>cursorId</code>.</li>

<li>History defaults to the most recent 24 hours when times are omitted; one query spans at most 24 hours.</li>

<li>The example queries the last hour; the history result is empty if no alarm occurred in that period.</li>

<li>Omitted or zero <code>limit</code> is 500 and the maximum is 500; larger values are clamped. <code>offset</code> must be nonnegative.</li>

<li>Result: <code>{ items, count, hasMore, nextCursorTs, nextCursorId }</code>. When more data exists, pass both next-cursor fields into the next request.</li>

<li><code>subscribe(callback)</code> returns an idempotent unsubscribe function and calls <code>(items, api)</code>. A Host may send a complete snapshot or change items; use it as a refresh signal rather than blindly appending.</li>

<li>getActive(request?) accepts the filters/pagination above; getActiveAlarms() is the no-argument convenience entry.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>function alarmItemsFromSnapshot(snapshot) {

if (Array.isArray(snapshot)) return snapshot;

if (Array.isArray(snapshot?.alarms)) return snapshot.alarms;

if (Array.isArray(snapshot?.activeAlarms)) return snapshot.activeAlarms;

return [];

}

renderAlarmSummary(alarmItemsFromSnapshot(api.alarms.getSnapshot()));

const activeResult = await api.alarms.getActiveAlarms();

renderAlarmSummary(activeResult.items || []);

const alarmEnd = new Date();

const alarmStart = new Date(alarmEnd.getTime() - 60 * 60 * 1000);

const historyResult = await api.alarms.queryHistory({

start: alarmStart.toISOString(),

end: alarmEnd.toISOString(),

severity: ["critical", "high"],

state: ["active", "recovered"],

limit: 200

});

const stopAlarms = api.alarms.subscribe(() => scheduleActiveAlarmRefresh());</code></pre></div>

</article>

<h3 id="custom-page-sdk-item-19">Alarm item and paging fields</h3>

Identify events by id and display state from state and timestamps. Leave missing optional fields empty; use messageText/displayName when translations are missing, without exposing internal keys.

<ul>

<li>Identity: <code>id</code>, <code>deviceId</code>, <code>deviceCode</code>, <code>deviceName</code>, <code>tagId</code>, <code>tagCode</code>, <code>fullCode</code>, and <code>displayName</code>.</li>

<li>Content: <code>messageText</code>, <code>alarmKind</code>, <code>severity</code>, <code>state</code>, <code>displayValue</code>, and <code>quality</code>.</li>

<li>Times: <code>activeTs</code>, <code>recoverTs</code>, <code>closeTs</code>, <code>ackTs</code>, <code>shelvedUntil</code>, and <code>serverTs</code>.</li>

<li>Flags: <code>suppressed</code>; some items also carry <code>ackUserId</code>, <code>areaCode</code>, <code>objectIdentifier</code>, and <code>groupCode</code>.</li>

<li><code>count</code> is this page's item count and <code>hasMore</code> signals another page. Cursor paging avoids offset duplicates or gaps while alarms change.</li>

<li>The SDK provides alarm reads and subscriptions, but no acknowledge, shelve, or close operations.</li>

</ul>

</article>

<h3 id="custom-page-sdk-item-20">Navigation: parent, child, assets root and URL</h3>

Custom api.navigation.gotoPage and PPT hqVisuDesigner.openPage share resolution. Targets need not all be prelisted. Mapping provides names/breadcrumbs; explicit paths take precedence over same-name mappings.

<ul>

<li><code>gotoPage(target, options?)</code>: resolve ./, ../, child and sibling paths from the current screen URL; append .html to local extensionless paths. Navigate across folders while remaining under the assets root.</li>

<li>assets/<folder>/... and /assets/<folder>/... address the current Runtime Unit user assets root, including navigation from published or built-in screens. Other local relative paths in those sources retain their package boundary.</li>

<li><code>openUrl(target, options?)</code>: uses the same rules; write external targets as http://, https:// or //. Dotted folder names are not guessed to be domains. Preserve query/hash.</li>

<li><code>gotoAndon(target, options?)</code>: request an Andon/fullscreen host window.</li>

<li><code>gotoScreen(screenCode)</code>: navigate by screen menu code, not an arbitrary file path.</li>

<li>options: openInNewWindow, frameTarget, parameters:[{key,value}]. At most 64 parameters, keys ≤256 and values ≤2048 characters; read them with URLSearchParams.</li>

<li>Legal HTTP(S) addresses can navigate; third-party iframe embedding depends on its CSP/X-Frame-Options. Open Portal administration routes top-level/in a new window. External sites gain no Tag or Portal identity.</li>

<li>Reject escapes above assets, javascript:/data:/file:, backslashes and ambiguous encodings. Each destination HTML needs its own static data scope. true means dispatch, not confirmed target loading.</li>

</ul>

api.navigation.gotoPage("details/equipment", { parameters: [{ key: "device", value: "<device-code>" }] });

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

// In the destination page:

const device = new URLSearchParams(location.search).get("device");</code></pre></div>

</article>

<h3 id="custom-page-sdk-item-21">Device-popup API</h3>

<code>api.dialog.openDevicePopup(payload)</code> asks the Host to open the formal device popup; <code>api.dialog.close()</code> asks it to close the current Host dialog. Check <code>api.supports("popup")</code> and call from a real click. A true result means dispatched only.

<ul>

<li><code>plc</code> or <code>deviceCode</code> is required, and that PLC must have at least one Tag inside page read scope.</li>

<li>Optional <code>focusTagNames</code> contains at most 64 Tags, all inside page read scope.</li>

<li><code>templateCode</code> / <code>id</code> can select a popup template.</li>

<li><code>diagnosisControl</code> and <code>groupRightIndex</code> are optional popup context.</li>

<li>A device popup does not expand page read/write scope or expose popup service objects.</li>

<li>Configure bound Tags, controls, alarms and trend areas in Popup Templates first. Real Popup writes still enforce user permissions, control flags, quality and Host confirmation.</li>

</ul>

// and <button id="close-popup">Close</button> to the HTML.

// Place this code inside the existing ready() scope.

document.getElementById("open-popup").disabled = !api.supports("popup");

try {

const dispatched = api.dialog.openDevicePopup({

plc: "<device-code>",

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

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

});

if (dispatched !== true) throw new Error("Popup request was not dispatched");

// Verify the actual drawer and target Tag; true is not a load-complete receipt.

} catch (error) { document.getElementById("status").textContent = error.message; }

};

document.getElementById("close-popup").onclick = () => api.dialog.close();</code></pre></div>

</article>

<h3 id="custom-page-sdk-item-22">Complete monitoring page (optional)</h3>

This HTML includes a live value, one setpoint write, active alarms, and trend history. Replace Tags and declarations, and adjust the input range before publishing. Runtime supplies the SDK.

<details class="manual-code-disclosure"><summary>View complete source</summary><div class="manual-code" data-code-language="html"><div class="manual-code-toolbar">HTMLHTML<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: HTML">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><!doctype html>

<head>

<title>Mingcedar equipment monitor</title>

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

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

</script>

window.HQVISU_PAGE_META = { layoutMode: "native" };

window.HQVISU_PAGE_NAME = "equipment-monitor";

window.HQVISU_PAGE_ALARM = {

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

plcCodes: [], functionGroupCodes: [], deviceGroupCodes: [], signalGroupCodes: []

};

</script>

<style>

body { font: 16px/1.6 system-ui; margin: 24px; color: #16263c; }

section { margin-block: 24px; } button, input { font: inherit; padding: 8px; }

table { border-collapse: collapse; width: 100%; }

th, td { text-align: left; padding: 8px; border-bottom: 1px solid #d9e1eb; }

pre { white-space: pre-wrap; overflow-wrap: anywhere; }

</style>

</head>

<body>

<h1>Equipment monitor</h1>

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

<label>Target (0–100) <input id="setpoint" type="number" min="0" max="100" step="0.1"></label>

<button id="write" disabled>Write setpoint</button><pre id="write-result"></pre>

</section>

<section><h2>Active alarms</h2><button id="alarms" disabled>Refresh alarms</button><div id="alarm-list"></div><p id="alarm-status"></p></section>

<section><h2>Last hour</h2><button id="history" disabled>Query historical trend</button><div id="trend"></div><p id="trend-status"></p></section>

(async function () {

const element = (id) => document.getElementById(id);

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

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

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

let stopValues = () => {};

let stopAlarms = () => {};

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

});

function refreshValue() {

const quality = api.ReadTagQuality(processTag);

? String(value) : "Unavailable — quality: " + quality;

}

stopValues = api.subscribe([processTag, setpointTag], refreshValue);

refreshValue();

element("write").disabled = !(api.supports("tag.write") && await api.permissions.has("tag:write"));

const input = element("setpoint").value.trim();

if (!input || !Number.isFinite(value) || value < 0 || value > 100) {

}

if (!confirm("Write setpoint " + value + "?")) return;

try {

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

const done = result?.accepted === true && result?.status === "done" && result?.outcomeUncertain !== true && result?.operatorVerificationRequired !== true && result?.transportOnly !== true;

element("write-result").textContent = (done ? "Command completed; verify normal collected state: " : "Verify before another write: ") + JSON.stringify(result ?? null);

} catch (error) {

}

// Keep the button disabled after submission; refresh only after result reconciliation.

};

let alarmPending = false;

async function refreshAlarms() {

if (alarmPending) return;

alarmPending = true;

try {

const result = await api.alarms.getActive({limit: 100, offset: 0});

api.renderTable(element("alarm-list"), result.items, {columns: [

{key:"fullCode",label:"Tag"}, {key:"messageText",label:"Message"},

{key:"severity",label:"Severity"}, {key:"state",label:"State"}

]});

element("alarm-status").textContent = result.hasMore ? "Showing first 100 alarms; narrow the filter or request the next page." : "Current active alarms: " + result.count;

} catch (error) { element("alarm-status").textContent = error.message; }

finally { alarmPending = false; }

}

element("alarms").disabled = !api.supports("alarm.read");

stopAlarms = api.supports("alarm.read") ? api.alarms.subscribe(refreshAlarms) : () => {};

if (api.supports("alarm.read")) await refreshAlarms();

element("history").disabled = !api.supports("history.read");

element("history").onclick = async () => {

try {

const end = new Date();

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

interval:"1m", aggregate:"avg", points:1000});

const rows = (result.items || []).flatMap(series => (series.points || []).map(point => ({

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

})));

api.renderTable(element("trend"), rows);

element("trend-status").textContent = rows.length

? "Interval: " + result.effectiveInterval + (result.truncated ? " (adjusted to point budget)" : "")

: "No archived values in this time range.";

} catch (error) { element("trend-status").textContent = error.message; }

finally { element("history").disabled = false; }

};

})().catch(error => { document.getElementById("status").textContent = error.message; });

</script>

</body>

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

</article>

<h3 id="custom-page-sdk-item-23">renderTable and bindJsonTable</h3>

<code>api.renderTable</code> and global <code>HQVISU_CUSTOM_PAGE.renderTable</code> render arrays, <code>{ rows }</code>, or <code>{ items }</code> as HTML tables and return <code>{ rowCount, columnCount }</code>. <code>bindJsonTable</code> renders once, subscribes to a JSON Tag, and returns an unsubscribe function.

<ul>

<li><code>target</code> may be a CSS selector or DOM element.</li>

<li><code>options.columns</code> can be an array of strings or <code>{ key, label }</code> objects.</li>

<li>When columns are omitted, the SDK infers columns from the first 25 rows.</li>

<li><code>options.className</code> sets the table class; the page owns the CSS.</li>

<li>Cells are written through <code>textContent</code>, not executed as HTML. A missing target returns <code>{ rowCount: 0, columnCount: 0 }</code>.</li>

<li><code>bindJsonTable(target, tagName, options)</code> accepts array JSON, <code>{ rows }</code>, or <code>{ items }</code>; empty or invalid JSON renders an empty table. It renders the raw snapshot without filtering Tag quality. For a quality-aware table, subscribe, check ReadTagQualityGood in the callback, then call renderTable.</li>

<li>Complex sorting, pagination, frozen columns, and Excel export should be implemented by the project page or a table component.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>api.renderTable("#quality-table", {

rows: [

{ tag: "<device-code>.<temperature-tag-code>", value: "72.4", quality: "good" },

{ tag: "<device-code>.<pressure-tag-code>", value: "0.68", quality: "good" }

]

}, {

className: "report-table",

columns: [

{ key: "tag", label: "Tag" },

{ key: "value", label: "Current value" },

{ key: "quality", label: "Quality" }

]

});

const stopTable = api.bindJsonTable("#event-table", "<device-code>.<event-rows-tag-code>", {

columns: ["time", "type", "message"]

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

</article>

<h3 id="custom-page-sdk-item-24">Language: follow the system LANG control</h3>

Use the system LANG control without adding another selector. Render the current locale, then subscribe to changes. Translate display text; retain response data, raw Tag values, and command status codes.

<ul>

<li><code>language.current()</code> / <code>getLocale()</code> → string.</li>

<li><code>language.translate(key, fallback?)</code> / <code>t(key, fallback?)</code>; root api.translate/api.t are equivalent. Missing keys return fallback or the key if no fallback is given. Maintain business translation keys in system language configuration.</li>

<li><code>language.onChange((locale, translations) => ...)</code> / <code>subscribe(...)</code> → cleanup function; no automatic initial callback.</li>

<li><code>language.setLocale(locale)</code> → string | Promise<string>; affects system language, not component-local state. Page language controls should stay consistent with the system header.</li>

<li>Breadcrumb names come from static navigation declarations; PageApi has no dynamic rename method. Do not repeat handshakes to refresh them.</li>

</ul>

function renderText() {

const locale = api.language.current();

document.documentElement.lang = locale;

const fallback = locale.startsWith("zh") ? "设备总览" : "Equipment overview";

document.getElementById("title").textContent = api.t("equipment.overview.title", fallback);

}

renderText(); // onChange does not supply an initial callback.

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

// Call stopLanguage() in this page/component's existing cleanup handler.</code></pre></div>

</article>

<h3 id="custom-page-sdk-item-25">Local development with the Mock Host</h3>

The versioned <code>runtime-page-sdk-mock-host-v1.js</code> provides development data without Mingcedar. Create the Mock Host before loading <code>hq-common.js</code> and <code>hq-custom-page.js</code>. It tests rendering, subscription, and error states; it is not a security, permission, audit, write-confirmation, history-store, or PLC simulator.

<ul>

<li><code>createHQVisuMockHost(options)</code> returns a development Host.</li>

<li><code>options.values</code>, <code>meta</code>, <code>user</code>, <code>alarms</code>, and <code>locale</code> establish initial state.</li>

<li><code>queryHistory</code> and <code>queryAlarmHistory</code> can supply custom query results.</li>

<li><code>host.__mock.setTag(name, value, meta)</code> pushes a Tag change; <code>setAlarms(items)</code> pushes an alarm snapshot.</li>

<li>Delivery validation must return to Mingcedar Runtime and retest capability, ordinary-user permission, write confirmation, and real query limits.</li>

<li>Use the supplied development files for local Mock work. In production, load the SDK from the URL provided by Runtime; do not deploy the development copy of hq-common.js as a standalone package.</li>

</ul>

<div class="manual-code" data-code-language="html"><div class="manual-code-toolbar">HTMLHTML<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: HTML">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><script src="./runtime-page-sdk-mock-host-v1.js"></script>

window.HQVISU_HOST = createHQVisuMockHost({

values: { "<device-code>.<process-tag-code>": 72.4 },

meta: { "<device-code>.<process-tag-code>": { quality: "good" } },

user: {

username: "<operator-name>",

displayName: "Shift Operator",

permissions: []

}

});

</script>

</article>

<h3 id="custom-page-sdk-item-26">PPT and custom pages: one public read/write vocabulary</h3>

Custom pages use api.ReadTagInteger / api.WriteTagInteger; PPT uses ReadTagInteger / WriteTagInteger. Case, parsing, quality fallbacks, dates, and result handling match. Replace old names when upgrading.

<ul>

<li>Reads: ReadTag, ReadCalculatedTag, ReadTagBoolean/Integer/Double/String/Json/DateTime, ReadTagQuality, ReadTagQualityGood.</li>

<li>Writes: WriteTag, WriteTagBoolean/Integer/Double/String/Json/DateTime, WriteTagBit.</li>

<li>Reads return the current snapshot synchronously. Await writes and inspect the result. Business wrappers should preserve quality checks, permission checks, and command-result handling.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const api = await HQVISU_CUSTOM_PAGE.ready();

// PPT script reads the same name without the api prefix:

// const value = ReadTagInteger("<device-code>.<tag-code>", null);</code></pre></div>

</article>

<h3 id="custom-page-sdk-item-27">Error handling and delivery checks</h3>

Use fallback and quality for unavailable reads, and await/try-catch for initialization, writes, history and alarms. Writes may have no return value; undefined is not success. Retain error.code, error.message and an available commandId, never capability secrets.

<ul>

<li>Open the page as administrator and as an ordinary user to verify the permission boundary.</li>

<li>Try an undeclared Tag and verify a clear rejection or empty state without a blank page.</li>

<li>Simulate bad or stale quality and confirm the page does not display it as a normal value.</li>

<li>Verify history range, aggregate meaning, units, decimals, and chart explanations.</li>

<li>Verify writes include confirmation, failure messages, and an operation reason when required by the project.</li>

<li>Verify <code>outcome_uncertain</code> / <code>pending_verification</code> enters a blocking state and never retries automatically.</li>

<li>On component unmount, cancel its Tag, alarm, language and table subscriptions. Call api.destroy() only when the document permanently leaves (pagehide with !event.persisted), not during BFCache suspension or Vue unmount. Do not reuse subscriptions or pending requests after destruction.</li>

<li>Open the browser console and confirm there are no SDK initialization failures, 404s, JSON parse errors, or unhandled Promises.</li>

<li>Common errors: INVALID_ARGUMENT (input), CAPABILITY_DENIED (page scope/capability), PERMISSION_DENIED (user permission), NOT_FOUND, TIMEOUT, UNAVAILABLE, RUNTIME_WRITE_OUTCOME_UNCERTAIN and RUNTIME_PAGE_DESTROYED. Distinguish page readiness, service availability and Tag quality.</li>

</ul>

const history = await api.history.query({

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

start,

end,

interval: "1h",

aggregate: "sum"

});

renderTrend(history.items || []);

} catch (err) {

renderEmptyState("History query failed: " + err.message);

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

</article>

<h3 id="sdk-native-module">Native HTML module: a complete page</h3>

Save as equipment-overview.html and replace the Tag in both declaration and script. The mjs exports only ready and default {ready}; obtain methods such as ReadTagInteger from await ready(). The page is responsive and follows LANG.

<head>

<title>Mingcedar equipment overview</title>

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

</script>

</head>

<body>

<h1 id="title">Equipment overview</h1>

import { ready } from "/runtime/hqVisuDesigner/hq-custom-page.mjs";

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

const element = id => document.getElementById(id);

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

if (event.persisted) return;

disposed = true;

stopValue?.(); stopLanguage?.(); page?.destroy();

});

try {

page = await ready({ tags: [tag] });

if (!disposed) {

function render() {

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

document.documentElement.lang = page.language.current();

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

const quality = page.ReadTagQuality(tag);

element("value").textContent = quality === "good" && value !== null ? String(value) : "—";

element("status").textContent = (zh ? "数据质量：" : "Quality: ") + quality;

}

render();

stopValue = page.subscribe([tag], render);

}

} catch (error) {

if (!disposed) element("status").textContent = (error.code ? error.code + ": " : "") + error.message;

}

</script>

</body>

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

</article>

<h3 id="sdk-vue-entry">Vue integration 1: declare scope in entry HTML</h3>

Use this index.html in an existing Vue 3/Vite project. Bundle Vue from project dependencies; no CDN is needed. readableTags and writableTags must match the component prop. Call ready after onMounted in SSR, otherwise it rejects with RUNTIME_PAGE_BROWSER_REQUIRED.

<!doctype html>

<head>

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

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

</script>

</head>

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

</article>

<h3 id="sdk-vue-main">Vue integration 2: mount the component</h3>

Save as src/main.js. Match the prop, entry declaration and component binding to the approved numeric setpoint Tag. Remove write declarations and controls for a read-only project.

import { createApp } from "vue";

import EquipmentPanel from "./EquipmentPanel.vue";

createApp(EquipmentPanel, {

tagName: "<device-code>.<setpoint-tag-code>"

}).mount("#app");</code></pre></div>

</article>

<h3 id="sdk-vue-component">Vue integration 3: read, write once, LANG and unmount</h3>

Save as src/EquipmentPanel.vue. On unmount, cancel only component subscriptions; stop setup if unmounted while awaiting. Submission disables the button, but reloads or remounts reset it. Reconcile the previous command and normal collected value before another write; persist and restore pending-verification state if blocking must survive reloads.

<details class="manual-code-disclosure"><summary>View complete source</summary><div class="manual-code" data-code-language="vue"><div class="manual-code-toolbar">VueVue<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: Vue">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><script setup>

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

const props = defineProps({ tagName: { type: String, required: true } });

const tag = props.tagName; // Remount with a new key when changing this Tag.

const value = ref(null), quality = ref("bad"), locale = ref("en-US");

const target = ref(""), message = ref(""), canWrite = ref(false), submitted = ref(false);

let page, stopValue, stopLanguage, disposed = false, allowed = false;

const text = (zh, en) => locale.value.startsWith("zh") ? zh : en;

function render() {

value.value = page.ReadTagDouble(tag, null);

quality.value = page.ReadTagQuality(tag);

canWrite.value = allowed && quality.value === "good";

}

onMounted(async () => {

try {

const sdkUrl = "/runtime/hqVisuDesigner/hq-custom-page.mjs";

const { ready } = await import(/* @vite-ignore */ sdkUrl);

if (disposed) return;

page = api;

locale.value = page.language.current();

stopLanguage = page.language.onChange(next => { if (!disposed) locale.value = next; });

render();

allowed = page.supports("tag.write") && await page.auth.hasPermission("tag:write") === true;

} catch (error) {

}

});

onUnmounted(() => {

disposed = true;

stopValue?.(); stopLanguage?.();

// Do not destroy the shared document SDK on component unmount.

});

async function write() {

if (submitted.value || !canWrite.value) return;

const input = String(target.value).trim(), next = Number(input);

// Replace 0–100 with the approved engineering range for this Tag.

if (!input || !Number.isFinite(next) || next < 0 || next > 100) {

message.value = text("请输入 0–100 的数值", "Enter a number from 0 to 100"); return;

}

submitted.value = true;

try {

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

} catch (error) {

if (!disposed) message.value = text("结果未确认，核对后再操作：", "Result unconfirmed; reconcile before another operation: ") + error.message;

}

// Keep submission blocked until the operator reconciles command and collected state.

}

</script>

<h1>{{ text("设备设定值", "Equipment setpoint") }}</h1>

<p>{{ tag }}: {{ quality === "good" ? value : "—" }} · {{ quality }}</p>

<label>{{ text("目标值（0–100）", "Target (0–100)") }} <input v-model="target" type="number" step="0.1"></label>

<button :disabled="!canWrite || submitted" @click="write">{{ text("写入一次", "Write once") }}</button>

<pre role="status">{{ message }}</pre>

</section>

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

</article>

<h3 id="sdk-vue-deploy">Vue integration 4: build and publish</h3>

Keep the existing Vue plugin and set Vite base: "./" so output can live under any assets subfolder. The SDK uses an absolute /runtime/ service URL, independent of the relative application asset base.

<ol>

<li>Run the project npm run build; confirm dist/index.html retains the hqvisu-custom-page static JSON declaration.</li>

<li>Upload dist contents with the original hierarchy into one Screen Files directory, including index.html and built assets/*.js/CSS. Uploading only .vue sources or only index.html is insufficient.</li>

<li>Point the runtime menu to that directory index.html. Check SDK readiness, GOOD values, LANG changes, remounting and actual operation results.</li>

</ol>

export default defineConfig({ plugins: [vue()], base: "./" });</code></pre></div>

</article>

<h3 id="sdk-calendar-values">Dates and large integers: preserve meaning</h3>

DATE_AND_TIME, DTL and LDT metadata denotes a timezone-free PLC calendar. ReadTagDateTime returns a Date carrying those calendar fields in UTC, not an actual UTC instant; read fields with getUTC*. WriteTagDateTime(Date) writes the same UTC fields without Z. Other instant-style Date values retain ISO instant semantics.

<ul>

<li>A PLC calendar value 08:30 must remain 08:30 in Shanghai and other zones; do not interpret that calendar container with local getters or toLocaleString.</li>

<li>Date preserves milliseconds only; retain original text for DTL/LDT sub-millisecond precision. Date validity, year and encoding ranges remain device-type checks.</li>

<li>For integers outside JavaScript safe range, preserve text through ReadTag/ReadTagString and pass decimal text or BigInt to WriteTagInteger; do not first convert through Number.</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: JavaScript">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>const date = api.ReadTagDateTime("<device-code>.<datetime-tag-code>", null);

if (date) {

const fields = [date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate(),

date.getUTCHours(), date.getUTCMinutes(), date.getUTCSeconds()];

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

</article>

</div>