權限與授權

了解 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.