Skip to Content
ClassesFWorksheetPermission

Class: FWorksheetPermission

Implementation class for WorksheetPermission Provides worksheet-level permission control

Properties

PropertyModifierTypeDescription

permission$

readonly

Observable<WorksheetPermissionSnapshot>

Observable stream of permission snapshot changes (BehaviorSubject) Emits immediately on subscription with current state, then on any permission point change

pointChange$

readonly

Observable<{ oldValue: …; point: …; value: …; }>

Observable stream of individual permission point changes Emits when a specific permission point value changes

rangeProtectionChange$

readonly

Observable<{ rules: …; type: …; }>

Observable stream of range protection rule changes Emits when protection rules are added, updated, or deleted

rangeProtectionRules$

readonly

Observable<…[]>

Observable stream of current range protection rules list (BehaviorSubject) Emits immediately on subscription with current rules, then auto-updates when rules change

Methods

applyConfig()

applyConfig(config): Promise<void>

Apply a permission configuration to the worksheet.

Parameters

ParameterTypeDescription
configIWorksheetPermissionConfigThe configuration to apply.

Returns

Promise<void>

A promise that resolves when the configuration is applied.

Example

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()

canEdit(): boolean

Check if the worksheet is editable.

Returns

boolean

true if the worksheet can be edited, false otherwise.

Example

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

canEditCell()

canEditCell(row, col): boolean

Check if a specific cell can be edited.

Parameters

ParameterTypeDescription
rownumberRow index.
colnumberColumn index.

Returns

boolean

true if the cell can be edited, false otherwise.

Example

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

canViewCell()

canViewCell(_row, _col): boolean

Check if a specific cell can be viewed.

Parameters

ParameterTypeDescription
_rownumberRow index (unused, for API consistency).
_colnumberColumn index (unused, for API consistency).

Returns

boolean

true if the cell can be viewed, false otherwise.

Example

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

debugCellPermission()

debugCellPermission(row, col): FRangeProtectionRule

Debug cell permission information.

Parameters

ParameterTypeDescription
rownumberRow index.
colnumberColumn index.

Returns

FRangeProtectionRule

Debug information about which rules affect this cell, or null if no rules apply.

Example

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

dispose()

dispose(): void

Clean up resources

Returns

void

getPoint()

getPoint(point): boolean

Get the value of a specific permission point.

Parameters

ParameterTypeDescription
pointWorksheetPermissionPointThe permission point to query.

Returns

boolean

true if allowed, false if denied.

Example

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

getSnapshot()

getSnapshot(): WorksheetPermissionSnapshot

Get a snapshot of all permission points.

Returns

WorksheetPermissionSnapshot

An object containing all permission point values.

Example

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

isProtected()

isProtected(): boolean

Check if worksheet is currently protected.

Returns

boolean

true if protected, false otherwise.

Example

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

listRangeProtectionRules()

listRangeProtectionRules(): Promise<...[]>

List all range protection rules for the worksheet.

Returns

Promise<…[]>

Array of protection rules.

Example

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

protect()

protect(options?): Promise<string>

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

Parameters

ParameterTypeDescription
options?IWorksheetProtectionOptionsProtection options including allowed users.

Returns

Promise<string>

The permissionId for the created protection.

Example

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()

protectRanges(configs): Promise<...[]>

Protect multiple ranges at once (batch operation).

Parameters

ParameterTypeDescription
configs{ options: …; ranges: …; }[]Array of protection configurations.

Returns

Promise<…[]>

Array of created protection rules.

Example

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()

setEditable(): Promise<void>

Set the worksheet to editable mode.

Returns

Promise<void>

A promise that resolves when the mode is set.

Example

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

setMode()

setMode(mode): Promise<void>

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

Parameters

ParameterTypeDescription
modeWorksheetModeThe permission mode to set (‘editable'

Returns

Promise<void>

A promise that resolves when the mode is set.

Example

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

setPoint()

setPoint(point, value): Promise<void>

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

Parameters

ParameterTypeDescription
pointWorksheetPermissionPointThe permission point to set.
valuebooleanThe value to set (true = allowed, false = denied).

Returns

Promise<void>

A promise that resolves when the point is set.

Example

const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet();
const permission = worksheet?.getWorksheetPermission();
await permission?.setPoint(univerAPI.Enum.WorksheetPermissionPoint.InsertRow, false);

setReadOnly()

setReadOnly(): Promise<void>

Set the worksheet to read-only mode.

Returns

Promise<void>

A promise that resolves when the mode is set.

Example

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

subscribe()

subscribe(listener): UnsubscribeFn

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

Parameters

ParameterTypeDescription
listener(snapshot) => voidCallback function to be called when permissions change.

Returns

UnsubscribeFn

Unsubscribe function.

Example

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()

unprotect(): Promise<void>

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

Returns

Promise<void>

A promise that resolves when protection is removed.

Example

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

unprotectRules()

unprotectRules(ruleIds): Promise<void>

Remove multiple protection rules at once.

Parameters

ParameterTypeDescription
ruleIdsstring[]Array of rule IDs to remove.

Returns

Promise<void>

A promise that resolves when the rules are removed.

Example

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