權限與授權

Univer 將權限分為整份內容的操作權限與內容內部的物件權限。Web SDK 依權限控制互動和命令執行；Server SDK 在讀取、協同提交和擴充服務邊界執行應用的授權策略。

Unit 級權限

一個 Unit（內容單元） 是一份完整的內容實例，例如一份活頁簿、文件、簡報、Relational Table、畫布或 PDF。以下 Unit 權限適用於 Sheet、Doc、Slide、Relational Table 和 Canvases；PDF 的目前範圍見下文。

編輯與留言相互獨立。留言的編輯、刪除和管理還應遵守應用對作者、擁有者等身分的策略。

列印和匯出同樣屬於 Unit 級權限。Sheet、Doc、Slide 和 Canvases 提供 Print 與 Export；Relational Table 目前提供 Export。各權限點需要搭配對應的功能外掛。

複製內容、複製整份檔案、匯出和下載屬於不同操作，需要分別設定。是否允許開啟檔案，由應用的讀取授權決定。

例如，Docs 可獨立控制整份文件的 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 使用自己的權限點列舉。

各產品的細部權限

試算表（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 的權限之下，可以控制單一元素的編輯，例如圖形、文字、圖片或連接線。適合保護架構底圖、流程框架，同時允許協作者維護指定節點。

整份畫布使用 board.getPermission()，元素使用 board.getElementPermission(elementId)。元素的有效編輯權限同時受 Canvases 級和元素級規則約束。

Canvases 權限 · 元素權限

PDF

PDF 目前主要透過檢視 / 編輯模式控制本機互動，與上述五類產品的 Unit / Object 權限 API 範圍不同。檔案讀取、下載和匯出策略由應用後端接入；PDF 目前也不屬於核心協同服務支援的五類 Unit。

PDF 接入與內容操作

權限繼承與協作者策略

物件級許可不能突破產品級和適用父層的限制。 例如，整份文件唯讀時，單獨將某段落設為可編輯，最終仍不可編輯。透過 canEdit() 查詢相應物件的有效結果。

Doc、Slide、Relational Table 和 Canvases 的子物件權限主要控制 Edit；複製和留言在產品級設定。Sheets 另外提供工作表和選取範圍的專用權限，各產品的權限粒度不同。

對 Doc、Slide、Relational Table 和 Canvases，可透過 setObjectPermissions() 批次管理物件的協作者策略：

這類策略需要接入 Authz 服務、為目標類型設定 objectPermissionTypes，並持久化物件綁定、規則和成員關係。請使用 SDK 匯出的物件 ID helper，保持內容物件 ID 穩定；policy: null 用於移除保護並恢復繼承。批次設定可能部分失敗，應檢查 failed 與 refreshError。Sheets 透過工作表 / 範圍保護介面接入相應策略。

前後端如何共同授權

應用維護一套可信的使用者身分、角色與文件 / 物件策略，分別驅動前端權限表現和伺服器端檢查。

Server SDK 提供 Middleware 授權入口，具體 ACL 和物件策略由應用提供。前端設定唯讀或物件保護，不會自動取代伺服器端校驗。 只有 Unit 級編輯檢查的應用，還需補充細部物件檢查，才能落實段落、元素、欄位或記錄的業務限制。

例如，已建立的 collabService 可接入應用自己的 acl：

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

本例只示範 Unit 級編輯授權。完整接入還需保護讀取、JOIN、權限規則修改以及擴充模組介面。對細部修改，可在 applyChangeset 等套用階段校驗實際受影響的物件，並保持策略可重試。

從身分與權限了解接入方式，生命週期入口見 Middleware 與 Event。

返回功能總覽