# ONES.getExtensionContext

URL: https://docs.ones.cn/developer/abilities/web-sdk/get-extension-context

Read the current extension entry context or subscribe to changes. The extension defines its context shape; Wiki macros use [`WikiMacroContext`](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-types/#wikimacrocontext) . The generic provides TypeScript checking, not runtime conversion or validation.

## Requirements

| Usage | ONES | Web SDK |
| --- | --- | --- |
| General extension context | `6.101.0+` | Use the SDK matching the environment |
| Wiki macro context described here | `7.45.0+` | `@ones-open/web-sdk@0.0.20+` |

## Signature

```ts
type SetState<T> = (context: T) => void
type Cleanup = () => void

interface ContextAPI {
  getExtensionContext<ExtensionContext = any>(): Promise<ExtensionContext>
  getExtensionContext<ExtensionContext = any>(setState: SetState<ExtensionContext>): Cleanup
}
```

`SetState` , `Cleanup` and `ContextAPI` illustrate the signature; they are not named SDK exports. Call `ONES.getExtensionContext` in your app.

## Parameters and callback

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `ExtensionContext` | Generic, defaults to `any` | No | The extension context type, such as `WikiMacroContext` |
| `setState` | `(context: ExtensionContext) => void` | No | Supplying it subscribes; omitting it reads once |
| Callback argument `context` | `ExtensionContext` | Supplied for every callback | The complete current context, not a patch or DOM event |
| Callback return value | `void` | — | Not consumed by the host; callbacks do not save data |

Wiki macro callback fields include identity, document version, `scene` , `platform` , `writable` , `customData` , `resources` and `toolbarState` . See [WikiMacroContext](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-types/#wikimacrocontext) for every field and union type. No previous-value, error or other event arguments are supplied.

## Returns

| Invocation | Return type | Description |
| --- | --- | --- |
| Without callback | `Promise<ExtensionContext>` | Reads once, without subscribing |
| With callback | `Cleanup` , or `() => void` | Synchronously returns a cleanup function, not a Promise |
| Calling cleanup | `void` | Removes this subscription; does not save, close or cancel editing |

After subscription starts, the callback asynchronously receives current context, then receives updates when the host changes that entry's context. Do not assume a fixed frequency, count or one notification per save. Configuration, edit state, permissions and collaboration may trigger updates. App database changes do not automatically trigger them.

Call cleanup on component or page destruction. Do not use `await` on the subscription to obtain context; read it in the callback. Handle errors from any asynchronous business requests in your app.

## Read context once

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

async function readContext() {
  const context = await ONES.getExtensionContext<WikiMacroContext>()
  console.log(context.customData, context.scene, context.writable)
  if (context.toolbarState.state === 'editing') {
    console.log(context.toolbarState.actionId, context.toolbarState.customParams)
  }
}
```

## Subscribe to context

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

function onContextChange(context: WikiMacroContext): void {
  const canConfigure =
    context.scene === 'edit' && context.writable && context.toolbarState.state === 'init'
  console.log({ canConfigure, customData: context.customData, resources: context.resources })
}

const unsubscribe: () => void = ONES.getExtensionContext<WikiMacroContext>(onContextChange)
window.addEventListener('pagehide', unsubscribe, { once: true })
// In a single-page app, also call unsubscribe() when this component or entry is destroyed.
```

## Use via external script

```html
<script src="https://unpkg.com/@ones-open/web-sdk@0.0.20/dist/index.iife.js"></script>
<script>
  const unsubscribe = window.SDK.ONES.getExtensionContext(function (context) {
    console.log(context.scene, context.writable, context.customData)
  })
  window.addEventListener('pagehide', unsubscribe, { once: true })
</script>
```

## Wiki macro scene notes

Reading and subscribing do not save the document or return card `exportSpec` . Render and edit entries can each subscribe to their instance. Public sharing, mobile and search do not run macros or emit callbacks. History supplies historical document configuration; disable configuration and business writes there. In normal viewing, `writable: false` does not by itself prohibit business operations; the app backend validates business permissions.