@univerjs/sheets
Version:
UniverSheet normal base-sheets
1,154 lines • 64.2 kB
TypeScript
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';
import { FWorksheetPermission } from './permission/f-worksheet-permission';
export interface IFacadeClearOptions {
contentsOnly?: boolean;
formatOnly?: boolean;
}
/**
* A Facade API object bounded to a worksheet. It provides a set of methods to interact with the worksheet.
* @hideconstructor
*/
export declare class FWorksheet extends FBaseInitialable {
protected readonly _fWorkbook: FWorkbook;
protected readonly _workbook: Workbook;
protected readonly _worksheet: Worksheet;
protected readonly _injector: Injector;
protected readonly _selectionManagerService: SheetsSelectionsService;
protected readonly _logService: ILogService;
protected readonly _commandService: ICommandService;
/**
* Creates a new worksheet facade instance
* @param {FWorkbook} _fWorkbook - The facade workbook instance
* @param {Workbook} _workbook - The workbook instance
* @param {Worksheet} _worksheet - The worksheet instance
* @param {Injector} _injector - The injector instance
* @param {SheetsSelectionsService} _selectionManagerService - The selection manager service
* @param {ILogService} _logService - The log service
* @param {ICommandService} _commandService - The command service
*/
constructor(_fWorkbook: FWorkbook, _workbook: Workbook, _worksheet: Worksheet, _injector: Injector, _selectionManagerService: SheetsSelectionsService, _logService: ILogService, _commandService: ICommandService);
dispose(): void;
/**
* Get the worksheet instance.
* @returns {Worksheet} The worksheet instance.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const sheet = fWorksheet.getSheet();
* console.log(sheet);
* ```
*/
getSheet(): Worksheet;
/**
* Get the injector instance.
* @returns {Injector} The injector instance.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const injector = fWorksheet.getInject();
* console.log(injector);
* ```
*/
getInject(): Injector;
/**
* Get the workbook instance.
* @returns {Workbook} The workbook instance.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const workbook = fWorksheet.getWorkbook();
* console.log(workbook);
* ```
*/
getWorkbook(): Workbook;
/**
* Get the worksheet id.
* @returns {string} The id of the worksheet.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const sheetId = fWorksheet.getSheetId();
* console.log(sheetId);
* ```
*/
getSheetId(): string;
/**
* Get the worksheet name.
* @returns {string} The name of the worksheet.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const sheetName = fWorksheet.getSheetName();
* console.log(sheetName);
* ```
*/
getSheetName(): string;
/**
* Get the current selection of the worksheet.
* @returns {FSelection} return the current selections of the worksheet or null if there is no selection.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const selection = fWorksheet.getSelection();
* console.log(selection);
* ```
*/
getSelection(): FSelection | null;
/**
* Get the default style of the worksheet.
* @returns {IStyleData} Default style of the worksheet.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const defaultStyle = fWorksheet.getDefaultStyle();
* console.log(defaultStyle);
* ```
*/
getDefaultStyle(): Nullable<IStyleData> | string;
/**
* Get the default style of the worksheet row
* @param {number} index - The row index
* @param {boolean} [keepRaw] - If true, return the raw style data maybe the style name or style data, otherwise return the data from row manager
* @returns {(Nullable<IStyleData> | string)} The default style of the worksheet row name or style data
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get default style for row 0 (1)
* const rowStyle = fWorksheet.getRowDefaultStyle(0);
* console.log(rowStyle);
* // Get raw style data for row 0
* const rawRowStyle = fWorksheet.getRowDefaultStyle(0, true);
* console.log(rawRowStyle);
* ```
*/
getRowDefaultStyle(index: number, keepRaw?: boolean): Nullable<IStyleData> | string;
/**
* 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
* @returns {(Nullable<IStyleData> | string)} The default style of the worksheet column name or style data
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get default style for column 0 (A)
* const colStyle = fWorksheet.getColumnDefaultStyle(0);
* console.log(colStyle);
* // Get raw style data for column 0
* const rawColStyle = fWorksheet.getColumnDefaultStyle(0, true);
* console.log(rawColStyle);
* ```
*/
getColumnDefaultStyle(index: number, keepRaw?: boolean): Nullable<IStyleData> | string;
/**
* Set the default style of the worksheet
* @param {string} style - The style to set
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* fWorksheet.setDefaultStyle('default');
* // or
* // fWorksheet.setDefaultStyle({fs: 12, ff: 'Arial'});
* ```
*/
setDefaultStyle(style: string | Nullable<IStyleData>): FWorksheet;
/**
* Set the default style of the worksheet row
* @param {number} index - The row index
* @param {string | Nullable<IStyleData>} style - The style name or style data
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* fWorksheet.setColumnDefaultStyle(0, 'default');
* // or
* // fWorksheet.setColumnDefaultStyle(0, {fs: 12, ff: 'Arial'});
* ```
*/
setColumnDefaultStyle(index: number, style: string | Nullable<IStyleData>): FWorksheet;
/**
* Set the default style of the worksheet column
* @param {number} index - The column index
* @param {string | Nullable<IStyleData>} style - The style name or style data
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* fWorksheet.setRowDefaultStyle(0, 'default');
* // or
* // fWorksheet.setRowDefaultStyle(0, {fs: 12, ff: 'Arial'});
* ```
*/
setRowDefaultStyle(index: number, style: string | Nullable<IStyleData>): FWorksheet;
/**
* Returns a Range object representing a single cell at the specified row and column.
* @param {number} row - The row index of the cell.
* @param {number} column - The column index of the cell.
* @returns {FRange} A Range object representing the specified cell.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get range for cell at row 0, column 0 (A1)
* const range = fWorksheet.getRange(0, 0);
* console.log(range);
* ```
*/
getRange(row: number, column: number): FRange;
/**
* Returns a Range object representing a range starting at the specified row and column, with the specified number of rows.
* @param {number} row - The starting row index of the range.
* @param {number} column - The starting column index of the range.
* @param {number} numRows - The number of rows in the range.
* @returns {FRange} A Range object representing the specified range.
*/
getRange(row: number, column: number, numRows: number): FRange;
/**
* Returns a Range object representing a range starting at the specified row and column, with the specified number of rows and columns.
* @param {number} row - The starting row index of the range.
* @param {number} column - The starting column index of the range.
* @param {number} numRows - The number of rows in the range.
* @param {number} numColumns - The number of columns in the range.
* @returns {FRange} A Range object representing the specified range.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get range for cells A1:C3
* const range = fWorksheet.getRange(0, 0, 3, 3);
* console.log(range);
* ```
*/
getRange(row: number, column: number, numRows: number, numColumns: number): FRange;
/**
* Returns a Range object specified by A1 notation.
* @param {string} a1Notation - A string representing a range in A1 notation.
* @returns {FRange} A Range object representing the specified range.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get range for cells A1:C3
* const range = fWorksheet.getRange("A1:C3");
* console.log(range);
* // Get range for a single cell
* const cell = fWorksheet.getRange("B2");
* console.log(cell);
* // Get range with sheet name
* const sheetName = fWorksheet.getSheetName();
* const rangeWithSheet = fWorksheet.getRange(`${sheetName}!A1:C3`);
* console.log(rangeWithSheet);
* ```
*/
getRange(a1Notation: string): FRange;
/**
* Returns a Range object for the specified range.
* @param {IRange} range - The range specification.
* @returns {FRange} A Range object representing the specified range.
*/
getRange(range: IRange): FRange;
/**
* Returns the current number of columns in the sheet, regardless of content.
* @returns {number} The maximum columns count of the sheet
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const totalColumns = fWorksheet.getMaxColumns();
* console.log(`Sheet has ${totalColumns} columns`);
* ```
*/
getMaxColumns(): number;
/**
* Returns the current number of rows in the sheet, regardless of content.
* @returns {number}The maximum rows count of the sheet
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const totalRows = fWorksheet.getMaxRows();
* console.log(`Sheet has ${totalRows} rows`);
* ```
*/
getMaxRows(): number;
/**
* Inserts a row after the given row position.
* @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.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Insert a row after the third row
* fWorksheet.insertRowAfter(2);
* // Insert a row after the first row
* fWorksheet.insertRowAfter(0);
* ```
*/
insertRowAfter(afterPosition: number): FWorksheet;
/**
* Inserts a row before the given row position.
* @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.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Insert a row before the third row
* fWorksheet.insertRowBefore(2);
* // Insert a row before the first row
* fWorksheet.insertRowBefore(0);
* ```
*/
insertRowBefore(beforePosition: number): FWorksheet;
/**
* Inserts one or more consecutive blank rows in a sheet starting at the specified location.
* @param {number} rowIndex - The index indicating where to insert a row, starting at 0 for the first row.
* @param {number} numRows - The number of rows to insert.
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Insert 3 rows before the third row
* fWorksheet.insertRows(2, 3);
* // Insert 1 row before the first row
* fWorksheet.insertRows(0);
* ```
*/
insertRows(rowIndex: number, numRows?: number): FWorksheet;
/**
* Inserts a number of rows after the given row position.
* @param {number} afterPosition - The row after which the new rows should be added, starting at 0 for the first row.
* @param {number} howMany - The number of rows to insert.
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Insert 3 rows after the third row
* fWorksheet.insertRowsAfter(2, 3);
* // Insert 1 row after the first row
* fWorksheet.insertRowsAfter(0, 1);
* ```
*/
insertRowsAfter(afterPosition: number, howMany: number): FWorksheet;
/**
* Inserts a number of rows before the given row position.
* @param {number} beforePosition - The row before which the new rows should be added, starting at 0 for the first row.
* @param {number} howMany - The number of rows to insert.
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Insert 3 rows before the third row
* fWorksheet.insertRowsBefore(2, 3);
* // Insert 1 row before the first row
* fWorksheet.insertRowsBefore(0, 1);
* ```
*/
insertRowsBefore(beforePosition: number, howMany: number): FWorksheet;
/**
* Deletes the row at the given row position.
* @param {number} rowPosition - The position of the row, starting at 0 for the first row.
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Delete the third row
* fWorksheet.deleteRow(2);
* // Delete the first row
* fWorksheet.deleteRow(0);
* ```
*/
deleteRow(rowPosition: number): FWorksheet;
/**
* Deletes a number of rows starting at the given row position.
* @param {number} rowPosition - The position of the first row to delete, starting at 0 for the first row.
* @param {number} howMany - The number of rows to delete.
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Delete 3 rows at row index 2 (rows 3-5)
* fWorksheet.deleteRows(2, 3);
* // Delete 1 row at row index 0 (first row)
* fWorksheet.deleteRows(0, 1);
* ```
*/
deleteRows(rowPosition: number, howMany: number): FWorksheet;
/**
* Deletes the rows specified by the given row points. Each point can be a single row index or a tuple representing a range of rows.
* @param {Array<number | [number, number]>} rowPoints - An array of row points to delete. Each point can be a single row index or a tuple representing a range of rows.
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Delete rows at index 2, and range from index 4 to 6 (rows 3, 5-7)
* fWorksheet.deleteRowsByPoints([2, [4, 6]]);
* ```
*/
deleteRowsByPoints(rowPoints: Array<number | [number, number]>): FWorksheet;
/**
* Moves the rows selected by the given range to the position indicated by the destinationIndex. The rowSpec itself does not have to exactly represent an entire row or group of rows to move—it selects all rows that the range spans.
* @param {FRange} rowSpec - A range spanning the rows that should be moved.
* @param {number} destinationIndex - The index that the rows should be moved to. Note that this index is based on the coordinates before the rows are moved. Existing data is shifted down to make room for the moved rows while the source rows are removed from the grid. Therefore, the data may end up at a different index than originally specified. Use 0-index for this method.
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Move 3 rows at row index 2 (rows 3-5) to row index 0
* const rowSpec1 = fWorksheet.getRange('3:5');
* fWorksheet.moveRows(rowSpec1, 0);
* // Move 1 row at row index 0 (first row) to row index 2
* const rowSpec2 = fWorksheet.getRange('1:1');
* fWorksheet.moveRows(rowSpec2, 2);
* ```
*/
moveRows(rowSpec: FRange, destinationIndex: number): FWorksheet;
/**
* Hides the rows in the given range.
* @param {FRange} row - The row range to hide.
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Hide 3 rows starting from row index 1 (rows 2-4)
* const row1 = fWorksheet.getRange('2:4');
* fWorksheet.hideRow(row1);
* // Hide single row at index 0 (first row)
* const row2 = fWorksheet.getRange('1:1');
* fWorksheet.hideRow(row2);
* ```
*/
hideRow(row: FRange): FWorksheet;
/**
* Hides one or more consecutive rows starting at the given index. Use 0-index for this method
* @param {number} rowIndex - The starting index of the rows to hide
* @param {number} numRow - The number of rows to hide
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Hide 3 rows starting from row index 1 (rows 2-4)
* fWorksheet.hideRows(1, 3);
* // Hide single row at index 0 (first row)
* fWorksheet.hideRows(0);
* ```
*/
hideRows(rowIndex: number, numRow?: number): FWorksheet;
/**
* Make the row in the given range visible.
* @param {FRange} row - The range to unhide, if hidden.
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Unhide 3 rows starting from row index 1 (rows 2-4)
* const row1 = fWorksheet.getRange('2:4');
* fWorksheet.unhideRow(row1);
* // Unhide single row at index 0 (first row)
* const row2 = fWorksheet.getRange('1:1');
* fWorksheet.unhideRow(row2);
* ```
*/
unhideRow(row: FRange): FWorksheet;
/**
* 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 worksheet instance for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Show 3 rows starting from row index 1 (rows 2-4)
* fWorksheet.showRows(1, 3);
* // Show single row at index 0 (first row)
* fWorksheet.showRows(0);
* ```
*/
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.
* @param {number} height - The height in pixels to set it to.
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Set the height of the second row to 30 pixels
* fWorksheet.setRowHeight(1, 30);
* // Set the height of the first row to 20 pixels
* fWorksheet.setRowHeight(0, 20);
* ```
*/
setRowHeight(rowPosition: number, height: number): FWorksheet;
/**
* Make certain row wrap and auto height.
* @param {number} rowPosition - The row position to change.
* @param {BooleanNumber} auto - Whether to auto fit the row height.
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```ts
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* fWorkSheet.autoFitRow(24);
* ```
*/
autoFitRow(rowPosition: number, auto?: BooleanNumber): 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 {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 worksheet instance for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* fWorksheet.setRowHeights(1, 10, 30);
* ```
*/
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
* @param {number} numRows - The number of rows to change
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* fWorksheet.setRowAutoHeight(1, 10);
* ```
*/
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
* @param {number} numRows - The number of rows to change
* @param {number} height - The height in pixels to set it to
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* fWorksheet.setRowHeightsForced(1, 10, 30);
* ```
*/
setRowHeightsForced(startRow: number, numRows: number, height: number): FWorksheet;
/**
* Set custom properties for given rows.
* @param {IObjectArrayPrimitiveType<CustomData>} custom - The custom properties to set
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* fWorkSheet.setRowCustom({ 0: { key: 'value' } });
* ```
*/
setRowCustom(custom: IObjectArrayPrimitiveType<CustomData>): FWorksheet;
/**
* Inserts a column after the given column position.
* @param {number} afterPosition - The column after which the new column should be added, starting at 0 for the first column
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Insert a column after column C
* fWorksheet.insertColumnAfter(2);
* // Insert a column after column A
* fWorksheet.insertColumnAfter(0);
* ```
*/
insertColumnAfter(afterPosition: number): FWorksheet;
/**
* Inserts a column before the given column position.
* @param {number} beforePosition - The column before which the new column should be added, starting at 0 for the first column
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Insert a column before column C
* fWorksheet.insertColumnBefore(2);
* // Insert a column before column A
* fWorksheet.insertColumnBefore(0);
* ```
*/
insertColumnBefore(beforePosition: number): FWorksheet;
/**
* Inserts one or more consecutive blank columns in a sheet starting at the specified location.
* @param {number} columnIndex - The index indicating where to insert a column, starting at 0 for the first column
* @param {number} numColumns - The number of columns to insert
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Insert 3 columns before column C
* fWorksheet.insertColumns(2, 3);
* // Insert 1 column before column A
* fWorksheet.insertColumns(0);
* ```
*/
insertColumns(columnIndex: number, numColumns?: number): FWorksheet;
/**
* Inserts a given number of columns after the given column position.
* @param {number} afterPosition - The column after which the new columns should be added, starting at 0 for the first column
* @param {number} howMany - The number of columns to insert
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Insert 3 columns after column C
* fWorksheet.insertColumnsAfter(2, 3);
* // Insert 1 column after column A
* fWorksheet.insertColumnsAfter(0, 1);
* ```
*/
insertColumnsAfter(afterPosition: number, howMany: number): FWorksheet;
/**
* Inserts a number of columns before the given column position.
* @param {number} beforePosition - The column before which the new columns should be added, starting at 0 for the first column
* @param {number} howMany - The number of columns to insert
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Insert 3 columns before column C
* fWorksheet.insertColumnsBefore(2, 3);
* // Insert 1 column before column A
* fWorksheet.insertColumnsBefore(0, 1);
* ```
*/
insertColumnsBefore(beforePosition: number, howMany: number): FWorksheet;
/**
* Deletes the column at the given column position.
* @param {number} columnPosition - The position of the column, starting at 0 for the first column
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Delete column C
* fWorksheet.deleteColumn(2);
* // Delete column A
* fWorksheet.deleteColumn(0);
* ```
*/
deleteColumn(columnPosition: number): FWorksheet;
/**
* Deletes a number of columns starting at the given column position.
* @param {number} columnPosition - The position of the first column to delete, starting at 0 for the first column
* @param {number} howMany - The number of columns to delete
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Delete 3 columns at column index 2 (columns C, D, E)
* fWorksheet.deleteColumns(2, 3);
* // Delete 1 column at column index 0 (column A)
* fWorksheet.deleteColumns(0, 1);
* ```
*/
deleteColumns(columnPosition: number, howMany: number): FWorksheet;
/**
* Deletes the columns specified by the given column points. Each point can be a single column index or a tuple representing a range of columns.
* @param {Array<number | [number, number]>} columnPoints - An array of column points to delete. Each point can be a single column index or a tuple representing a range of columns.
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Delete columns at index 2, and range from index 4 to 6 (columns C, E-G)
* fWorksheet.deleteColumnsByPoints([2, [4, 6]]);
* ```
*/
deleteColumnsByPoints(columnPoints: Array<number | [number, number]>): FWorksheet;
/**
* Moves the columns selected by the given range to the position indicated by the destinationIndex. The columnSpec itself does not have to exactly represent an entire column or group of columns to move—it selects all columns that the range spans.
* @param {FRange} columnSpec - A range spanning the columns that should be moved
* @param {number} destinationIndex - The index that the columns should be moved to. Note that this index is based on the coordinates before the columns are moved. Existing data is shifted right to make room for the moved columns while the source columns are removed from the grid. Therefore, the data may end up at a different index than originally specified. Use 0-index for this method
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Move columns C, D, E to column index 2 (columns B, C, D)
* const columnSpec1 = fWorksheet.getRange('C:E');
* fWorksheet.moveColumns(columnSpec1, 1);
* // Move column F to column index 0 (column A)
* const columnSpec2 = fWorksheet.getRange('F:F');
* fWorksheet.moveColumns(columnSpec2, 0);
* ```
*/
moveColumns(columnSpec: FRange, destinationIndex: number): FWorksheet;
/**
* Hides the column or columns in the given range.
* @param {FRange} column - The column range to hide
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Hide columns C, D, E
* const column1 = fWorksheet.getRange('C:E');
* fWorksheet.hideColumn(column1);
* // Hide column A
* const column2 = fWorksheet.getRange('A:A');
* fWorksheet.hideColumn(column2);
* ```
*/
hideColumn(column: FRange): FWorksheet;
/**
* Hides 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 hide
* @param {number} numColumn - The number of columns to hide
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Hide columns C, D, E
* fWorksheet.hideColumns(2, 3);
* // Hide column A
* fWorksheet.hideColumns(0, 1);
* ```
*/
hideColumns(columnIndex: number, numColumn?: number): FWorksheet;
/**
* Show the column in the given range.
* @param {FRange} column - The range to unhide, if hidden
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Unhide columns C, D, E
* const column1 = fWorksheet.getRange('C:E');
* fWorksheet.unhideColumn(column1);
* // Unhide column A
* const column2 = fWorksheet.getRange('A:A');
* fWorksheet.unhideColumn(column2);
* ```
*/
unhideColumn(column: FRange): FWorksheet;
/**
* 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} numColumns - The number of columns to unhide
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Unhide columns C, D, E
* fWorksheet.showColumns(2, 3);
* // Unhide column A
* fWorksheet.showColumns(0, 1);
* ```
*/
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
* @param {number} width - The width in pixels to set it to
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Set width of column B to 100 pixels
* fWorksheet.setColumnWidth(1, 100);
* ```
*/
setColumnWidth(columnPosition: number, width: number): FWorksheet;
/**
* Sets the width of the given columns in pixels.
* @param {number} startColumn - The starting column position to change
* @param {number} numColumn - The number of columns to change
* @param {number} width - The width in pixels to set it to
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Set width of columns B-D (index 1-3) to 100 pixels
* fWorksheet.setColumnWidths(1, 3, 100);
* ```
*/
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
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```ts
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* fWorkSheet.setColumnCustom({ 0: { key: 'value' } });
* ```
*/
setColumnCustom(custom: IObjectArrayPrimitiveType<CustomData>): FWorksheet;
/**
* Get all merged cells in the current worksheet
* @returns {FRange[]} All the merged cells in the worksheet
* @example
* ```ts
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get all merged ranges in the sheet
* const mergedData = fWorksheet.getMergeData();
* // Process each merged range
* mergedData.forEach(range => {
* console.log(range.getA1Notation());
* });
* ```
*/
getMergeData(): FRange[];
/**
* Get all merged cells in the current sheet
* @returns {FRange[]} all merged cells
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get all merged ranges in the sheet
* const mergedRanges = fWorksheet.getMergedRanges();
* // Process each merged range
* mergedRanges.forEach(range => {
* console.log(range.getA1Notation());
* });
* ```
*/
getMergedRanges(): FRange[];
/**
* Get the merged cell data of the specified row and column.
* @param {number} row - The row index
* @param {number} column - The column index
* @returns {FRange|undefined} The merged cell data, or undefined if the cell is not merged
* @example
* ```ts
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const merge = fWorkSheet.getCellMergeData(0, 0);
* if (merge) {
* console.log('Merged range:', merge.getA1Notation());
* }
* ```
*/
getCellMergeData(row: number, column: number): FRange | undefined;
/**
* Returns the selected range in the active sheet, or null if there is no active range.
* @returns {FRange | null} the active range
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the currently active range
* const activeRange = fWorksheet.getActiveRange();
* if (activeRange) {
* console.log('Active range:', activeRange.getA1Notation());
* }
* ```
*/
getActiveRange(): FRange | null;
/**
* Sets the active selection region for this sheet.
* @param {FRange} range - The range to set as the active selection
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```ts
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* fWorkSheet.setActiveRange(fWorkSheet.getRange('A10:B10'));
* ```
*/
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
* @returns This sheet, for chaining
* @example
* ```ts
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* fWorkSheet.setActiveSelection(fWorkSheet.getRange('A10:B10'));
* ```
*/
setActiveSelection: (range: FRange) => FWorksheet;
/**
* Sets the frozen state of the current sheet.
* @param {IFreeze} 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 {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Freeze first 3 rows and 2 columns
* fWorksheet.setFreeze({
* startRow: 3,
* startColumn: 2,
* xSplit: 2,
* ySplit: 3
* });
* ```
*/
setFreeze(freeze: IFreeze): FWorksheet;
/**
* Cancels the frozen state of the current sheet.
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Cancel freeze
* fWorksheet.cancelFreeze();
* ```
*/
cancelFreeze(): FWorksheet;
/**
* Get the freeze state of the current sheet.
* @returns {IFreeze} The freeze state of the current sheet
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the freeze state of the current sheet
* const freeze = fWorksheet.getFreeze();
* console.log(freeze);
* ```
*/
getFreeze(): IFreeze;
/**
* Set the number of frozen columns.
* @param columns - The number of columns to freeze.
* To unfreeze all columns, set this value to 0.
* @returns {FWorksheet} This FWorksheet instance.
* @example
* ```typescript
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // freeze the first 3 columns.
* fWorkSheet.setFrozenColumns(3);
* ```
*/
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.
* @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.
* @example
* ```typescript
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // freeze the column B and C, and column A will be invisible.
* fWorkSheet.setFrozenColumns(1, 2);
* ```
*/
setFrozenColumns(startColumn: number, endColumn: number): FWorksheet;
/**
* Set the number of frozen rows.
* @param rows - The number of rows to freeze.
* To unfreeze all rows, set this value to 0.
* @returns {FWorksheet} This FWorksheet instance.
* @example
* ```typescript
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // freeze the first 3 rows.
* fWorkSheet.setFrozenRows(3);
* ```
*/
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 - The start row of the range to freeze
* @param endRow - The end row of the range to freeze
* @returns {FWorksheet} This FWorksheet instance.
* @example
* ```typescript
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // freeze the second and third rows, and the first row will be invisible.
* fWorkSheet.setFrozenRows(1, 2);
* ```
*/
setFrozenRows(startRow: number, endRow: number): FWorksheet;
/**
* Get the number of frozen columns.
* @returns {number} The number of frozen columns, returns 0 if no columns are frozen.
* @example
* ```typescript
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the number of frozen columns
* const frozenColumns = fWorkSheet.getFrozenColumns();
* console.log(frozenColumns);
* ```
*/
getFrozenColumns(): number;
/**
* Get the number of frozen rows.
* @returns {number} The number of frozen rows. returns 0 if no rows are frozen.
* @example
* ```typescript
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the number of frozen rows
* const frozenRows = fWorkSheet.getFrozenRows();
* console.log(frozenRows);
* ```
*/
getFrozenRows(): number;
/**
* Get freezed rows.
* @returns {IRowRange} The range of the frozen rows.
* @example
* ```ts
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the range of the frozen rows
* const frozenRows = fWorkSheet.getFrozenRowRange();
* console.log(frozenRows);
* ```
*/
getFrozenRowRange(): IRowRange;
/**
* Get freezed columns
* @returns {IColumnRange} The range of the frozen columns.
* @example
* ```ts
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the range of the frozen columns
* const frozenColumns = fWorkSheet.getFrozenColumnRange();
* console.log(frozenColumns);
* ```
*/
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.
* @example
* ```ts
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // check if the gridlines are hidden
* if (fWorkSheet.hasHiddenGridLines()) {
* console.log('Gridlines are hidden');
* }
* ```
*/
hasHiddenGridLines(): boolean;
/**
* 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 fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // hide the gridlines
* fWorkSheet.setHiddenGridlines(true);
* ```
*/
setHiddenGridlines(hidden: boolean): FWorksheet;
/**
* Set the color of the gridlines in the sheet.
* @param {string|undefined} color - The color to set for the gridlines.Undefined or null to reset to the default color.
* @returns {FWorksheet} Returns the current worksheet instance for method chaining
* @example
* ```ts
* const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // set the gridlines color to red
* fWorkSheet.setGridLinesColor('#ff0000');
* ```
*/
setGridLinesColor(color: string | undefined): FWorksheet;
/**
* Get the color of the gridlines in the sheet.
* @returns {string | undefined} The color of the gridlines in the sheet or undefined. The default color is 'rgb(214, 216, 219)'.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorkSheet = fWorkbook.getActiveSheet();
* // get the gridlines color of the sheet
* console.log(fWorkSheet.getGridLinesColor());
* ```
*/
getGridLinesColor(): string | undefined;
/**
* Sets the sheet tab color.
* @param {string|null|undefined} color - A color code in CSS notation (like '#ffffff' or 'white'), or null to reset the tab color.
* @returns {FWorksheet} Returns the current worksheet instance for method chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorkSheet = fWorkbook.getActiveSheet();
* // set the tab color to red
* fWorkSheet.setTabColor('#ff0000');
* ```
*/
setTabColor(color: string): FWorksheet;
/**
* Get the tab color of the sheet.
* @returns {string} The tab color of the sheet or undefined.
* The default color is css style property 'unset'.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorkSheet = fWorkbook.getActiveSheet();
* // get the tab color of the sheet
* console.log(fWorkSheet.getTabColor());
* ```
*/
getTabColor(): string | undefined;
/**
* @deprecated use `univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (params) => {})` instead
*/
onCellDataChange(callback: (cellValue: ObjectMatrix<Nullable<ICellData>>) => void): IDisposable;
/**
* @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeSheetEditEnd, (params) => {})` instead
*/
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 curre