@univerjs/sheets 0.5.4 → 0.5.5-experimental.20250123-34738ff

package/lib/types/facade/f-permission.d.ts

@@ -1,6 +1,11 @@
-import { IRange, RangePermissionPointConstructor, WorkbookPermissionPointConstructor, WorkSheetPermissionPointConstructor, FBase, IAuthzIoService, ICommandService, Injector, IPermissionService } from '@univerjs/core';
+import { RangePermissionPointConstructor, WorkbookPermissionPointConstructor, WorkSheetPermissionPointConstructor, FBase, IAuthzIoService, ICommandService, Injector, IPermissionService } from '@univerjs/core';
 import { Observable } from 'rxjs';
+import { FRange } from './f-range';
 import { RangeProtectionRuleModel, WorkbookEditablePermission, WorksheetEditPermission, WorksheetProtectionPointModel, WorksheetProtectionRuleModel, WorksheetViewPermission } from '@univerjs/sheets';
+/**
+ * @description Used to generate permission instances to control permissions for the entire workbook
+ * @hideconstructor
+ */
 export declare class FPermission extends FBase {
     protected readonly _injector: Injector;
     protected readonly _commandService: ICommandService;
@@ -9,6 +14,9 @@ export declare class FPermission extends FBase {
     protected readonly _rangeProtectionRuleModel: RangeProtectionRuleModel;
     protected readonly _worksheetProtectionPointRuleModel: WorksheetProtectionPointModel;
     protected readonly _authzIoService: IAuthzIoService;
+    /**
+     * Permission point definition, can read the point constructor want to modify from here
+     */
     permissionPointsDefinition: {
         WorkbookCommentPermission: typeof import('@univerjs/sheets').WorkbookCommentPermission;
         WorkbookCopyPermission: typeof import('@univerjs/sheets').WorkbookCopyPermission;
@@ -40,8 +48,6 @@ export declare class FPermission extends FBase {
         WorksheetInsertRowPermission: typeof import('@univerjs/sheets').WorksheetInsertRowPermission;
         WorksheetManageCollaboratorPermission: typeof import('@univerjs/sheets').WorksheetManageCollaboratorPermission;
         WorksheetPivotTablePermission: typeof import('@univerjs/sheets').WorksheetPivotTablePermission;
-        WorksheetSelectProtectedCellsPermission: typeof import('@univerjs/sheets').WorksheetSelectProtectedCellsPermission;
-        WorksheetSelectUnProtectedCellsPermission: typeof import('@univerjs/sheets').WorksheetSelectUnProtectedCellsPermission;
         WorksheetSetCellStylePermission: typeof import('@univerjs/sheets').WorksheetSetCellStylePermission;
         WorksheetSetCellValuePermission: typeof import('@univerjs/sheets').WorksheetSetCellValuePermission;
         WorksheetSetColumnStylePermission: typeof import('@univerjs/sheets').WorksheetSetColumnStylePermission;
@@ -51,36 +57,83 @@ export declare class FPermission extends FBase {
         RangeProtectionPermissionEditPoint: typeof import('@univerjs/sheets').RangeProtectionPermissionEditPoint;
         RangeProtectionPermissionViewPoint: typeof import('@univerjs/sheets').RangeProtectionPermissionViewPoint;
     };
-    rangeRuleChangedAfterAuth$: Observable<unknown>;
-    sheetRuleChangedAfterAuth$: Observable<unknown>;
+    /**
+     * An observable object used to monitor permission change events within a range, thereby triggering corresponding subsequent processing.
+     */
+    rangeRuleChangedAfterAuth$: Observable<string>;
+    /**
+     * An observable object used to monitor permission change events within a worksheet, thereby triggering corresponding subsequent processing.
+     */
+    sheetRuleChangedAfterAuth$: Observable<string>;
     constructor(_injector: Injector, _commandService: ICommandService, _permissionService: IPermissionService, _worksheetProtectionRuleModel: WorksheetProtectionRuleModel, _rangeProtectionRuleModel: RangeProtectionRuleModel, _worksheetProtectionPointRuleModel: WorksheetProtectionPointModel, _authzIoService: IAuthzIoService);
     /**
      * 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;
     /**
      * 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 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)
+     * ```
      */
     addWorksheetBasePermission(unitId: string, subUnitId: string): Promise<string | undefined>;
     /**
      * 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;
     /**
@@ -92,16 +145,46 @@ export declare 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);
      */
     setWorksheetPermissionPoint(unitId: string, subUnitId: string, FPointClass: WorkSheetPermissionPointConstructor, value: boolean): Promise<string | undefined>;
     /**
      * 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);
+     * ```
      */
-    addRangeBaseProtection(unitId: string, subUnitId: string, ranges: IRange[]): Promise<{
+    addRangeBaseProtection(unitId: string, subUnitId: string, ranges: FRange[]): Promise<{
         permissionId: string;
         ruleId: string;
     } | undefined>;
@@ -110,6 +193,21 @@ export declare 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;
     /**
@@ -120,6 +218,24 @@ export declare 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;
     /**
@@ -132,6 +248,22 @@ export declare 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;
 }