# FCollaboration

> Language fallback: requested `ko-KR`; content is `en-US`.

- Human documentation: [https://docs.univer.ai/ko-KR/reference/facade/collaboration](https://docs.univer.ai/ko-KR/reference/facade/collaboration)

- Agent Markdown: [https://docs.univer.ai/ko-KR/reference/facade/collaboration.md](https://docs.univer.ai/ko-KR/reference/facade/collaboration.md)

- Requested language: `ko-KR`

- Content language: `en-US`

- Documentation version: `1.0.4`

- Source: [facade/collaboration.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/collaboration.mdx)

---

The Facade API object for the Collaboration module. It provides methods to interact with the
Univer Collaboration backend server, such as loading Univer Sheets and subscribing to collaborators.

## Access

Access through:

* [`FUniver.getCollaboration()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#getcollaboration)

## Setup

Register [`@univerjs-pro/collaboration-client`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/collaboration-client.md) or a preset that includes it. In plugin mode, import `@univerjs-pro/collaboration-client/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/facade.md).

## `@univerjs-pro/collaboration-client`

### `FCollaboration.flush`

Wait until all currently queued collaboration changes for a unit are synchronized.

This is intended as an explicit barrier for scripts, agents, and tests after a batch of
facade mutations. It does not make individual facade APIs asynchronous.

```typescript
flush(unitId?: string, options?: ICollaborationFlushOptions): Promise<void>
```

**Parameters**

* `unitId` — Optional. Optional unit ID. If omitted, uses the focused unit.
* `options` — Optional. Default: `{}`. Optional timeout configuration.

**Returns**

Resolves when the unit reaches CollaborationStatus.SYNCED.

**Examples**

```ts
const collaboration = univerAPI.getCollaboration()
document.insertText(0, 'Saved through collaboration')
await collaboration.flush(document.getId())
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ICollaborationFlushOptions`](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/facade/f-collaboration.d.ts)

**Package:** [`@univerjs-pro/collaboration-client`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/collaboration-client.md) · [Type definitions](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/facade/f-collaboration.d.ts)

### `FCollaboration.getCollaborationStatus`

Get the synchronization status of a unit.

```typescript
getCollaborationStatus(unitId?: string): CollaborationStatus
```

**Parameters**

* `unitId` — Optional. Optional unit ID. If not provided, uses the focused unit.

**Returns**

The current synchronization status.
Returns CollaborationStatus.NOT_COLLAB if no unit is found or collaboration is not enabled.

Possible status values:

* `NOT_COLLAB`: Not in collaboration mode
* `SYNCED`: All changes are synchronized
* `PENDING`: Local changes waiting to be sent
* `AWAITING`: Changes sent, waiting for server acknowledgement
* `AWAITING_WITH_PENDING`: Awaiting acknowledgement with new local changes
* `FETCH_MISS`: Fetching missing changesets from server
* `CONFLICT`: Conflict detected and being resolved
* `OFFLINE`: Network is offline

**Examples**

```ts
const collaboration = univerAPI.getCollaboration()

// Node environment - specify unitId
const workbook = await collaboration.loadSheetAsync('unit-id')
await new Promise((resolve) => setTimeout(resolve, 1000)) // Wait for collaboration to initialize
const status = collaboration.getCollaborationStatus('unit-id')

// Browser environment - use focused unit (backward compatible)
const status = collaboration.getCollaborationStatus()

// Check if synchronized
if (status === univerAPI.Enum.CollaborationStatus.SYNCED) {
  console.log('All changes are synced!')
}
```

**Types:** [`CollaborationStatus`](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/controllers/collaboration/collaboration-state.d.ts)

**Package:** [`@univerjs-pro/collaboration-client`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/collaboration-client.md) · [Type definitions](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/facade/f-collaboration.d.ts)

### `FCollaboration.loadBaseAsync`

Load a Univer Base from the server with a unit ID.

```typescript
loadBaseAsync(unitId: string, context?: ILogContext): Promise<FBaseFacade | null>
```

**Parameters**

* `unitId` — Required. ID of the Univer Base that you would like to load.
* `context` — Optional. Optional context.

**Returns**

The Base facade or null if ID cannot be associated with a Univer Base.

**Examples**

```ts
const collaboration = univerAPI.getCollaboration()
const base = await collaboration.loadBaseAsync('your-unit-id')
```

**Types:** [`FBaseFacade`](https://docs.univer.ai/ko-KR/reference/facade/base.md) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ILogContext`](https://unpkg.com/@univerjs-pro/collaboration/lib/types/utils.d.ts)

**Package:** [`@univerjs-pro/collaboration-client`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/collaboration-client.md) · [Type definitions](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/facade/f-collaboration.d.ts)

### `FCollaboration.loadBoardAsync`

Load a Univer Board from the server with a unit ID.

```typescript
loadBoardAsync(unitId: string, context?: ILogContext): Promise<FBoard | null>
```

**Parameters**

* `unitId` — Required. ID of the Univer Board that you would like to load.
* `context` — Optional. Optional context.

**Returns**

The `FBoard` or null if ID cannot be associated with a Univer Board.

**Examples**

```ts
const collaboration = univerAPI.getCollaboration()
const board = await collaboration.loadBoardAsync('your-unit-id')
```

**Types:** [`FBoard`](https://docs.univer.ai/ko-KR/reference/facade/board.md) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ILogContext`](https://unpkg.com/@univerjs-pro/collaboration/lib/types/utils.d.ts)

**Package:** [`@univerjs-pro/collaboration-client`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/collaboration-client.md) · [Type definitions](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/facade/f-collaboration.d.ts)

### `FCollaboration.loadDocAsync`

Load a Univer Document from the server with a unit ID.

```typescript
loadDocAsync(unitId: string, context?: ILogContext): Promise<FDocument | null>
```

**Parameters**

* `unitId` — Required. ID of the Univer Document that you would like to load.
* `context` — Optional. Optional context.

**Returns**

The `FDocument` or null if ID cannot be associated with a Univer Document.

**Examples**

```ts
const collaboration = univerAPI.getCollaboration()
const document = await collaboration.loadDocAsync('your-unit-id')
```

**Types:** [`FDocument`](https://docs.univer.ai/ko-KR/reference/facade/document.md) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ILogContext`](https://unpkg.com/@univerjs-pro/collaboration/lib/types/utils.d.ts)

**Package:** [`@univerjs-pro/collaboration-client`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/collaboration-client.md) · [Type definitions](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/facade/f-collaboration.d.ts)

### `FCollaboration.loadPdfAsync`

Load a Univer PDF from the server with a unit ID.

```typescript
loadPdfAsync(unitId: string, context?: ILogContext): Promise<FPdf | null>
```

**Parameters**

* `unitId` — Required. ID of the Univer PDF that you would like to load.
* `context` — Optional. Optional context.

**Returns**

The `FPdf` or null if ID cannot be associated with a Univer PDF.

**Examples**

```ts
const collaboration = univerAPI.getCollaboration()
const pdf = await collaboration.loadPdfAsync('your-unit-id')
```

**Types:** [`FPdf`](https://docs.univer.ai/ko-KR/reference/facade/pdf.md) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ILogContext`](https://unpkg.com/@univerjs-pro/collaboration/lib/types/utils.d.ts)

**Package:** [`@univerjs-pro/collaboration-client`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/collaboration-client.md) · [Type definitions](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/facade/f-collaboration.d.ts)

### `FCollaboration.loadSheetAsync`

Load a Univer Sheet from the server with a unit ID.

```typescript
loadSheetAsync(unitId: string, context?: ILogContext): Promise<FWorkbook | null>
```

**Parameters**

* `unitId` — Required. ID of the Univer Sheet that you would like to load.
* `context` — Optional. Optional context.

**Returns**

The `FWorkbook` or null if ID cannot be associated with a Univer Sheet.

**Examples**

```ts
const collaboration = univerAPI.getCollaboration()
const workbook = await collaboration.loadSheetAsync('your-unit-id')
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ILogContext`](https://unpkg.com/@univerjs-pro/collaboration/lib/types/utils.d.ts)

**Package:** [`@univerjs-pro/collaboration-client`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/collaboration-client.md) · [Type definitions](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/facade/f-collaboration.d.ts)

### `FCollaboration.loadSlideAsync`

Load a Univer Slide from the server with a unit ID.

```typescript
loadSlideAsync(unitId: string, context?: ILogContext): Promise<FPresentation | null>
```

**Parameters**

* `unitId` — Required. ID of the Univer Slide that you would like to load.
* `context` — Optional. Optional context.

**Returns**

The `FPresentation` or null if ID cannot be associated with a Univer Slide.

**Examples**

```ts
const collaboration = univerAPI.getCollaboration()
const presentation = await collaboration.loadSlideAsync('your-unit-id')
```

**Types:** [`FPresentation`](https://docs.univer.ai/ko-KR/reference/facade/presentation.md) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ILogContext`](https://unpkg.com/@univerjs-pro/collaboration/lib/types/utils.d.ts)

**Package:** [`@univerjs-pro/collaboration-client`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/collaboration-client.md) · [Type definitions](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/facade/f-collaboration.d.ts)

### `FCollaboration.subscribeCollaborators`

Subscribe collaborators of a Univer file.

```typescript
subscribeCollaborators(unitId: string, callback: (members: IMember[]) => void): IDisposable
```

**Parameters**

* `unitId` — Required. ID of the Univer file.
* `callback` — Required. A callback function that will be called when the collaborators change.

**Returns**

A handler to dispose the subscription.

**Examples**

```ts
const collaboration = univerAPI.getCollaboration()
collaboration.subscribeCollaborators('your-unit-id', (members) => {
  console.log(members)
})
```

**Types:** [`IDisposable`](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/facade/f-collaboration.d.ts) · [`IMember`](https://unpkg.com/@univerjs/protocol/lib/types/ts/universer/v1/comb.d.ts)

**Package:** [`@univerjs-pro/collaboration-client`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/collaboration-client.md) · [Type definitions](https://unpkg.com/@univerjs-pro/collaboration-client/lib/types/facade/f-collaboration.d.ts)