# Collaboration

> Language fallback: requested `zh-CN`; content is `en-US`.

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

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

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

| Packages | `@univerjs-pro/collaboration-client` |
| -------- | ------------------------------------ |

Load collaborative units, observe collaborators and synchronization state, and wait for pending changes to reach the server.

```ts
import '@univerjs-pro/collaboration-client/facade'

const collaboration = univerAPI.getCollaboration()
```

## Unit loading

```typescript
loadSheetAsync(unitId: string, context?: ILogContext): Promise<FWorkbook | null>
loadDocAsync(unitId: string, context?: ILogContext): Promise<FDocument | null>
loadBaseAsync(unitId: string, context?: ILogContext): Promise<FBase | null>
loadSlideAsync(unitId: string, context?: ILogContext): Promise<FPresentation | null>
loadBoardAsync(unitId: string, context?: ILogContext): Promise<FBoard | null>
loadPdfAsync(unitId: string, context?: ILogContext): Promise<FPdf | null>
```

Each method loads the server snapshot, waits until collaboration is ready, and returns the matching Facade object. It returns `null` when the unit cannot be loaded as the requested type.

```ts
const board = await collaboration.loadBoardAsync('board-unit-id')
if (!board) throw new Error('Board not found')
```

PDF loading requires the PDF Facade entry in addition to collaboration:

```ts
import '@univerjs-pro/pdfs/facade'

const pdf = await collaboration.loadPdfAsync('pdf-unit-id')
```

For lower-level access, `univerAPI` also exposes:

```typescript
loadServerUnit(unitId: string, unitType: UniverInstanceType, subUnitId?: string): Promise<UnitModel | null>
loadServerUnitOfRevision(unitId: string, unitType: UniverInstanceType, rev: number): Promise<UnitModel | null>
```

## Synchronization

```typescript
getCollaborationStatus(unitId?: string): CollaborationStatus
flush(unitId?: string, options?: { timeout?: number }): Promise<void>
```

`getCollaborationStatus()` uses the focused unit when `unitId` is omitted and returns `NOT_COLLAB` when collaboration is unavailable. Other statuses include `SYNCED`, `PENDING`, `AWAITING`, `AWAITING_WITH_PENDING`, `FETCH_MISS`, `CONFLICT`, and `OFFLINE`.

Use `flush()` as an explicit barrier after a batch of Facade mutations. It resolves at `SYNCED`, defaults to a 30-second timeout, and rejects when there is no target unit, collaboration is unavailable, a conflict occurs, or the timeout expires. Temporary offline status remains waitable.

```ts
document.insertText(0, 'Saved through collaboration')
await collaboration.flush(document.getId(), { timeout: 15_000 })
```

## Collaborators

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

Dispose the returned handle when the subscription is no longer needed.

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

subscription.dispose()
```

Source: 

`@univerjs-pro/collaboration-client`