# General API

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [bases/features/core/general-api.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/bases/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 Bases application.

## Importing

```typescript
import { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/bases/facade'
import '@univerjs/ui/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 === 'base.command.set-base-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 Bases command renames the active Base:

```typescript
const base = univerAPI.getActiveBase()

if (base) {
  await univerAPI.executeCommand('base.command.set-base-name', {
    unitId: base.getId(),
    name: 'Product Tracker',
  })
}
```

## Events API

The event names exposed through `univerAPI.Event` come from Univer core and the plugins registered in the current application. Core provides shared command and unit events; Bases plugins add events for tables, fields, records, views, and other Base changes. 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 === 'base.command.set-base-name') {
    console.log('The Base 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 Bases UI plugin is registered, `copy` and `paste` operate on the current Base 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 [Bases UI components](https://docs.univer.ai/guides/bases/ui/components.md) to learn how to extend menus, the toolbar, and other Bases interface areas.

## WebSocket

To use WebSocket APIs, install `@univerjs/network`, register `UniverNetworkPlugin`, and import its Facade extension.

```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/bases')

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_BASE)
console.log(univerAPI.Enum.BaseFieldType.Text)
```

## Utility Method API

Facade exposes shared utilities through `univerAPI.Util`:

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