FWorksheetPermission

Implementation class for WorksheetPermission Provides worksheet-level permission control

This class should not be instantiated directly. Use factory methods on univerAPI instead.

Access

Access through:

FWorksheet.getWorksheetPermission()

Setup

Register @univerjs/sheets or a preset that includes it. In plugin mode, import @univerjs/sheets/facade. Additional methods below require their listed plugin packages. See Facade setup.

`@univerjs/sheets`

`FWorksheetPermission.applyConfig`

Apply a permission configuration to the worksheet.

TypeScript

applyConfig(config: IWorksheetPermissionConfig): Promise<void>

Parameters

config — Required. The configuration to apply.

Returns

A promise that resolves when the configuration is applied.

Examples

TypeScript

const worksheet = univerAPI.getActiveWorkbook()?.getSheetByName('Sheet1')if (!worksheet) throw new Error('worksheet is not available')const permission = worksheet?.getWorksheetPermission()await permission?.applyConfig({  mode: 'readOnly',  points: {    [univerAPI.Enum.WorksheetPermissionPoint.View]: true,    [univerAPI.Enum.WorksheetPermissionPoint.Edit]: false,  },})

Types: Promise · IWorksheetPermissionConfig

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.canEdit`

Check if the worksheet is editable.

TypeScript

canEdit(): boolean

Returns

true if the worksheet can be edited, false otherwise.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')if (fWorksheet.getWorksheetPermission().canEdit()) {  console.log('Worksheet is editable')}

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.canEditCell`

Check if a specific cell can be edited.

TypeScript

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

Parameters

row — Required. Row index.
col — Required. Column index.

Returns

true if the cell can be edited, false otherwise.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Check if cell C3 can be editedconst fRange = fWorksheet.getRange('C3')const canEdit = fWorksheet.getWorksheetPermission().canEditCell(fRange.getRow(), fRange.getColumn())console.log(canEdit)

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.canView`

Check if the worksheet is viewable.

TypeScript

canView(): boolean

Returns

true if the worksheet can be viewed, false otherwise.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')if (fWorksheet.getWorksheetPermission().canView()) {  console.log('Worksheet is viewable')}

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.canViewCell`

Check if a specific cell can be viewed.

TypeScript

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

Parameters

row — Required. Row index.
col — Required. Column index.

Returns

true if the cell can be viewed, false otherwise.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Check if cell C3 can be viewedconst fRange = fWorksheet.getRange('C3')const canView = fWorksheet.getWorksheetPermission().canViewCell(fRange.getRow(), fRange.getColumn())console.log(canView)

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.debugCellPermission`

Debug cell permission information.

TypeScript

debugCellPermission(row: number, col: number): Promise<FRangeProtectionRule | undefined>

Parameters

row — Required. Row index.
col — Required. Column index.

Returns

A promise resolving to the protection rule affecting this cell, or undefined if no range protection rule applies.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Get debug info for cell C3const fRange = fWorksheet.getRange('C3')const debugInfo = await fWorksheet  .getWorksheetPermission()  .debugCellPermission(fRange.getRow(), fRange.getColumn())console.log(debugInfo)

Types: FRangeProtectionRule · Promise

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.getPoint`

Get the value of a specific permission point.

TypeScript

getPoint(point: WorksheetPermissionPoint): boolean

Parameters

point — Required. The permission point to query.

Returns

true if allowed, false if denied.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const permission = fWorksheet.getWorksheetPermission()const canInsertRow = permission.getPoint(univerAPI.Enum.WorksheetPermissionPoint.InsertRow)console.log(canInsertRow)

Types: WorksheetPermissionPoint

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.getSnapshot`

Get a snapshot of all permission points.

TypeScript

getSnapshot(): WorksheetPermissionSnapshot

Returns

An object containing all permission point values.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const snapshot = fWorksheet.getWorksheetPermission().getSnapshot()console.log(snapshot)

Types: WorksheetPermissionSnapshot

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.isProtected`

Check if worksheet is currently protected.

TypeScript

isProtected(): boolean

Returns

true if protected, false otherwise.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')if (fWorksheet.getWorksheetPermission().isProtected()) {  console.log('Worksheet is protected')}

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.listRangeProtectionRules`

List all range protection rules for the worksheet.

TypeScript

listRangeProtectionRules(options?: { ignoreCollaborators?: boolean; }): Promise<FRangeProtectionRule[]>

Parameters

options — Optional. Options for listing range protection rules.

Returns

Array of protection rules.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const rules = await fWorksheet.getWorksheetPermission().listRangeProtectionRules()console.log(rules)

Types: FRangeProtectionRule · Promise

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.protect`

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

TypeScript

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

Parameters

options — Optional. Protection options including allowed users.

Returns

The permissionId for the created protection.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const permission = fWorksheet.getWorksheetPermission()// Create worksheet protection with collaboratorsconst permissionId = await permission.protect({  allowedUsers: ['user1', 'user2'],  name: 'My Worksheet Protection',})// Now set permission pointsawait permission?.setMode('readOnly')

Types: Promise · IWorksheetProtectionOptions

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.protectRanges`

Protect multiple ranges at once (batch operation).

TypeScript

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

Parameters

configs — Required. Array of protection configurations.

Returns

Array of created protection rules.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const rules = await fWorksheet.getWorksheetPermission().protectRanges([  {    ranges: [fWorksheet.getRange('A1:B2')],    options: {      name: 'Protected Area 1',      allowedUsers: ['user1', 'user2'],      allowViewByOthers: true,    },  },  {    ranges: [fWorksheet.getRange('C3:D4')],    options: { name: 'Protected Area 2', allowViewByOthers: false },  },])console.log(rules)

Types: FRangeProtectionRule · Promise · Array · FRange · IRangeProtectionOptions

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.setEditable`

Set the worksheet to editable mode.

TypeScript

setEditable(): Promise<void>

Returns

A promise that resolves when the mode is set.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')await fWorksheet.getWorksheetPermission().setEditable()

Types: Promise

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.setMode`

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

TypeScript

setMode(mode: WorksheetMode): Promise<void>

Parameters

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

Returns

A promise that resolves when the mode is set.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')await fWorksheet.getWorksheetPermission().setMode('readOnly')

Types: Promise · WorksheetMode

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.setPoint`

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

TypeScript

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

Parameters

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

Returns

A promise that resolves when the point is set.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const permission = fWorksheet.getWorksheetPermission()await permission.setPoint(univerAPI.Enum.WorksheetPermissionPoint.InsertRow, false)

Types: Promise · WorksheetPermissionPoint

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.setReadOnly`

Set the worksheet to read-only mode.

TypeScript

setReadOnly(): Promise<void>

Returns

A promise that resolves when the mode is set.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')await fWorksheet.getWorksheetPermission().setReadOnly()

Types: Promise

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.unprotect`

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

TypeScript

unprotect(): Promise<boolean>

Returns

A promise resolving to whether protection was removed; also resolves to true if already unprotected.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')await fWorksheet.getWorksheetPermission().unprotect()

Types: Promise

Package: @univerjs/sheets · Type definitions

`FWorksheetPermission.unprotectRules`

Remove multiple protection rules at once.

TypeScript

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

Parameters

ruleIds — Required. Array of rule IDs to remove.

Returns

A promise resolving to whether the rules were removed; also resolves to true for an empty ID list.

Examples

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const worksheetPermission = fWorksheet.getWorksheetPermission()const rules = await worksheetPermission.listRangeProtectionRules()// Unprotect the first rule as an exampleif (rules.length > 0) {  const result = await worksheetPermission.unprotectRules([rules[0].id])  console.log(result)}

Types: Promise

Package: @univerjs/sheets · Type definitions

How is this guide?