权限与授权

了解 Unit 级操作权限、各产品的对象权限,以及前后端协同授权。

Univer 将权限划分为两层:整份内容上的操作权限与内容内部的对象权限。Web SDK 用这两层权限控制交互和命令执行,Server SDK 负责读取、协同提交和扩展服务这几处边界上的授权。

Unit 级权限

一个 Unit(内容单元) 是一份完整的内容实例,例如工作簿、文档、演示文稿、Relational Table、画布或 PDF。下面的 Unit 级权限适用于 Sheet、Doc、Slide、Relational Table 和 Canvases;PDF 在后面的小节单独说明。

权限控制什么典型用法
编辑(Edit)修改内容与结构。查看者只读,编辑者可填写和调整内容。
复制(Copy)在编辑器内复制内容。允许阅读和评论,同时禁止复制。
评论(Comment)发起评论或回复(需已安装评论功能)。审阅者可以评论,正文保持只读。
打印(Print)使用产品的打印功能。允许在线阅读,同时禁止打印。
导出(Export)将内容导出为支持的文件格式。便于交付文件或归档。

编辑和评论彼此独立。编辑、删除和管理评论,同样遵循应用设定的作者与所有者策略。

打印和导出同样属于 Unit 级权限。Sheet、Doc、Slide 和 Canvases 两者都支持;Relational Table 目前只支持 Export。每个权限点需要与对应的功能插件配合使用。

复制内容、复制整份文件、导出、下载是四个不同的操作,需要分别配置。文件能否打开,取决于应用的读取授权。

例如,一篇 Doc 的 Unit 级权限可以单独设置:

TypeScript
import { UnitAction } from '@univerjs/protocol'const document = univerAPI.getActiveDocument()if (!document) throw new Error('Open a document first')const permission = document.getPermission()await permission.setReadOnly()await permission.setPoint(UnitAction.Copy, false)await permission.setPoint(UnitAction.Comment, true)await permission.setPoint(UnitAction.Print, false)await permission.setPoint(UnitAction.Export, false)

运行这段示例前,需要先注册产品和评论插件;插件模式下还需要导入 @univerjs/docs/facade。各产品的权限入口见下文,Sheets 使用自己的一套权限点枚举。

当一个非空 changeset 只包含内置的评论新增、删除、解决、更新或引用更新 mutation 时,Pro 协同服务端检查 UnitAction.Comment。混合 changeset,以及任何会改动文档内容的 mutation(包括 Docs 的评论标记),仍然要求 UnitAction.Edit。评论作者和所有者的策略,也需要由应用自行执行。如果使用自定义的 Collaboration SDK Service Middleware,应在 submitChangeset 策略中做同样的分类;一律按 Edit 检查,会使只有评论权限的审阅者无法提交评论。

按产品控制内容细节

电子表格(Sheet)

权限按工作簿 → 工作表 → 单元格区域逐层细化。工作簿层控制整份文件的编辑、复制和评论;工作表权限点进一步限制单元格值、样式、行列变更、排序、筛选、透视表以及附加对象。区域保护规定指定范围能否编辑、能否查看,也可以指定允许操作的协作者。

例如,需要锁住预算公式、只开放费用填写区时,可分别调用 getWorkbookPermission()、getWorksheetPermission() 和 getRangePermission()。在设置工作表或区域保护的权限点之前,需要先创建对应的保护规则。如果某些数据不允许读取,应用还需要按业务策略控制读取接口的返回范围。

Sheets 权限与保护规则

文档(Doc)

文档层之下,还可以保护节(Section)、段落和内容实体。实体包括表格、绘图、自定义块,以及带稳定标识的范围;页眉和页脚中的段落通过所属 segment 定位。

例如,保护合同的固定条款,只开放需要填写的段落。节和段落使用 getPermission(),内容实体使用 document.getEntityPermission()。最终生效的权限由文档、适用的父级以及对象自身的规则共同决定。

文档级权限 · 节、段落与实体权限

演示文稿(Slide)

权限可覆盖整份演示文稿、单张幻灯片、页面元素,以及母版编辑入口和母版元素。品牌模板和固定图形可以保持锁定,同时开放选定的文本框、图片或图表对象供编辑。

整份演示文稿使用 presentation.getPermission(),单张幻灯片使用 slide.getPermission(),单个元素使用 slide.getElementPermission()。母版相关的访问入口由 Presentation Facade 提供。

Slides 权限 · Presentation Facade

关系型表格(Relational Table)

Relational Table 的权限覆盖表、字段、记录、视图和仪表盘。编辑一个单元格时,Relational Table、表、字段、记录四层限制会同时生效;视图配置和仪表盘也可以单独保护。

例如,保护字段结构和财务记录,同时让业务人员继续维护日常任务。表、字段、记录、视图分别使用 getPermission() 设置;仪表盘需要对应插件。按用户过滤可读字段和记录,由应用的数据读取策略负责。

Relational Table 权限 · 对象权限 API

画布(Canvases)

在 Canvases Unit 内,可以保护每个元素,包括图形、文本、图片和连接线。架构底图或流程框架可以保持受保护状态,协作者只编辑需要维护的节点。

整份画布使用 board.getPermission(),单个元素使用 board.getElementPermission(elementId)。编辑一个元素需要同时具备 Canvases 级和元素级权限。

Canvases 权限 · 元素权限

PDF

PDF 目前通过查看 / 编辑模式控制本地交互,其作用范围与上面五类产品的 Unit / Object 权限 API 不同。文件读取、下载和导出的授权由应用后端负责。PDF 也不属于核心协同服务支持的五类 Unit。

PDF 接入与内容操作

权限继承与协作者策略

对象级的授权不会覆盖 Unit 级限制,也不会覆盖适用父级的限制。 整份文档只读时,将某个段落设为可编辑不会生效。支持的对象可以通过 canEdit() 查询最终结果。

Doc、Slide、Relational Table 和 Canvases 的子对象权限主要控制 Edit,复制和评论在 Unit 级配置。Sheets 另外增加了工作表和选区两类权限点,因此各产品的权限粒度不同。

Doc、Slide、Relational Table 和 Canvases 提供 setObjectPermissions(),用于批量设置对象的协作者策略:

策略允许谁编辑对象
all已拥有该 Unit 编辑权限的协作者。
owner对象所有者,前提是 Unit 和父级权限允许。
members仅限你选择的现有 Unit 协作者。

使用这类策略需要接入 Authz 服务,为目标类型配置 objectPermissionTypes,并持久化对象绑定、规则和成员关系。对象 ID 应使用 SDK 导出的 helper 生成,并保持内容对象 ID 稳定。policy: null 会移除保护并恢复继承。批量写入可能只对部分对象成功,因此需要检查 failed 和 refreshError。Sheets 通过工作表 / 区域保护接口实现这类策略。

前后端如何共同授权

应用维护一套可信的用户身份、角色与 Unit / 对象策略,前端行为和服务端授权都由它驱动。

100%
层级负责什么
Web SDK读取当前用户可执行的操作,更新权限点和编辑入口,检查命令,并将受限操作反馈给用户。
应用 Authz 接口使用可信的登录身份查询或修改策略,返回该用户对 Unit 和对象的实际权限,同时校验策略管理资格。
Transport校验 Cookie、Session 或 Token 凭据并建立可信身份;客户端提交的用户字段不能作为授权依据。
Endpoint校验 WebSocket 连接和 joinUnit 的房间成员资格,决定谁可以加入文档的实时房间。
Service在 readUnitData 校验读取,在 submitChangeset 校验提交;存在对象策略时,在应用 changeset 的过程中结合受影响内容校验对象权限。

Server SDK 提供 Middleware 授权入口,ACL 和对象策略由应用提供。前端的只读设置和对象保护本身并不构成后端授权。 如果应用只检查 Unit 级 Edit,还需要补充对象级检查,才能约束对段落、元素、字段或记录的修改。

例如,将一个已有的 collabService 接入自己的 acl:

TypeScript
import { CollabError } from '@univerjs-pro/collaboration-service'collabService.use('submitChangeset', async (context, next) => {  const allowed = await acl.canEdit(    context.userID,    context.request.changeset.unitID,  )  if (!allowed) {    throw new CollabError('PERMISSION_DENIED', 'Editing is not allowed')  }  await next()})

本例只覆盖 Unit 级编辑授权。读取、JOIN、策略变更和扩展接口同样需要保护。细粒度写入可以在 applyChangeset 这类应用阶段校验受影响的对象,策略需要能够安全重试。

完整接入方式见身份与权限,生命周期钩子的说明见 Middleware 与 Event。

返回功能总览

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.