如何使用 Univer 实现工作表或范围保护

背景

在多人协作编辑表格的场景中，经常需要对某些工作表或特定范围进行保护，以防止数据被意外修改。例如，在财务报表中，管理员可能希望锁定公式区域或只允许特定用户对某些范围进行编辑。针对这一需求，Univer 提供了强大的权限管理模块，可以轻松实现工作表或范围的保护功能。

Univer 是一个前后端同构的全栈开发框架，可以在 web 端和服务端创建、编辑电子表格、文档以及幻灯片。
关注 Univer Github

方案

Univer 的权限模块支持对工作簿、工作表以及特定单元格范围进行权限控制。通过简单的 API 调用，开发者可以灵活设置不同层级的权限，包括只读、完全限制编辑或自定义权限规则。

以下将通过两个场景来详细说明如何使用 Univer 实现工作表和范围的保护功能。

参考 Univer 官方文档-权限控制

---

实现

1. 设置工作表权限

通过权限模块，您可以为整个工作表设置权限，控制用户是否可以编辑工作表内容。以下是一个实现代码示例：

async function setWorksheetPermission() {
    const workbook = univerAPI.getActiveWorkbook(); // 获取当前活动的工作簿
    const unitId = workbook.getId(); // 获取工作簿 ID
    const subUnitId = workbook.getActiveSheet().getSheetId(); // 获取当前活动工作表的 ID
    const permission = univerAPI.getPermission(); // 获取权限模块

    const worksheetEditPermission = permission.permissionPointsDefinition.WorksheetEditPermission;

    // 创建基础工作表权限
    const permissionId = await permission.addWorksheetBasePermission(unitId, subUnitId);

    permission.sheetRuleChangedAfterAuth$.subscribe((currentPermissionId) => {
        if(currentPermissionId === permissionId){
            // 设置工作表为不可编辑状态
            permission.setWorksheetPermissionPoint(unitId, subUnitId, worksheetEditPermission, false);
        }
    })
}

关键点

• addWorksheetBasePermission 用于创建工作表的基础权限。
• setWorksheetPermissionPoint 可细化控制某项具体的编辑权限点。

---

2. 设置选区范围权限

有些情况下，只需要对特定单元格范围设置保护，而非整个工作表。以下代码展示了如何实现多选区的权限保护：

async function setRangePermission() {
    const workbook = univerAPI.getActiveWorkbook(); // 获取当前活动的工作簿
    const sheet = workbook.getActiveSheet(); // 获取当前活动的工作表
    const unitId = workbook.getId(); // 获取工作簿 ID
    const subUnitId = sheet.getSheetId(); // 获取工作表 ID

    const range1 = sheet.getRange('A1:B3').getRange(); // 第一个保护范围
    const range2 = sheet.getRange('C4:D5').getRange(); // 第二个保护范围
    const ranges = [range1, range2]; // 多个保护范围集合

    const permission = univerAPI.getPermission(); // 获取权限模块
    const rangeProtectionPermissionEditPoint = permission.permissionPointsDefinition.RangeProtectionPermissionEditPoint;

    // 添加范围保护并获取返回的规则 ID 和权限 ID
    const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges);
    const { permissionId, ruleId } = res;

    permission.rangeRuleChangedAfterAuth$.subscribe((currentPermissionId)=>{
        if(currentPermissionId === permissionId){
            // 设置范围保护为不可编辑
            permission.setRangeProtectionPermissionPoint(unitId, subUnitId, permissionId, rangeProtectionPermissionEditPoint, false);
        }
    })
}

关键点

• addRangeBaseProtection 支持对多个范围设置保护规则。
• 返回值中包含 ruleId（规则唯一标识）和 permissionId（用于拼接权限点位）。
• setRangeProtectionPermissionPoint 用于设置具体范围的权限点，例如编辑权限。

---

总结

Univer 提供了灵活且强大的权限管理工具，可以满足多种复杂的协作场景需求。通过上述两种方法，您可以轻松实现：

1. 整个工作表的保护，适用于全局只读或锁定场景。
2. 多选区的范围保护，适用于细粒度的权限管理。

这种灵活性和易用性，让开发者在使用 Univer 时能够快速构建更安全、高效的表格协作系统。如果您希望了解更多细节或应用场景，请参考 Univer 官网 univer.ai。