@univerjs/sheets 0.6.1 → 0.6.2-nightly.202503031606

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

@@ -1,11 +1,11 @@
-import { CustomData, ICellData, IColumnRange, IDisposable, IFreeze, IObjectArrayPrimitiveType, IRange, IRowRange, IStyleData, Nullable, Workbook, Worksheet, BooleanNumber, ICommandService, ILogService, Injector, ObjectMatrix } from '@univerjs/core';
+import { CellValue, CustomData, ICellData, IColumnRange, IDisposable, IFreeze, IObjectArrayPrimitiveType, IRange, IRowRange, IStyleData, Nullable, Workbook, Worksheet, BooleanNumber, ICommandService, ILogService, Injector, ObjectMatrix } from '@univerjs/core';
 import { FDefinedName } from './f-defined-name';
 import { FWorkbook } from './f-workbook';
 import { FBaseInitialable } from '@univerjs/core/facade';
 import { SheetsSelectionsService } from '@univerjs/sheets';
 import { FRange } from './f-range';
 import { FSelection } from './f-selection';
-interface IFacadeClearOptions {
+export interface IFacadeClearOptions {
     contentsOnly?: boolean;
     formatOnly?: boolean;
 }
@@ -441,7 +441,7 @@ export declare class FWorksheet extends FBaseInitialable {
     /**
      * Scrolling sheet to make specific rows visible.
      * @param {number} rowIndex - The starting index of the rows
-     * @param {number} numRow - The number of rows
+     * @param {number} numRows - The number of rows
      * @returns {FWorksheet} This worksheet instance for chaining
      * @example
      * ```typescript
@@ -452,7 +452,7 @@ export declare class FWorksheet extends FBaseInitialable {
      * fWorksheet.showRows(0);
      * ```
      */
-    showRows(rowIndex: number, numRow?: number): FWorksheet;
+    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 {number} rowPosition - The row position to change.
@@ -494,6 +494,24 @@ export declare class FWorksheet extends FBaseInitialable {
      * ```
      */
     setRowHeights(startRow: number, numRows: number, height: number): FWorksheet;
+    /**
+     * Gets the height in pixels of the given row.
+     * @param {number} rowPosition - The position of the row to examine. index starts at 0.
+     * @returns {number} The height in pixels of the given row.
+     * @example
+     * ```typescript
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set the value of the cell A1 to 'Hello, Univer!', set the font size to 30 and font weight to bold
+     * const fRange = fWorksheet.getRange('A1');
+     * fRange.setValue('Hello, Univer!').setFontSize(30).setFontWeight('bold');
+     *
+     * // Get the height of the first row
+     * console.log(fWorksheet.getRowHeight(0));
+     * ```
+     */
+    getRowHeight(rowPosition: number): number;
     /**
      * Sets the height of the given rows to auto.
      * @param {number} startRow - The starting row position to change
@@ -506,6 +524,21 @@ export declare class FWorksheet extends FBaseInitialable {
      * ```
      */
     setRowAutoHeight(startRow: number, numRows: number): FWorksheet;
+    /**
+     * Sets the height of the given ranges to auto.
+     * @param {IRange[]} ranges - The ranges to change
+     * @returns {FWorksheet} This worksheet instance for chaining
+     * @example
+     * ```typescript
+     * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const ranges = [
+     * { startRow: 1, endRow: 10, startColumn: 0, endColumn: 10 },
+     * { startRow: 11, endRow: 20, startColumn: 0, endColumn: 10 },
+     * ]
+     * fWorksheet.setRangesAutoHeight(ranges);
+     * ```
+     */
+    setRangesAutoHeight(ranges: IRange[]): 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 {number} startRow - The starting row position to change
@@ -699,7 +732,7 @@ export declare class FWorksheet extends FBaseInitialable {
     /**
      * Show one or more consecutive columns starting at the given index. Use 0-index for this method
      * @param {number} columnIndex - The starting index of the columns to unhide
-     * @param {number} numColumn - The number of columns to unhide
+     * @param {number} numColumns - The number of columns to unhide
      * @returns {FWorksheet} This sheet, for chaining
      * @example
      * ```typescript
@@ -710,7 +743,7 @@ export declare class FWorksheet extends FBaseInitialable {
      * fWorksheet.showColumns(0, 1);
      * ```
      */
-    showColumns(columnIndex: number, numColumn?: number): FWorksheet;
+    showColumns(columnIndex: number, numColumns?: number): FWorksheet;
     /**
      * Sets the width of the given column in pixels.
      * @param {number} columnPosition - The position of the given column to set
@@ -738,6 +771,27 @@ export declare class FWorksheet extends FBaseInitialable {
      * ```
      */
     setColumnWidths(startColumn: number, numColumn: number, width: number): FWorksheet;
+    /**
+     * Gets the width in pixels of the given column.
+     * @param {number} columnPosition - The position of the column to examine. index starts at 0.
+     * @returns {number} The width of the column in pixels
+     * @example
+     * ```typescript
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set the long text value in cell A1
+     * const fRange = fWorksheet.getRange('A1');
+     * fRange.setValue('Whenever it is a damp, drizzly November in my soul...');
+     *
+     * // Set the column A to a width which fits the text
+     * fWorksheet.autoResizeColumn(0);
+     *
+     * // Get the width of the column A
+     * console.log(fWorksheet.getColumnWidth(0));
+     * ```
+     */
+    getColumnWidth(columnPosition: number): number;
     /**
      * Set custom properties for given columns.
      * @param {IObjectArrayPrimitiveType<CustomData>} custom - The custom properties to set
@@ -819,6 +873,16 @@ export declare class FWorksheet extends FBaseInitialable {
      * ```
      */
     setActiveRange(range: FRange): FWorksheet;
+    /**
+     * Returns the active cell in this sheet.
+     * @returns {FRange | null} The active cell
+     * @example
+     * ```typescript
+     * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * console.log(fWorkSheet.getActiveCell().getA1Notation());
+     * ```
+     */
+    getActiveCell(): FRange | null;
     /**
      * Sets the active selection region for this sheet.
      * @param range - The range to set as the active selection
@@ -1330,5 +1394,18 @@ export declare class FWorksheet extends FBaseInitialable {
      * ```
      */
     getColumnCustomMetadata(index: number): CustomData | undefined;
+    /**
+     * Appends a row to the bottom of the current data region in the sheet. If a cell's content begins with =, it's interpreted as a formula.
+     * @param {CellValue[]} rowContents - An array of values for the new row.
+     * @returns {FWorksheet} Returns the current worksheet instance for method chaining.
+     * @example
+     * ```ts
+     * // Appends a new row with 4 columns to the bottom of the current
+     * // data region in the sheet containing the values in the array.
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorkSheet = fWorkbook.getActiveSheet();
+     * fWorkSheet.appendRow([1, 'Hello Univer', true, '=A1']);
+     * ```
+     */
+    appendRow(rowContents: CellValue[]): FWorksheet;
 }
-export {};

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

@@ -1,60 +1,69 @@
 import { CellValue, ICellData, IObjectMatrixPrimitiveType, IRange, IRangeWithCoord, Worksheet, HorizontalAlign, VerticalAlign } from '@univerjs/core';
+export type FDefaultAlignment = 'general';
 export type FHorizontalAlignment = 'left' | 'center' | 'normal';
 export type FVerticalAlignment = 'top' | 'middle' | 'bottom';
 /**
- *
- * @param value
+ * Transform the Facade API horizontal alignment to the Univer Core horizontal alignment.
+ * @param {FHorizontalAlignment} value - The Facade API horizontal alignment.
+ * @returns {HorizontalAlign} The Univer Core horizontal alignment.
  */
 export declare function transformFacadeHorizontalAlignment(value: FHorizontalAlignment): HorizontalAlign;
 /**
- *
- * @param value
+ * Transform the Univer Core horizontal alignment to the Facade API horizontal alignment.
+ * @param {HorizontalAlign} value - The Univer Core horizontal alignment.
+ * @returns {FHorizontalAlignment} The Facade API horizontal alignment.
  */
-export declare function transformCoreHorizontalAlignment(value: HorizontalAlign): FHorizontalAlignment;
+export declare function transformCoreHorizontalAlignment(value: HorizontalAlign): FHorizontalAlignment | FDefaultAlignment;
 /**
- *
- * @param value
+ * Transform the Facade API vertical alignment to the Univer Core vertical alignment.
+ * @param {FVerticalAlignment} value - The Facade API vertical alignment.
+ * @returns {VerticalAlign} The Univer Core vertical alignment.
  */
 export declare function transformFacadeVerticalAlignment(value: FVerticalAlignment): VerticalAlign;
 /**
- *
- * @param value
+ * Transform the Univer Core vertical alignment to the Facade API vertical alignment.
+ * @param {VerticalAlign} value - The Univer Core vertical alignment.
+ * @returns {FVerticalAlignment} The Facade API vertical alignment.
  */
-export declare function transformCoreVerticalAlignment(value: VerticalAlign): FVerticalAlignment;
+export declare function transformCoreVerticalAlignment(value: VerticalAlign): FVerticalAlignment | FDefaultAlignment;
 /**
  * Covert cell value to cell data.
- * @param value
- * @returns
+ * @param {CellValue | ICellData} value - The cell value.
+ * @returns {ICellData} The cell data.
  */
 export declare function covertCellValue(value: CellValue | ICellData): ICellData;
 /**
  * Covert cell value array or matrix to cell data.
- * @param value
- * @param range
- * @returns
+ * @param {CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>} value - The cell value array or matrix.
+ * @param {IRange} range - The range.
+ * @returns {IObjectMatrixPrimitiveType<ICellData>} The cell data matrix.
  */
 export declare function covertCellValues(value: CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>, range: IRange): IObjectMatrixPrimitiveType<ICellData>;
 /**
- *
- * @param mergeInfo
- * @param range
+ * Judge whether the range is merged.
+ * @param {IRangeWithCoord} mergeInfo - The merge info.
+ * @param {IRange} range - The range.
+ * @returns {boolean} Whether the range is merged.
  */
 export declare function isCellMerged(mergeInfo: IRangeWithCoord, range: IRange): boolean;
 /**
- *
- * @param mergeInfo
- * @param range
+ * Judge whether the range is single cell.
+ * @param {IRangeWithCoord} mergeInfo - The merge info.
+ * @param {IRange} range - The range.
+ * @returns {boolean} Whether the range is single cell.
  */
 export declare function isSingleCell(mergeInfo: IRangeWithCoord, range: IRange): boolean;
 /**
- *
- * @param range
- * @param worksheet
+ * Covert the range to row range.
+ * @param {IRange} range - The range.
+ * @param {Worksheet} worksheet - The worksheet.
+ * @returns {IRange} The row range.
  */
 export declare function covertToRowRange(range: IRange, worksheet: Worksheet): IRange;
 /**
- *
- * @param range
- * @param worksheet
+ * Covert the range to column range.
+ * @param {IRange} range - The range.
+ * @param {Worksheet} worksheet - The worksheet.
+ * @returns {IRange} The column range.
  */
 export declare function covertToColRange(range: IRange, worksheet: Worksheet): IRange;

package/lib/types/index.d.ts

@@ -70,7 +70,7 @@ export { RangeProtectionPermissionViewPoint } from './services/permission/permis
 export { RangeProtectionPermissionManageCollaPoint } from './services/permission/permission-point/range/manage-collaborator';
 export { RangeProtectionPermissionDeleteProtectionPoint } from './services/permission/permission-point/range/delete-protection';
 export { baseProtectionActions } from './services/permission/range-permission/util';
-export { generateNullCell, generateNullCellValue } from './basics/utils';
+export { generateNullCell, generateNullCellValue, getVisibleRanges, rangeToDiscreteRange } from './basics/utils';
 export { getSheetCommandTarget, getSheetCommandTargetWorkbook, getSheetMutationTarget } from './commands/commands/utils/target-util';
 export { alignToMergedCellsBorders, getCellAtRowCol, isSingleCellSelection, setEndForRange } from './commands/commands/utils/selection-utils';
 export { getSelectionsService } from './commands/utils/selection-command-util';
@@ -88,6 +88,7 @@ export { DeleteWorksheetProtectionCommand } from './commands/commands/delete-wor
 export { addMergeCellsUtil, AddWorksheetMergeAllCommand, AddWorksheetMergeCommand, AddWorksheetMergeHorizontalCommand, AddWorksheetMergeVerticalCommand, } from './commands/commands/add-worksheet-merge.command';
 export { SetWorksheetRangeThemeStyleCommand } from './commands/commands/add-worksheet-range-theme.command';
 export { DeleteWorksheetRangeThemeStyleCommand } from './commands/commands/delete-worksheet-range-theme.command';
+export { AppendRowCommand, type IAppendRowCommandParams } from './commands/commands/append-row.command';
 export { ClearSelectionAllCommand } from './commands/commands/clear-selection-all.command';
 export { ClearSelectionContentCommand } from './commands/commands/clear-selection-content.command';
 export { ClearSelectionFormatCommand } from './commands/commands/clear-selection-format.command';
@@ -105,7 +106,7 @@ export { type ISetRowDataMutationParams, SetRowDataMutation, SetRowDataMutationF
 export { type ISetRowDataCommandParams, SetRowDataCommand } from './commands/commands/set-row-data.command';
 export { type ISetColDataMutationParams, SetColDataMutation, SetColDataMutationFactory } from './commands/mutations/set-col-data.mutation';
 export { type ISetColDataCommandParams, SetColDataCommand } from './commands/commands/set-col-data.command';
-export { type IInsertColCommandParams, type IInsertRowCommandParams, InsertColAfterCommand, InsertColBeforeCommand, InsertColByRangeCommand, InsertColCommand, InsertRowAfterCommand, InsertRowBeforeCommand, InsertRowByRangeCommand, InsertRowCommand, } from './commands/commands/insert-row-col.command';
+export { type IInsertColCommandParams, type IInsertRowCommandParams, InsertColAfterCommand, InsertColBeforeCommand, InsertColByRangeCommand, InsertColCommand, InsertMultiColsLeftCommand, InsertMultiColsRightCommand, InsertMultiRowsAboveCommand, InsertMultiRowsAfterCommand, InsertRowAfterCommand, InsertRowBeforeCommand, InsertRowByRangeCommand, InsertRowCommand, } from './commands/commands/insert-row-col.command';
 export { type IInsertSheetCommandParams, InsertSheetCommand } from './commands/commands/insert-sheet.command';
 export { getMoveRangeUndoRedoMutations, type IMoveRangeCommandParams, MoveRangeCommand } from './commands/commands/move-range.command';
 export { type IMoveColsCommandParams, type IMoveRowsCommandParams, MoveColsCommand, MoveRowsCommand, } from './commands/commands/move-rows-cols.command';
@@ -183,7 +184,7 @@ export type { ISetWorksheetProtectionParams } from './commands/mutations/set-wor
 export { SetWorksheetRightToLeftMutation } from './commands/mutations/set-worksheet-right-to-left.mutation';
 export { type ISetWorksheetRowAutoHeightMutationParams, type ISetWorksheetRowHeightMutationParams, type ISetWorksheetRowIsAutoHeightMutationParams, SetWorksheetRowAutoHeightMutation, SetWorksheetRowAutoHeightMutationFactory, SetWorksheetRowHeightMutation, SetWorksheetRowIsAutoHeightMutation, } from './commands/mutations/set-worksheet-row-height.mutation';
 export { type IScrollToCellOperationParams, ScrollToCellOperation } from './commands/operations/scroll-to-cell.operation';
-export { type ISetSelectionsOperationParams, SetSelectionsOperation } from './commands/operations/selection.operation';
+export { type ISelectRangeCommandParams, type ISetSelectionsOperationParams, SelectRangeCommand, SetSelectionsOperation } from './commands/operations/selection.operation';
 export { type ISetWorksheetActiveOperationParams, SetWorksheetActiveOperation } from './commands/operations/set-worksheet-active.operation';
 export { type IToggleCellCheckboxCommandParams, ToggleCellCheckboxCommand } from './commands/commands/toggle-checkbox.command';
 export { SCOPE_WORKBOOK_VALUE_DEFINED_NAME } from './controllers/defined-name-data.controller';

package/lib/types/services/ref-range/util.d.ts

@@ -2,10 +2,10 @@ import { IAccessor, ICommandInfo, IMutationInfo, IRange, Nullable, RANGE_TYPE }
 import { IInsertColMutationParams, IInsertRowMutationParams, IRemoveColMutationParams, IRemoveRowsMutationParams, IRemoveSheetMutationParams } from '../../basics';
 import { IInsertColCommandParams, IInsertRowCommandParams } from '../../commands/commands/insert-row-col.command';
 import { IRemoveRowColCommandInterceptParams } from '../../commands/commands/remove-row-col.command';
-import { ISheetCommandSharedParams } from '../../commands/utils/interface';
-import { EffectRefRangeParams, IDeleteRangeMoveLeftCommand, IDeleteRangeMoveUpCommand, IInsertColCommand, IInsertRangeMoveDownCommand, IInsertRangeMoveRightCommand, IInsertRowCommand, IMoveColsCommand, IMoveRangeCommand, IMoveRowsCommand, IOperator, IRemoveRowColCommand, IReorderRangeCommand } from './type';
 import { IMoveRangeMutationParams } from '../../commands/mutations/move-range.mutation';
 import { IMoveColumnsMutationParams, IMoveRowsMutationParams } from '../../commands/mutations/move-rows-cols.mutation';
+import { ISheetCommandSharedParams } from '../../commands/utils/interface';
+import { EffectRefRangeParams, IDeleteRangeMoveLeftCommand, IDeleteRangeMoveUpCommand, IInsertColCommand, IInsertRangeMoveDownCommand, IInsertRangeMoveRightCommand, IInsertRowCommand, IMoveColsCommand, IMoveRangeCommand, IMoveRowsCommand, IOperator, IRemoveRowColCommand, IReorderRangeCommand } from './type';
 import { SheetsSelectionsService } from '../selections/selection.service';
 export declare const handleRangeTypeInput: (range: IRange) => {
     rangeType?: RANGE_TYPE;
@@ -55,6 +55,15 @@ export declare const handleBaseRemoveRange: (_removeRange: IRange, _targetRange:
 export declare const handleIRemoveCol: (param: IRemoveRowColCommand, targetRange: IRange) => IOperator[];
 export declare const handleIRemoveRow: (param: IRemoveRowColCommand, targetRange: IRange) => IOperator[];
 export declare const handleReorderRange: (param: IReorderRangeCommand, targetRange: IRange) => IOperator[];
+/**
+ * see docs/tldr/ref-range/insert-rows-cols.tldr
+ * calculate insert steps(move step) or expand size(length) to ref range.
+ *
+ * @param _insertRange inserted range
+ * @param _targetRange ref range
+ * @returns {step: number, length: number} step means inserted count of row/col before ref range, that would cause range move few cells(steps) afterward.
+ * length means expand size of row/col in ref range, that would make ref range larger than before.
+ */
 export declare const handleBaseInsertRange: (_insertRange: IRange, _targetRange: IRange) => {
     step: number;
     length: number;

package/lib/types/services/selections/selection.service.d.ts

@@ -3,6 +3,10 @@ import { Observable } from 'rxjs';
 import { ISelectionWithStyle } from '../../basics/selection';
 import { ISelectionManagerSearchParam, SelectionMoveType } from './type';
 import { WorkbookSelectionModel } from './selection-data-model';
+/**
+ * For normal selection.
+ * Ref selection is in RefSelectionService which extends this class.
+ */
 export declare class SheetsSelectionsService extends RxDisposable {
     protected readonly _instanceSrv: IUniverInstanceService;
     private get _currentSelectionPos();