# Wiki.macro.openEditor

URL: https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-open-editor

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

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

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `options` | `object` | Yes | Parameters for the action |
| `options.actionId` | `string` | Yes | An ID declared in `config.actions[].id` , not a button label |
| `options.customParams` | [`WikiMacroJSON`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-types/#wikimacrojson) | No | Temporary 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 code | Meaning and trigger | Recommended handling |
| --- | --- | --- |
| `INVALID_JSON` | `customParams` 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_LARGE` | The serialized UTF-8 size of `customParams` exceeds 32 KiB. | Reduce the temporary parameters; do not use them for large business payloads. |
| `READ_ONLY` | The 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_CONFLICT` | The 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_EXPIRED` | The 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_CONFLICT` | Collaboration 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_UNKNOWN` | The 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_UNAVAILABLE` | `actionId` 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](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 { 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

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

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