# Wiki.macro.saveData

URL: https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-save-data

Save complete macro configuration, static content and resource references while keeping the edit session open. Only the macro edit entry may call this method.

## Requirements

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

Declare and enable a [Wiki custom macro](https://docs.ones.cn/developer/abilities/extensions/wiki-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

```ts
import type { WikiMacroContent } from '@ones-open/web-sdk'

interface MacroAPI {
  saveData(content: WikiMacroContent): Promise<void>
}
```

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | [`WikiMacroContent`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-types/#wikimacrocontent) | Yes | Complete replacement, not a patch |
| `content.customData` | [`WikiMacroJSON`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-types/#wikimacrojson) | Yes | Configuration, at most 32 KiB; use `null` when empty |
| `content.exportSpec` | [`WikiMacroExportSpec[]`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-types/#wikimacroexportspec) | Yes | Ordered static text, links and images; use `[]` when empty |
| `content.resources` | `string[]` | Yes | Document resource IDs to retain; use `[]` when empty |

`exportSpec` and `resources` each allow up to 1000 entries; their combined JSON must not exceed 1 MiB in UTF-8. Static image references are merged into the resource set. Resources must be available to the current document.

## Returns and behavior

`Promise<void>` resolves only when interactive data and card static content are confirmed saved. It does not return updated context; subscribe to [`ONES.getExtensionContext`](https://docs.ones.cn/developer/abilities/web-sdk/get-extension-context/) for changes.

Saving participates in document revisions but does not publish the Wiki page. Multiple saves become one undo action when editing finishes. Cancel restores the pre-session content, including confirmed saves. Wait for saving to succeed before calling [`finishEdit`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-finish-edit/) .

The render entry cannot save even if `writable` is `true` . Viewing-mode business data belongs to the app; use [backend static updates](https://docs.ones.cn/developer/abilities/extensions/wiki-macro/#update-static-content-from-the-app-backend) to publish business results.

## Errors

| Error code | Meaning and trigger | Recommended handling |
| --- | --- | --- |
| `INVALID_JSON` | `customData` is missing, or the content contains non-JSON values such as `undefined` , functions, circular references, `Date` , `NaN` or `Infinity` . The host also validates the resource array structure. | Submit complete `WikiMacroContent` ; use `customData: null` when there is no configuration. |
| `DATA_TOO_LARGE` | Serialized UTF-8 `customData` exceeds 32 KiB, or the SDK detects that combined serialized `exportSpec` and `resources` exceed 1 MiB. | Reduce the relevant fields and reference files by resource ID. |
| `INVALID_EXPORT_SPEC` | Invalid `exportSpec` or `resources` structure, unsupported static entries or fields, invalid HTTP/HTTPS/mailto links, image URLs instead of document resource IDs, more than 1000 entries, or the host/server detects static content and resource references above 1 MiB. | Follow the [static content types](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-types/#wikimacroexportspec) and correct entries, resource IDs and size. The resource set after merging image references must also remain within the limits. |
| `READ_ONLY` | Called from the render entry; the page is in viewing/history mode; the macro is not writable, edit permission was lost or login credentials are unavailable. | Save only from a writable macro edit entry; retain the form while access is unavailable. |
| `SESSION_EXPIRED` | There is no active edit session, or it has finished, been cancelled, expired or become invalid after page destruction or a document service change. | Keep unsaved content, reopen editing and read current configuration; ask the user to confirm before resubmitting. |
| `RESOURCE_NOT_ACCESSIBLE` | An ID in `resources` or a static image is not a valid document file identifier, or the file is missing, belongs to another document or cannot be read by this document. | Use IDs uploaded for this document; upload missing files again or remove invalid references. |
| `REVISION_CONFLICT` | The macro revision no longer matches the save request, or another operation changed the session state. | Read current configuration and let the user review differences; do not repeatedly overwrite it with stale content. |
| `COMMIT_UNKNOWN` | The save result is unconfirmed, for example after a timeout, a lost response or while the server confirms a write. Data may already have been saved. | Keep the draft and retry `saveData` with exactly the same content. Do not call `finishEdit` , close the dialog or submit different content yet. |
| `CARD_UPDATE_FAILED` | Macro data in the document is confirmed saved, but card `exportSpec` and resource references could not be synchronized, or required card information is missing. Public sharing and exports may still show older content. | Retry `saveData` with exactly the same content to complete card synchronization; do not report full success until synchronization succeeds. |
| `MACRO_UNAVAILABLE` | The runtime is missing or the entry does not match; the macro block no longer exists; the app, macro or a dependency is unavailable; or server availability authorization failed. | Retain the draft, check that the app and macro remain enabled, and verify current page and session state after recovery. |

The SDK, host and server can reject the same invalid content at different validation stages; do not rely on a single error code to validate a field. For `COMMIT_UNKNOWN` and `CARD_UPDATE_FAILED` , Wiki retains the original request identifier for retries; apps do not generate request IDs. Catch failures with `try / catch` ; see [Catching errors](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-types/#calling-and-catching-errors) for the error object contract.

## Examples

### Install via package manager

```ts
import { Wiki } from '@ones-open/web-sdk'
import type { WikiMacroContent } from '@ones-open/web-sdk'

async function saveAndFinish(title: string) {
  const content: WikiMacroContent = {
    customData: { title },
    exportSpec: [
      { type: 'text', data: title },
      { type: 'link', data: { title: 'Details', url: 'https://example.com/details' } },
    ],
    resources: [],
  }
  try {
    await Wiki.macro.saveData(content)
    await Wiki.macro.finishEdit()
  } catch (error) {
    console.error(error)
  }
}
```

### Use via external script

```html
<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.saveData({
      customData: { title: 'Note' },
      exportSpec: [{ type: 'text', data: 'Note' }],
      resources: [],
    })
  })().catch(console.error)
</script>
```

## Related documentation

- [Macro types and fields](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-types/)
- [ONES.getExtensionContext](https://docs.ones.cn/developer/abilities/web-sdk/get-extension-context/)
- [Wiki custom macro capability](https://docs.ones.cn/developer/abilities/extensions/wiki-macro/)