# Wiki macro types

URL: https://docs.ones.cn/developer/abilities/web-sdk/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.

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

## Type declarations

```ts
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](https://docs.ones.cn/developer/abilities/extensions/wiki-macro/#update-static-content-from-the-app-backend) .

## 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`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-save-data/) 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`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-open-editor/) | `options: { actionId: string; customParams?: WikiMacroJSON }` | `Promise<void>` |
| [`saveData`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-save-data/) | `content: WikiMacroContent` | `Promise<void>` |
| [`finishEdit`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-finish-edit/) | — | `Promise<void>` |
| [`cancelEdit`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-cancel-edit/) | — | `Promise<void>` |
| [`uploadResource`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-upload-resource/) | `file: File` | `Promise<string>` |
| [`setStatus`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-set-status/) | `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)`](https://docs.ones.cn/developer/abilities/web-sdk/get-extension-context/) .

## Content type example

```ts
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.