@univerjs/sheets 0.5.3 → 0.5.4-experimental.20250114-7c09c35

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

@@ -1,4 +1,4 @@
-import { CustomData, ICellData, IDisposable, IFreeze, IObjectArrayPrimitiveType, IStyleData, Nullable, Workbook, Worksheet, FBaseInitialable, ICommandService, ILogService, Injector, ObjectMatrix } from '@univerjs/core';
+import { CustomData, ICellData, IColumnRange, IDisposable, IEventParamConfig, IFreeze, IObjectArrayPrimitiveType, IRowRange, IStyleData, Nullable, Workbook, Worksheet, FBaseInitialable, ICommandService, ILogService, Injector, ObjectMatrix } from '@univerjs/core';
 import { FDefinedName } from './f-defined-name';
 import { FWorkbook } from './f-workbook';
 import { SheetsSelectionsService } from '@univerjs/sheets';
@@ -20,6 +20,33 @@ export declare class FWorksheet extends FBaseInitialable {
     protected readonly _logService: ILogService;
     protected readonly _commandService: ICommandService;
     constructor(_fWorkbook: FWorkbook, _workbook: Workbook, _worksheet: Worksheet, _injector: Injector, _selectionManagerService: SheetsSelectionsService, _logService: ILogService, _commandService: ICommandService);
+    getSheet(): Worksheet;
+    private _eventRegistry;
+    private _ensureEventRegistry;
+    /**
+     * Add an event listener
+     * @param event key of event
+     * @param callback callback when event triggered
+     * @returns {Disposable} The Disposable instance, for remove the listener
+     * @example
+     * ```ts
+     * univerAPI.addEvent(univerAPI.event.UnitCreated, (params) => {
+     *     console.log('unit created', params);
+     * });
+     * ```
+     */
+    addEvent(event: keyof IEventParamConfig, callback: (params: IEventParamConfig[typeof event]) => void): IDisposable;
+    /**
+     * Fire an event, used in internal only.
+     * @param event {string} key of event
+     * @param params {any} params of event
+     * @returns {boolean} should cancel
+     * @example
+     * ```ts
+     * this.fireEvent(univerAPI.event.UnitCreated, params);
+     * ```
+     */
+    protected fireEvent<T extends keyof IEventParamConfig>(event: T, params: IEventParamConfig[T]): boolean | undefined;
     /**
      * Returns the injector
      * @returns The injector
@@ -60,7 +87,7 @@ export declare class FWorksheet extends FBaseInitialable {
     /**
      * Get the default style of the worksheet column
      * @param {number} index The column index
-     * @param  {boolean} [keepRaw] If true, return the raw style data maybe the style name or style data, otherwise return the data from col manager
+     * @param {boolean} [keepRaw] If true, return the raw style data maybe the style name or style data, otherwise return the data from col manager
      * @returns {Nullable<IStyleData> | string} The default style of the worksheet column name or style data
      */
     getColumnDefaultStyle(index: number, keepRaw?: boolean): Nullable<IStyleData> | string;
@@ -116,24 +143,24 @@ export declare class FWorksheet extends FBaseInitialable {
     getRange(a1Notation: string): FRange;
     /**
      * Returns the current number of columns in the sheet, regardless of content.
-     * @return The maximum columns count of the sheet
+     * @returns {number} The maximum columns count of the sheet
      */
     getMaxColumns(): number;
     /**
      * Returns the current number of rows in the sheet, regardless of content.
-     * @return The maximum rows count of the sheet
+     * @returns {number}The maximum rows count of the sheet
      */
     getMaxRows(): number;
     /**
      * Inserts a row after the given row position.
-     * @param afterPosition The row after which the new row should be added, starting at 0 for the first row.
-     * @returns This sheet, for chaining.
+     * @param {number} afterPosition The row after which the new row should be added, starting at 0 for the first row.
+     * @returns {FWorksheet} This sheet, for chaining.
      */
     insertRowAfter(afterPosition: number): FWorksheet;
     /**
      * Inserts a row before the given row position.
-     * @param beforePosition The row before which the new row should be added, starting at 0 for the first row.
-     * @returns This sheet, for chaining.
+     * @param {number} beforePosition The row before which the new row should be added, starting at 0 for the first row.
+     * @returns {FWorksheet} This sheet, for chaining.
      */
     insertRowBefore(beforePosition: number): FWorksheet;
     /**
@@ -185,45 +212,46 @@ export declare class FWorksheet extends FBaseInitialable {
     hideRow(row: FRange): FWorksheet;
     /**
      * Hides one or more consecutive rows starting at the given index. Use 0-index for this method.
-     * @param rowIndex The starting index of the rows to hide.
-     * @param numRows The number of rows to hide.
-     * @returns This sheet, for chaining.
+     * @param {number} rowIndex The starting index of the rows to hide.
+     * @param {number} numRows The number of rows to hide.
+     * @returns {FWorksheet} This sheet, for chaining.
      */
     hideRows(rowIndex: number, numRows?: number): FWorksheet;
     /**
-     * Unhides the row in the given range.
-     * @param row The range to unhide, if hidden.
-     * @returns This sheet, for chaining.
+     * Make the row in the given range visible.
+     * @param {FRange} row The range to unhide, if hidden.
+     * @returns {FWorksheet} This sheet, for chaining.
      */
     unhideRow(row: FRange): FWorksheet;
     /**
-     * Unhides one or more consecutive rows starting at the given index. Use 0-index for this method.
-     * @param rowIndex The starting index of the rows to unhide.
-     * @param numRows The number of rows to unhide.
-     * @returns This sheet, for chaining.
+     * Scrolling sheet to make specific rows visible.
+     * @param {number} rowIndex The starting index of the rows
+     * @param {number} numRows The number of rows
+     * @returns {FWorksheet} This sheet, for chaining.
      */
     showRows(rowIndex: number, numRows?: number): FWorksheet;
     /**
      * Sets the row height of the given row in pixels. By default, rows grow to fit cell contents. If you want to force rows to a specified height, use setRowHeightsForced(startRow, numRows, height).
-     * @param rowPosition The row position to change.
-     * @param height The height in pixels to set it to.
-     * @returns This sheet, for chaining.
+     * @param {number} rowPosition The row position to change.
+     * @param {number} height The height in pixels to set it to.
+     * @returns {FWorksheet} This sheet, for chaining.
      */
     setRowHeight(rowPosition: number, height: number): FWorksheet;
     /**
-     * Sets the height of the given rows in pixels. By default, rows grow to fit cell contents. If you want to force rows to a specified height, use setRowHeightsForced(startRow, numRows, height).
-     * @param startRow The starting row position to change.
-     * @param numRows The number of rows to change.
-     * @param height The height in pixels to set it to.
-     * @returns This sheet, for chaining.
+     * Sets the height of the given rows in pixels.
+     * By default, rows grow to fit cell contents. If you want to force rows to a specified height, use setRowHeightsForced(startRow, numRows, height).
+     * @param {number} startRow The starting row position to change.
+     * @param {number} numRows The number of rows to change.
+     * @param {number} height The height in pixels to set it to.
+     * @returns {FWorksheet} This sheet, for chaining.
      */
     setRowHeights(startRow: number, numRows: number, height: number): FWorksheet;
     /**
      * Sets the height of the given rows in pixels. By default, rows grow to fit cell contents. When you use setRowHeightsForced, rows are forced to the specified height even if the cell contents are taller than the row height.
-     * @param startRow The starting row position to change.
-     * @param numRows The number of rows to change.
-     * @param height The height in pixels to set it to.
-     * @returns This sheet, for chaining.
+     * @param {number} startRow The starting row position to change.
+     * @param {number} numRows The number of rows to change.
+     * @param {number} height The height in pixels to set it to.
+     * @returns {FWorksheet} This sheet, for chaining.
      */
     setRowHeightsForced(startRow: number, numRows: number, height: number): FWorksheet;
     /**
@@ -299,13 +327,13 @@ export declare class FWorksheet extends FBaseInitialable {
      */
     hideColumns(columnIndex: number, numColumns?: number): FWorksheet;
     /**
-     * Unhides the column in the given range.
+     * Show the column in the given range.
      * @param column The range to unhide, if hidden.
      * @returns This sheet, for chaining.
      */
     unhideColumn(column: FRange): FWorksheet;
     /**
-     * Unhides one or more consecutive columns starting at the given index. Use 0-index for this method.
+     * Show one or more consecutive columns starting at the given index. Use 0-index for this method.
      * @param columnIndex The starting index of the columns to unhide.
      * @param numColumns The number of columns to unhide.
      * @returns This sheet, for chaining.
@@ -351,19 +379,19 @@ export declare class FWorksheet extends FBaseInitialable {
     getActiveRange(): FRange | null;
     /**
      * Sets the active selection region for this sheet.
-     * @param range The range to set as the active selection.
+     * @param {FRange} range The range to set as the active selection.
+     * @returns {FWorksheet} This sheet, for chaining.
      */
-    setActiveRange(range: FRange): void;
+    setActiveRange(range: FRange): FWorksheet;
     /**
      * Sets the active selection region for this sheet.
      * @param range The range to set as the active selection.
      */
-    setActiveSelection: (range: FRange) => void;
+    setActiveSelection: (range: FRange) => FWorksheet;
     /**
      * Sets the frozen state of the current sheet.
      * @param freeze - the scrolling viewport start range and count of freezed rows and columns.
      * that means if you want to freeze the first 3 rows and 2 columns, you should set freeze as { startRow: 3, startColumn: 2, xSplit: 2, ySplit: 3 }
-     *
      * @deprecated use `setFrozenRows` and `setFrozenColumns` instead.
      * @returns True if the command was successful, false otherwise.
      */
@@ -376,7 +404,6 @@ export declare class FWorksheet extends FBaseInitialable {
     /**
      * Get the freeze state of the current sheet.
      * @returns The freeze state of the current sheet.
-     *
      * @deprecated use `getRowFreezeStatus` and `getColumnFreezeStatus` instead.
      */
     getFreeze(): IFreeze;
@@ -385,21 +412,21 @@ export declare class FWorksheet extends FBaseInitialable {
      * @param columns The number of columns to freeze.
      * To unfreeze all columns, set this value to 0.
      */
-    setFrozenColumns(columns: number): void;
+    setFrozenColumns(columns: number): FWorksheet;
     /**
      * Set freeze column, then the range from startColumn to endColumn will be fixed.
      * e.g. setFrozenColumns(0, 2) will fix the column range from 0 to 2.
      * e.g. setFrozenColumns(2, 3) will fix the column range from 2 to 3, And column from 0 to 1 will be invisible.
-     *
      * @example
-     * ``` ts
+     * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorkSheet = fWorkbook.getActiveSheet();
      * // freeze the first too columns.
      * fWorkSheet.setFrozenColumns(0, 2);
      * ```
-     * @param startColumn
-     * @param endColumn
+     * @param startColumn - The start column of the range to freeze.
+     * @param endColumn - The end column of the range to freeze.
+     * @returns {FWorksheet} This FWorksheet instance.
      */
     setFrozenColumns(startColumn: number, endColumn: number): FWorksheet;
     /**
@@ -407,14 +434,13 @@ export declare class FWorksheet extends FBaseInitialable {
      * @param rows The number of rows to freeze.
      * To unfreeze all rows, set this value to 0.
      */
-    setFrozenRows(rows: number): void;
+    setFrozenRows(rows: number): FWorksheet;
     /**
      * Set freeze row, then the range from startRow to endRow will be fixed.
      * e.g. setFrozenRows(0, 2) will fix the row range from 0 to 2.
      * e.g. setFrozenRows(2, 3) will fix the row range from 2 to 3, And row from 0 to 1 will be invisible.
-     * @param startRow
-     * @param endRow
-     *
+     * @param startRow - The start row of the range to freeze.
+     * @param endRow - The end row of the range to freeze.
      * @example
      * ``` ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -426,30 +452,24 @@ export declare class FWorksheet extends FBaseInitialable {
     setFrozenRows(startColumn: number, endColumn: number): FWorksheet;
     /**
      * Get the number of frozen columns.
-     * @returns The number of frozen columns.
-     * Returns 0 if no columns are frozen.
+     * @returns The number of frozen columns, returns 0 if no columns are frozen.
      */
     getFrozenColumns(): number;
     /**
      * Get the number of frozen rows.
-     * @returns The number of frozen rows.
-     * Returns 0 if no rows are frozen.
+     * @returns The number of frozen rows. returns 0 if no rows are frozen.
      */
     getFrozenRows(): number;
     /**
      * Get freezed rows.
+     * @returns {IRowRange} The range of the frozen rows.
      */
-    getFrozenRowRange(): {
-        startRow: number;
-        endRow: number;
-    };
+    getFrozenRowRange(): IRowRange;
     /**
      * Get freezed columns
+     * @returns {IColumnRange} The range of the frozen columns.
      */
-    getFrozenColumnRange(): {
-        startColumn: number;
-        endColumn: number;
-    };
+    getFrozenColumnRange(): IColumnRange;
     /**
      * Returns true if the sheet's gridlines are hidden; otherwise returns false. Gridlines are visible by default.
      * @returns {boolean} True if the sheet's gridlines are hidden; otherwise false.
@@ -467,6 +487,7 @@ export declare class FWorksheet extends FBaseInitialable {
     /**
      * Hides or reveals the sheet gridlines.
      * @param {boolean} hidden If `true`, hide gridlines in this sheet; otherwise show the gridlines.
+     * @returns {FWorksheet} Returns the current worksheet instance for method chaining
      * @example
      * ``` ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -556,13 +577,14 @@ export declare class FWorksheet extends FBaseInitialable {
     onBeforeCellDataChange(callback: (cellValue: ObjectMatrix<Nullable<ICellData>>) => void): IDisposable;
     /**
      * Hides this sheet. Has no effect if the sheet is already hidden. If this method is called on the only visible sheet, it throws an exception.
+     * @returns {FWorksheet} Returns the current worksheet instance for method chaining
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorkSheet = fWorkbook.getActiveSheet();
      * // hide the active sheet
      * fWorkSheet.hideSheet();
-     * ``
+     * ```
      */
     hideSheet(): FWorksheet;
     /**
@@ -682,6 +704,7 @@ export declare class FWorksheet extends FBaseInitialable {
      */
     getLastColumns(): number;
     /**
+     * @deprecated use getLastColumn instead.
      * Returns the position of the last column that has content. Same as getLastColumns.
      * @returns {number} the last column of the sheet that contains content.
      * @example
@@ -694,6 +717,7 @@ export declare class FWorksheet extends FBaseInitialable {
      */
     getLastColumn(): number;
     /**
+     * @deprecated use getLastRow instead.
      * Returns the position of the last row that has content.
      * @returns {number} the last row of the sheet that contains content.
      * @example
@@ -743,5 +767,80 @@ export declare class FWorksheet extends FBaseInitialable {
      * ```
      */
     getDefinedNames(): FDefinedName[];
+    /**
+     * Set custom metadata of worksheet
+     * @param {CustomData | undefined} custom custom metadata
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorkSheet = fWorkbook.getActiveSheet();
+     * fWorkSheet.setCustomMetadata({ key: 'value' });
+     * ```
+     */
+    setCustomMetadata(custom: CustomData | undefined): FWorksheet;
+    /**
+     * Set custom metadata of row
+     * @param {number} index row index
+     * @param {CustomData | undefined} custom custom metadata
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorkSheet = fWorkbook.getActiveSheet();
+     * fWorkSheet.setRowCustomMetadata(0, { key: 'value' });
+     * ```
+     */
+    setRowCustomMetadata(index: number, custom: CustomData | undefined): FWorksheet;
+    /**
+     * Set custom metadata of column
+     * @param {number} index column index
+     * @param {CustomData | undefined} custom custom metadata
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorkSheet = fWorkbook.getActiveSheet();
+     * fWorkSheet.setColumnCustomMetadata(0, { key: 'value' });
+     * ```
+     */
+    setColumnCustomMetadata(index: number, custom: CustomData | undefined): FWorksheet;
+    /**
+     * Get custom metadata of row
+     * @param {number} index row index
+     * @returns {CustomData | undefined} custom metadata
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorkSheet = fWorkbook.getActiveSheet();
+     * const custom = fWorkSheet.getRowCustomMetadata(0);
+     * ```
+     */
+    getRowCustomMetadata(index: number): CustomData | undefined;
+    /**
+     * Get custom metadata of column
+     * @param {number} index column index
+     * @returns {CustomData | undefined} custom metadata
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorkSheet = fWorkbook.getActiveSheet();
+     * const custom = fWorkSheet.getColumnCustomMetadata(0);
+     * ```
+     */
+    getColumnCustomMetadata(index: number): CustomData | undefined;
+    /**
+     * Get all merged cells in the current worksheet
+     * @returns {FRange[]} All the merged cells in the worksheet
+     * @example
+     * ```ts
+     * const workbook = univerAPI.getActiveWorkbook();
+     * const worksheet = workbook.getActiveSheet();
+     * const rangeFirst = worksheet.getRange(0, 0, 2, 2);
+     * const mergeFirst = rangeFirst.merge();
+     * const rangeSecond = worksheet.getRange(5, 0, 2, 2);
+     * const mergeSecond = rangeSecond.merge();
+     * const mergeData = worksheet.getMergeData();
+     * console.log('debugger', mergeData);
+     * ```
+     */
+    getMergeData(): FRange[];
 }
 export {};

package/lib/types/facade/index.d.ts

@@ -17,7 +17,6 @@ import './f-univer';
 export * from './f-event';
 export { FPermission } from './f-permission';
 export { FRange } from './f-range';
-export type { FontLine, FontStyle, FontWeight } from './f-range';
 export { FSelection } from './f-selection';
 export { FSheetHooks } from './f-sheet-hooks';
 export { FWorkbook } from './f-workbook';

package/lib/types/facade/utils.d.ts

@@ -1,24 +1,60 @@
 import { CellValue, ICellData, IObjectMatrixPrimitiveType, IRange, IRangeWithCoord, Worksheet, HorizontalAlign, VerticalAlign } from '@univerjs/core';
 export type FHorizontalAlignment = 'left' | 'center' | 'normal';
 export type FVerticalAlignment = 'top' | 'middle' | 'bottom';
+/**
+ *
+ * @param value
+ */
 export declare function transformFacadeHorizontalAlignment(value: FHorizontalAlignment): HorizontalAlign;
+/**
+ *
+ * @param value
+ */
 export declare function transformCoreHorizontalAlignment(value: HorizontalAlign): FHorizontalAlignment;
+/**
+ *
+ * @param value
+ */
 export declare function transformFacadeVerticalAlignment(value: FVerticalAlignment): VerticalAlign;
+/**
+ *
+ * @param value
+ */
 export declare function transformCoreVerticalAlignment(value: VerticalAlign): FVerticalAlignment;
 /**
- * covert cell value to cell data
+ * Covert cell value to cell data.
  * @param value
  * @returns
  */
 export declare function covertCellValue(value: CellValue | ICellData): ICellData;
 /**
- * covert cell value array or matrix to cell data
+ * Covert cell value array or matrix to cell data.
  * @param value
  * @param range
  * @returns
  */
 export declare function covertCellValues(value: CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>, range: IRange): IObjectMatrixPrimitiveType<ICellData>;
+/**
+ *
+ * @param mergeInfo
+ * @param range
+ */
 export declare function isCellMerged(mergeInfo: IRangeWithCoord, range: IRange): boolean;
+/**
+ *
+ * @param mergeInfo
+ * @param range
+ */
 export declare function isSingleCell(mergeInfo: IRangeWithCoord, range: IRange): boolean;
+/**
+ *
+ * @param range
+ * @param worksheet
+ */
 export declare function covertToRowRange(range: IRange, worksheet: Worksheet): IRange;
+/**
+ *
+ * @param range
+ * @param worksheet
+ */
 export declare function covertToColRange(range: IRange, worksheet: Worksheet): IRange;

package/lib/types/index.d.ts

@@ -49,6 +49,8 @@ export { getNextPrimaryCell } from './services/selections/move-active-cell-util'
 export { ExclusiveRangeService, IExclusiveRangeService } from './services/exclusive-range/exclusive-range-service';
 export { defaultWorksheetPermissionPoint, getAllWorksheetPermissionPoint, getAllWorksheetPermissionPointByPointPanel } from './services/permission';
 export type { IWorksheetProtectionRule } from './services/permission/type';
+export { SheetPermissionCheckController } from './controllers/permission/sheet-permission-check.controller';
+export { SheetPermissionInitController } from './controllers/permission/sheet-permission-init.controller';
 export { WorksheetProtectionPointModel, WorksheetProtectionRuleModel } from './services/permission/worksheet-permission';
 export { defaultWorkbookPermissionPoints, getAllWorkbookPermissionPoint } from './services/permission/workbook-permission';
 export { WorkbookCommentPermission, WorkbookCopyPermission, WorkbookCreateProtectPermission, WorkbookCreateSheetPermission, WorkbookDeleteSheetPermission, WorkbookDuplicatePermission, WorkbookEditablePermission, WorkbookExportPermission, WorkbookHideSheetPermission, WorkbookHistoryPermission, WorkbookManageCollaboratorPermission, WorkbookMoveSheetPermission, WorkbookPrintPermission, WorkbookRecoverHistoryPermission, WorkbookRenameSheetPermission, WorkbookSharePermission, WorkbookViewHistoryPermission, WorkbookViewPermission, WorksheetCopyPermission, WorksheetDeleteColumnPermission, WorksheetDeleteProtectionPermission, WorksheetDeleteRowPermission, WorksheetEditExtraObjectPermission, WorksheetEditPermission, WorksheetFilterPermission, WorksheetInsertColumnPermission, WorksheetInsertHyperlinkPermission, WorksheetInsertRowPermission, WorksheetManageCollaboratorPermission, WorksheetPivotTablePermission, WorksheetSelectProtectedCellsPermission, WorksheetSelectUnProtectedCellsPermission, WorksheetSetCellStylePermission, WorksheetSetCellValuePermission, WorksheetSetColumnStylePermission, WorksheetSetRowStylePermission, WorksheetSortPermission, WorksheetViewPermission, } from './services/permission/permission-point';

package/lib/types/model/range-theme-util.d.ts

@@ -44,15 +44,15 @@ export declare class RangeThemeStyle {
      */
     lastRowStyle: Nullable<IRangeThemeStyleItem>;
     /**
-     * @property {Nullable<IRangeThemeStyleItem>} effect for the first column.
+     * @property {Nullable<IRangeThemeStyleItem>} firstColumnStyle effect for the first column.
      */
     firstColumnStyle: Nullable<IRangeThemeStyleItem>;
     /**
-     * @property {Nullable<IRangeThemeStyleItem>} effect for the second column.
+     * @property {Nullable<IRangeThemeStyleItem>} secondColumnStyle effect for the second column.
      */
     secondColumnStyle: Nullable<IRangeThemeStyleItem>;
     /**
-     * @property {Nullable<IRangeThemeStyleItem>} effect for the last column.
+     * @property {Nullable<IRangeThemeStyleItem>} lastColumnStyle effect for the last column.
      */
     lastColumnStyle: Nullable<IRangeThemeStyleItem>;
     /**