跳到主要内容

Wiki.macro.setStatus

Report macro display status to Wiki. If saved data or referenced resources cannot be rendered, the app can ask the host to show static content.

Requirements​

ONES@ones-open/web-sdk
7.45.0+0.0.20+

Declare and enable a Wiki custom macro. Each method targets the calling entry's macro instance and does not accept another macro's ID. Public sharing, mobile and search do not load the macro runtime and cannot call these methods.

Signature​

interface MacroAPI {
  setStatus(status: 'valid' | 'dataInvalid' | 'resourceInvalid'): Promise<void>
}

Parameters​

ValueTypeMeaning
'valid'String literalCurrent macro data and resources can be displayed
'dataInvalid'String literalThe app cannot interpret or display the saved data
'resourceInvalid'String literalReferenced resources are unavailable and prevent display

status is required and only accepts these values. There is no status callback parameter, and context subscriptions do not add a status field.

Returns and behavior​

Promise<void> resolves when the host accepts the report; no static content or updated macro data is returned.

dataInvalid and resourceInvalid trigger host static fallback without clearing saved data, writing exportSpec or adding a page version. The runtime may stop after fallback; do not rely on another valid call to automatically reload it. Reopen the page after fixing data or resources.

This is not a save API. Show app-owned loading UI while business requests are pending rather than reporting invalid data.

Errors​

Error codeMeaning and triggerRecommended handling
INVALID_JSONstatus is not one of the strings valid, dataInvalid or resourceInvalid, for example undefined, a misspelled value or an object.Pass one of the three values declared in the signature.
MACRO_UNAVAILABLEThe entry has no bound macro runtime or does not match the macro instance. Further calls can also fail after fallback unmounts the runtime.Report only from an active macro entry; do not rely on an unmounted entry calling valid to restore rendering.

Wrap the complete call in try / catch; see Catching errors for the error object contract.

Examples​

Install via package manager​

import { ONES, Wiki } from '@ones-open/web-sdk'
import type { WikiMacroContext } from '@ones-open/web-sdk'

async function checkSavedContent() {
  const context = await ONES.getExtensionContext<WikiMacroContext>()
  const value = context.customData
  const supported =
    value !== null &&
    typeof value === 'object' &&
    !Array.isArray(value) &&
    typeof value.title === 'string'
  await Wiki.macro.setStatus(supported ? 'valid' : 'dataInvalid')
}

Use via external script​

<script src="https://unpkg.com/@ones-open/web-sdk@0.0.20/dist/index.iife.js"></script>
<script>
  ;(async function () {
    await window.SDK.Wiki.macro.setStatus('dataInvalid')
  })().catch(console.error)
</script>