API ReferenceIcons

GitHubdream-num/univer

Univer SheetsUniver DocsUniver SlidesUniver ProRecipesAI Skills

Permission Control

GitHubEdit on GitHub

Univer provides permission control capabilities to restrict user operations on workbooks, worksheets, and ranges. When a user attempts an operation without the required permission, execution is halted and the user is notified. For example, you can protect a range to control whether collaborators can edit, view, copy, or filter within that range.

Precautions before use

Univer provides extensible foundational capabilities, not out-of-the-box customized features. If you need persistence, organizational structures, or other tailored requirements, you must implement the storage of permission rules and integrate organizational structures yourself—typically through custom plugins. Therefore, it is normal to find the permission list empty or user information missing after setting permissions. This data must be fetched via your own API requests, which is custom logic you need to implement. Refer to the third-party integration section below for details.

Preview

Core Concepts

  • Scope: Permissions apply at three levels—workbook, worksheet, and range.
  • Permission Points: Each feature corresponds to a permission point. Modifying a point controls whether that feature is available.
  • Protection Rules: Before setting permission points for worksheets and ranges, you must create a protection rule.

Permission Point Explanation

In a local, non-persistent environment (without collaborative editing), you can control permissions directly by modifying permission points. For persistent permissions, refer to the "Integrating a Third-Party Authorization Service" section below. In a collaborative editing scenario, updating a permission point synchronizes the server state:

  • false: The permission point requires at least the owner role
  • true: The permission point requires at least the reader role

Basic Example

The most common permission setting methods are shown below at three levels: workbook, worksheet, and range.

Workbook Permissions Code Example

Workbook-level permissions can be set directly via the Facade API.

The following example disables editing for the entire workbook. For other functions, replace the permission point accordingly (see the workbook permission points list):

const fWorkbook = univerAPI.getActiveWorkbook()
const workbookPermission = fWorkbook.getWorkbookPermission()

// Set the workbook to be non-editable
await workbookPermission.setPoint(univerAPI.Enum.WorkbookPermissionPoint.Edit, false)

Key points:

  • Workbook permission points can be set directly without creating protection rules.

Worksheet Permissions Code Example

Worksheet and range permissions can be set via the Facade API or commands. The following example demonstrates how to set worksheet edit permissions. For other features, replace the permission point accordingly (see the worksheet permission points list):

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const worksheetPermission = fWorksheet.getWorksheetPermission()

// Create worksheet protection, allow specified users to edit
const permissionId = await worksheetPermission.protect({
  allowedUsers: ['user1', 'user2'],
  name: 'My Worksheet Protection',
})

// To set permission points, you must first protect the worksheet
await worksheetPermission.setPoint(univerAPI.Enum.WorksheetPermissionPoint.Edit, false)

Delete Worksheet Permissions

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const worksheetPermission = fWorksheet.getWorksheetPermission()

// Remove worksheet protection
await worksheetPermission.unprotect()

Custom Range Permissions Code Example

Range permissions can also be set via API and command modes. Here, we'll use range edit permissions as an example. Other range functions require replacing the permission points, see the list of permission points - Range for details.

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
const rangePermission = fRange.getRangePermission()

// Set range protection permission, allow specified users to edit but not allow others to view
const rule = await rangePermission.protect({
  name: 'My protected range',
  allowViewByOthers: false,
  allowedUsers: ['user1', 'user2'],
})
console.log(rule)

// To set permission points, you must first create a range protection rule.
await rule.setPoint(univerAPI.Enum.RangePermissionPoint.Edit, false)
await rule.setPoint(univerAPI.Enum.RangePermissionPoint.View, true)

Delete Range Protection Permissions

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
const rangePermission = fRange.getRangePermission()

// delete all rules within the range
await rangePermission.unprotect()

// Or delete specific rules within the range
const rules = await rangePermission.listRules()
if (rules.length > 0) {
  await rules[0].remove()
}

Extended usage

When you need to check permissions in your own plugin, you can manipulate the permission points directly.

The following example uses WorkbookEditablePermission to demonstrate how to check permissions in your own plugin. Other permission points work similarly.

import { IPermissionService } from '@univerjs/core'
import { WorkbookEditablePermission } from '@univerjs/sheets'

class YourService {
  constructor(@IPermissionService private _permissionService: IPermissionService) {
  }

  setWorkbookNotEditable() {
    this._permissionService.updatePermissionPoint(new WorkbookEditablePermission('unitId').id, false)
  }

  setWorkbookEditable() {
    this._permissionService.updatePermissionPoint(new WorkbookEditablePermission('unitId').id, true)
  }
}

You can also extend and modify other permission points to control different features. See the full list at the bottom of this page.

How to Extend Permission Points

To customize permission points, implement IPermissionPoint and register it with the permission service:

import type { IPermissionPoint } from '@univerjs/core'
import { IPermissionService, PermissionStatus } from '@univerjs/core'
import { UnitAction, UnitObject } from '@univerjs/protocol'

export class CustomPermissionPoint implements IPermissionPoint {
  type = UnitObject.Unkonwn // your type
  subType = UnitAction.View // your subType
  status = PermissionStatus.INIT
  value = true // Default value
  id: string
  constructor(unitId: string, subUnitId: string, customId: string) {
    // The id must be unique within `IPermissionService`.
    this.id = `${unitId}.${subUnitId}.${customId}`
  }
}

class YourService {
  constructor(@IPermissionService private _permissionService: IPermissionService) {
    this._init()
  }

  _init() {
    this._permissionService.addPermissionPoint(new CustomPermissionPoint('unitId', 'subUnitId', 'my-id'))
  }
}

// How to use it elsewhere
class ConsumeService {
  constructor(@IPermissionService private _permissionService: IPermissionService) {
  }

  doSomething() {
    const point = this._permissionService.getPermissionPoint(new CustomPermissionPoint('unitId', 'subUnitId', 'my-id').id)
    console.log(point.value)
  }

  bindEvent() {
    // This returns an RxJS observable that lets you listen for permission changes
    const point$ = this._permissionService.getPermissionPoint$(new CustomPermissionPoint('unitId', 'subUnitId', 'my-id').id)
    console.log(point$)
  }
}

Integrating a Third-Party Authorization Service (Advanced)

Caution

It is recommended to avoid mixing custom permission access with the Permission Facade API, as it allows for more granular control over permission points.

The logic for determining permissions is typically handled by an external service, which involves a communication process. In the frontend SDK implementation, we use the AuthzIoLocalService to handle this logic.

In a production environment, we need to replace this implementation with a backend service. The frontend needs to implement the corresponding request functions based on the IAuthzIoService interface for runtime replacement.

Permission

Here is a simple example demonstrating the addition and deletion of protected range permissions for two predefined roles (Owner/Reader). The Owner has editing/viewing permissions for protected ranges, while the Reader cannot edit or view the contents of cells within protected ranges.

import type { Injector } from '@univerjs/core'
import type { IActionInfo, IAllowedRequest, IBatchAllowedResponse, ICollaborator, ICreateRequest, ICreateRequest_SelectRangeObject, IListPermPointRequest, IPermissionPoint, IPutCollaboratorsRequest, IUnitRoleKV, IUpdatePermPointRequest } from '@univerjs/protocol'
import { createDefaultUser, generateRandomId, IAuthzIoService, Inject, IResourceManagerService, isDevRole, Univer, UserManagerService } from '@univerjs/core'
import { ObjectScope, UnitAction, UnitObject, UnitRole, UniverType } from '@univerjs/protocol'

class YourAuthzService implements IAuthzIoService {
  private _permissionMap: Map<string, ICreateRequest_SelectRangeObject & { objectType: UnitObject }> = new Map([])

  constructor(
    @IResourceManagerService private _resourceManagerService: IResourceManagerService,
    @Inject(UserManagerService) private _userManagerService: UserManagerService,
  ) {
    this._initSnapshot()
    this._initDefaultUser()
  }

  private _initDefaultUser() {
    const currentUser = this._userManagerService.getCurrentUser()
    const currentUserIsValid = currentUser && currentUser.userID
    if (!currentUserIsValid) {
      this._userManagerService.setCurrentUser(createDefaultUser(UnitRole.Owner))
    }
  }

  private _getRole(type: UnitRole) {
    const user = this._userManagerService.getCurrentUser()
    if (!user) {
      return false
    }
    return isDevRole(user.userID, type)
  }

  private _initSnapshot() {
    this._resourceManagerService.registerPluginResource({
      toJson: (_unitId: string) => {
        const obj = [...this._permissionMap.keys()].reduce((r, k) => {
          const v = this._permissionMap.get(k)
          r[k] = v!
          return r
        }, {} as Record<string, ICreateRequest_SelectRangeObject & { objectType: UnitObject }>)
        return JSON.stringify(obj)
      },
      parseJson: (json: string) => {
        return JSON.parse(json)
      },
      pluginName: 'SHEET_AuthzIoMockService_PLUGIN',
      businesses: [UniverType.UNIVER_SHEET, UniverType.UNIVER_DOC, UniverType.UNIVER_SLIDE],
      onLoad: (_unitId, resource) => {
        for (const key in resource) {
          this._permissionMap.set(key, resource[key])
        }
      },
      onUnLoad: () => {
        this._permissionMap.clear()
      },
    })
  }

  async create(config: ICreateRequest): Promise<string> {
    const permissionId = generateRandomId(8)
    if (config.objectType === UnitObject.SelectRange && config.selectRangeObject) {
      this._permissionMap.set(permissionId, { ...config.selectRangeObject, objectType: config.objectType })
    }
    return permissionId
  }

  async batchAllowed(config: IAllowedRequest[]): Promise<IBatchAllowedResponse['objectActions']> {
    const selectionRangeConfig = config.filter(c => c.objectType === UnitObject.SelectRange)
    if (selectionRangeConfig.length) {
      const currentUser = this._userManagerService.getCurrentUser()
      const res = [] as IBatchAllowedResponse['objectActions']
      selectionRangeConfig.forEach((c) => {
        res.push({
          unitID: c.unitID,
          objectID: c.objectID,
          actions: c.actions.map((action) => {
            if (isDevRole(currentUser.userID, UnitRole.Owner)) {
              return { action, allowed: true }
            }
            return { action, allowed: false }
          }),
        })
      })
      return res
    }
    return Promise.resolve([])
  }

  async list(config: IListPermPointRequest): Promise <IPermissionPoint[]> {
    const result: IPermissionPoint[] = []
    config.objectIDs.forEach((objectID) => {
      const rule = this._permissionMap.get(objectID)
      if (rule) {
        const item = {
          objectID,
          unitID: config.unitID,
          objectType: rule!.objectType,
          name: rule!.name,
          shareOn: false,
          shareRole: UnitRole.Owner,
          shareScope: -1,
          scope: {
            read: ObjectScope.AllCollaborator,
            edit: ObjectScope.AllCollaborator,
          },
          creator: createDefaultUser(UnitRole.Owner),
          strategies: [
            {
              action: UnitAction.View,
              role: UnitRole.Owner,
            },
            {
              action: UnitAction.Edit,
              role: UnitRole.Owner,
            },
          ],
          actions: config.actions.map((a) => {
            return { action: a, allowed: this._getRole(UnitRole.Owner) }
          }),
        }
        result.push(item)
      }
    })
    return result
  }

  async listCollaborators(): Promise<ICollaborator[]> {
    // List the existing collaborators
    return []
  }

  async allowed(_config: IAllowedRequest): Promise<IActionInfo[]> {
    // Because this is a mockService for handling permissions, we will not write real logic in it. We will only return an empty array to ensure that the permissions originally set by the user are not modified.
    // If you want to achieve persistence of permissions, you can modify the logic here.
    return Promise.resolve([])
  }

  async listRoles(): Promise<{ roles: IUnitRoleKV[], actions: UnitAction[] }> {
    return {
      roles: [],
      actions: [],
    }
  }

  async update(config: IUpdatePermPointRequest): Promise<void> {
    // Update bit information
  }

  async updateCollaborator(): Promise<void> {
    // Update collaborator information
    return undefined
  }

  async createCollaborator(): Promise<void> {
    // Create new collaborator information
    return undefined
  }

  async deleteCollaborator(): Promise<void> {
    return undefined
  }

  async putCollaborators(config: IPutCollaboratorsRequest): Promise<void> {
    return undefined
  }
}

export class YourPlugin extends Plugin {
  constructor(
    _config: unknown,
    @Inject(Injector) protected override _injector: Injector,
  ) {
  }

  override onStarting(): void {
    this._injector.add([IAuthzIoService, { useClass: YourAuthzService }])
  }
}

// By setting the override option to [[IAuthzIoService, null]], you can instruct Univer not to register the built-in IAuthzIoService.
// This way, Univer will use the service provided by YourAuthzService as the implementation of the authorization service.
const univer = new Univer({
  override: [[IAuthzIoService, null]],
})

univer.registerPlugin(YourPlugin)

List of permission points

You can view the source code for all permission points here.

When workbook permissions overlap with worksheet or range permissions, all relevant permissions must be set to true for the feature to be usable.

Workbook Permissions

API EnumCorresponding Permission Point ClassDescription
univerAPI.Enum.WorkbookPermissionPoint.EditWorkbookEditablePermissionCan edit
univerAPI.Enum.WorkbookPermissionPoint.ViewWorkbookViewPermissionCan view
univerAPI.Enum.WorkbookPermissionPoint.PrintWorkbookPrintPermissionCan print
univerAPI.Enum.WorkbookPermissionPoint.ExportWorkbookExportPermissionCan export
univerAPI.Enum.WorkbookPermissionPoint.ShareWorkbookSharePermissionCan share
univerAPI.Enum.WorkbookPermissionPoint.CopyContentWorkbookCopyPermissionCan copy
univerAPI.Enum.WorkbookPermissionPoint.DuplicateFileWorkbookDuplicatePermissionCan duplicate
univerAPI.Enum.WorkbookPermissionPoint.CommentWorkbookCommentPermissionCan comment
univerAPI.Enum.WorkbookPermissionPoint.ManageCollaboratorWorkbookManageCollaboratorPermissionCan manage collaborators
univerAPI.Enum.WorkbookPermissionPoint.CreateSheetWorkbookCreateSheetPermissionCan create worksheets
univerAPI.Enum.WorkbookPermissionPoint.DeleteSheetWorkbookDeleteSheetPermissionCan delete worksheets
univerAPI.Enum.WorkbookPermissionPoint.RenameSheetWorkbookRenameSheetPermissionCan rename worksheets
univerAPI.Enum.WorkbookPermissionPoint.MoveSheetWorkbookMoveSheetPermissionCan move worksheets
univerAPI.Enum.WorkbookPermissionPoint.HideSheetWorkbookHideSheetPermissionCan hide worksheets
univerAPI.Enum.WorkbookPermissionPoint.CopySheetWorkbookCopySheetPermissionCan copy worksheets
univerAPI.Enum.WorkbookPermissionPoint.ViewHistoryWorkbookViewHistoryPermissionCan view history
univerAPI.Enum.WorkbookPermissionPoint.RecoverHistoryWorkbookRecoverHistoryPermissionCan recover history
univerAPI.Enum.WorkbookPermissionPoint.CreateProtectionWorkbookCreateProtectPermissionCan create protection
univerAPI.Enum.WorkbookPermissionPoint.InsertRowWorkbookInsertRowPermissionCan insert rows
univerAPI.Enum.WorkbookPermissionPoint.InsertColumnWorkbookInsertColumnPermissionCan insert columns
univerAPI.Enum.WorkbookPermissionPoint.DeleteRowWorkbookDeleteRowPermissionCan delete rows
univerAPI.Enum.WorkbookPermissionPoint.DeleteColumnWorkbookDeleteColumnPermissionCan delete columns

Worksheet Permissions

API EnumCorresponding Permission Point ClassDescription
univerAPI.Enum.WorksheetPermissionPoint.EditWorksheetEditPermissionCan edit
univerAPI.Enum.WorksheetPermissionPoint.ViewWorksheetViewPermissionCan view
univerAPI.Enum.WorksheetPermissionPoint.CopyWorksheetCopyPermissionCan copy
univerAPI.Enum.WorksheetPermissionPoint.SetCellValueWorksheetSetCellValuePermissionCan edit cell values
univerAPI.Enum.WorksheetPermissionPoint.SetCellStyleWorksheetSetCellStylePermissionCan edit cell styles
univerAPI.Enum.WorksheetPermissionPoint.SetRowStyleWorksheetSetRowStylePermissionCan set row styles
univerAPI.Enum.WorksheetPermissionPoint.SetColumnStyleWorksheetSetColumnStylePermissionCan set column styles
univerAPI.Enum.WorksheetPermissionPoint.InsertRowWorksheetInsertRowPermissionCan insert rows
univerAPI.Enum.WorksheetPermissionPoint.InsertColumnWorksheetInsertColumnPermissionCan insert columns
univerAPI.Enum.WorksheetPermissionPoint.DeleteRowWorksheetDeleteRowPermissionCan delete rows
univerAPI.Enum.WorksheetPermissionPoint.DeleteColumnWorksheetDeleteColumnPermissionCan delete columns
univerAPI.Enum.WorksheetPermissionPoint.SortWorksheetSortPermissionCan sort
univerAPI.Enum.WorksheetPermissionPoint.FilterWorksheetFilterPermissionCan filter
univerAPI.Enum.WorksheetPermissionPoint.PivotTableWorksheetPivotTablePermissionCan use pivot tables
univerAPI.Enum.WorksheetPermissionPoint.InsertHyperlinkWorksheetInsertHyperlinkPermissionCan use hyperlinks
univerAPI.Enum.WorksheetPermissionPoint.ManageCollaboratorWorksheetManageCollaboratorPermissionCan manage collaborators
univerAPI.Enum.WorksheetPermissionPoint.DeleteProtectionWorksheetDeleteProtectionPermissionCan delete protection
univerAPI.Enum.WorksheetPermissionPoint.EditExtraObjectWorksheetEditExtraObjectPermissionCan edit extra objects
univerAPI.Enum.WorksheetPermissionPoint.SelectProtectedCellsWorksheetSelectProtectedCellsPermissionCan select protected cells
univerAPI.Enum.WorksheetPermissionPoint.SelectUnProtectedCellsWorksheetSelectUnProtectedCellsPermissionCan select unprotected cells

Range Protection

API EnumCorresponding Permission Point ClassDescription
univerAPI.Enum.RangePermissionPoint.EditRangeProtectionPermissionEditPointCan edit protected ranges
univerAPI.Enum.RangePermissionPoint.ViewRangeProtectionPermissionViewPointCan view content of protected ranges
univerAPI.Enum.RangePermissionPoint.DeleteRangeProtectionPermissionDeleteProtectionPointCan delete protected ranges
univerAPI.Enum.RangePermissionPoint.ManageCollaboratorRangeProtectionPermissionManageCollaPointCan manage collaborators for protected ranges

Configuration

Protected Range Shadow Strategy

The protected range shadow is shown by default. You can hide it with the following configuration:

createUniver({
  presets: [
    UniverSheetsCorePreset({
      sheets: {
        /**
         * Strategy for showing the protected range shadow.
         * - true or 'always': Show shadow for all protected ranges (default behavior)
         * - 'non-editable': Only show shadow for ranges that cannot be edited (Edit permission is false)
         * - 'non-viewable': Only show shadow for ranges that cannot be viewed (View permission is false)
         * - false or 'none': Never show shadow for protected ranges
         * @default true
         */
        protectedRangeShadow: false,
      },
    }),
  ],
})
univer.registerPlugin(UniverSheetsUIPlugin, {
  /**
   * Strategy for showing the protected range shadow.
   * - true or 'always': Show shadow for all protected ranges (default behavior)
   * - 'non-editable': Only show shadow for ranges that cannot be edited (Edit permission is false)
   * - 'non-viewable': Only show shadow for ranges that cannot be viewed (View permission is false)
   * - false or 'none': Never show shadow for protected ranges
   * @default true
   */
  protectedRangeShadow: false,
})

You can also modify it dynamically via the API:

// Set to only show shadows for non-editable ranges
univerAPI.setProtectedRangeShadowStrategy('non-editable')

// Get the current protected range shadow display strategy
console.log(univerAPI.getProtectedRangeShadowStrategy())

// Subscribe to changes in the protected range shadow strategy
const subscription = univerAPI.getProtectedRangeShadowStrategy$().subscribe((strategy) => {
  console.log('Global strategy changed to:', strategy)
  // Update UI or perform other actions
})

// Later, unsubscribe to clean up
subscription.unsubscribe()

Custom User Component

Univer's built-in user selector has limited flexibility. For more complex scenarios, you can provide a custom component as shown below.

You can refer to Custom Components for how to create custom components.

const { univer } = createUniver({
  presets: [
    UniverSheetsCorePreset({
      sheets: {
        protectedRangeUserSelector: {
        /**
         * Custom component; must implement the `IPermissionDetailUserPartProps` interface.
         */
          component: CustomPermissionDetailUserPart,
          /**
           * The framework of the component. Must be passed correctly.
           */
          framework: 'react',
        },
      },
    }),
  ],
})
univer.registerPlugin(UniverSheetsUIPlugin, {
  protectedRangeUserSelector: {
    /**
     * Custom component; must implement the `IPermissionDetailUserPartProps` interface.
     */
    component: CustomPermissionDetailUserPart,
    /**
     * The framework of the component. Must be passed correctly.
     */
    framework: 'react',
  },
})

After configuring your custom user component, synchronize the selected user list to SheetPermissionUserManagerService via setSelectUserList() for later use.

import { SheetPermissionUserManagerService, useDependency } from '@univerjs/preset-sheets-core'

const sheetPermissionUserManagerService = useDependency(SheetPermissionUserManagerService)
// For the specific data structure, refer to: https://github.com/dream-num/univer/blob/b4d4cfa063c9e6d5a82d1fc6b05edc206a415252/packages/sheets-ui/src/services/permission/sheet-permission-user-list.service.ts#L57
sheetPermissionUserManagerService.setSelectUserList([])
import { SheetPermissionUserManagerService } from '@univerjs/sheets-ui'
import { useDependency } from '@univerjs/ui'

const sheetPermissionUserManagerService = useDependency(SheetPermissionUserManagerService)
// For the specific data structure, refer to: https://github.com/dream-num/univer/blob/b4d4cfa063c9e6d5a82d1fc6b05edc206a415252/packages/sheets-ui/src/services/permission/sheet-permission-user-list.service.ts#L57
sheetPermissionUserManagerService.setSelectUserList([])

Facade API

The Facade API provides a unified entry point for permissions. Below, we will group common methods by workbook, worksheet, and range.

Workbook Permissions

Get Workbook Permission Instance

const fWorkbook = univerAPI.getActiveWorkbook()
const workbookPermission = fWorkbook.getWorkbookPermission()

Set Workbook Permission Point

For the WorkbookPermissionPoint enum values, see the workbook permission points list.

const fWorkbook = univerAPI.getActiveWorkbook()
const workbookPermission = fWorkbook.getWorkbookPermission()

// Disable the workbook print permission
await workbookPermission.setPoint(univerAPI.Enum.WorkbookPermissionPoint.Print, false)

Predefined modes:

const fWorkbook = univerAPI.getActiveWorkbook()
const workbookPermission = fWorkbook.getWorkbookPermission()

// Set to owner mode
await workbookPermission.setMode('owner')

// Set to editor mode
await workbookPermission.setMode('editor')

// Set to viewer mode
await workbookPermission.setMode('viewer')

// Set to commenter mode
await workbookPermission.setMode('commenter')

Shortcut methods:

  • FWorkbookPermission.setReadOnly(): Sets read-only mode (equivalent to setMode('viewer'))
  • FWorkbookPermission.setEditable(): Sets editable mode (equivalent to setMode('editor'))

Get Workbook Permission Point Status

const fWorkbook = univerAPI.getActiveWorkbook()
const workbookPermission = fWorkbook.getWorkbookPermission()

// Check whether the workbook can be printed
const canPrint = workbookPermission.getPoint(univerAPI.Enum.WorkbookPermissionPoint.Print)
console.log('Can print:', canPrint)

// Get the status of all workbook permission points
const snapshot = workbookPermission.getSnapshot()
console.log('Workbook permission snapshot:', snapshot)

Shortcut methods:

  • FWorkbookPermission.canEdit(): Returns true if the workbook is editable

Collaborator Management

Caution

Collaborator management APIs are only available in collaborative editing scenarios with the USIP service integrated. When using a custom permission service, implement collaborator management logic yourself as described in the "Integrating a Third-Party Authorization Service" section above.

  • Get Collaborators List
const fWorkbook = univerAPI.getActiveWorkbook()
const workbookPermission = fWorkbook.getWorkbookPermission()

const collaborators = await workbookPermission.listCollaborators()
console.log(collaborators)
  • Add Collaborators
const fWorkbook = univerAPI.getActiveWorkbook()
const workbookPermission = fWorkbook.getWorkbookPermission()

// Add multiple collaborators at once
await workbookPermission.setCollaborators([
  {
    user: { userID: 'user1', name: 'John Doe', avatar: 'https://...' },
    role: univerAPI.Enum.UnitRole.Editor,
  },
  {
    user: { userID: 'user2', name: 'Jane Smith', avatar: '' },
    role: univerAPI.Enum.UnitRole.Reader,
  },
])

// Add a single collaborator
await workbookPermission.addCollaborator(
  { userID: 'user1', name: 'John Doe', avatar: 'https://...' },
  univerAPI.Enum.UnitRole.Editor,
)
  • Update collaborator role
const fWorkbook = univerAPI.getActiveWorkbook()
const workbookPermission = fWorkbook.getWorkbookPermission()

await workbookPermission.updateCollaborator(
  { userID: 'user1', name: 'John Doe Updated', avatar: 'https://...' },
  univerAPI.Enum.UnitRole.Reader,
)
  • Remove collaborators
const fWorkbook = univerAPI.getActiveWorkbook()
const workbookPermission = fWorkbook.getWorkbookPermission()

// Remove multiple collaborators
await workbookPermission.removeCollaborators(['user1', 'user2'])

// Remove a single collaborator
await workbookPermission.removeCollaborator('user1')

Worksheet Permissions

Get Worksheet Permission Instance

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const worksheetPermission = fWorksheet.getWorksheetPermission()

Worksheet Protection

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const worksheetPermission = fWorksheet.getWorksheetPermission()

// Protect the worksheet, allowing only specified users to edit
const permissionId = await worksheetPermission.protect({
  allowedUsers: ['user1', 'user2'],
  name: 'My Worksheet Protection',
})

// Check if the worksheet is protected
const isProtected = worksheetPermission.isProtected()
console.log('Is worksheet protected:', isProtected)

if (isProtected) {
  // Unprotect the worksheet
  await worksheetPermission.unprotect()
}

Set Worksheet Permission Point

For the WorksheetPermissionPoint enum values, see the worksheet permission points list.

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const worksheetPermission = fWorksheet.getWorksheetPermission()

// To set permission points, you must first protect the worksheet
await worksheetPermission.protect()

// Disable the worksheet insert-row permission
await worksheetPermission.setPoint(univerAPI.Enum.WorksheetPermissionPoint.InsertRow, false)

Using predefined modes:

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const worksheetPermission = fWorksheet.getWorksheetPermission()

// To set permission points, you must first protect the worksheet
await worksheetPermission.protect()

// Set to editable mode
await worksheetPermission.setMode('editable')

// Set to read-only mode
await worksheetPermission.setMode('readOnly')

// Set to filter/sort only mode
await worksheetPermission.setMode('filterOnly')

// Apply a custom configuration
await worksheetPermission.applyConfig({
  mode: 'readOnly',
  points: {
    [univerAPI.Enum.WorksheetPermissionPoint.InsertRow]: true,
    [univerAPI.Enum.WorksheetPermissionPoint.InsertColumn]: true,
  },
})

Shortcut methods:

  • FWorksheetPermission.setReadOnly(): Sets read-only mode (equivalent to setMode('readOnly'))
  • FWorksheetPermission.setEditable(): Sets editable mode (equivalent to setMode('editable'))

Get Worksheet Permission Point Status

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const worksheetPermission = fWorksheet.getWorksheetPermission()

// Check whether the worksheet can insert rows
const canInsertRow = worksheetPermission.getPoint(univerAPI.Enum.WorksheetPermissionPoint.InsertRow)

// Get the status of all worksheet permission points
const snapshot = worksheetPermission.getSnapshot()

Using shortcut methods:

  • FWorksheetPermission.canEdit(): boolean: Check if the worksheet is editable
  • FWorksheetPermission.canEditCell(row: number, col: number): boolean: Check if a specific cell is editable
  • FWorksheetPermission.canView(): boolean: Check if the worksheet is viewable
  • FWorksheetPermission.canViewCell(row: number, col: number): boolean: Check if a specific cell is viewable
  • FWorksheetPermission.debugCellPermission(row: number, col: number): ICellPermissionDebugInfo: Get permission debug info for a specific cell

Range Permissions

Get Range Permission Instance

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
const rangePermission = fRange.getRangePermission()

Set Range Protection

  • Protect ranges via the worksheet-level API:
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const worksheetPermission = fWorksheet.getWorksheetPermission()

// Protect two ranges: A1:B2 is viewable by everyone but not editable,
// while C3:D4 is editable only by specified users and hidden from others
const rules = await worksheetPermission.protectRanges([
  {
    ranges: [fWorksheet.getRange('A1:B2')],
    options: { name: 'Protected Area 1', allowViewByOthers: true },
  },
  {
    ranges: [fWorksheet.getRange('C3:D4')],
    options: { name: 'Protected Area 2', allowViewByOthers: false, allowedUsers: ['user1'] },
  },
])
console.log(rules)

// List all protection rules on the worksheet
const rules = await worksheetPermission.listRangeProtectionRules()
console.log(rules)

// Delete the first rule
await worksheetPermission.unprotectRules([rules[0].id])

// Or delete a rule via `FRangeProtectionRule.remove()`
await ruleList[0].remove()
  • Protect a range via the range-level API:
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
const rangePermission = fRange.getRangePermission()

// Protect the range so only specified users can edit it, while others cannot view it
const rule = await rangePermission.protect({
  name: 'My protected range',
  allowViewByOthers: false,
  allowedUsers: ['user1', 'user2'],
})
console.log(rule)

// List all protection rules covering the range
const rules = await rangePermission.listRules()
console.log(rules)

// Delete all protection rules covering the range
await rangePermission.unprotect()

// Or delete a rule via `FRangeProtectionRule.remove()`
await rules[0].remove()

Set Range Permission Point

For the RangePermissionPoint enum values, see the range protection points list.

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
const rangePermission = fRange.getRangePermission()

// To set permission points, you must first create a range protection rule
if (rangePermission.isProtected()) {
  const rules = await rangePermission.listRules()

  // Disable editing but enable viewing for the first protection rule
  await rules[0].setPoint(univerAPI.Enum.RangePermissionPoint.Edit, false)
  await rules[0].setPoint(univerAPI.Enum.RangePermissionPoint.View, true)
} else {
  const rule = await rangePermission.protect({
    name: 'My protected range',
    allowViewByOthers: false,
    allowedUsers: ['user1', 'user2'],
  })

  // Disable editing but enable viewing for the A1:B2 range
  await rule.setPoint(univerAPI.Enum.RangePermissionPoint.Edit, false)
  await rule.setPoint(univerAPI.Enum.RangePermissionPoint.View, true)
}

Range Permission Rule API

FRangeProtectionRule provides the following members:

APIDescription
id: stringThe unique identifier of the protection rule
permissionId: stringThe permission ID associated with the protection rule
ranges: FRange[]The ranges covered by the protection rule
options: IRangeProtectionOptionsThe options of the protection rule, including the name of the rule, whether to allow others to view, and the list of users allowed to edit
updateRanges(ranges: FRange[]): Promise<boolean>Update the ranges covered by the protection rule
remove(): Promise<boolean>Remove the protection rule
setPoint(point: RangePermissionPoint, value: boolean): Promise<void>Set the status of a specific permission point for the protection rule (e.g., edit/view/delete)
getPoint(point: RangePermissionPoint): booleanGet the status of a specific permission point for the protection rule (e.g., edit/view/delete)
canEdit(): booleanCheck if the protection rule allows editing
canView(): booleanCheck if the protection rule allows viewing
canDelete(): booleanCheck if the protection rule allows deletion
canManageCollaborator(): booleanCheck if the protection rule allows managing collaborators
getSnapshot(): RangePermissionSnapshotGet a snapshot of the current permission status of the protection rule, including all permission points
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const worksheetPermission = fWorksheet.getWorksheetPermission()
const rules = await worksheetPermission.listRangeProtectionRules()
const rule = rules?.[0]

// Get the ID of the first protection rule
const ruleId = rule?.id
console.log(ruleId)

// Get the ranges of the first protection rule
const ranges = rule?.ranges
console.log(ranges)

// Update the ranges of the first protection rule to A1:C3
await rule?.updateRanges([fWorksheet.getRange('A1:C3')])

// Remove the first protection rule
await rule?.remove()

Hide the Permission Dialog

univerAPI.setPermissionDialogVisible(false)

Migrating from the Old API

API Method DescriptionMigration Guide
Get Permission Instance
Old API:
FWorkbook.getPermission()
New API:
Workbook: FWorkbook.getWorkbookPermission()
Worksheet: FWorksheet.getWorksheetPermission()
Range: FRange.getRangePermission()
Set Workbook Permission Point
Old API:
FPermission.setWorkbookPermissionPoint(unitId: string, FPointClass: WorkbookPermissionPointConstructor, value: boolean)
New API:
FWorkbookPermission.setPoint(point: WorkbookPermissionPoint, value: boolean)
Get Workbook Permission Point Status
Old API:
FPermission.checkWorkbookPermissionPoint(unitId: string, FPointClass: WorkbookPermissionPointConstructor): boolean
New API:
FWorkbookPermission.getPoint(point: WorkbookPermissionPoint): boolean
Set Workbook Edit Permission
Old API:
FPermission.setWorkbookEditPermission(unitId: string, value: boolean)
New API:
FWorkbookPermission.setPoint(univerAPI.Enum.WorkbookPermissionPoint.Edit, value: boolean)
Add Worksheet Protection
Old API:
FPermission.addWorksheetBasePermission(unitId: string, subUnitId: string)
New API:
FWorksheetPermission.protect(options?: IWorksheetProtectionOptions)
Remove Worksheet Protection
Old API:
FPermission.removeWorksheetPermission(unitId: string, subUnitId: string)
New API:
FWorksheetPermission.unprotect()
Set Worksheet Permission Point
Old API:
FPermission.setWorksheetPermissionPoint(unitId: string, subUnitId: string, FPointClass: WorkSheetPermissionPointConstructor, value: boolean)
New API:
FWorksheetPermission.setPoint(point: WorksheetPermissionPoint, value: boolean)
Get Worksheet Permission Point Status
Old API:
FPermission.checkWorksheetPermissionPoint(unitId: string, subUnitId: string, FPointClass: WorkSheetPermissionPointConstructor): boolean
New API:
FWorksheetPermission.getPoint(point: WorksheetPermissionPoint): boolean
Get Permission Info of Specific Cell
Old API:
FPermission.getPermissionInfoWithCell(unitId: string, subUnitId: string, row: number, column: number)
New API:
FWorksheetPermission.debugCellPermission(row: number, col: number): ICellPermissionDebugInfo
Set Range Protection Permission
Old API:
FPermission.addRangeBaseProtection(unitId: string, subUnitId: string, ranges: FRange[])
New API:
Worksheet: FWorksheetPermission.protectRanges(configs)
Range: FRangePermission.protect(options?: IRangeProtectionOptions)
Remove Range Protection Permission
Old API:
FPermission.removeRangeProtection(unitId: string, subUnitId: string, ruleIds: string[])
New API:
Worksheet: FWorksheetPermission.unprotectRules(ruleIds: string[])
Range: FRangePermission.unprotect()
Range Protection Rule: FRangeProtectionRule.remove()
Set Range Protection Permission Point
Old API:
FPermission.setRangeProtectionPermissionPoint(unitId: string, subUnitId: string, permissionId: string, FPointClass: RangePermissionPointConstructor, value: boolean)
New API:
FRangeProtectionRule.setPoint(point: RangePermissionPoint, value: boolean)
Update Range Protection Permission Ranges
Old API:
FPermission.setRangeProtectionRanges(unitId: string, subUnitId: string, ruleId: string, ranges: FRange[])
New API:
FRangeProtectionRule.updateRanges(ranges: FRange[])
Hide Permission Dialog
Old API:
FPermission.setPermissionDialogVisible(false)
New API:
univerAPI.setPermissionDialogVisible(false)

How is this guide?

Table of Contents

Core ConceptsBasic ExampleWorkbook Permissions Code ExampleWorksheet Permissions Code ExampleDelete Worksheet PermissionsCustom Range Permissions Code ExampleDelete Range Protection PermissionsExtended usageHow to Extend Permission PointsIntegrating a Third-Party Authorization Service (Advanced)List of permission pointsWorkbook PermissionsWorksheet PermissionsRange ProtectionConfigurationProtected Range Shadow StrategyCustom User ComponentFacade APIWorkbook PermissionsGet Workbook Permission InstanceSet Workbook Permission PointGet Workbook Permission Point StatusCollaborator ManagementWorksheet PermissionsGet Worksheet Permission InstanceWorksheet ProtectionSet Worksheet Permission PointGet Worksheet Permission Point StatusRange PermissionsGet Range Permission InstanceSet Range ProtectionSet Range Permission PointRange Permission Rule APIHide the Permission DialogMigrating from the Old API
Capalyze