# General API

- Human documentation: [https://docs.univer.ai/guides/docs/features/core/general-api](https://docs.univer.ai/guides/docs/features/core/general-api)

- Agent Markdown: [https://docs.univer.ai/guides/docs/features/core/general-api.md](https://docs.univer.ai/guides/docs/features/core/general-api.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [docs/features/core/general-api.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/features/core/general-api.mdx)

---

The Facade API available in Univer depends on the current unit type and the plugins you register. This page covers the common APIs used in a Univer Docs application.

## Importing

```typescript
import { FUniver } from '@univerjs/core/facade'

const univerAPI = FUniver.newAPI(univer)
```

## Commands

Most operations in Univer are registered with the command system. This unified execution path supports features such as undo, redo, and collaboration.

> [!NOTE]
> For more details on the design, see the [Univer command system](/blog/univer#command-system).

### Listening to commands

Use `Event.BeforeCommandExecute` to run logic before a command, or `Event.CommandExecuted` to run logic after it finishes.

```typescript
const beforeDisposable = univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, ({ id, params }) => {
  console.log('Before command:', id, params)
})

const afterDisposable = univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id, params }) => {
  console.log('Command executed:', id, params)
})
```

To prevent a command from running, set `event.cancel` to `true` in a `BeforeCommandExecute` listener.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, (event) => {
  if (event.id === 'doc.command.set-name') {
    event.cancel = true
  }
})
```

Event listeners return an `IDisposable`. Dispose listeners when you no longer need them.

```typescript
beforeDisposable.dispose()
afterDisposable.dispose()
disposable.dispose()
```

### Executing commands

If you know a command ID and its parameters, run it with `FUniver.executeCommand`. For example, the following Docs command renames the active document:

```typescript
const document = univerAPI.getActiveDocument()

if (document) {
  await univerAPI.executeCommand('doc.command.set-name', {
    unitId: document.getId(),
    name: 'Project Notes',
  })
}
```

## Events API

The event names exposed through `univerAPI.Event` come from Univer core and the plugins registered in the current application. Core provides command and document lifecycle events, while Docs plugins can extend the event surface with their own events. Check that an event belongs to a plugin you have registered before using it.

See the [Facade Events reference](https://docs.univer.ai/reference/facade/events.md#available-event-names) for the event names and parameter types available in the current release.

Use `addEvent` to subscribe and dispose the returned object to unsubscribe:

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id }) => {
  if (id === 'doc.command.set-name') {
    console.log('The document name changed')
  }
})

// Remove the listener when it is no longer needed
disposable.dispose()
```

## Undo and Redo

```typescript
await univerAPI.undo()
await univerAPI.redo()
```

## System Clipboard

After the Docs UI plugin is registered, `copy` and `paste` operate on the current document selection and caret position.

```typescript
await univerAPI.copy()
await univerAPI.paste()
```

> [!NOTE]
> Copy and paste rely on the browser's native clipboard API. They can fail when the page does not have focus, the call is
> not initiated by a user action, or clipboard permission is unavailable. See the [MDN clipboard
> documentation](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API).

## UI

See [Docs UI components](https://docs.univer.ai/guides/docs/ui/components.md) to learn how to extend menus, the toolbar, and other Docs interface areas.

## WebSocket

Preset installations expose `univerAPI.createSocket(url)`. In plugin mode, install `@univerjs/network`, register `UniverNetworkPlugin`, and import its Facade extension first.

```typescript
import { UniverNetworkPlugin } from '@univerjs/network'
import '@univerjs/network/facade'

univer.registerPlugin(UniverNetworkPlugin)
```

You can then subscribe to socket events, send messages, and close the connection:

```typescript
const socket = univerAPI.createSocket('wss://example.com/docs')

socket.open$.subscribe(() => {
  socket.send('hello')
})

socket.message$.subscribe((message) => {
  console.log('WebSocket message:', message.data)
})

socket.error$.subscribe((error) => {
  console.error('WebSocket error:', error)
})

socket.close()
```

## Enum API

Facade exposes common enum types through `univerAPI.Enum`:

```typescript
console.log(univerAPI.Enum.UniverInstanceType.UNIVER_DOC)
console.log(univerAPI.Enum.LifecycleStages.Rendered)
```

## Utility Method API

Facade exposes shared utilities through `univerAPI.Util`:

```typescript
console.log(univerAPI.Util.tools.isString('Univer Docs')) // true
```