權限與授權
了解 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 級權限可以單獨設定:
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()。在設定工作表或區域保護的權限點之前,需要先建立對應的保護規則。如果某些資料不允許讀取,應用還需要按業務策略控制讀取介面的返回範圍。
文件(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 級和元素級權限。
PDF 目前透過檢視 / 編輯模式控制本地互動,其作用範圍與上面五類產品的 Unit / Object 權限 API 不同。檔案讀取、下載和匯出的授權由應用後端負責。PDF 也不屬於核心協同服務支援的五類 Unit。
權限繼承與協作者策略
物件級的授權不會覆蓋 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 / 物件策略,前端行為和伺服器端授權都由它驅動。
| 層級 | 負責什麼 |
|---|---|
| Web SDK | 讀取當前使用者可執行的操作,更新權限點和編輯入口,檢查命令,並將受限操作反饋給使用者。 |
| 應用 Authz 介面 | 使用可信的登入身分查詢或修改策略,返回該使用者對 Unit 和物件的實際權限,同時校驗策略管理資格。 |
| Transport | 校驗 Cookie、Session 或 Token 憑據並建立可信身分;客戶端提交的使用者欄位不能作為授權依據。 |
| Endpoint | 校驗 WebSocket 連線和 joinUnit 的房間成員資格,決定誰可以加入文件的即時房間。 |
| Service | 在 readUnitData 校驗讀取,在 submitChangeset 校驗提交;存在物件策略時,在應用 changeset 的過程中結合受影響內容校驗物件權限。 |
Server SDK 提供 Middleware 授權入口,ACL 和物件策略由應用提供。前端的只讀設定和物件保護本身並不構成後端授權。 如果應用只檢查 Unit 級 Edit,還需要補充物件級檢查,才能約束對段落、元素、欄位或記錄的修改。
例如,將一個已有的 collabService 接入自己的 acl:
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。
你覺得這篇文檔如何?