跳到主要内容

Wiki.macro.saveData

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. 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​

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

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

Parameters​

ParameterTypeRequiredDescription
contentWikiMacroContentYesComplete replacement, not a patch
content.customDataWikiMacroJSONYesConfiguration, at most 32 KiB; use null when empty
content.exportSpecWikiMacroExportSpec[]YesOrdered static text, links and images; use [] when empty
content.resourcesstring[]YesDocument 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 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.

The render entry cannot save even if writable is true. Viewing-mode business data belongs to the app; use backend static updates to publish business results.

Errors​

Error codeMeaning and triggerRecommended handling
INVALID_JSONcustomData 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_LARGESerialized 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_SPECInvalid 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 and correct entries, resource IDs and size. The resource set after merging image references must also remain within the limits.
READ_ONLYCalled 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_EXPIREDThere 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_ACCESSIBLEAn 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_CONFLICTThe 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_UNKNOWNThe 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_FAILEDMacro 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_UNAVAILABLEThe 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 for the error object contract.

Examples​

Install via package manager​

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​

<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>