Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

chore: update permission facade (#4557)

ybzkybfd9ba4dcf63
diff --git a/packages/facade/src/apis/sheets/__tests__/f-permission.spec.ts b/packages/facade/src/apis/sheets/__tests__/f-permission.spec.ts
index cba8db68d5..92a5ee28ac 100644
--- a/packages/facade/src/apis/sheets/__tests__/f-permission.spec.ts
+++ b/packages/facade/src/apis/sheets/__tests__/f-permission.spec.ts
@@ -80,13 +80,15 @@ describe('Test FPermission', () => {
it('set range protection point false', async () => {
const permission = univerAPI.getPermission();
- const unitId = univerAPI.getActiveWorkbook()?.getId();
- const subUnitId = univerAPI.getActiveWorkbook()?.getActiveSheet().getSheetId();
- const ranges = [{ startRow: 0, endRow: 1, startColumn: 0, endColumn: 1 }];
- const newRanges = [{ startRow: 0, endRow: 2, startColumn: 0, endColumn: 2 }];
+ const workbook = univerAPI.getActiveWorkbook();
+ const worksheet = workbook?.getActiveSheet();
+ const unitId = workbook?.getId();
+ const subUnitId = worksheet?.getSheetId();
+ const rangeFirst = worksheet?.getRange(0, 0, 2, 2);
+ const rangeSecond = worksheet?.getRange(0, 0, 3, 3);
- if (unitId && subUnitId) {
- const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges);
+ if (unitId && subUnitId && rangeFirst && rangeSecond) {
+ const res = await permission.addRangeBaseProtection(unitId, subUnitId, [rangeFirst]);
if (!res?.permissionId || !res?.ruleId) {
return;
}
@@ -103,9 +105,9 @@ describe('Test FPermission', () => {
catchErr = true;
}
expect(catchErr).toBe(true);
- permission.setRangeProtectionRanges(unitId, subUnitId, res.ruleId, newRanges);
+ permission.setRangeProtectionRanges(unitId, subUnitId, res.ruleId, [rangeSecond]);
let rule = rangeProtectionRuleModel.getRule(unitId, subUnitId, res.ruleId);
- expect(rule?.ranges).toStrictEqual(newRanges);
+ expect(rule?.ranges).toStrictEqual([rangeSecond].map((range) => range.getRange()));
permission.removeRangeProtection(unitId, subUnitId, [res.ruleId]);
rule = rangeProtectionRuleModel.getRule(unitId, subUnitId, res.ruleId);
expect(rule).toBeUndefined();
diff --git a/packages/sheets/src/facade/f-permission.ts b/packages/sheets/src/facade/f-permission.ts
index 59a2d7939e..08b58988c9 100644
--- a/packages/sheets/src/facade/f-permission.ts
+++ b/packages/sheets/src/facade/f-permission.ts
@@ -14,18 +14,29 @@
* limitations under the License.
*/
-import type { IRange, RangePermissionPointConstructor, WorkbookPermissionPointConstructor, WorkSheetPermissionPointConstructor } from '@univerjs/core';
+import type { RangePermissionPointConstructor, WorkbookPermissionPointConstructor, WorkSheetPermissionPointConstructor } from '@univerjs/core';
import type { Observable } from 'rxjs';
+import type { FRange } from './f-range';
import { FBase, generateRandomId, IAuthzIoService, ICommandService, Inject, Injector, IPermissionService, Rectangle } from '@univerjs/core';
import { AddRangeProtectionMutation, AddWorksheetProtectionMutation, DeleteRangeProtectionMutation, DeleteWorksheetProtectionMutation, getAllWorksheetPermissionPoint, getAllWorksheetPermissionPointByPointPanel, PermissionPointsDefinitions, RangeProtectionRuleModel, SetRangeProtectionMutation, SetWorksheetPermissionPointsMutation, UnitObject, WorkbookEditablePermission, WorksheetEditPermission, WorksheetProtectionPointModel, WorksheetProtectionRuleModel, WorksheetViewPermission } from '@univerjs/sheets';
/**
+ * @description Used to generate permission instances to control permissions for the entire workbook
* @hideconstructor
*/
export class FPermission extends FBase {
+ /**
+ * Permission point definition, can read the point constructor want to modify from here
+ */
public permissionPointsDefinition = PermissionPointsDefinitions;
- public rangeRuleChangedAfterAuth$: Observable<unknown>;
- public sheetRuleChangedAfterAuth$: Observable<unknown>;
+ /**
+ * An observable object used to monitor permission change events within a range, thereby triggering corresponding subsequent processing.
+ */
+ public rangeRuleChangedAfterAuth$: Observable<string>;
+ /**
+ * An observable object used to monitor permission change events within a worksheet, thereby triggering corresponding subsequent processing.
+ */
+ public sheetRuleChangedAfterAuth$: Observable<string>;
constructor(
@Inject(Injector) protected readonly _injector: Injector,
@@ -43,12 +54,19 @@ export class FPermission extends FBase {
/**
* Configures a specific permission point for a workbook.
- *
* This function sets or updates a permission point for a workbook identified by `unitId`.
* It creates a new permission point if it does not already exist, and updates the point with the provided value.
* @param {string} unitId - The unique identifier of the workbook for which the permission is being set.
* @param {WorkbookPermissionPointConstructor} FPointClass - The constructor function for creating a permission point instance. Other point constructors can See the [permission-point documentation](https://github.com/dream-num/univer/tree/dev/packages/sheets/src/services/permission/permission-point) for more details.
* @param {boolean} value - The boolean value to determine whether the permission point is enabled or disabled.
+ *
+ * @example
+ * ```typescript
+ * const workbook = univerAPI.getActiveWorkbook();
+ * const permission = workbook.getPermission();
+ * const unitId = workbook.getId();
+ * permission.setWorkbookPermissionPoint(unitId, permission.permissionPointsDefinition.WorkbookEditablePermission, false)
+ * ```
*/
setWorkbookPermissionPoint(unitId: string, FPointClass: WorkbookPermissionPointConstructor, value: boolean): void {
const instance = new FPointClass(unitId);
@@ -63,6 +81,14 @@ export class FPermission extends FBase {
* This function is used to set whether the workbook can be edited
* @param {string} unitId - The unique identifier of the workbook for which the permission is being set.
* @param {boolean} value - A value that controls whether the workbook can be edited
+ *
+ * @example
+ * ```typescript
+ * const workbook = univerAPI.getActiveWorkbook();
+ * const permission = workbook.getPermission();
+ * const unitId = workbook.getId();
+ * permission.setWorkbookEditPermission(unitId, false);
+ * ```
*/
setWorkbookEditPermission(unitId: string, value: boolean): void {
this.setWorkbookPermissionPoint(unitId, WorkbookEditablePermission, value);
@@ -70,9 +96,25 @@ export class FPermission extends FBase {
/**
* This function is used to add a base permission for a worksheet.
+ * Note that after adding, only the background mask of the permission module will be rendered. If you want to modify the function permissions,
+ * you need to modify the permission points with the permissionId returned by this function.
* @param {string} unitId - The unique identifier of the workbook for which the permission is being set.
* @param {string} subUnitId - The unique identifier of the worksheet for which the permission is being set.
* @returns {Promise<string | undefined>} - Returns the `permissionId` if the permission is successfully added. If the operation fails or no result is returned, it resolves to `undefined`.
+ *
+ * @example
+ * ```typescript
+ * const workbook = univerAPI.getActiveWorkbook();
+ * const permission = workbook.getPermission();
+ * const unitId = workbook.getId();
+ * const worksheet = workbook.getActiveSheet();
+ * const subUnitId = worksheet.getSheetId();
+ * // Note that there will be no permission changes after this step is completed. It only returns an ID for subsequent permission changes.
+ * // For details, please see the example of the **`setWorksheetPermissionPoint`** API.
+ * const permissionId = await permission.addWorksheetBasePermission(unitId, subUnitId)
+ * // Can still edit and read it.
+ * console.log('debugger', permissionId)
+ * ```
*/
async addWorksheetBasePermission(unitId: string, subUnitId: string): Promise<string | undefined> {
const hasRangeProtection = this._rangeProtectionRuleModel.getSubunitRuleList(unitId, subUnitId).length > 0;
@@ -107,6 +149,16 @@ export class FPermission extends FBase {
* Delete the entire table protection set for the worksheet and reset the point permissions of the worksheet to true
* @param {string} unitId - The unique identifier of the workbook for which the permission is being set.
* @param {string} subUnitId - The unique identifier of the worksheet for which the permission is being set.
+ *
+ * @example
+ * ```typescript
+ * const workbook = univerAPI.getActiveWorkbook();
+ * const permission = workbook.getPermission();
+ * const unitId = workbook.getId();
+ * const worksheet = workbook.getActiveSheet();
+ * const subUnitId = worksheet.getSheetId();
+ * permission.removeWorksheetPermission(unitId, subUnitId);
+ * ```
*/
removeWorksheetPermission(unitId: string, subUnitId: string): void {
this._commandService.syncExecuteCommand(DeleteWorksheetProtectionMutation.id, {
@@ -130,6 +182,17 @@ export class FPermission extends FBase {
* See the [permission-point documentation](https://github.com/dream-num/univer/tree/dev/packages/sheets/src/services/permission/permission-point) for more details.
* @param {boolean} value - The new permission value to be set for the worksheet.
* @returns {Promise<string | undefined>} - Returns the `permissionId` if the permission point is successfully set or created. If no permission is set, it resolves to `undefined`.
+ *
+ * @example
+ * ```typescript
+ * const workbook = univerAPI.getActiveWorkbook();
+ * const permission = workbook.getPermission();
+ * const unitId = workbook.getId();
+ * const worksheet = workbook.getActiveSheet();
+ * const subUnitId = worksheet.getSheetId();
+ * const permissionId = await permission.addWorksheetBasePermission(unitId, subUnitId)
+ * // After this line of code , the worksheet will no longer be editable
+ * permission.setWorksheetPermissionPoint(unitId, subUnitId, permission.permissionPointsDefinition.WorksheetEditPermission, false);
*/
async setWorksheetPermissionPoint(unitId: string, subUnitId: string, FPointClass: WorkSheetPermissionPointConstructor, value: boolean): Promise<string | undefined> {
const hasBasePermission = this._worksheetProtectionRuleModel.getRule(unitId, subUnitId);
@@ -175,12 +238,31 @@ export class FPermission extends FBase {
/**
* Adds a range protection to the worksheet.
+ * Note that after adding, only the background mask of the permission module will be rendered. If you want to modify the function permissions,
+ * you need to modify the permission points with the permissionId returned by this function.
* @param {string} unitId - The unique identifier of the workbook.
* @param {string} subUnitId - The unique identifier of the worksheet.
- * @param {IRange[]} ranges - The ranges to be protected.
+ * @param {FRange[]} ranges - The ranges to be protected.
* @returns {Promise<{ permissionId: string, ruleId: string } | undefined>} - Returns an object containing the `permissionId` and `ruleId` if the range protection is successfully added. If the operation fails or no result is returned, it resolves to `undefined`. permissionId is used to stitch permission point ID,ruleId is used to store permission rules
+ *
+ * @example
+ * ```typescript
+ *const workbook = univerAPI.getActiveWorkbook();
+ * const permission = workbook.getPermission();
+ * const unitId = workbook.getId();
+ * const worksheet = workbook.getActiveSheet();
+ * const subUnitId = worksheet.getSheetId();
+ * const range = worksheet.getRange(0,0,2,2);
+ * const ranges = [];
+ * ranges.push(range);
+ * // Note that there will be no permission changes after this step is completed. It only returns an ID for subsequent permission changes.
+ * // For details, please see the example of the **`setRangeProtectionPermissionPoint`** API.
+ * const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges);
+ * const {permissionId, ruleId} = res;
+ * console.log('debugger', permissionId, ruleId);
+ * ```
*/
- async addRangeBaseProtection(unitId: string, subUnitId: string, ranges: IRange[]): Promise<{
+ async addRangeBaseProtection(unitId: string, subUnitId: string, ranges: FRange[]): Promise<{
permissionId: string;
ruleId: string;
} | undefined> {
@@ -202,7 +284,7 @@ export class FPermission extends FBase {
const overlap = subunitRuleList.some((rule) => {
return rule.ranges.some((range) => {
return ranges.some((newRange) => {
- return Rectangle.intersects(newRange, range);
+ return Rectangle.intersects(newRange.getRange(), range);
});
});
});
@@ -217,7 +299,7 @@ export class FPermission extends FBase {
unitType: UnitObject.SelectRange,
unitId,
subUnitId,
- ranges,
+ ranges: ranges.map((range) => range.getRange()),
id: ruleId,
}],
});
@@ -234,6 +316,21 @@ export class FPermission extends FBase {
* @param {string} unitId - The unique identifier of the workbook.
* @param {string} subUnitId - The unique identifier of the worksheet.
* @param {string[]} ruleIds - The rule IDs of the range protection to be removed.
+ *
+ * @example
+ * ```typescript
+ * const workbook = univerAPI.getActiveWorkbook();
+ * const permission = workbook.getPermission();
+ * const unitId = workbook.getId();
+ * const worksheet = workbook.getActiveSheet();
+ * const subUnitId = worksheet.getSheetId();
+ * const range = worksheet.getRange(0,0,2,2);
+ * const ranges = [];
+ * ranges.push(range);
+ * const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges);
+ * const ruleId = res.ruleId;
+ * permission.removeRangeProtection(unitId, subUnitId, [ruleId]);
+ * ```
*/
removeRangeProtection(unitId: string, subUnitId: string, ruleIds: string[]): void {
const res = this._commandService.syncExecuteCommand(DeleteRangeProtectionMutation.id, {
@@ -262,6 +359,24 @@ export class FPermission extends FBase {
* @param {RangePermissionPointConstructor} FPointClass - The constructor for the range permission point class.
* See the [permission-point documentation](https://github.com/dream-num/univer/tree/dev/packages/sheets/src/services/permission/permission-point) for more details.
* @param {boolean} value - The new permission value to be set for the range (e.g., true for allowing access, false for restricting access).
+ *
+ * @example
+ * ```typescript
+ * const workbook = univerAPI.getActiveWorkbook();
+ * const permission = workbook.getPermission();
+ * const unitId = workbook.getId();
+ * const worksheet = workbook.getActiveSheet();
+ * const subUnitId = worksheet.getSheetId();
+ * const range = worksheet.getRange(0, 0, 2, 2);
+ * const ranges = [];
+ * ranges.push(range);
+ * // Note that there will be no permission changes after this step is completed. It only returns an ID for subsequent permission changes.
+ * // For details, please see the example of the **`setRangeProtectionPermissionPoint`** API.
+ * const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges);
+ * const {permissionId, ruleId} = res;
+ * // After passing the following line of code, the range set above will become uneditable
+ * permission.setRangeProtectionPermissionPoint(unitId,subUnitId,permissionId, permission.permissionPointsDefinition.RangeProtectionPermissionEditPoint, false);
+ * ```
*/
setRangeProtectionPermissionPoint(unitId: string, subUnitId: string, permissionId: string, FPointClass: RangePermissionPointConstructor, value: boolean): void {
const instance = new FPointClass(unitId, subUnitId, permissionId);
@@ -282,15 +397,31 @@ export class FPermission extends FBase {
* @param {string} subUnitId - The unique identifier of the worksheet within the workbook.
* @param {string} ruleId - The ruleId of the range protection rule that is being updated.
* @param {IRange[]} ranges - The array of new ranges to be set for the range protection rule.
+ *
+ * @example
+ * ```typescript
+ * const workbook = univerAPI.getActiveWorkbook();
+ * const permission = workbook.getPermission();
+ * const unitId = workbook.getId();
+ * const worksheet = workbook.getActiveSheet();
+ * const subUnitId = worksheet.getSheetId();
+ * const range = worksheet.getRange(0, 0, 2, 2);
+ * const ranges = [];
+ * ranges.push(range);
+ * const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges);
+ * const {permissionId, ruleId} = res;
+ * const newRange = worksheet.getRange(3, 3, 2, 2);
+ * permission.setRangeProtectionRanges(unitId, subUnitId, ruleId, [newRange]);
+ * ```
*/
- setRangeProtectionRanges(unitId: string, subUnitId: string, ruleId: string, ranges: IRange[]): void {
+ setRangeProtectionRanges(unitId: string, subUnitId: string, ruleId: string, ranges: FRange[]): void {
const rule = this._rangeProtectionRuleModel.getRule(unitId, subUnitId, ruleId);
if (rule) {
const subunitRuleList = this._rangeProtectionRuleModel.getSubunitRuleList(unitId, subUnitId).filter((r) => r.id !== ruleId);
const overlap = subunitRuleList.some((rule) => {
return rule.ranges.some((range) => {
return ranges.some((newRange) => {
- return Rectangle.intersects(newRange, range);
+ return Rectangle.intersects(newRange.getRange(), range);
});
});
});
@@ -303,7 +434,7 @@ export class FPermission extends FBase {
ruleId,
rule: {
...rule,
- ranges,
+ ranges: ranges.map((range) => range.getRange()),
},
});
}
diff --git a/packages/sheets/src/model/range-protection-rule.model.ts b/packages/sheets/src/model/range-protection-rule.model.ts
index 581e81a3ad..eaab96f7d7 100644
--- a/packages/sheets/src/model/range-protection-rule.model.ts
+++ b/packages/sheets/src/model/range-protection-rule.model.ts
@@ -66,7 +66,7 @@ export class RangeProtectionRuleModel {
ruleChange$ = this._ruleChange.asObservable();
- private _ruleRefresh = new Subject();
+ private _ruleRefresh = new Subject<string>();
ruleRefresh$ = this._ruleRefresh.asObservable();
ruleRefresh(id: string) {
diff --git a/packages/sheets/src/services/permission/permission-point/const.ts b/packages/sheets/src/services/permission/permission-point/const.ts
index 518c5f5654..0bc7c358d6 100644
--- a/packages/sheets/src/services/permission/permission-point/const.ts
+++ b/packages/sheets/src/services/permission/permission-point/const.ts
@@ -46,8 +46,6 @@ import { WorksheetInsertHyperlinkPermission } from './worksheet/insert-hyperlink
import { WorksheetInsertRowPermission } from './worksheet/insert-row';
import { WorksheetManageCollaboratorPermission } from './worksheet/manage-collaborator';
import { WorksheetPivotTablePermission } from './worksheet/pivot-table';
-import { WorksheetSelectProtectedCellsPermission } from './worksheet/select-protected-cells';
-import { WorksheetSelectUnProtectedCellsPermission } from './worksheet/select-un-protected-cells';
import { WorksheetSetCellStylePermission } from './worksheet/set-cell-style';
import { WorksheetSetCellValuePermission } from './worksheet/set-cell-value';
import { WorksheetSetColumnStylePermission } from './worksheet/set-column-style';
@@ -55,47 +53,197 @@ import { WorksheetSetRowStylePermission } from './worksheet/set-row-style';
import { WorksheetSortPermission } from './worksheet/sort';
import { WorksheetViewPermission } from './worksheet/view';
+/**
+ * @ignore
+ */
export const PermissionPointsDefinitions = {
+ /**
+ * The permission point for adding or editing workbook comments
+ */
WorkbookCommentPermission,
+
+ /**
+ * The permission point for copy in workbook
+ */
WorkbookCopyPermission,
+
+ /**
+ * The permission point for creating protect in a workbook
+ */
WorkbookCreateProtectPermission,
+
+ /**
+ * The permission point for creating new sheets in a workbook
+ */
WorkbookCreateSheetPermission,
+
+ /**
+ * The permission point for deleting sheets in a workbook
+ */
WorkbookDeleteSheetPermission,
+
+ /**
+ * The permission point for duplicating a sheet in a workbook
+ */
WorkbookDuplicatePermission,
+
+ /**
+ * The permission point for editing workbook content
+ */
WorkbookEditablePermission,
+
+ /**
+ * The permission point for exporting workbook data
+ */
WorkbookExportPermission,
+
+ /**
+ * The permission point for hiding sheets in a workbook
+ */
WorkbookHideSheetPermission,
+
+ /**
+ * The permission point for viewing and managing workbook history
+ */
WorkbookHistoryPermission,
+
+ /**
+ * The permission point for managing collaborators in a workbook
+ */
WorkbookManageCollaboratorPermission,
+
+ /**
+ * The permission point for moving sheets within a workbook
+ */
WorkbookMoveSheetPermission,
+
+ /**
+ * The permission point for printing a workbook
+ */
WorkbookPrintPermission,
+
+ /**
+ * The permission point for recovering a previous history state of a workbook
+ */
WorkbookRecoverHistoryPermission,
+
+ /**
+ * The permission point for renaming sheets in a workbook
+ */
WorkbookRenameSheetPermission,
+
+ /**
+ * The permission point for sharing a workbook with others
+ */
WorkbookSharePermission,
+
+ /**
+ * The permission point for viewing the history of a workbook
+ */
WorkbookViewHistoryPermission,
+
+ /**
+ * The permission point for viewing a workbook
+ */
WorkbookViewPermission,
+
+ /**
+ * The permission point for copying contents from a worksheet
+ */
WorksheetCopyPermission,
+ /**
+ * The permission point for deleting columns in a worksheet
+ */
WorksheetDeleteColumnPermission,
+
+ /**
+ * The permission point for deleting worksheet protection rules
+ */
WorksheetDeleteProtectionPermission,
+
+ /**
+ * The permission point for deleting rows in a worksheet
+ */
WorksheetDeleteRowPermission,
+
+ /**
+ * The permission point for editing extra objects (e.g. shapes) in a worksheet
+ */
WorksheetEditExtraObjectPermission,
+
+ /**
+ * The permission point for editing the content of a worksheet
+ */
WorksheetEditPermission,
+
+ /**
+ * The permission point for applying filters in a worksheet
+ */
WorksheetFilterPermission,
+
+ /**
+ * The permission point for inserting columns into a worksheet
+ */
WorksheetInsertColumnPermission,
+
+ /**
+ * The permission point for inserting hyperlinks in a worksheet
+ */
WorksheetInsertHyperlinkPermission,
+
+ /**
+ * The permission point for inserting rows into a worksheet
+ */
WorksheetInsertRowPermission,
+
+ /**
+ * The permission point for managing collaborators of a worksheet
+ */
WorksheetManageCollaboratorPermission,
+
+ /**
+ * The permission point for creating or modifying pivot tables in a worksheet
+ */
WorksheetPivotTablePermission,
- WorksheetSelectProtectedCellsPermission,
- WorksheetSelectUnProtectedCellsPermission,
+
+ /**
+ * The permission point for setting the style of cells in a worksheet
+ */
WorksheetSetCellStylePermission,
+
+ /**
+ * The permission point for setting the value of cells in a worksheet
+ */
WorksheetSetCellValuePermission,
+
+ /**
+ * The permission point for setting the style of columns in a worksheet
+ */
WorksheetSetColumnStylePermission,
+
+ /**
+ * The permission point for setting the style of rows in a worksheet
+ */
WorksheetSetRowStylePermission,
+
+ /**
+ * The permission point for performing sort operations on a worksheet
+ */
WorksheetSortPermission,
+
+ /**
+ * The permission point for viewing the content of a worksheet
+ */
WorksheetViewPermission,
+ /**
+ * The permission point for editing the range protection settings
+ */
RangeProtectionPermissionEditPoint,
+
+ /**
+ * The permission point for viewing the range protection settings
+ */
RangeProtectionPermissionViewPoint,
};
diff --git a/packages/sheets/src/services/permission/worksheet-permission/worksheet-permission-rule.model.ts b/packages/sheets/src/services/permission/worksheet-permission/worksheet-permission-rule.model.ts
index af794a00ac..df23a09df3 100644
--- a/packages/sheets/src/services/permission/worksheet-permission/worksheet-permission-rule.model.ts
+++ b/packages/sheets/src/services/permission/worksheet-permission/worksheet-permission-rule.model.ts
@@ -34,7 +34,7 @@ export class WorksheetProtectionRuleModel {
type: IRuleChangeType;
}>();
- private _ruleRefresh = new Subject();
+ private _ruleRefresh = new Subject<string>();
private _resetOrder = new Subject();
ruleChange$ = this._ruleChange.asObservable();