@univerjs/sheets
Version:
UniverSheet normal base-sheets
1,214 lines • 68.8 kB
TypeScript
import { AbsoluteRefType, BorderStyleTypes, BorderType, CellValue, CustomData, ICellData, IDocumentData, IObjectMatrixPrimitiveType, IRange, IStyleData, Nullable, Workbook, Worksheet, Dimension, ICommandService, Injector, RichTextValue, TextStyleValue, WrapStrategy } from '@univerjs/core';
import { AUTO_FILL_APPLY_TYPE, IMergeCellsUtilOptions, 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';
import { FRangePermission } from './permission/f-range-permission';
export type FontLine = 'none' | 'underline' | 'line-through';
export type FontStyle = 'normal' | 'italic';
export type FontWeight = 'normal' | 'bold';
/**
* The type of the style to get.
*
* - `row`: get composed style of row, col and default worksheet style. Row style has the highest priority, then col style.
* - `col`: get composed style of col, row and default worksheet style. Col style has the highest priority, then row style.
* - `cell`: get style of cell without merging row style, col style and default worksheet style.
*/
export type GetStyleType = 'row' | 'col' | 'cell';
/**
* Represents a range of cells in a sheet. You can call methods on this Facade API object
* to read contents or manipulate the range.
*
* @hideconstructor
*/
export declare class FRange extends FBaseInitialable {
protected readonly _workbook: Workbook;
protected readonly _worksheet: Worksheet;
protected readonly _range: IRange;
protected readonly _injector: Injector;
protected readonly _commandService: ICommandService;
protected readonly _formulaDataModel: FormulaDataModel;
constructor(_workbook: Workbook, _worksheet: Worksheet, _range: IRange, _injector: Injector, _commandService: ICommandService, _formulaDataModel: FormulaDataModel);
/**
* Get the unit ID of the current workbook
* @returns {string} The unit ID of the workbook
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getUnitId());
* ```
*/
getUnitId(): string;
/**
* Gets the name of the worksheet
* @returns {string} The name of the worksheet
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getSheetName());
* ```
*/
getSheetName(): string;
/**
* Gets the ID of the worksheet
* @returns {string} The ID of the worksheet
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getSheetId());
* ```
*/
getSheetId(): string;
/**
* Gets the area where the statement is applied
* @returns {IRange} The area where the statement is applied
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* const range = fRange.getRange();
* const { startRow, startColumn, endRow, endColumn } = range;
* console.log(range);
* ```
*/
getRange(): IRange;
/**
* 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()); // 0
* ```
*/
getRow(): number;
/**
* 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.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
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getWidth());
* ```
*/
getWidth(): number;
/**
* Gets the height of the applied area
* @returns {number} The height of the area
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getHeight());
* ```
*/
getHeight(): number;
/**
* Return range whether this range is merged
* @returns {boolean} if true is merged
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.isMerged());
* // merge cells A1:B2
* fRange.merge();
* console.log(fRange.isMerged());
* ```
*/
isMerged(): boolean;
/**
* Return first cell style data in this range. Please note that if there are row styles, col styles and (or)
* worksheet style, they will be merged into the cell style. You can use `type` to specify the type of the style to get.
*
* @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
* default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
* 'cell' means get the style of cell without merging row style, col style and default worksheet style.
* Default is 'row'.
*
* @returns {IStyleData | null} The cell style data
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getCellStyleData());
* ```
*/
getCellStyleData(type?: GetStyleType): IStyleData | null;
/**
* Get the font family of the cell.
*
* @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
* default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
* 'cell' means get the style of cell without merging row style, col style and default worksheet style.
* Default is 'row'.
*
* @returns {string | null} The font family of the cell
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getFontFamily());
* ```
*/
getFontFamily(type?: GetStyleType): string | null;
/**
* Get the font size of the cell.
*
* @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
* default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
* 'cell' means get the style of cell without merging row style, col style and default worksheet style.
* Default is 'row'.
*
* @returns {number | null} The font size of the cell
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getFontSize());
* ```
*/
getFontSize(type?: GetStyleType): number | null;
/**
* Return first cell style in this range.
*
* @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
* default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
* 'cell' means get the style of cell without merging row style, col style and default worksheet style.
* Default is 'row'.
*
* @returns {TextStyleValue | null} The cell style
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getCellStyle());
* ```
*/
getCellStyle(type?: GetStyleType): TextStyleValue | null;
/**
* Returns the cell styles for the cells in the range.
*
* @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
* default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
* 'cell' means get the style of cell without merging row style, col style and default worksheet style.
* Default is 'row'.
*
* @returns {Array<Array<TextStyleValue | null>>} A two-dimensional array of cell styles.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getCellStyles());
* ```
*/
getCellStyles(type?: GetStyleType): Array<Array<TextStyleValue | null>>;
/**
* Return first cell value in this range
* @returns {CellValue | null} The cell value
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getValue());
*
* // set the first cell value to 123
* fRange.setValueForCell(123);
* console.log(fRange.getValue()); // 123
* ```
*/
getValue(): CellValue | null;
/**
* Return first cell value in this range
* @param {boolean} includeRichText Should the returns of this func to include rich text
* @returns {CellValue | RichTextValue | null} The cell value
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getValue(true));
*
* // set the first cell value to 123
* const richText = univerAPI.newRichText({ body: { dataStream: 'Hello World\r\n' } })
* .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } })
* .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } });
* fRange.setRichTextValueForCell(richText);
* console.log(fRange.getValue(true).toPlainText()); // Hello World
* ```
*/
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.
* @example
* ```ts
* // Get plain values
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getValues());
* ```
*/
getValues(): Nullable<CellValue>[][];
/**
* Returns the cell values for the cells in the range.
* @param {boolean} includeRichText Should the returns of this func to include rich text
* @returns {Nullable<RichTextValue | CellValue>[][]} A two-dimensional array of cell values.
* @example
* ```ts
* // Get values with rich text if available
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getValues(true));
* ```
*/
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
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getCellData());
* ```
*/
getCellData(): ICellData | null;
/**
* Alias for getCellDataGrid.
* @returns {Nullable<ICellData>[][]} A two-dimensional array of cell data.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getCellDatas());
* ```
*/
getCellDatas(): Nullable<ICellData>[][];
/**
* Returns the cell data for the cells in the range.
* @returns {Nullable<ICellData>[][]} A two-dimensional array of cell data.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getCellDataGrid());
* ```
*/
getCellDataGrid(): Nullable<ICellData>[][];
/**
* Returns the value and rich text value for the cells in the range.
* @returns {Nullable<CellValue | RichTextValue>[][]} A two-dimensional array of value and rich text value
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getValueAndRichTextValues());
* ```
*/
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.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getFormulas());
* ```
*/
getFormulas(): string[][];
/**
* 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();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getWrap());
* ```
*/
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
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getWrapStrategy());
* ```
*/
getWrapStrategy(): WrapStrategy;
/**
* 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();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getHorizontalAlignment());
* ```
*/
getHorizontalAlignment(): string;
/**
* 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();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getVerticalAlignment());
* ```
*/
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
* @returns {FRange} This range, for chaining
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setCustomMetaData({ key: 'value' });
* console.log(fRange.getCustomMetaData());
* ```
*/
setCustomMetaData(data: CustomData): FRange;
/**
* Set custom meta data for current range.
* @param {CustomData[][]} datas The custom meta data
* @returns {FRange} This range, for chaining
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setCustomMetaDatas([
* [{ key: 'value' }, { key: 'value2' }],
* [{ key: 'value3' }, { key: 'value4' }],
* ]);
* console.log(fRange.getCustomMetaDatas());
* ```
*/
setCustomMetaDatas(datas: CustomData[][]): FRange;
/**
* Returns the custom meta data for the cell at the start of this range.
* @returns {CustomData | null} The custom meta data
* @example
* ```
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getCustomMetaData());
* ```
*/
getCustomMetaData(): CustomData | null;
/**
* Returns the custom meta data for the cells in the range.
* @returns {CustomData[][]} A two-dimensional array of custom meta data
* @example
* ```
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getCustomMetaDatas());
* ```
*/
getCustomMetaDatas(): Nullable<CustomData>[][];
/**
* Sets basic border properties for the current range.
* @param {BorderType} type The type of border to apply
* @param {BorderStyleTypes} style The border style
* @param {string} [color] Optional border color in CSS notation
* @returns {FRange} This range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setBorder(univerAPI.Enum.BorderType.ALL, univerAPI.Enum.BorderStyleTypes.THIN, '#ff0000');
* ```
*/
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
* @returns {FRange} This range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setBackgroundColor('red');
* ```
*/
setBackgroundColor(color: string): FRange;
/**
* Set background color for current range.
* @param {string} color The background color
* @returns {FRange} This range, for chaining
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setBackground('red');
* ```
*/
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.
* @returns {FRange} This range, for chaining
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('B2');
* fRange.setValue(123);
*
* // or
* fRange.setValue({ v: 234, s: { bg: { rgb: '#ff0000' } } });
* ```
*/
setValue(value: CellValue | ICellData): FRange;
/**
* Set new value for current cell, first cell in this 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.
* @returns {FRange} This range, for chaining
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setValueForCell(123);
*
* // or
* fRange.setValueForCell({ v: 234, s: { bg: { rgb: '#ff0000' } } });
* ```
*/
setValueForCell(value: CellValue | ICellData): FRange;
/**
* Set the rich text value for the cell at the start of this range.
* @param {RichTextValue | IDocumentData} value The rich text value
* @returns {FRange} The range
* @example
* ```
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getValue(true));
*
* // Set A1 cell value to rich text
* const richText = univerAPI.newRichText()
* .insertText('Hello World')
* .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } })
* .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } });
* fRange.setRichTextValueForCell(richText);
* console.log(fRange.getValue(true).toPlainText()); // Hello World
* ```
*/
setRichTextValueForCell(value: RichTextValue | IDocumentData): FRange;
/**
* Set the rich text value for the cells in the range.
* @param {RichTextValue[][]} values The rich text value
* @returns {FRange} The range
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getValue(true));
*
* // Set A1:B2 cell value to rich text
* const richText = univerAPI.newRichText()
* .insertText('Hello World')
* .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } })
* .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } });
* fRange.setRichTextValues([
* [richText, richText],
* [null, null]
* ]);
* console.log(fRange.getValue(true).toPlainText()); // Hello World
* ```
*/
setRichTextValues(values: (RichTextValue | IDocumentData)[][]): FRange;
/**
* Set the cell wrap of the given range.
* Cells with wrap enabled (the default) resize to display their full content. Cells with wrap disabled display as much as possible in the cell without resizing or running to multiple lines.
* @param {boolean} isWrapEnabled Whether to enable wrap
* @returns {FRange} this range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setWrap(true);
* console.log(fRange.getWrap());
* ```
*/
setWrap(isWrapEnabled: boolean): FRange;
/**
* Sets the text wrapping strategy for the cells in the range.
* @param {WrapStrategy} strategy The text wrapping strategy
* @returns {FRange} this range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setWrapStrategy(univerAPI.Enum.WrapStrategy.WRAP);
* console.log(fRange.getWrapStrategy());
* ```
*/
setWrapStrategy(strategy: WrapStrategy): FRange;
/**
* Set the vertical (top to bottom) alignment for the given range (top/middle/bottom).
* @param {"top" | "middle" | "bottom"} alignment The vertical alignment
* @returns {FRange} this range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setVerticalAlignment('top');
* ```
*/
setVerticalAlignment(alignment: FVerticalAlignment): FRange;
/**
* Set the horizontal (left to right) alignment for the given range (left/center/right).
* @param {"left" | "center" | "normal"} alignment The horizontal alignment
* @returns {FRange} this range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setHorizontalAlignment('left');
* ```
*/
setHorizontalAlignment(alignment: FHorizontalAlignment): FRange;
/**
* Sets a different value for each cell in the range. The value can be a two-dimensional array or a standard range matrix (must match the dimensions of this range), consisting of numbers, strings, Boolean values or Composed of standard cell formats. If a value begins with `=`, it is interpreted as a formula.
* @param {CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>} value The value can be a two-dimensional array or a standard range matrix (must match the dimensions of this range), consisting of numbers, strings, Boolean values or Composed of standard cell formats.
* @returns {FRange} This range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setValues([
* [1, { v: 2, s: { bg: { rgb: '#ff0000' } } }],
* [3, 4]
* ]);
* ```
*/
setValues(value: CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>): FRange;
/**
* Sets the font weight for the given range (normal/bold),
* @param {FontWeight|null} fontWeight The font weight, either 'normal' or 'bold'; a null value resets the font weight.
* @returns {FRange} This range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setFontWeight('bold');
* ```
*/
setFontWeight(fontWeight: FontWeight | null): this;
/**
* Sets the font style for the given range ('italic' or 'normal').
* @param {FontStyle|null} fontStyle The font style, either 'italic' or 'normal'; a null value resets the font style.
* @returns {FRange} This range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setFontStyle('italic');
* ```
*/
setFontStyle(fontStyle: FontStyle | null): this;
/**
* Sets the font line style of the given range ('underline', 'line-through', or 'none').
* @param {FontLine|null} fontLine The font line style, either 'underline', 'line-through', or 'none'; a null value resets the font line style.
* @returns {FRange} This range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setFontLine('underline');
* ```
*/
setFontLine(fontLine: FontLine | null): this;
/**
* Sets the font underline style of the given ITextDecoration
* @param {ITextDecoration|null} value The font underline style of the given ITextDecoration; a null value resets the font underline style
* @returns {void}
*/
private _setFontUnderline;
/**
* Sets the font strikethrough style of the given ITextDecoration
* @param {ITextDecoration|null} value The font strikethrough style of the given ITextDecoration; a null value resets the font strikethrough style
* @returns {void}
*/
private _setFontStrikethrough;
/**
* Sets the font family, such as "Arial" or "Helvetica".
* @param {string|null} fontFamily The font family to set; a null value resets the font family.
* @returns {FRange} This range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setFontFamily('Arial');
* ```
*/
setFontFamily(fontFamily: string | null): this;
/**
* Sets the font size, with the size being the point size to use.
* @param {number|null} size A font size in point size. A null value resets the font size.
* @returns {FRange} This range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setFontSize(24);
* ```
*/
setFontSize(size: number | null): this;
/**
* Sets the font color in CSS notation (such as '#ffffff' or 'white').
* @param {string|null} color The font color in CSS notation (such as '#ffffff' or 'white'); a null value resets the color.
* @returns {FRange} This range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setFontColor('#ff0000');
* ```
*/
setFontColor(color: string | null): this;
/**
* Merge cells in a range into one merged cell
* @param {IMergeCellsUtilOptions} [options] - The options for merging cells.
* @param {boolean} [options.defaultMerge] - If true, only the value in the upper left cell is retained. If false, a confirm dialog will be shown to the user. Default is true.
* @param {boolean} [options.isForceMerge] - If true, the overlapping merged cells will be removed before performing the new merge. Default is false.
* @returns {FRange} This range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.merge();
* console.log(fRange.isMerged());
* ```
*
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('B1:C2');
* // Assume A1:B2 is already merged.
* fRange.merge({ isForceMerge: true });
* ```
*/
merge(options?: IMergeCellsUtilOptions): FRange;
/**
* Merges cells in a range horizontally.
* @param {IMergeCellsUtilOptions} [options] - The options for merging cells.
* @param {boolean} [options.defaultMerge] - If true, only the value in the upper left cell is retained. If false, a confirm dialog will be shown to the user. Default is true.
* @param {boolean} [options.isForceMerge] - If true, the overlapping merged cells will be removed before performing the new merge. Default is false.
* @returns {FRange} This range, for chaining
* @example
* ```ts
* // Assume the active sheet is a new sheet with no merged cells.
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.mergeAcross();
* // There will be two merged cells. A1:B1 and A2:B2.
* const mergeData = fWorksheet.getMergeData();
* mergeData.forEach((item) => {
* console.log(item.getA1Notation());
* });
* ```
*
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('B1:C2');
* // Assume A1:B2 is already merged.
* fRange.mergeAcross({ isForceMerge: true });
* ```
*/
mergeAcross(options?: IMergeCellsUtilOptions): FRange;
/**
* Merges cells in a range vertically.
* @param {IMergeCellsUtilOptions} [options] - The options for merging cells.
* @param {boolean} [options.defaultMerge] - If true, only the value in the upper left cell is retained. If false, a confirm dialog will be shown to the user. Default is true.
* @param {boolean} [options.isForceMerge] - If true, the overlapping merged cells will be removed before performing the new merge. Default is false.
* @returns {FRange} This range, for chaining
* @example
* ```ts
* // Assume the active sheet is a new sheet with no merged cells.
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.mergeVertically();
* // There will be two merged cells. A1:A2 and B1:B2.
* const mergeData = fWorksheet.getMergeData();
* mergeData.forEach((item) => {
* console.log(item.getA1Notation());
* });
* ```
*
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('B1:C2');
* // Assume A1:B2 is already merged.
* fRange.mergeVertically({ isForceMerge: true });
* ```
*/
mergeVertically(options?: IMergeCellsUtilOptions): FRange;
/**
* Returns true if cells in the current range overlap a merged cell.
* @returns {boolean} is overlap with a merged cell
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.merge();
* const anchor = fWorksheet.getRange('A1');
* console.log(anchor.isPartOfMerge()); // true
* ```
*/
isPartOfMerge(): boolean;
/**
* Break all horizontally- or vertically-merged cells contained within the range list into individual cells again.
* @returns {FRange} This range, for chaining
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.merge();
* const anchor = fWorksheet.getRange('A1');
* console.log(anchor.isPartOfMerge()); // true
* fRange.breakApart();
* console.log(anchor.isPartOfMerge()); // false
* ```
*/
breakApart(): FRange;
/**
* Iterate cells in this range. Merged cells will be respected.
* @param {Function} callback the callback function to be called for each cell in the range
* @param {number} callback.row the row number of the cell
* @param {number} callback.col the column number of the cell
* @param {ICellData} callback.cell the cell data
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.forEach((row, col, cell) => {
* console.log(row, col, cell);
* });
* ```
*/
forEach(callback: (row: number, col: number, cell: ICellData) => void): void;
/**
* Returns a string description of the range, in A1 notation.
* @param {boolean} [withSheet] - If true, the sheet name is included in the A1 notation.
* @param {AbsoluteRefType} [startAbsoluteRefType] - The absolute reference type for the start cell.
* @param {AbsoluteRefType} [endAbsoluteRefType] - The absolute reference type for the end cell.
* @returns {string} The A1 notation of the range.
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
*
* // By default, the A1 notation is returned without the sheet name and without absolute reference types.
* const fRange = fWorksheet.getRange('A1:B2');
* console.log(fRange.getA1Notation()); // A1:B2
*
* // By setting withSheet to true, the sheet name is included in the A1 notation.
* fWorksheet.setName('Sheet1');
* console.log(fRange.getA1Notation(true)); // Sheet1!A1:B2
*
* // By setting startAbsoluteRefType, the absolute reference type for the start cell is included in the A1 notation.
* console.log(fRange.getA1Notation(false, univerAPI.Enum.AbsoluteRefType.ROW)); // A$1:B2
* console.log(fRange.getA1Notation(false, univerAPI.Enum.AbsoluteRefType.COLUMN)); // $A1:B2
* console.log(fRange.getA1Notation(false, univerAPI.Enum.AbsoluteRefType.ALL)); // $A$1:B2
*
* // By setting endAbsoluteRefType, the absolute reference type for the end cell is included in the A1 notation.
* console.log(fRange.getA1Notation(false, null, univerAPI.Enum.AbsoluteRefType.ROW)); // A1:B$2
* console.log(fRange.getA1Notation(false, null, univerAPI.Enum.AbsoluteRefType.COLUMN)); // A1:$B2
* console.log(fRange.getA1Notation(false, null, univerAPI.Enum.AbsoluteRefType.ALL)); // A1:$B$2
*
* // By setting all parameters example
* console.log(fRange.getA1Notation(true, univerAPI.Enum.AbsoluteRefType.ALL, univerAPI.Enum.AbsoluteRefType.ALL)); // Sheet1!$A$1:$B$2
* ```
*/
getA1Notation(withSheet?: boolean, startAbsoluteRefType?: AbsoluteRefType, endAbsoluteRefType?: AbsoluteRefType): string;
/**
* Sets the specified range as the active range, with the top left cell in the range as the current cell.
* @returns {FRange} This range, for chaining.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.activate(); // the active cell will be A1
* ```
*/
activate(): FRange;
/**
* Sets the specified cell as the current cell.
* If the specified cell is present in an existing range, then that range becomes the active range with the cell as the current cell.
* If the specified cell is not part of an existing range, then a new range is created with the cell as the active range and the current cell.
* @returns {FRange} This range, for chaining.
* @description If the range is not a single cell, an error will be thrown.
* @example
* ```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();
* 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;
/**
* Splits a column of text into multiple columns based on an auto-detected delimiter.
* @param {boolean} [treatMultipleDelimitersAsOne] Whether to treat multiple continuous delimiters as one. The default value is false.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
*
* // A1:A3 has following values:
* // A |
* // 1,2,3 |
* // 4,,5,6 |
* const fRange = fWorksheet.getRange('A1:A3');
* fRange.setValues([
* ['A'],
* ['1,2,3'],
* ['4,,5,6']
* ]);
*
* // After calling splitTextToColumns(true), the range will be:
* // A | |
* // 1 | 2 | 3
* // 4 | 5 | 6
* fRange.splitTextToColumns(true);
*
* // After calling splitTextToColumns(false), the range will be:
* // A | | |
* // 1 | 2 | 3 |
* // 4 | | 5 | 6
* fRange.splitTextToColumns(false);
* ```
*/
splitTextToColumns(treatMultipleDelimitersAsOne?: boolean): void;
/**
* Splits a column of text into multiple columns based on a specified delimiter.
* @param {boolean} [treatMultipleDelimitersAsOne] Whether to treat multiple continuous delimiters as one. The default value is false.
* @param {SplitDelimiterEnum} [delimiter] The delimiter to use to split the text. The default delimiter is Tab(1)、Comma(2)、Semi