FRangePermission

packages	`@univerjs/sheets`

Implementation class for RangePermission Manages range-level permissions

APIs

`canDelete`

Check if the current user can delete this protection rule.

Signature

canDelete(): boolean

Returns

(boolean) — true if can delete rule, false otherwise.

Examples

const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2')
const permission = range?.getRangePermission()
if (permission?.canDelete()) {
  console.log('You can delete this protection rule')
}

`canEdit`

Check if the current user can edit this range.

Signature

canEdit(): boolean

Returns

(boolean) — true if editable, false otherwise.

Examples

const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2')
const permission = range?.getRangePermission()
if (permission?.canEdit()) {
  console.log('You can edit this range')
}

`canManageCollaborator`

Check if the current user can manage collaborators for this range.

Signature

canManageCollaborator(): boolean

Returns

(boolean) — true if can manage collaborators, false otherwise.

Examples

const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2')
const permission = range?.getRangePermission()
if (permission?.canManageCollaborator()) {
  console.log('You can manage collaborators for this range')
}

`canView`

Check if the current user can view this range.

Signature

canView(): boolean

Returns

(boolean) — true if viewable, false otherwise.

Examples

const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2')
const permission = range?.getRangePermission()
if (permission?.canView()) {
  console.log('You can view this range')
}

`dispose`

Clean up resources

Signature

dispose(): void

`getPoint`

Get the value of a specific permission point.

Signature

getPoint(point: RangePermissionPoint): boolean

Parameters

point (RangePermissionPoint) — The permission point to query.

Returns

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

Examples

const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2')
const permission = range?.getRangePermission()
const canEdit = permission?.getPoint(univerAPI.Enum.RangePermissionPoint.Edit)
console.log(canEdit)

`getSnapshot`

Get the current permission snapshot.

Signature

getSnapshot(): RangePermissionSnapshot

Returns

(RangePermissionSnapshot) — Snapshot of all permission points.

Examples

const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2')
const permission = range?.getRangePermission()
const snapshot = permission?.getSnapshot()
console.log(snapshot)

`isProtected`

Check if the current range is protected.

Signature

isProtected(): boolean

Returns

(boolean) — true if protected, false otherwise.

Examples

const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2')
const permission = range?.getRangePermission()
const isProtected = permission?.isProtected()
console.log(isProtected)

`listRules`

List all protection rules.

Signature

listRules(): Promise<FRangeProtectionRule[]>

Returns

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

Examples

const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2')
const permission = range?.getRangePermission()
const rules = await permission?.listRules()
console.log(rules)

`protect`

Protect the current range.

Signature

protect(options?: IRangeProtectionOptions): Promise<FRangeProtectionRule>

Parameters

options (IRangeProtectionOptions) — Protection options.

Returns

(Promise<FRangeProtectionRule>) — The created protection rule.

Examples

const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2')
const permission = range?.getRangePermission()
const rule = await permission?.protect({
  name: 'My protected range',
  allowEdit: true,
  allowedUsers: ['user1', 'user2'],
  allowViewByOthers: false,
})
console.log(rule)

`setPoint`

Set a specific permission point for the range (low-level API).

Important: This method only updates the permission point value for an existing protection rule. It does NOT create permission checks that will block actual editing operations. You must call protect() first to create a protection rule before using this method.

This method is useful for:

Fine-tuning permissions after creating a protection rule with protect()
Dynamically adjusting permissions based on runtime conditions
Advanced permission management scenarios

Signature

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

Parameters

point (RangePermissionPoint) — 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.

Tags

@throws — If no protection rule exists for this range.

Examples

const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2')
const permission = range?.getRangePermission()

// First, create a protection rule
await permission?.protect({ name: 'My Range', allowEdit: true })

// Then you can dynamically update permission points
await permission?.setPoint(univerAPI.Enum.RangePermissionPoint.Edit, false) // Now disable edit
await permission?.setPoint(univerAPI.Enum.RangePermissionPoint.View, true) // Ensure view is enabled

Subscribe to permission changes (simplified interface).

Signature

subscribe(listener: (snapshot: RangePermissionSnapshot) => void): (() => void)

Parameters

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

Returns

((() => void)) — Unsubscribe function.

Examples

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

`unprotect`

Unprotect the current range.

Signature

unprotect(): Promise<void>

Returns

(Promise<void>) — A promise that resolves when the range is unprotected.

Examples

const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2')
const permission = range?.getRangePermission()
await permission?.unprotect()

Table of Contents