FWorkbookPermission

packages	`@univerjs/sheets`

Implementation class for WorkbookPermission Provides workbook-level permission control

APIs

`addCollaborator`

Add a single collaborator.

Signature

addCollaborator(user: IUser, role: UnitRole): Promise<void>

Parameters

user (IUser) — The user information (userID, name, avatar).
role (UnitRole) — The role to assign.

Returns

(Promise<void>) — A promise that resolves when the collaborator is added.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
await permission?.addCollaborator(
  { userID: 'user1', name: 'John Doe', avatar: 'https://...' },
  univerAPI.Enum.UnitRole.Editor,
)

`canEdit`

Check if the workbook is editable.

Signature

canEdit(): boolean

Returns

(boolean) — true if the workbook can be edited, false otherwise.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
if (permission?.canEdit()) {
  console.log('Workbook is editable')
}

`dispose`

Clean up resources

Signature

dispose(): void

`getPoint`

Get the value of a specific permission point.

Signature

getPoint(point: WorkbookPermissionPoint): boolean

Parameters

point (WorkbookPermissionPoint) — The permission point to query.

Returns

(boolean) — true if allowed, false if denied.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
const canPrint = permission?.getPoint(univerAPI.Enum.WorkbookPermissionPoint.Print)
console.log(canPrint)

`getSnapshot`

Get a snapshot of all permission points.

Signature

getSnapshot(): WorkbookPermissionSnapshot

Returns

(WorkbookPermissionSnapshot) — An object containing all permission point values.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
const snapshot = permission?.getSnapshot()
console.log(snapshot)

`listCollaborators`

List all collaborators of the workbook.

Signature

listCollaborators(): Promise<ICollaborator[]>

Returns

(Promise<ICollaborator[]>) — Array of collaborators with their roles.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
const collaborators = await permission?.listCollaborators()
console.log(collaborators)

`removeCollaborator`

Remove a collaborator from the workbook.

Signature

removeCollaborator(userId: string): Promise<void>

Parameters

userId (string) — The user ID to remove.

Returns

(Promise<void>) — A promise that resolves when the collaborator is removed.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
await permission?.removeCollaborator('user1')

`removeCollaborators`

Remove multiple collaborators at once.

Signature

removeCollaborators(userIds: string[]): Promise<void>

Parameters

userIds (string[]) — Array of user IDs to remove.

Returns

(Promise<void>) — A promise that resolves when the collaborators are removed.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
await permission?.removeCollaborators(['user1', 'user2'])

`setCollaborators`

Set multiple collaborators at once (replaces existing collaborators).

Signature

setCollaborators(collaborators: Array<{ user: IUser; role: UnitRole }>): Promise<void>

Parameters

collaborators (Array<{ user: IUser; role: UnitRole }>) — Array of collaborators with user information and role.

Returns

(Promise<void>) — A promise that resolves when the collaborators are set.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
await permission?.setCollaborators([
  {
    user: { userID: 'user1', name: 'John Doe', avatar: 'https://...' },
    role: univerAPI.Enum.UnitRole.Editor,
  },
  {
    user: { userID: 'user2', name: 'Jane Smith', avatar: '' },
    role: univerAPI.Enum.UnitRole.Reader,
  },
])

`setEditable`

Set the workbook to editable mode (editor mode).

Signature

setEditable(): Promise<void>

Returns

(Promise<void>) — A promise that resolves when the mode is set.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
await permission?.setEditable()

`setMode`

Listen to permission point changes /** Set permission mode for the workbook.

Signature

setMode(mode: WorkbookMode): Promise<void>

Parameters

mode (WorkbookMode) — The permission mode to set ('owner' | 'editor' | 'viewer' | 'commenter').

Returns

(Promise<void>) — A promise that resolves when the mode is set.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
await permission?.setMode('editor')

`setPoint`

Set a specific permission point.

Signature

setPoint(point: WorkbookPermissionPoint, value: boolean): Promise<void>

Parameters

point (WorkbookPermissionPoint) — The permission point to set.
value (boolean) — The value to set (true = allowed, false = denied).

Returns

(Promise<void>) — A promise that resolves when the point is set.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
await permission?.setPoint(univerAPI.Enum.WorkbookPermissionPoint.Print, false)

`setReadOnly`

Set the workbook to read-only mode (viewer mode).

Signature

setReadOnly(): Promise<void>

Returns

(Promise<void>) — A promise that resolves when the mode is set.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
await permission?.setReadOnly()

Subscribe to permission changes (simplified interface for users not familiar with RxJS).

Signature

subscribe(listener: (snapshot: WorkbookPermissionSnapshot) => void): UnsubscribeFn

Parameters

listener ((snapshot: WorkbookPermissionSnapshot) => void) — Callback function to be called when permissions change.

Returns

(UnsubscribeFn) — Unsubscribe function.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
const unsubscribe = permission?.subscribe((snapshot) => {
  console.log('Permission changed:', snapshot)
})
// Later, to stop listening:
unsubscribe?.()

`updateCollaborator`

Update an existing collaborator's role and information.

Signature

updateCollaborator(user: IUser, role: UnitRole): Promise<void>

Parameters

user (IUser) — The updated user information (userID, name, avatar).
role (UnitRole) — The new role to assign.

Returns

(Promise<void>) — A promise that resolves when the collaborator is updated.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook?.getWorkbookPermission()
await permission?.updateCollaborator(
  { userID: 'user1', name: 'John Doe Updated', avatar: 'https://...' },
  univerAPI.Enum.UnitRole.Reader,
)

Table of Contents