跳到主要内容

Wiki.macro.openEditor

Open a declared configuration action from the macro render entry. Wiki checks document editing access, acquires a collaboration lock and loads the edit entry.

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 { WikiMacroJSON } from '@ones-open/web-sdk'

interface MacroAPI {
  openEditor(options: { actionId: string; customParams?: WikiMacroJSON }): Promise<void>
}

Parameters​

ParameterTypeRequiredDescription
optionsobjectYesParameters for the action
options.actionIdstringYesAn ID declared in config.actions[].id, not a button label
options.customParamsWikiMacroJSONNoTemporary edit-entry parameters, such as an initial tab. Must be JSON, at most 32 KiB

The edit entry reads these values from context.toolbarState when state === 'editing'. actionId identifies the action; customParams may be undefined when omitted. Parameters are not automatically saved in customData.

Returns and behavior​

Promise<void> resolves after acquiring the edit session and initiating entry loading. It does not mean the user has saved or finished, and returns neither form data nor a dialog instance.

Use only in page edit mode when the macro is writable. Viewing, history, missing edit permission or another session's lock prevents opening. writable describes document configuration access, not app business permissions.

Errors​

Error codeMeaning and triggerRecommended handling
INVALID_JSONcustomParams is not a valid JSON value, for example it contains undefined, a function, a circular reference, a Date or a non-finite number.Pass data that conforms to WikiMacroJSON.
DATA_TOO_LARGEThe serialized UTF-8 size of customParams exceeds 32 KiB.Reduce the temporary parameters; do not use them for large business payloads.
READ_ONLYThe macro is not writable: the page is in viewing or history mode, the user cannot edit, another session holds the lock, or login credentials are unavailable.Disable configuration based on current context; restore access or sign in before opening again.
LOCK_CONFLICTThe macro already has an edit session, or another session acquired the lock before this request reached the server.Do not open another dialog; wait for the existing session to finish or release the lock.
SESSION_EXPIREDThe session became invalid during acquisition, for example because the page was destroyed or the document service changed.Start editing again once the page is available.
REVISION_CONFLICTCollaboration state changed while the edit session was being created, so the request's state is no longer current.Reload current page and macro state before opening again.
COMMIT_UNKNOWNThe acquisition result is unconfirmed, for example after a timeout, a lost connection or while the server confirms an earlier operation. The lock may already have been acquired.Keep current content and retry the same open operation; Wiki continues confirming the original request.
MACRO_UNAVAILABLEactionId is not declared in config.actions; the runtime is missing or the entry does not match; the macro, app or a dependency is unavailable; or card retrieval or availability authorization failed.Check the action ID and app configuration; retry after recovery and contact an administrator if the problem persists.

Disable repeated clicks during the call. 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 openConfiguration() {
  const context = await ONES.getExtensionContext<WikiMacroContext>()
  if (context.scene !== 'edit' || !context.writable || context.toolbarState.state !== 'init') return

  try {
    await Wiki.macro.openEditor({ actionId: 'configure', customParams: { tab: 'content' } })
  } catch (error) {
    console.error(error)
  }
}

Read temporary parameters in the edit entry​

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

const context = await ONES.getExtensionContext<WikiMacroContext>()
if (context.toolbarState.state === 'editing') {
  console.log(context.toolbarState.actionId, context.toolbarState.customParams)
}

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.openEditor({
      actionId: 'configure',
      customParams: { tab: 'content' },
    })
  })().catch(console.error)
</script>