Wiki macro types

These types are exported directly from @ones-open/web-sdk, for ONES 7.45.0+ and Web SDK 0.0.20+. Callback and cleanup aliases used in examples are local declarations, not additional package exports.

import type {
  WikiMacroJSON,
  WikiMacroExportSpec,
  WikiMacroContent,
  WikiMacroContext,
  WikiMacroSDK,
} from '@ones-open/web-sdk'

Type declarations

type WikiMacroJSON =
  | null
  | boolean
  | number
  | string
  | WikiMacroJSON[]
  | { [key: string]: WikiMacroJSON }

type WikiMacroExportSpec =
  | { type: 'text'; data: string }
  | { type: 'link'; data: { title: string; url: string } }
  | { type: 'image'; data: string }

interface WikiMacroContent {
  customData: WikiMacroJSON
  exportSpec: WikiMacroExportSpec[]
  resources: string[]
}

interface WikiMacroContext extends Omit<WikiMacroContent, 'exportSpec'> {
  protocolVersion: 2
  appId: string
  installationId: string
  macroKey: string
  cardUuid: string
  teamId: string
  documentId: string
  pageId: string
  blockId: string
  documentVersion: number
  scene: 'edit' | 'view' | 'history' | 'publicShare'
  platform: 'desktop' | 'mobile'
  writable: boolean
  isInsertedByCurrentUser: boolean
  serviceId: string
  toolbarState:
    | { state: 'init' }
    | { state: 'editing'; actionId: string; customParams?: WikiMacroJSON }
}

interface WikiMacroSDK {
  openEditor(options: { actionId: string; customParams?: WikiMacroJSON }): Promise<void>
  saveData(content: WikiMacroContent): Promise<void>
  finishEdit(): Promise<void>
  cancelEdit(): Promise<void>
  uploadResource(file: File): Promise<string>
  setStatus(status: 'valid' | 'dataInvalid' | 'resourceInvalid'): Promise<void>
}

WikiMacroJSON

Allows null, booleans, finite numbers, strings, JSON arrays and plain objects. Rejects undefined, functions, Symbol, BigInt, NaN, Infinity, circular references, Date, accessors and sparse arrays. Convert dates to strings first. customData JSON is limited to 32 KiB in UTF-8; openEditor.customParams uses the same JSON validation.

WikiMacroExportSpec

A discriminated union on type. Fields are listed below; array order determines static display order.

type	data type	Nested fields	Description
'text'	string	None	Plain text with line breaks, not HTML. Empty strings are allowed
'link'	{ title: string; url: string }	Both data.title: string and data.url: string are required	Displays a link title; only http:, https: and mailto: URLs are allowed
'image'	string	None	Image resource ID available to the document, usually returned by uploadResource. Do not save local paths or data: URLs from the frontend

Image IDs are merged into resource references. Backend static publishing may also use HTTPS image URLs; see the macro guide.

WikiMacroContent

Field	Type	Required	Description
customData	WikiMacroJSON	Yes	Document configuration; null when empty
exportSpec	WikiMacroExportSpec[]	Yes	Complete static output; an empty array clears it
resources	string[]	Yes	Document resource IDs to retain; [] when empty

saveData replaces the complete content. Include every value that must be retained. exportSpec and resources each allow up to 1000 entries; their combined JSON is limited to 1 MiB in UTF-8.

WikiMacroContext

The Promise result and subscription callback use the same context type. All fields below are required in the type; only toolbarState.customParams is optional within editing state.

Field	Type	Description
protocolVersion	2	Always 2, the macro context protocol.
appId	string	App identifier.
installationId	string	App installation identifier in the organization.
macroKey	string	Macro key declared by the app.
cardUuid	string	Wiki card ID used to bind backend static updates to this instance.
teamId	string	Team containing the macro.
documentId	string	Collaborative document ID; distinct from the Wiki page ID.
pageId	string	Wiki page ID.
blockId	string	Macro block ID in the document.
documentVersion	number	Current collaborative revision or viewed historical version.
scene	'edit' | 'view' | 'history' | 'publicShare'	Page scene; edit alone does not grant save access. Also check the entry and writable.
platform	'desktop' | 'mobile'	Host platform. The current interactive runtime uses desktop.
writable	boolean	Whether this session can edit macro configuration. Permissions, readonly state and locks may change it. Not an app business permission.
isInsertedByCurrentUser	boolean	Whether the current editing client inserted the macro. Useful for initialization, not authorization.
serviceId	string	Host collaborative service identifier. Usually not needed by apps; not an authentication credential.
customData	WikiMacroJSON	Macro configuration from the document version, not live data from the app business database.
resources	string[]	Macro resource IDs saved in the document version.
toolbarState	工具栏状态	Editing state for this session, detailed below.

Context does not contain exportSpec or app database records. publicShare and mobile are values supported by the type; current public sharing, mobile and search use static content and do not load app entries or emit those context callbacks. Historical versions run the render entry with scene: history; disable business writes.

toolbarState

state	Other fields	Meaning
'init'	No actionId or customParams	This session is not configuring the macro
'editing'	Required actionId: string; optional customParams?: WikiMacroJSON	This session opened a declared configuration action

Narrow on state before reading actionId or customParams. Lock owner and expiry are not exposed. Update configuration buttons using the subscribed writable value.

WikiMacroSDK

Member	Parameters	Return value
openEditor	options: { actionId: string; customParams?: WikiMacroJSON }	Promise<void>
saveData	content: WikiMacroContent	Promise<void>
finishEdit	—	Promise<void>
cancelEdit	—	Promise<void>
uploadResource	file: File	Promise<string>
setStatus	status: 'valid' | 'dataInvalid' | 'resourceInvalid'	Promise<void>

Use the interface through Wiki.macro and import types with import type. None of these six methods accepts a callback; handle results and failures through Promises. For context updates use ONES.getExtensionContext(callback).

Content type example

import type { WikiMacroContent, WikiMacroExportSpec } from '@ones-open/web-sdk'

const exportSpec: WikiMacroExportSpec[] = [
  { type: 'text', data: 'Project summary' },
  { type: 'link', data: { title: 'Details', url: 'https://example.com/details' } },
]
const content: WikiMacroContent = {
  customData: { title: 'Project summary', recordId: 'record-001' },
  exportSpec,
  resources: [],
}
console.log(content)

Calling and catching errors

Wrap method calls in try / catch. Accessing a Wiki.macro member can itself throw MACRO_UNAVAILABLE when the runtime is not registered or the entry does not match. Do not rely only on an earlier permission or context read. The SDK does not export a dedicated macro error class or guarantee a uniform code field.