Events and connection status

Handle events pushed by the add-on and recognize connection establishment, disconnection, and invalidation.

Events announce occurrences

Export just finished suits an event; current export progress suits state. Events are not rereadable tables. Newly opened pages should query current state rather than reconstruct everything from the last event.

Emit where work actually completes

Python; plugin is a bound handle

python

plugin.bridge().event.emit("plugin.my_addon.job_done", {"name": "导出"})

Place the call on the real completion path, not at page load or task start. Payloads must be JSON-compatible. Sending a notification does not execute a background task.

Retain the subscription handle

Put this function in an external script and call from the component. output is an existing status element. Retain the handle and await handle.release() on exit.

Event subscription function

javascript

async function listenForCompletion(output) {
  const webui = window.acquireNexusWebUI();
  return await webui.event.on("plugin.my_addon.job_done", (payload, meta) => {
    output.textContent = meta.dropped
      ? "部分通知已丢弃，请重新读取任务状态。"
      : `${payload.name}已完成。`;
  });
}

Handle subscription failure. If the component is destroyed while awaiting the handle, release it when it arrives. meta.dropped means older notifications were discarded; reread actual state rather than treating event count as task count.

Connection readiness is not task completion

Signal	How the page should interpret it
ready	Connection ready; application data still needs reading.
stale	Session information is stale; old data is no longer current.
disconnected	Disconnected; show a message and pause connection-dependent operations.
reconnected	Reconnected; check current state before continuing.
session_closed	Session closed; end its interactions and listeners.

Register through webui.lifecycle.on and clean up the handle with release. Do not indiscriminately duplicate listeners on every recovery.

Acquire the SDK correctly

Connection entry point for trusted local pages

javascript

const webui = window.acquireNexusWebUI();
await webui.ready();

Use this in an existing async initialization function and handle failure. whenNexusWebUIReady returns readiness information, not the SDK; do not call action or state on its result. Ordinary browsers and development servers lack this bridge. See Local page restrictions.

Check closure and recovery boundaries

Completion notifications appear only after actual success; failures are reported as failures.
Reopened pages obtain current results through state without waiting for another event.
Repeated component mounting does not duplicate notifications.
Disconnects do not automatically resend side effects. Save and restart normally when required.

Based on advanced usage and public lifecycle types.

Back to User guide · All topics