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
canEdit(): booleanReturns
boolean— true if the worksheet can be edited, false otherwise.
Examples
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
canEditCell(row: number, col: number): booleanParameters
rownumber— No descriptioncolnumber— No description
Returns
boolean— true if the cell can be edited, false otherwise.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
// Check if cell C3 can be edited
const 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
canView(): booleanReturns
boolean— true if the worksheet can be viewed, false otherwise.
Examples
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
canViewCell(row: number, col: number): booleanParameters
rownumber— No descriptioncolnumber— No description
Returns
boolean— true if the cell can be viewed, false otherwise.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
// Check if cell C3 can be viewed
const 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
getPoint(point: WorksheetPermissionPoint): booleanParameters
pointWorksheetPermissionPoint— No description
Returns
boolean— true if allowed, false if denied.
Examples
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
getSnapshot(): WorksheetPermissionSnapshotReturns
WorksheetPermissionSnapshot— An object containing all permission point values.
Examples
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
isProtected(): booleanReturns
boolean— true if protected, false otherwise.
Examples
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
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
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
async applyConfig(config: IWorksheetPermissionConfig): Promise<void>Parameters
configIWorksheetPermissionConfig— No description
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
}
});@univerjs/sheets
setEditable
Set the worksheet to editable mode.
Signature
async setEditable(): Promise<void>Returns
Promise<void>— A promise that resolves when the mode is set.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
await fWorksheet.getWorksheetPermission().setEditable();@univerjs/sheets
setMode
Set permission mode for the worksheet. Automatically creates worksheet protection if not already protected.
Signature
async setMode(mode: WorksheetMode): Promise<void>Parameters
modeWorksheetMode— No description
Returns
Promise<void>— A promise that resolves when the mode is set.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
await fWorksheet.getWorksheetPermission().setMode('readOnly');@univerjs/sheets
setPoint
Set a specific permission point for the worksheet. Automatically creates worksheet protection if not already protected.
Signature
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
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
async setReadOnly(): Promise<void>Returns
Promise<void>— A promise that resolves when the mode is set.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
await fWorksheet.getWorksheetPermission().setReadOnly();@univerjs/sheets
Miscellaneous
debugCellPermission
Debug cell permission information.
Signature
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
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
// Get debug info for cell C3
const fRange = fWorksheet.getRange('C3');
const debugInfo = await fWorksheet.getWorksheetPermission().debugCellPermission(fRange.getRow(), fRange.getColumn());
console.log(debugInfo);@univerjs/sheets
protect
Create worksheet protection with collaborators support. This must be called before setting permission points for collaboration to work.
Signature
async protect(options?: IWorksheetProtectionOptions): Promise<string>Parameters
optionsIWorksheetProtectionOptions(optional) — No description
Returns
Promise<string>— The permissionId for the created protection.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const permission = fWorksheet.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');@univerjs/sheets
protectRanges
Protect multiple ranges at once (batch operation).
Signature
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
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
async unprotect(): Promise<boolean>Returns
Promise<boolean>— A promise that resolves when protection is removed.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
await fWorksheet.getWorksheetPermission().unprotect();@univerjs/sheets
unprotectRules
Remove multiple protection rules at once.
Signature
async unprotectRules(ruleIds: string[]): Promise<boolean>Parameters
ruleIdsstring[]— No description
Returns
Promise<boolean>— A promise that resolves when the rules are removed.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const worksheetPermission = fWorksheet.getWorksheetPermission();
const rules = await worksheetPermission.listRangeProtectionRules();
// Unprotect the first rule as an example
if (rules.length > 0) {
const result = await worksheetPermission.unprotectRules([rules[0].id]);
console.log(result);
}@univerjs/sheets