@univerjs/sheets 0.5.5 → 0.6.0-alpha.0

package/lib/types/facade/f-defined-name.d.ts

@@ -2,6 +2,9 @@ import { FWorksheet } from './f-worksheet';
 import { FBase, IAuthzIoService, ICommandService, Injector, IPermissionService, LocaleService } from '@univerjs/core';
 import { IDefinedNamesService, ISetDefinedNameMutationParam } from '@univerjs/engine-formula';
 import { RangeProtectionRuleModel, WorksheetProtectionPointModel, WorksheetProtectionRuleModel } from '@univerjs/sheets';
+/**
+ * @hideconstructor
+ */
 export declare class FDefinedNameBuilder {
     private _definedNameParam;
     constructor();
@@ -13,8 +16,8 @@ export declare class FDefinedNameBuilder {
      * ```ts
      * const workbook = univerAPI.getActiveWorkbook();
      * const definedNameBuilder = univerAPI.newDefinedName()
-     *    .setName('MyDefinedName')
-     *  .build();
+     *   .setName('MyDefinedName')
+     *   .build();
      * workbook.insertDefinedNameBuilder(definedNameBuilder);
      * ```
      */
@@ -27,9 +30,9 @@ export declare class FDefinedNameBuilder {
      * ```ts
      * const workbook = univerAPI.getActiveWorkbook();
      * const definedNameBuilder = univerAPI.newDefinedName()
-     *  .setFormula('SUM(Sheet1!$A$1)')
-     * .setName('MyDefinedName')
-     * .build();
+     *   .setFormula('SUM(Sheet1!$A$1)')
+     *   .setName('MyDefinedName')
+     *   .build();
      * workbook.insertDefinedNameBuilder(definedNameBuilder);
      * ```
      */
@@ -42,8 +45,8 @@ export declare class FDefinedNameBuilder {
      * ```ts
      * const workbook = univerAPI.getActiveWorkbook();
      * const definedNameBuilder = univerAPI.newDefinedName()
-     *  .setRef('Sheet1!$A$1')
-     * .build();
+     *   .setRef('Sheet1!$A$1')
+     *   .build();
      * workbook.insertDefinedNameBuilder(definedNameBuilder);
      * ```
      */
@@ -59,8 +62,8 @@ export declare class FDefinedNameBuilder {
      * ```ts
      * const workbook = univerAPI.getActiveWorkbook();
      * const definedNameBuilder = univerAPI.newDefinedName()
-     *  .setRefByRange(1, 3, 2, 5)
-     * .build();
+     *   .setRefByRange(1, 3, 2, 5)
+     *   .build();
      * workbook.insertDefinedNameBuilder(definedNameBuilder);
      * ```
      */
@@ -73,8 +76,8 @@ export declare class FDefinedNameBuilder {
      * ```ts
      * const workbook = univerAPI.getActiveWorkbook();
      * const definedNameBuilder = univerAPI.newDefinedName()
-     *  .setComment('This is a comment')
-     * .build();
+     *   .setComment('This is a comment')
+     *   .build();
      * workbook.insertDefinedNameBuilder(definedNameBuilder);
      * ```
      */
@@ -87,8 +90,8 @@ export declare class FDefinedNameBuilder {
      * ```ts
      * const workbook = univerAPI.getActiveWorkbook();
      * const definedNameBuilder = univerAPI.newDefinedName()
-     *  .setHidden(true)
-     * .build();
+     *   .setHidden(true)
+     *   .build();
      * workbook.insertDefinedNameBuilder(definedNameBuilder);
      * ```
      */
@@ -100,15 +103,18 @@ export declare class FDefinedNameBuilder {
      * ```ts
      * const workbook = univerAPI.getActiveWorkbook();
      * const definedNameBuilder = univerAPI.newDefinedName()
-     *  .setRef('Sheet1!$A$1')
-     *  .setName('MyDefinedName')
-     *  .build();
+     *   .setRef('Sheet1!$A$1')
+     *   .setName('MyDefinedName')
+     *   .build();
      * workbook.insertDefinedNameBuilder(definedNameBuilder);
      * ```
      */
     build(): ISetDefinedNameMutationParam;
     load(param: ISetDefinedNameMutationParam): FDefinedNameBuilder;
 }
+/**
+ * @hideconstructor
+ */
 export declare class FDefinedName extends FBase {
     protected _definedNameParam: ISetDefinedNameMutationParam;
     protected readonly _injector: Injector;

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

@@ -1,4 +1,7 @@
 import { SheetSkeletonChangeType, SheetValueChangeType } from '@univerjs/sheets';
+/**
+ * @ignore
+ */
 export interface IFSheetsEnum {
     /**
      * Sheet value change command types. These commands affect the content or style of cells.

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

@@ -6,6 +6,7 @@ import { FWorksheet } from './f-worksheet';
 /**
  * Interface for sheet-related events
  * Provides event names for sheet creation, workbook creation, and gridline changes
+ * @ignore
  */
 export interface IFSheetEventMixin {
     /**
@@ -13,10 +14,10 @@ export interface IFSheetEventMixin {
      * @see {@link ISheetCreatedEventParams}
      * @example
      * ```ts
-     univerAPI.addEvent(univerAPI.Event.SheetCreated, (params) => {
-         const { workbook, worksheet } = params;
-         console.log('sheet created', params);
-     });
+     * univerAPI.addEvent(univerAPI.Event.SheetCreated, (params) => {
+     *   const { workbook, worksheet } = params;
+     *   console.log('sheet created', params);
+     * });
      * ```
      */
     get SheetCreated(): 'SheetCreated';
@@ -26,8 +27,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.BeforeSheetCreate, (params) => {
-     *      const { workbook, index, sheet } = params;
-     *     console.log('before sheet create', params);
+     *   const { workbook, index, sheet } = params;
+     *   console.log('before sheet create', params);
      * });
      * ```
      */
@@ -38,8 +39,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.ActiveSheetChanged, (params) => {
-     *      const { workbook, activeSheet, oldActiveSheet } = params;
-     *     console.log('before active sheet changed', params);
+     *   const { workbook, activeSheet, oldActiveSheet } = params;
+     *   console.log('before active sheet changed', params);
      * });
      * ```
      */
@@ -50,8 +51,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.ActiveSheetChanged, (params) => {
-     *      const { workbook, activeSheet } = params;
-     *     console.log('after active sheet changed', params);
+     *   const { workbook, activeSheet } = params;
+     *   console.log('after active sheet changed', params);
      * });
      * ```
      */
@@ -62,8 +63,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.BeforeSheetDelete, (params) => {
-     *      const { workbook, worksheetId } = params;
-     *     console.log('before sheet delete', params);
+     *   const { workbook, worksheetId } = params;
+     *   console.log('before sheet delete', params);
      * });
      * ```
      */
@@ -74,8 +75,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.BeforeSheetDelete, (params) => {
-     *      const { workbook, worksheet } = params;
-     *     console.log('before sheet delete', params);
+     *   const { workbook, worksheet } = params;
+     *   console.log('before sheet delete', params);
      * });
      * ```
      */
@@ -86,8 +87,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.SheetMoved, (params) => {
-     *      const { workbook, worksheet, newIndex } = params;
-     *     console.log('sheet moved', params);
+     *   const { workbook, worksheet, newIndex } = params;
+     *   console.log('sheet moved', params);
      * });
      * ```
      */
@@ -98,8 +99,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.BeforeSheetMove, (params) => {
-     *      const { workbook, worksheet, newIndex, oldIndex } = params;
-     *     console.log('before sheet move', params);
+     *   const { workbook, worksheet, newIndex, oldIndex } = params;
+     *   console.log('before sheet move', params);
      * });
      * ```
      */
@@ -110,8 +111,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.SheetNameChanged, (params) => {
-     *      const { workbook, worksheet, newName } = params;
-     *     console.log('sheet name changed', params);
+     *   const { workbook, worksheet, newName } = params;
+     *   console.log('sheet name changed', params);
      * });
      * ```
      */
@@ -122,8 +123,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.BeforeSheetNameChange, (params) => {
-     *      const { workbook, worksheet, newName, oldName } = params;
-     *     console.log('before sheet name changed', params);
+     *   const { workbook, worksheet, newName, oldName } = params;
+     *   console.log('before sheet name changed', params);
      * });
      * ```
      */
@@ -134,8 +135,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.SheetTabColorChanged, (params) => {
-     *      const { workbook, worksheet, color } = params;
-     *     console.log('sheet tab color changed', params);
+     *   const { workbook, worksheet, color } = params;
+     *   console.log('sheet tab color changed', params);
      * });
      * ```
      */
@@ -146,8 +147,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.BeforeSheetTabColorChange, (params) => {
-     *      const { workbook, worksheet, color, oldColor } = params;
-     *     console.log('before sheet tab color changed', params);
+     *   const { workbook, worksheet, color, oldColor } = params;
+     *   console.log('before sheet tab color changed', params);
      * });
      * ```
      */
@@ -158,8 +159,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.SheetHideChanged, (params) => {
-     *      const { workbook, worksheet } = params;
-     *     console.log('sheet hide changed', params);
+     *   const { workbook, worksheet } = params;
+     *   console.log('sheet hide changed', params);
      * });
      * ```
      */
@@ -170,8 +171,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.BeforeSheetHideChange, (params) => {
-     *      const { workbook, worksheet, hide } = params;
-     *     console.log('before sheet hide changed', params);
+     *   const { workbook, worksheet, hide } = params;
+     *   console.log('before sheet hide changed', params);
      * });
      * ```
      */
@@ -182,8 +183,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.WorkbookCreated, (params) => {
-     *      const { unitId, type, workbook, unit } = params;
-     *     console.log('workbook created', params);
+     *   const { unitId, type, workbook, unit } = params;
+     *   console.log('workbook created', params);
      * });
      * ```
      */
@@ -194,8 +195,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.WorkbookDisposed, (params) => {
-     *      const { unitId, unitType, snapshot } = params;
-     *     console.log('unit disposed', params);
+     *   const { unitId, unitType, snapshot } = params;
+     *   console.log('unit disposed', params);
      * });
      * ```
      */
@@ -206,8 +207,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.GridlineChanged, (params) => {
-     *      const { workbook, worksheet, enabled, color } = params;
-     *     console.log('gridline changed', params);
+     *   const { workbook, worksheet, enabled, color } = params;
+     *   console.log('gridline changed', params);
      * });
      * ```
      */
@@ -218,8 +219,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.BeforeGridlineEnableChange, (params) => {
-     *      const { workbook, worksheet, enabled } = params;
-     *     console.log('gridline changed', params);
+     *   const { workbook, worksheet, enabled } = params;
+     *   console.log('gridline changed', params);
      * });
      * ```
      */
@@ -230,8 +231,8 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.BeforeGridlineColorChange, (params) => {
-     *      const { workbook, worksheet, color } = params;
-     *     console.log('gridline changed', params);
+     *   const { workbook, worksheet, color } = params;
+     *   console.log('gridline changed', params);
      * });
      * ```
      */
@@ -241,7 +242,7 @@ export interface IFSheetEventMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (p)=> {
-     *      const { workbook, effectedRanges, payload } = p;
+     *   const { workbook, effectedRanges, payload } = p;
      * });
      * ```
      */
@@ -490,6 +491,7 @@ export interface ISheetValueChangedEvent extends IEventBase {
 /**
  * Configuration interface for sheet-related events
  * Provides event names and their corresponding event parameter interfaces
+ * @ignore
  */
 export interface ISheetEventParamConfig {
     /** Event fired after a worksheet is created */

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;
 }