FPermission

packages	`@univerjs/sheets`

Deprecated This class is deprecated. Use the new permission API instead:

For workbook-level permissions, use workbook.getWorkbookPermission()
For worksheet-level permissions, use worksheet.getWorksheetPermission()
For range-level permissions, use range.getRangePermission()

The new API provides:

More intuitive and type-safe interfaces
Better support for RxJS Observable streams
Enum-based permission points instead of class constructors
Simplified collaborator management
Mode-based permission settings (viewer, editor, owner, etc.)

Migration examples:

Tags

@description — Used to generate permission instances to control permissions for the entire workbook

Examples

// Old API
const permission = workbook.getPermission()
await permission.addRangeBaseProtection(unitId, subUnitId, ranges)

// New API
const worksheet = workbook.getSheetBySheetId(subUnitId)
const permission = worksheet.getWorksheetPermission()
await permission.protectRanges([{ ranges, options: { name: 'Protected', allowEdit: false } }])

Adds a range protection to the worksheet. Note that after adding, only the background mask of the permission module will be rendered. If you want to modify the function permissions, you need to modify the permission points with the permissionId returned by this function.

Deprecated Use worksheet.getWorksheetPermission().protectRanges() instead

Signature

addRangeBaseProtection(unitId: string, subUnitId: string, ranges: FRange[], options?: IRangeProtectionOptions): Promise<{
        permissionId: string;
        ruleId: string;
    } | undefined>

Parameters

unitId (string) — - The unique identifier of the workbook.
subUnitId (string) — - The unique identifier of the worksheet.
ranges (FRange[]) — - The ranges to be protected.
options (IRangeProtectionOptions) — - Optional protection options including allowed users and name.

Returns

(Promise<{ permissionId: string; ruleId: string; } | undefined>) — - Returns an object containing the permissionId and ruleId if the range protection is successfully added. If the operation fails or no result is returned, it resolves to undefined. permissionId is used to stitch permission point ID，ruleId is used to store permission rules

Examples

// Old API
const workbook = univerAPI.getActiveWorkbook()
const permission = workbook.getPermission()
const unitId = workbook.getId()
const worksheet = workbook.getActiveSheet()
const subUnitId = worksheet.getSheetId()
const range = worksheet.getRange('A1:B2')
const ranges = []
ranges.push(range)
const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges, {
  name: 'Protected Area',
  allowEdit: false,
})
const { permissionId, ruleId } = res
console.log('debugger', permissionId, ruleId)

// New API (recommended)
const worksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const permission = worksheet.getWorksheetPermission()
const range = worksheet.getRange('A1:B2')
await permission.protectRanges([{
  ranges: [range],
  options: { name: 'Protected Area', allowEdit: false },
}])

`addWorksheetBasePermission`

This function is used to add a base permission for a worksheet. Note that after adding, only the background mask of the permission module will be rendered. If you want to modify the function permissions, you need to modify the permission points with the permissionId returned by this function.

Signature

addWorksheetBasePermission(unitId: string, subUnitId: string, options?: IWorksheetProtectionOptions): Promise<string | undefined>

Parameters

unitId (string) — - The unique identifier of the workbook for which the permission is being set.
subUnitId (string) — - The unique identifier of the worksheet for which the permission is being set.
options (IWorksheetProtectionOptions) — - Optional protection options including allowed users and name.

Returns

(Promise<string | undefined>) — - Returns the permissionId if the permission is successfully added. If the operation fails or no result is returned, it resolves to undefined.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook.getPermission()
const unitId = workbook.getId()
const worksheet = workbook.getActiveSheet()
const subUnitId = worksheet.getSheetId()
// Note that there will be no permission changes after this step is completed. It only returns an ID for subsequent permission changes.
// For details, please see the example of the **`setWorksheetPermissionPoint`** API.
const permissionId = await permission.addWorksheetBasePermission(unitId, subUnitId, {
  allowedUsers: ['user1', 'user2'],
  name: 'My Protection',
})
// Can still edit and read it.
console.log('debugger', permissionId)

`checkWorkbookPermissionPoint`

Check if a specific permission point is enabled for a workbook.

Signature

checkWorkbookPermissionPoint(unitId: string, FPointClass: WorkbookPermissionPointConstructor): boolean | undefined

Parameters

unitId (string) — - The unique identifier of the workbook.
FPointClass (WorkbookPermissionPointConstructor) — - The constructor for the permission point class. See the permission-point documentation for more details.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook.getPermission()
const unitId = workbook.getId()
// Check if the workbook is editable
const isEditable = permission.checkWorkbookPermissionPoint(unitId, permission.permissionPointsDefinition.WorkbookEditablePermission)
console.log('Workbook is editable:', isEditable)

`checkWorksheetPermissionPoint`

Check if a specific permission point is enabled for a worksheet.

Signature

checkWorksheetPermissionPoint(unitId: string, subUnitId: string, FPointClass: WorkSheetPermissionPointConstructor): boolean | undefined

Parameters

unitId (string) — - The unique identifier of the workbook.
subUnitId (string) — - The unique identifier of the worksheet.
FPointClass (WorkSheetPermissionPointConstructor) — - The constructor for the permission point class. See the permission-point documentation for more details.

Returns

(boolean | undefined) — - Returns true if the permission point is enabled, false if it is disabled, or undefined if the permission point does not exist.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook.getPermission()
const unitId = workbook.getId()
const worksheet = workbook.getActiveSheet()
const subUnitId = worksheet.getSheetId()
// Check if the worksheet is editable
const isEditable = permission.checkWorksheetPermissionPoint(unitId, subUnitId, permission.permissionPointsDefinition.WorksheetEditPermission)
console.log('Worksheet is editable:', isEditable)

`getPermissionInfoWithCell`

Get the permission information for a specific cell in a worksheet.

Signature

getPermissionInfoWithCell(unitId: string, subUnitId: string, row: number, column: number): {
        permissionId: string;
        ruleId: string;
    } | undefined

Parameters

unitId (string) — - The unique identifier of the workbook.
subUnitId (string) — - The unique identifier of the worksheet within the workbook.
row (number) — - The row index of the cell.
column (number) — - The column index of the cell.

Returns

({ permissionId: string; ruleId: string; } | undefined) — - Returns an object containing the permissionId and ruleId if the cell is protected by a range protection rule. If no protection is found, it returns undefined.

Examples

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const permission = fWorkbook.getPermission()
const unitId = fWorkbook.getId()
const subUnitId = fWorksheet.getSheetId()

// Get the permission information for cell C3
const cell = fWorksheet.getRange('C3')
const permissionInfo = permission.getPermissionInfoWithCell(
  unitId,
  subUnitId,
  cell.getRow(),
  cell.getColumn(),
)
console.log(permissionInfo)

// If the cell is protected, you can remove the protection like this:
if (permissionInfo) {
  const { ruleId } = permissionInfo

  // After 2 seconds, remove the protection for the cell
  setTimeout(() => {
    permission.removeRangeProtection(unitId, subUnitId, [ruleId])
  }, 2000)
}

`removeRangeProtection`

Removes the range protection from the worksheet.

Deprecated Use worksheet.getWorksheetPermission().unprotectRules() instead

Signature

removeRangeProtection(unitId: string, subUnitId: string, ruleIds: string[]): void

Parameters

unitId (string) — - The unique identifier of the workbook.
subUnitId (string) — - The unique identifier of the worksheet.
ruleIds (string[]) — - The rule IDs of the range protection to be removed.

Examples

// Old API
const workbook = univerAPI.getActiveWorkbook()
const permission = workbook.getPermission()
const unitId = workbook.getId()
const worksheet = workbook.getActiveSheet()
const subUnitId = worksheet.getSheetId()
const range = worksheet.getRange('A1:B2')
const ranges = []
ranges.push(range)
const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges)
const ruleId = res.ruleId
permission.removeRangeProtection(unitId, subUnitId, [ruleId])

// New API (recommended)
const worksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const permission = worksheet.getWorksheetPermission()
await permission.unprotectRules([ruleId])

`removeWorksheetPermission`

Delete the entire table protection set for the worksheet and reset the point permissions of the worksheet to true

Signature

removeWorksheetPermission(unitId: string, subUnitId: string): void

Parameters

unitId (string) — - The unique identifier of the workbook for which the permission is being set.
subUnitId (string) — - The unique identifier of the worksheet for which the permission is being set.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook.getPermission()
const unitId = workbook.getId()
const worksheet = workbook.getActiveSheet()
const subUnitId = worksheet.getSheetId()
permission.removeWorksheetPermission(unitId, subUnitId)

`setRangeProtectionPermissionPoint`

Modify the permission points of a custom area

Signature

setRangeProtectionPermissionPoint(unitId: string, subUnitId: string, permissionId: string, FPointClass: RangePermissionPointConstructor, value: boolean): void

Parameters

unitId (string) — - The unique identifier of the workbook.
subUnitId (string) — - The unique identifier of the worksheet within the workbook.
permissionId (string) — - The unique identifier of the permission that controls access to the range.
FPointClass (RangePermissionPointConstructor) — - The constructor for the range permission point class. See the permission-point documentation for more details.
value (boolean) — - The new permission value to be set for the range (e.g., true for allowing access, false for restricting access).

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook.getPermission()
const unitId = workbook.getId()
const worksheet = workbook.getActiveSheet()
const subUnitId = worksheet.getSheetId()
const range = worksheet.getRange('A1:B2')
const ranges = []
ranges.push(range)
// Note that there will be no permission changes after this step is completed. It only returns an ID for subsequent permission changes.
// For details, please see the example of the **`setRangeProtectionPermissionPoint`** API.
const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges)
const { permissionId, ruleId } = res
// After passing the following line of code, the range set above will become uneditable
permission.setRangeProtectionPermissionPoint(unitId, subUnitId, permissionId, permission.permissionPointsDefinition.RangeProtectionPermissionEditPoint, false)

`setRangeProtectionRanges`

Sets the ranges for range protection in a worksheet.

This method finds the rule by unitId, subUnitId, and ruleId, and updates the rule with the provided ranges. It checks for overlaps with existing ranges in the same subunit and shows an error message if any overlap is detected. If no overlap is found, it executes the command to update the range protection with the new ranges.

Signature

setRangeProtectionRanges(unitId: string, subUnitId: string, ruleId: string, ranges: FRange[]): void

Parameters

unitId (string) — - The unique identifier of the workbook.
subUnitId (string) — - The unique identifier of the worksheet within the workbook.
ruleId (string) — - The ruleId of the range protection rule that is being updated.
ranges (FRange[]) — - The array of new ranges to be set for the range protection rule.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook.getPermission()
const unitId = workbook.getId()
const worksheet = workbook.getActiveSheet()
const subUnitId = worksheet.getSheetId()
const range = worksheet.getRange('A1:B2')
const ranges = []
ranges.push(range)
const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges)
const { permissionId, ruleId } = res
const newRange = worksheet.getRange('C1:D2')
permission.setRangeProtectionRanges(unitId, subUnitId, ruleId, [newRange])

`setWorkbookEditPermission`

This function is used to set whether the workbook can be edited

Signature

setWorkbookEditPermission(unitId: string, value: boolean): void

Parameters

unitId (string) — - The unique identifier of the workbook for which the permission is being set.
value (boolean) — - A value that controls whether the workbook can be edited

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook.getPermission()
const unitId = workbook.getId()
permission.setWorkbookEditPermission(unitId, false)

`setWorkbookPermissionPoint`

Configures a specific permission point for a workbook. This function sets or updates a permission point for a workbook identified by unitId. It creates a new permission point if it does not already exist, and updates the point with the provided value.

Signature

setWorkbookPermissionPoint(unitId: string, FPointClass: WorkbookPermissionPointConstructor, value: boolean): void

Parameters

unitId (string) — - The unique identifier of the workbook for which the permission is being set.
FPointClass (WorkbookPermissionPointConstructor) — - The constructor function for creating a permission point instance. Other point constructors can See the permission-point documentation for more details.
value (boolean) — - The boolean value to determine whether the permission point is enabled or disabled.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook.getPermission()
const unitId = workbook.getId()
permission.setWorkbookPermissionPoint(unitId, permission.permissionPointsDefinition.WorkbookEditablePermission, false)

`setWorksheetPermissionPoint`

Sets the worksheet permission point by updating or adding the permission point for the worksheet. If the worksheet doesn't have a base permission, it creates one to used render

Signature

setWorksheetPermissionPoint(unitId: string, subUnitId: string, FPointClass: WorkSheetPermissionPointConstructor, value: boolean): Promise<string | undefined>

Parameters

unitId (string) — - The unique identifier of the workbook.
subUnitId (string) — - The unique identifier of the worksheet.
FPointClass (WorkSheetPermissionPointConstructor) — - The constructor for the permission point class. See the permission-point documentation for more details.
value (boolean) — - The new permission value to be set for the worksheet.

Returns

(Promise<string | undefined>) — - Returns the permissionId if the permission point is successfully set or created. If no permission is set, it resolves to undefined.

Examples

const workbook = univerAPI.getActiveWorkbook()
const permission = workbook.getPermission()
const unitId = workbook.getId()
const worksheet = workbook.getActiveSheet()
const subUnitId = worksheet.getSheetId()
const permissionId = await permission.addWorksheetBasePermission(unitId, subUnitId)
// After this line of code , the worksheet will no longer be editable
permission.setWorksheetPermissionPoint(unitId, subUnitId, permission.permissionPointsDefinition.WorksheetEditPermission, false)

FPermission

APIs

`addRangeBaseProtection`

`addWorksheetBasePermission`

`checkWorkbookPermissionPoint`

`checkWorksheetPermissionPoint`

`getPermissionInfoWithCell`

`removeRangeProtection`

`removeWorksheetPermission`

`setRangeProtectionPermissionPoint`

`setRangeProtectionRanges`

`setWorkbookEditPermission`

`setWorkbookPermissionPoint`

`setWorksheetPermissionPoint`

Table of Contents