FWorksheetPermission
| Packages | @univerjs/sheets |
|---|
Implementation class for WorksheetPermission Provides worksheet-level permission control
This class should not be instantiated directly. Use factory methods on
univerAPIinstead.
Overview
@univerjs/sheets
| Method | Description |
|---|---|
applyConfig | Apply a permission configuration to the worksheet |
canEdit | Check if the worksheet is editable |
canEditCell | Check if a specific cell can be edited |
canView | Check if the worksheet is viewable |
canViewCell | Check if a specific cell can be viewed |
debugCellPermission | Debug cell permission information |
getPoint | Get the value of a specific permission point |
getSnapshot | Get a snapshot of all permission points |
isProtected | Check if worksheet is currently protected |
listRangeProtectionRules | List all range protection rules for the worksheet |
protect | Create worksheet protection with collaborators support |
protectRanges | Protect multiple ranges at once (batch operation) |
setEditable | Set the worksheet to editable mode |
setMode | Set permission mode for the worksheet |
setPoint | Set a specific permission point for the worksheet |
setReadOnly | Set the worksheet to read-only mode |
unprotect | Remove worksheet protection |
unprotectRules | Remove multiple protection rules at once |
APIs
Getters & Queries
canEdit
Check if the worksheet is editable.
Signature
TypeScript
canEdit(): booleanReturns
boolean— true if the worksheet can be edited, false otherwise.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();if (fWorksheet.getWorksheetPermission().canEdit()) { console.log('Worksheet is editable');}@univerjs/sheets
canEditCell
Check if a specific cell can be edited.
Signature
TypeScript
canEditCell(row: number, col: number): booleanParameters
rownumber— No descriptioncolnumber— No description
Returns
boolean— true if the cell can be edited, false otherwise.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();// Check if cell C3 can be editedconst fRange = fWorksheet.getRange('C3');const canEdit = fWorksheet.getWorksheetPermission().canEditCell(fRange.getRow(), fRange.getColumn());console.log(canEdit);@univerjs/sheets
canView
Check if the worksheet is viewable.
Signature
TypeScript
canView(): booleanReturns
boolean— true if the worksheet can be viewed, false otherwise.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();if (fWorksheet.getWorksheetPermission().canView()) { console.log('Worksheet is viewable');}@univerjs/sheets
canViewCell
Check if a specific cell can be viewed.
Signature
TypeScript
canViewCell(row: number, col: number): booleanParameters
rownumber— No descriptioncolnumber— No description
Returns
boolean— true if the cell can be viewed, false otherwise.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();// Check if cell C3 can be viewedconst fRange = fWorksheet.getRange('C3');const canView = fWorksheet.getWorksheetPermission().canViewCell(fRange.getRow(), fRange.getColumn());console.log(canView);@univerjs/sheets
getPoint
Get the value of a specific permission point.
Signature
TypeScript
getPoint(point: WorksheetPermissionPoint): booleanParameters
pointWorksheetPermissionPoint— No description
Returns
boolean— true if allowed, false if denied.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const permission = fWorksheet.getWorksheetPermission();const canInsertRow = permission.getPoint(univerAPI.Enum.WorksheetPermissionPoint.InsertRow);console.log(canInsertRow);@univerjs/sheets
getSnapshot
Get a snapshot of all permission points.
Signature
TypeScript
getSnapshot(): WorksheetPermissionSnapshotReturns
WorksheetPermissionSnapshot— An object containing all permission point values.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const snapshot = fWorksheet.getWorksheetPermission().getSnapshot();console.log(snapshot);@univerjs/sheets
isProtected
Check if worksheet is currently protected.
Signature
TypeScript
isProtected(): booleanReturns
boolean— true if protected, false otherwise.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();if (fWorksheet.getWorksheetPermission().isProtected()) { console.log('Worksheet is protected');}@univerjs/sheets
listRangeProtectionRules
List all range protection rules for the worksheet.
Signature
TypeScript
async listRangeProtectionRules(options?: { ignoreCollaborators?: boolean; // Option to ignore fetching collaborators for performance }): Promise<FRangeProtectionRule[]>Parameters
options{ ignoreCollaborators?: boolean; }(optional) — No description
Returns
Promise<FRangeProtectionRule[]>— Array of protection rules.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const rules = await fWorksheet.getWorksheetPermission().listRangeProtectionRules();console.log(rules);@univerjs/sheets
Setters & Modifiers
applyConfig
Apply a permission configuration to the worksheet.
Signature
TypeScript
async applyConfig(config: IWorksheetPermissionConfig): Promise<void>Parameters
configIWorksheetPermissionConfig— No description
Returns
Promise<void>— A promise that resolves when the configuration is applied.
Examples
TypeScript
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 }});@univerjs/sheets
setEditable
Set the worksheet to editable mode.
Signature
TypeScript
async setEditable(): Promise<void>Returns
Promise<void>— A promise that resolves when the mode is set.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();await fWorksheet.getWorksheetPermission().setEditable();@univerjs/sheets
setMode
Set the permission mode for the worksheet. Creates worksheet protection automatically if it is not already protected.
Signature
TypeScript
async setMode(mode: WorksheetMode): Promise<void>Parameters
modeWorksheetMode— No description
Returns
Promise<void>— A promise that resolves when the mode is set.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();await fWorksheet.getWorksheetPermission().setMode('readOnly');@univerjs/sheets
setPoint
Set a specific permission point for the worksheet. Creates worksheet protection automatically if it is not already protected.
Signature
TypeScript
async setPoint(point: WorksheetPermissionPoint, value: boolean): Promise<void>Parameters
pointWorksheetPermissionPoint— No descriptionvalueboolean— No description
Returns
Promise<void>— A promise that resolves when the point is set.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const permission = fWorksheet.getWorksheetPermission();await permission.setPoint(univerAPI.Enum.WorksheetPermissionPoint.InsertRow, false);@univerjs/sheets
setReadOnly
Set the worksheet to read-only mode.
Signature
TypeScript
async setReadOnly(): Promise<void>Returns
Promise<void>— A promise that resolves when the mode is set.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();await fWorksheet.getWorksheetPermission().setReadOnly();@univerjs/sheets
Miscellaneous
debugCellPermission
Debug cell permission information.
Signature
TypeScript
async debugCellPermission(row: number, col: number): Promise<FRangeProtectionRule | undefined>Parameters
rownumber— No descriptioncolnumber— No description
Returns
Promise<FRangeProtectionRule>— Debug information about which rules affect this cell, or null if no rules apply.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();// Get debug info for cell C3const fRange = fWorksheet.getRange('C3');const debugInfo = await fWorksheet.getWorksheetPermission().debugCellPermission(fRange.getRow(), fRange.getColumn());console.log(debugInfo);@univerjs/sheets
protect
Create worksheet protection with collaborator support. This must be called before setting permission points in a collaborative scenario.
Signature
TypeScript
async protect(options?: IWorksheetProtectionOptions): Promise<string>Parameters
optionsIWorksheetProtectionOptions(optional) — No description
Returns
Promise<string>— The permissionId for the created protection.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();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');@univerjs/sheets
protectRanges
Protect multiple ranges at once (batch operation).
Signature
TypeScript
async protectRanges(configs: Array<{ ranges: FRange[]; options?: IRangeProtectionOptions; }>): Promise<FRangeProtectionRule[]>Parameters
configs{ ranges: FRange[]; options?: IRangeProtectionOptions; }[]— No description
Returns
Promise<FRangeProtectionRule[]>— Array of created protection rules.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();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);@univerjs/sheets
unprotect
Remove worksheet protection. This deletes the protection rule and resets all permission points to allowed.
Signature
TypeScript
async unprotect(): Promise<boolean>Returns
Promise<boolean>— A promise that resolves when protection is removed.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();await fWorksheet.getWorksheetPermission().unprotect();@univerjs/sheets
unprotectRules
Remove multiple protection rules at once.
Signature
TypeScript
async unprotectRules(ruleIds: string[]): Promise<boolean>Parameters
ruleIdsstring[]— No description
Returns
Promise<boolean>— A promise that resolves when the rules are removed.
Examples
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();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);}@univerjs/sheetsHow is this guide?