FWorksheetPermission

packages	`@univerjs/sheets`

Implementation class for WorksheetPermission Provides worksheet-level permission control

APIs

`applyConfig`

Apply a permission configuration to the worksheet.

Signature

applyConfig(config: IWorksheetPermissionConfig): Promise<void>

Parameters

config (IWorksheetPermissionConfig) — The configuration to apply.

Returns

(Promise<void>) — A promise that resolves when the configuration is applied.

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
await permission?.applyConfig({
  mode: 'readOnly',
  points: {
    [univerAPI.Enum.WorksheetPermissionPoint.View]: true,
    [univerAPI.Enum.WorksheetPermissionPoint.Edit]: false,
  },
})

`canEdit`

Check if the worksheet is editable.

Signature

canEdit(): boolean

Returns

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

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
if (permission?.canEdit()) {
  console.log('Worksheet is editable')
}

`canEditCell`

Check if a specific cell can be edited.

Signature

canEditCell(row: number, col: number): boolean

Parameters

row (number) — Row index.
col (number) — Column index.

Returns

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

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
const canEdit = permission?.canEditCell(0, 0)
console.log(canEdit)

`canViewCell`

Check if a specific cell can be viewed.

Signature

canViewCell(_row: number, _col: number): boolean

Parameters

_row (number) — Row index (unused, for API consistency).
_col (number) — Column index (unused, for API consistency).

Returns

(boolean) — true if the cell can be viewed, false otherwise.

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
const canView = permission?.canViewCell(0, 0)
console.log(canView)

`debugCellPermission`

Debug cell permission information.

Signature

debugCellPermission(row: number, col: number): FRangeProtectionRule | undefined

Parameters

row (number) — Row index.
col (number) — Column index.

Returns

(FRangeProtectionRule | undefined) — Debug information about which rules affect this cell, or null if no rules apply.

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
const debugInfo = permission?.debugCellPermission(0, 0)
console.log(debugInfo)

`dispose`

Clean up resources

Signature

dispose(): void

`getPoint`

Get the value of a specific permission point.

Signature

getPoint(point: WorksheetPermissionPoint): boolean

Parameters

point (WorksheetPermissionPoint) — The permission point to query.

Returns

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

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
const canInsertRow = permission?.getPoint(univerAPI.Enum.WorksheetPermissionPoint.InsertRow)
console.log(canInsertRow)

`getSnapshot`

Get a snapshot of all permission points.

Signature

getSnapshot(): WorksheetPermissionSnapshot

Returns

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

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
const snapshot = permission?.getSnapshot()
console.log(snapshot)

`isProtected`

Check if worksheet is currently protected.

Signature

isProtected(): boolean

Returns

(boolean) — true if protected, false otherwise.

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
if (permission?.isProtected()) {
  console.log('Worksheet is protected')
}

`listRangeProtectionRules`

List all range protection rules for the worksheet.

Signature

listRangeProtectionRules(): Promise<FRangeProtectionRule[]>

Returns

(Promise<FRangeProtectionRule[]>) — Array of protection rules.

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
const rules = await permission?.listRangeProtectionRules()
console.log(rules)

`protect`

Create worksheet protection with collaborators support. This must be called before setting permission points for collaboration to work.

Signature

protect(options?: IWorksheetProtectionOptions): Promise<string>

Parameters

options (IWorksheetProtectionOptions) — Protection options including allowed users.

Returns

(Promise<string>) — The permissionId for the created protection.

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()

// Create worksheet protection with collaborators
const permissionId = await permission?.protect({
  allowedUsers: ['user1', 'user2'],
  name: 'My Worksheet Protection',
})

// Now set permission points
await permission?.setMode('readOnly')

`protectRanges`

Protect multiple ranges at once (batch operation).

Signature

protectRanges(configs: Array<{
            ranges: FRange[];
            options?: IRangeProtectionOptions;
        }>): Promise<FRangeProtectionRule[]>

Parameters

configs (Array<{ ranges: FRange[]; options?: IRangeProtectionOptions; }>) — Array of protection configurations.

Returns

(Promise<FRangeProtectionRule[]>) — Array of created protection rules.

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
const rules = await permission?.protectRanges([
  {
    ranges: [worksheet.getRange('A1:B2')],
    options: { name: 'Protected Area 1', allowEdit: false, allowViewByOthers: true },
  },
  {
    ranges: [worksheet.getRange('C3:D4')],
    options: { name: 'Protected Area 2', allowEdit: true, allowViewByOthers: false },
  },
])
console.log(rules)

`setEditable`

Set the worksheet to editable mode.

Signature

setEditable(): Promise<void>

Returns

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

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
await permission?.setEditable()

`setMode`

Set permission mode for the worksheet. Automatically creates worksheet protection if not already protected.

Signature

setMode(mode: WorksheetMode): Promise<void>

Parameters

mode (WorksheetMode) — The permission mode to set ('editable' | 'readOnly' | 'filterOnly' | 'commentOnly').

Returns

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

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
await permission?.setMode('readOnly')

`setPoint`

Set a specific permission point for the worksheet. Automatically creates worksheet protection if not already protected.

Signature

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

Parameters

point (WorksheetPermissionPoint) — 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 worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
await permission?.setPoint(univerAPI.Enum.WorksheetPermissionPoint.InsertRow, false)

`setReadOnly`

Set the worksheet to read-only mode.

Signature

setReadOnly(): Promise<void>

Returns

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

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
await permission?.setReadOnly()

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

Signature

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

Parameters

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

Returns

(UnsubscribeFn) — Unsubscribe function.

Examples

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

`unprotect`

Remove worksheet protection. This deletes the protection rule and resets all permission points to allowed.

Signature

unprotect(): Promise<void>

Returns

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

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
await permission?.unprotect()

`unprotectRules`

Remove multiple protection rules at once.

Signature

unprotectRules(ruleIds: string[]): Promise<void>

Parameters

ruleIds (string[]) — Array of rule IDs to remove.

Returns

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

Examples

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const permission = worksheet?.getWorksheetPermission()
await permission?.unprotectRules(['rule1', 'rule2'])

Table of Contents