@univerjs/sheets 0.6.1 → 0.6.2

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

@@ -1,5 +1,6 @@
-import { BorderStyleTypes, BorderType, CellValue, CustomData, ICellData, IDocumentData, IObjectMatrixPrimitiveType, IRange, IStyleData, Nullable, Workbook, Worksheet, ICommandService, Injector, RichTextValue, TextStyleValue, WrapStrategy } from '@univerjs/core';
+import { BorderStyleTypes, BorderType, CellValue, CustomData, ICellData, IDocumentData, IObjectMatrixPrimitiveType, IRange, IStyleData, Nullable, Workbook, Worksheet, Dimension, ICommandService, Injector, RichTextValue, TextStyleValue, WrapStrategy } from '@univerjs/core';
 import { SplitDelimiterEnum } from '@univerjs/sheets';
+import { IFacadeClearOptions } from './f-worksheet';
 import { FHorizontalAlignment, FVerticalAlignment } from './utils';
 import { FBaseInitialable } from '@univerjs/core/facade';
 import { FormulaDataModel } from '@univerjs/engine-formula';
@@ -71,29 +72,53 @@ export declare class FRange extends FBaseInitialable {
      */
     getRange(): IRange;
     /**
-     * Gets the starting row number of the applied area
-     * @returns {number} The starting row number of the area
+     * Gets the starting row index of the range. index starts at 0.
+     * @returns {number} The starting row index of the range.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
      * const fRange = fWorksheet.getRange('A1:B2');
-     * console.log(fRange.getRow());
+     * console.log(fRange.getRow()); // 0
      * ```
      */
     getRow(): number;
     /**
-     * Gets the starting column number of the applied area
-     * @returns {number} The starting column number of the area
+     * Gets the ending row index of the range. index starts at 0.
+     * @returns {number} The ending row index of the range.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
      * const fRange = fWorksheet.getRange('A1:B2');
-     * console.log(fRange.getColumn());
+     * console.log(fRange.getLastRow()); // 1
+     * ```
+     */
+    getLastRow(): number;
+    /**
+     * Gets the starting column index of the range. index starts at 0.
+     * @returns {number} The starting column index of the range.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * console.log(fRange.getColumn()); // 0
      * ```
      */
     getColumn(): number;
+    /**
+     * Gets the ending column index of the range. index starts at 0.
+     * @returns {number} The ending column index of the range.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * console.log(fRange.getLastColumn()); // 1
+     * ```
+     */
+    getLastColumn(): number;
     /**
      * Gets the width of the applied area
      * @returns {number} The width of the area
@@ -205,6 +230,46 @@ export declare class FRange extends FBaseInitialable {
      * ```
      */
     getValue(includeRichText: true): Nullable<CellValue | RichTextValue>;
+    /**
+     * Returns the raw value of the top-left cell in the range. Empty cells return `null`.
+     * @returns {Nullable<CellValue>} The raw value of the cell. Returns `null` if the cell is empty.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * fRange.setValueForCell({
+     *   v: 0.2,
+     *   s: {
+     *     n: {
+     *       pattern: '0%',
+     *     },
+     *   },
+     * });
+     * console.log(fRange.getRawValue()); // 0.2
+     * ```
+     */
+    getRawValue(): Nullable<CellValue>;
+    /**
+     * Returns the displayed value of the top-left cell in the range. The value is a String. Empty cells return an empty string.
+     * @returns {string} The displayed value of the cell. Returns an empty string if the cell is empty.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * fRange.setValueForCell({
+     *   v: 0.2,
+     *   s: {
+     *     n: {
+     *       pattern: '0%',
+     *     },
+     *   },
+     * });
+     * console.log(fRange.getDisplayValue()); // 20%
+     * ```
+     */
+    getDisplayValue(): string;
     /**
      * Returns the cell values for the cells in the range.
      * @returns {Nullable<CellValue>[][]} A two-dimensional array of cell values.
@@ -232,6 +297,92 @@ export declare class FRange extends FBaseInitialable {
      * ```
      */
     getValues(includeRichText: true): (Nullable<RichTextValue | CellValue>)[][];
+    /**
+     * Returns a two-dimensional array of the range raw values. Empty cells return `null`.
+     * @returns {Array<Array<Nullable<CellValue>>>} The raw value of the cell. Returns `null` if the cell is empty.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * fRange.setValues([
+     *   [
+     *     {
+     *       v: 0.2,
+     *       s: {
+     *         n: {
+     *           pattern: '0%',
+     *         },
+     *       },
+     *     },
+     *     {
+     *       v: 45658,
+     *       s: {
+     *         n: {
+     *           pattern: 'yyyy-mm-dd',
+     *         },
+     *       },
+     *     }
+     *   ],
+     *   [
+     *     {
+     *       v: 1234.567,
+     *       s: {
+     *         n: {
+     *           pattern: '#,##0.00',
+     *         }
+     *       }
+     *     },
+     *     null,
+     *   ],
+     * ]);
+     * console.log(fRange.getRawValues()); // [[0.2, 45658], [1234.567, null]]
+     * ```
+     */
+    getRawValues(): Array<Array<Nullable<CellValue>>>;
+    /**
+     * Returns a two-dimensional array of the range displayed values. Empty cells return an empty string.
+     * @returns {string[][]} A two-dimensional array of values.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * fRange.setValues([
+     *   [
+     *     {
+     *       v: 0.2,
+     *       s: {
+     *         n: {
+     *           pattern: '0%',
+     *         },
+     *       },
+     *     },
+     *     {
+     *       v: 45658,
+     *       s: {
+     *         n: {
+     *           pattern: 'yyyy-mm-dd',
+     *         },
+     *       },
+     *     }
+     *   ],
+     *   [
+     *     {
+     *       v: 1234.567,
+     *       s: {
+     *         n: {
+     *           pattern: '#,##0.00',
+     *         }
+     *       }
+     *     },
+     *     null,
+     *   ],
+     * ]);
+     * console.log(fRange.getDisplayValues()); // [['20%', '2025-01-01'], ['1,234.57', '']]
+     * ```
+     */
+    getDisplayValues(): string[][];
     /**
      * Return first cell model data in this range
      * @returns {ICellData | null} The cell model data
@@ -322,6 +473,18 @@ export declare class FRange extends FBaseInitialable {
      * ```
      */
     getValueAndRichTextValues(): Nullable<CellValue | RichTextValue>[][];
+    /**
+     * Returns the formula (A1 notation) of the top-left cell in the range, or an empty string if the cell is empty or doesn't contain a formula.
+     * @returns {string} The formula for the cell.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * console.log(fRange.getFormula());
+     * ```
+     */
+    getFormula(): string;
     /**
      * Returns the formulas (A1 notation) for the cells in the range. Entries in the 2D array are empty strings for cells with no formula.
      * @returns {string[][]} A two-dimensional array of formulas in string format.
@@ -335,8 +498,8 @@ export declare class FRange extends FBaseInitialable {
      */
     getFormulas(): string[][];
     /**
-     * Returns true if the cell wrap is enabled for the top left cell of the range.
-     * @returns {boolean} True if the cell wrap is enabled
+     * Gets whether text wrapping is enabled for top-left cell in the range.
+     * @returns {boolean} whether text wrapping is enabled for the cell.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -346,6 +509,17 @@ export declare class FRange extends FBaseInitialable {
      * ```
      */
     getWrap(): boolean;
+    /**
+     * Gets whether text wrapping is enabled for cells in the range.
+     * @returns {boolean[][]} A two-dimensional array of whether text wrapping is enabled for each cell in the range.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * console.log(fRange.getWraps());
+     */
+    getWraps(): boolean[][];
     /**
      * Returns the text wrapping strategy for the top left cell of the range.
      * @returns {WrapStrategy} The text wrapping strategy
@@ -359,8 +533,8 @@ export declare class FRange extends FBaseInitialable {
      */
     getWrapStrategy(): WrapStrategy;
     /**
-     * Returns the horizontal alignment for the top left cell of the range.
-     * @returns {string} The horizontal alignment
+     * Returns the horizontal alignment of the text (left/center/right) of the top-left cell in the range.
+     * @returns {string} The horizontal alignment of the text in the cell.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -371,8 +545,20 @@ export declare class FRange extends FBaseInitialable {
      */
     getHorizontalAlignment(): string;
     /**
-     * Returns the vertical alignment for the top left cell of the range.
-     * @returns {string} The vertical alignment
+     * Returns the horizontal alignments of the cells in the range.
+     * @returns {string[][]} A two-dimensional array of horizontal alignments of text associated with cells in the range.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * console.log(fRange.getHorizontalAlignments());
+     * ```
+     */
+    getHorizontalAlignments(): string[][];
+    /**
+     * Returns the vertical alignment (top/middle/bottom) of the top-left cell in the range.
+     * @returns {string} The vertical alignment of the text in the cell.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -382,6 +568,18 @@ export declare class FRange extends FBaseInitialable {
      * ```
      */
     getVerticalAlignment(): string;
+    /**
+     * Returns the vertical alignments of the cells in the range.
+     * @returns {string[][]} A two-dimensional array of vertical alignments of text associated with cells in the range.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * console.log(fRange.getVerticalAlignments());
+     * ```
+     */
+    getVerticalAlignments(): string[][];
     /**
      * Set custom meta data for first cell in current range.
      * @param {CustomData} data The custom meta data
@@ -450,6 +648,30 @@ export declare class FRange extends FBaseInitialable {
      * ```
      */
     setBorder(type: BorderType, style: BorderStyleTypes, color?: string): FRange;
+    /**
+     * Returns the background color of the top-left cell in the range.
+     * @returns {string} The color code of the background.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * console.log(fRange.getBackground());
+     * ```
+     */
+    getBackground(): string;
+    /**
+     * Returns the background colors of the cells in the range.
+     * @returns {string[][]} A two-dimensional array of color codes of the backgrounds.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * console.log(fRange.getBackgrounds());
+     * ```
+     */
+    getBackgrounds(): string[][];
     /**
      * Set background color for current range.
      * @param {string} color The background color
@@ -476,6 +698,19 @@ export declare class FRange extends FBaseInitialable {
      * ```
      */
     setBackground(color: string): FRange;
+    /**
+     * Set rotation for text in current range.
+     * @param {number} rotation - The rotation angle in degrees
+     * @returns This range, for chaining
+     * @example
+     * ```typescript
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * fRange.setTextRotation(45);
+     * ```
+     */
+    setTextRotation(rotation: number): FRange;
     /**
      * Sets the value of the range.
      * @param {CellValue | ICellData} value The value can be a number, string, boolean, or standard cell format. If it begins with `=`, it is interpreted as a formula. The value is tiled to all cells in the range.
@@ -842,11 +1077,26 @@ export declare class FRange extends FBaseInitialable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set the range A1:B2 as the active range, default active cell is A1
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.activate();
+     * console.log(fWorksheet.getActiveRange().getA1Notation()); // A1:B2
+     * console.log(fWorksheet.getActiveCell().getA1Notation()); // A1
+     *
+     * // Set the cell B2 as the active cell
+     * // Because B2 is in the active range A1:B2, the active range will not change, and the active cell will be changed to B2
      * const cell = fWorksheet.getRange('B2');
-     * cell.activateAsCurrentCell(); // the active cell will be B2
-     * console.log(fWorksheet.getActiveRange().getA1Notation()); // B2
+     * cell.activateAsCurrentCell();
+     * console.log(fWorksheet.getActiveRange().getA1Notation()); // A1:B2
+     * console.log(fWorksheet.getActiveCell().getA1Notation()); // B2
+     *
+     * // Set the cell C3 as the active cell
+     * // Because C3 is not in the active range A1:B2, a new active range C3:C3 will be created, and the active cell will be changed to C3
+     * const cell2 = fWorksheet.getRange('C3');
+     * cell2.activateAsCurrentCell();
+     * console.log(fWorksheet.getActiveRange().getA1Notation()); // C3:C3
+     * console.log(fWorksheet.getActiveCell().getA1Notation()); // C3
      * ```
      */
     activateAsCurrentCell(): FRange;
@@ -955,4 +1205,286 @@ export declare class FRange extends FBaseInitialable {
      * ```
      */
     getUsedThemeStyle(): string | undefined;
+    /**
+     * Clears content and formatting information of the range. Or Optionally clears only the contents or only the formatting.
+     * @param {IFacadeClearOptions} [options] - Options for clearing the range. If not provided, the contents and formatting are cleared both.
+     * @param {boolean} [options.contentsOnly] - If true, the contents of the range are cleared. If false, the contents and formatting are cleared. Default is false.
+     * @param {boolean} [options.formatOnly] - If true, the formatting of the range is cleared. If false, the contents and formatting are cleared. Default is false.
+     * @returns {FWorksheet} Returns the current worksheet instance for method chaining
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorkSheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorkSheet.getRange('A1:D10');
+     *
+     * // clear the content and format of the range A1:D10
+     * fRange.clear();
+     *
+     * // clear the content only of the range A1:D10
+     * fRange.clear({ contentsOnly: true });
+     * ```
+     */
+    clear(options?: IFacadeClearOptions): FRange;
+    /**
+     * Clears content of the range, while preserving formatting information.
+     * @returns {FWorksheet} Returns the current worksheet instance for method chaining
+     * @example
+     * ```typescript
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorkSheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorkSheet.getRange('A1:D10');
+     *
+     * // clear the content only of the range A1:D10
+     * fRange.clearContent();
+     * ```
+     */
+    clearContent(): FRange;
+    /**
+     * Clears formatting information of the range, while preserving contents.
+     * @returns {FWorksheet} Returns the current worksheet instance for method chaining
+     * @example
+     * ```typescript
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorkSheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorkSheet.getRange('A1:D10');
+     * // clear the format only of the range A1:D10
+     * fRange.clearFormat();
+     * ```
+     */
+    clearFormat(): FRange;
+    /**
+     * Inserts empty cells into this range. Existing data in the sheet along the provided dimension is shifted away from the inserted range.
+     * @param {Dimension} shiftDimension - The dimension along which to shift existing data.
+     * @example
+     * ```ts
+     * // Assume the active sheet empty sheet.
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const values = [
+     *   [1, 2, 3, 4],
+     *   [2, 3, 4, 5],
+     *   [3, 4, 5, 6],
+     *   [4, 5, 6, 7],
+     *   [5, 6, 7, 8],
+     * ];
+     *
+     * // Set the range A1:D5 with some values, the range A1:D5 will be:
+     * // 1 | 2 | 3 | 4
+     * // 2 | 3 | 4 | 5
+     * // 3 | 4 | 5 | 6
+     * // 4 | 5 | 6 | 7
+     * // 5 | 6 | 7 | 8
+     * const fRange = fWorksheet.getRange('A1:D5');
+     * fRange.setValues(values);
+     * console.log(fWorksheet.getRange('A1:D5').getValues()); // [[1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]
+     *
+     * // Insert the empty cells into the range A1:B2 along the columns dimension, the range A1:D5 will be:
+     * //   |   | 1 | 2
+     * //   |   | 2 | 3
+     * // 3 | 4 | 5 | 6
+     * // 4 | 5 | 6 | 7
+     * // 5 | 6 | 7 | 8
+     * const fRange2 = fWorksheet.getRange('A1:B2');
+     * fRange2.insertCells(univerAPI.Enum.Dimension.COLUMNS);
+     * console.log(fWorksheet.getRange('A1:D5').getValues()); // [[null, null, 1, 2], [null, null, 2, 3], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]
+     *
+     * // Set the range A1:D5 values again, the range A1:D5 will be:
+     * // 1 | 2 | 3 | 4
+     * // 2 | 3 | 4 | 5
+     * // 3 | 4 | 5 | 6
+     * // 4 | 5 | 6 | 7
+     * // 5 | 6 | 7 | 8
+     * fRange.setValues(values);
+     *
+     * // Insert the empty cells into the range A1:B2 along the rows dimension, the range A1:D5 will be:
+     * //   |   | 3 | 4
+     * //   |   | 4 | 5
+     * // 1 | 2 | 5 | 6
+     * // 2 | 3 | 6 | 7
+     * // 3 | 4 | 7 | 8
+     * const fRange3 = fWorksheet.getRange('A1:B2');
+     * fRange3.insertCells(univerAPI.Enum.Dimension.ROWS);
+     * console.log(fWorksheet.getRange('A1:D5').getValues()); // [[null, null, 3, 4], [null, null, 4, 5], [1, 2, 5, 6], [2, 3, 6, 7], [3, 4, 7, 8]]
+     * ```
+     */
+    insertCells(shiftDimension: Dimension): void;
+    /**
+     * Deletes this range of cells. Existing data in the sheet along the provided dimension is shifted towards the deleted range.
+     * @param {Dimension} shiftDimension - The dimension along which to shift existing data.
+     * @example
+     * ```ts
+     * // Assume the active sheet empty sheet.
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const values = [
+     *   [1, 2, 3, 4],
+     *   [2, 3, 4, 5],
+     *   [3, 4, 5, 6],
+     *   [4, 5, 6, 7],
+     *   [5, 6, 7, 8],
+     * ];
+     *
+     * // Set the range A1:D5 with some values, the range A1:D5 will be:
+     * // 1 | 2 | 3 | 4
+     * // 2 | 3 | 4 | 5
+     * // 3 | 4 | 5 | 6
+     * // 4 | 5 | 6 | 7
+     * // 5 | 6 | 7 | 8
+     * const fRange = fWorksheet.getRange('A1:D5');
+     * fRange.setValues(values);
+     * console.log(fWorksheet.getRange('A1:D5').getValues()); // [[1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]
+     *
+     * // Delete the range A1:B2 along the columns dimension, the range A1:D5 will be:
+     * // 3 | 4 |   |
+     * // 4 | 5 |   |
+     * // 3 | 4 | 5 | 6
+     * // 4 | 5 | 6 | 7
+     * // 5 | 6 | 7 | 8
+     * const fRange2 = fWorksheet.getRange('A1:B2');
+     * fRange2.deleteCells(univerAPI.Enum.Dimension.COLUMNS);
+     * console.log(fWorksheet.getRange('A1:D5').getValues()); // [[3, 4, null, null], [4, 5, null, null], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]
+     *
+     * // Set the range A1:D5 values again, the range A1:D5 will be:
+     * // 1 | 2 | 3 | 4
+     * // 2 | 3 | 4 | 5
+     * // 3 | 4 | 5 | 6
+     * // 4 | 5 | 6 | 7
+     * // 5 | 6 | 7 | 8
+     * fRange.setValues(values);
+     *
+     * // Delete the range A1:B2 along the rows dimension, the range A1:D5 will be:
+     * // 3 | 4 | 3 | 4
+     * // 4 | 5 | 4 | 5
+     * // 5 | 6 | 5 | 6
+     * //   |   | 6 | 7
+     * //   |   | 7 | 8
+     * const fRange3 = fWorksheet.getRange('A1:B2');
+     * fRange3.deleteCells(univerAPI.Enum.Dimension.ROWS);
+     * console.log(fWorksheet.getRange('A1:D5').getValues()); // [[3, 4, 3, 4], [4, 5, 4, 5], [5, 6, 5, 6], [null, null, 6, 7], [null, null, 7, 8]]
+     * ```
+     */
+    deleteCells(shiftDimension: Dimension): void;
+    /**
+     * Returns a copy of the range expanded `Direction.UP` and `Direction.DOWN` if the specified dimension is `Dimension.ROWS`, or `Direction.NEXT` and `Direction.PREVIOUS` if the dimension is `Dimension.COLUMNS`.
+     * The expansion of the range is based on detecting data next to the range that is organized like a table.
+     * The expanded range covers all adjacent cells with data in them along the specified dimension including the table boundaries.
+     * If the original range is surrounded by empty cells along the specified dimension, the range itself is returned.
+     * @param {Dimension} [dimension] - The dimension along which to expand the range. If not provided, the range will be expanded in both dimensions.
+     * @returns {FRange} The range's data region or a range covering each column or each row spanned by the original range.
+     * @example
+     * ```ts
+     * // Assume the active sheet is a new sheet with no data.
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set the range A1:D4 with some values, the range A1:D4 will be:
+     * //  |     |     |
+     * //  |     | 100 |
+     * //  | 100 |     | 100
+     * //  |     | 100 |
+     * fWorksheet.getRange('C2').setValue(100);
+     * fWorksheet.getRange('B3').setValue(100);
+     * fWorksheet.getRange('D3').setValue(100);
+     * fWorksheet.getRange('C4').setValue(100);
+     *
+     * // Get C3 data region along the rows dimension, the range will be C2:D4
+     * const range = fWorksheet.getRange('C3').getDataRegion(univerAPI.Enum.Dimension.ROWS);
+     * console.log(range.getA1Notation()); // C2:C4
+     *
+     * // Get C3 data region along the columns dimension, the range will be B3:D3
+     * const range2 = fWorksheet.getRange('C3').getDataRegion(univerAPI.Enum.Dimension.COLUMNS);
+     * console.log(range2.getA1Notation()); // B3:D3
+     *
+     * // Get C3 data region along the both dimension, the range will be B2:D4
+     * const range3 = fWorksheet.getRange('C3').getDataRegion();
+     * console.log(range3.getA1Notation()); // B2:D4
+     * ```
+     */
+    getDataRegion(dimension?: Dimension): FRange;
+    /**
+     * Returns true if the range is totally blank.
+     * @returns {boolean} true if the range is blank; false otherwise.
+     * @example
+     * ```ts
+     * // Assume the active sheet is a new sheet with no data.
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * console.log(fRange.isBlank()); // true
+     *
+     * // Set the range A1:B2 with some values
+     * fRange.setValueForCell(123);
+     * console.log(fRange.isBlank()); // false
+     * ```
+     */
+    isBlank(): boolean;
+    /**
+     * Returns a new range that is offset from this range by the given number of rows and columns (which can be negative).
+     * The new range is the same size as the original range.
+     * @param {number} rowOffset - The number of rows down from the range's top-left cell; negative values represent rows up from the range's top-left cell.
+     * @param {number} columnOffset - The number of columns right from the range's top-left cell; negative values represent columns left from the range's top-left cell.
+     * @returns {FRange} The new range.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * console.log(fRange.getA1Notation()); // A1:B2
+     *
+     * // Offset the range by 1 row and 1 column
+     * const newRange = fRange.offset(1, 1);
+     * console.log(newRange.getA1Notation()); // B2:C3
+     * ```
+     */
+    offset(rowOffset: number, columnOffset: number): FRange;
+    /**
+     * Returns a new range that is relative to the current range, whose upper left point is offset from the current range by the given rows and columns, and with the given height in cells.
+     * @param {number} rowOffset - The number of rows down from the range's top-left cell; negative values represent rows up from the range's top-left cell.
+     * @param {number} columnOffset - The number of columns right from the range's top-left cell; negative values represent columns left from the range's top-left cell.
+     * @param {number} numRows - The height in rows of the new range.
+     * @returns {FRange} The new range.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * console.log(fRange.getA1Notation()); // A1:B2
+     *
+     * // Offset the range by 1 row and 1 column, and set the height of the new range to 3
+     * const newRange = fRange.offset(1, 1, 3);
+     * console.log(newRange.getA1Notation()); // B2:C4
+     * ```
+     */
+    offset(rowOffset: number, columnOffset: number, numRows: number): FRange;
+    /**
+     * Updates the formula for this range. The given formula must be in A1 notation.
+     * @param {string} formula - A string representing the formula to set for the cell.
+     * @returns {FRange} This range instance for chaining.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1');
+     * fRange.setFormula('=SUM(A2:A5)');
+     * console.log(fRange.getFormula()); // '=SUM(A2:A5)'
+     * ```
+     */
+    setFormula(formula: string): FRange;
+    /**
+     * Sets a rectangular grid of formulas (must match dimensions of this range). The given formulas must be in A1 notation.
+     * @param {string[][]} formulas - A two-dimensional string array of formulas.
+     * @returns {FRange} This range instance for chaining.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * fRange.setFormulas([
+     *   ['=SUM(A2:A5)', '=SUM(B2:B5)'],
+     *   ['=SUM(A6:A9)', '=SUM(B6:B9)'],
+     * ]);
+     * console.log(fRange.getFormulas()); // [['=SUM(A2:A5)', '=SUM(B2:B5)'], ['=SUM(A6:A9)', '=SUM(B6:B9)']]
+     * ```
+     */
+    setFormulas(formulas: string[][]): FRange;
 }

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

@@ -316,6 +316,16 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```
      */
     getActiveRange(): FRange | null;
+    /**
+     * Returns the active cell in this spreadsheet.
+     * @returns {FRange | null} The active cell
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * console.log(fWorkbook.getActiveCell().getA1Notation());
+     * ```
+     */
+    getActiveCell(): FRange | null;
     /**
      * Deletes the currently active sheet.
      * @returns {boolean} true if the sheet was deleted, false otherwise