FRange
Represents a range of cells in a sheet. You can call methods on this Facade API object to read contents or manipulate the range.
Get this object from the initialized univerAPI instance. The example assumes a workbook is already open.
const workbook = univerAPI.getActiveWorkbook()const sheet = workbook?.getActiveSheet()if (!sheet) throw new Error('No active worksheet')const range = sheet.getRange('A1:B2')range.setValues([ [1, 2], [3, 4],])console.log(range.getValues())Access
Access through:
FThreadComment.getRange()FTextFinder.findAll()FTextFinder.findNext()FTextFinder.findPrevious()FTextFinder.getCurrentMatch()FFilter.getRange()FDataValidation.getRanges()FWorkbook.getActiveRange()
Setup
Register @univerjs/sheets or a preset that includes it. In plugin mode, import @univerjs/sheets/facade. Additional methods below require their listed plugin packages. See Facade setup.
@univerjs/sheets
FRange.activate
Sets the specified range as the active range, with the top left cell in the range as the current cell.
activate(): FRangeReturns
This range, for chaining.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.activate() // the active cell will be A1Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.activateAsCurrentCell
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.
activateAsCurrentCell(): FRangeReturns
This range, for chaining.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Set the range A1:B2 as the active range, default active cell is A1const fRange = fWorksheet.getRange('A1:B2')fRange.activate()console.log(fWorksheet.getActiveRange().getA1Notation()) // A1:B2console.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 B2const cell = fWorksheet.getRange('B2')cell.activateAsCurrentCell()console.log(fWorksheet.getActiveRange().getA1Notation()) // A1:B2console.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 C3const cell2 = fWorksheet.getRange('C3')cell2.activateAsCurrentCell()console.log(fWorksheet.getActiveRange().getA1Notation()) // C3:C3console.log(fWorksheet.getActiveCell().getA1Notation()) // C3Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.autoFill
Fills the target range with data based on the data in the current range.
autoFill(targetRange: FRange, applyType?: AUTO_FILL_APPLY_TYPE): Promise<boolean>Parameters
targetRange— Required. The range to be filled with data.applyType— Optional. The type of data fill to be applied.
Returns
A promise that resolves to true if the fill operation was successful, false otherwise.
Examples
// Auto-fill the range D1:D10 based on the data in the range C1:C2const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:A4')// Auto-fill without specifying applyType (default behavior)await fRange.autoFill(fWorksheet.getRange('A1:A20'))// Auto-fill with 'COPY' typeawait fRange.autoFill(fWorksheet.getRange('A1:A20'), 'COPY')// Auto-fill with 'SERIES' typeawait fRange.autoFill(fWorksheet.getRange('A1:A20'), 'SERIES')// Operate on a specific worksheetconst fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetBySheetId('sheetId')const fRange = fWorksheet.getRange('A1:A4')// Auto-fill without specifying applyType (default behavior)await fRange.autoFill(fWorksheet.getRange('A1:A20'))// Auto-fill with 'COPY' typeawait fRange.autoFill(fWorksheet.getRange('A1:A20'), 'COPY')// Auto-fill with 'SERIES' typeawait fRange.autoFill(fWorksheet.getRange('A1:A20'), 'SERIES')Types: Promise · FRange · AUTO_FILL_APPLY_TYPE
Package: @univerjs/sheets · Type definitions
FRange.breakApart
Break all horizontally- or vertically-merged cells contained within the range list into individual cells again.
breakApart(): FRangeReturns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.merge()const anchor = fWorksheet.getRange('A1')console.log(anchor.isPartOfMerge()) // truefRange.breakApart()console.log(anchor.isPartOfMerge()) // falseTypes: FRange
Package: @univerjs/sheets · Type definitions
FRange.clear
Clears the range content and formatting, or only one of them as specified by the options. Both content and formatting are cleared when both flags are true or both are false.
clear(options?: IFacadeClearOptions): FRangeParameters
options— Optional. Options for clearing the range. If not provided, the contents and formatting are cleared both.
Returns
This range, for chaining.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorkSheet = fWorkbook.getSheetByName('Sheet1')if (!fWorkSheet) throw new Error('fWorkSheet is not available')const fRange = fWorkSheet.getRange('A1:D10')// clear the content and format of the range A1:D10fRange.clear()// clear the content only of the range A1:D10fRange.clear({ contentsOnly: true })Types: FRange · IFacadeClearOptions
Package: @univerjs/sheets · Type definitions
FRange.clearContent
Clears content of the range, while preserving formatting information.
clearContent(): FRangeReturns
This range, for chaining.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorkSheet = fWorkbook.getSheetByName('Sheet1')if (!fWorkSheet) throw new Error('fWorkSheet is not available')const fRange = fWorkSheet.getRange('A1:D10')// clear the content only of the range A1:D10fRange.clearContent()Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.clearFormat
Clears formatting information of the range, while preserving contents.
clearFormat(): FRangeReturns
This range, for chaining.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorkSheet = fWorkbook.getSheetByName('Sheet1')if (!fWorkSheet) throw new Error('fWorkSheet is not available')const fRange = fWorkSheet.getRange('A1:D10')// clear the format only of the range A1:D10fRange.clearFormat()Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.deleteCells
Deletes this range of cells. Existing data in the sheet along the provided dimension is shifted towards the deleted range.
deleteCells(shiftDimension: Dimension): voidParameters
shiftDimension— Required. The dimension along which to shift existing data.
Examples
// Assume the active sheet empty sheet.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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 | 8const 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 | 8const 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 | 8fRange.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 | 8const 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]]Types: Dimension
Package: @univerjs/sheets · Type definitions
FRange.forEach
Iterate cells in this range. Merged cells will be respected.
forEach(callback: (row: number, col: number, cell: ICellData) => void): voidParameters
callback— Required. the callback function to be called for each cell in the range
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.forEach((row, col, cell) => { console.log(row, col, cell)})Types: ICellData
Package: @univerjs/sheets · Type definitions
FRange.getA1Notation
Returns a string description of the range, in A1 notation.
getA1Notation(withSheet?: boolean, startAbsoluteRefType?: AbsoluteRefType, endAbsoluteRefType?: AbsoluteRefType): stringParameters
withSheet— Optional. If true, the sheet name is included in the A1 notation.startAbsoluteRefType— Optional. The absolute reference type for the start cell.endAbsoluteRefType— Optional. The absolute reference type for the end cell.
Returns
The A1 notation of the range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// 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:B2console.log(fRange.getA1Notation(false, univerAPI.Enum.AbsoluteRefType.COLUMN)) // $A1:B2console.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$2console.log(fRange.getA1Notation(false, null, univerAPI.Enum.AbsoluteRefType.COLUMN)) // A1:$B2console.log(fRange.getA1Notation(false, null, univerAPI.Enum.AbsoluteRefType.ALL)) // A1:$B$2// By setting all parameters exampleconsole.log( fRange.getA1Notation( true, univerAPI.Enum.AbsoluteRefType.ALL, univerAPI.Enum.AbsoluteRefType.ALL, ),) // Sheet1!$A$1:$B$2Types: AbsoluteRefType
Package: @univerjs/sheets · Type definitions
FRange.getBackground
Returns the background color of the top-left cell in the range.
getBackground(): stringReturns
The color code of the background.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getBackground())Package: @univerjs/sheets · Type definitions
FRange.getBackgrounds
Returns the background colors of the cells in the range.
getBackgrounds(): string[][]Returns
A two-dimensional array of color codes of the backgrounds.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getBackgrounds())Package: @univerjs/sheets · Type definitions
FRange.getCellData
Return first cell model data in this range
getCellData(): ICellData | nullReturns
The cell model data
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCellData())Types: ICellData
Package: @univerjs/sheets · Type definitions
FRange.getCellDataGrid
Returns the cell data for the cells in the range.
getCellDataGrid(): Nullable<ICellData>[][]Returns
A two-dimensional array of cell data.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCellDataGrid())Package: @univerjs/sheets · Type definitions
FRange.getCellDatas
Alias for getCellDataGrid.
getCellDatas(): Nullable<ICellData>[][]Returns
A two-dimensional array of cell data.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCellDatas())Package: @univerjs/sheets · Type definitions
FRange.getCellStyle
Return first cell style in this range.
getCellStyle(type?: GetStyleType): TextStyleValue | nullParameters
type— Optional. Default:'row'. 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
The cell style
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCellStyle())Types: TextStyleValue · GetStyleType
Package: @univerjs/sheets · Type definitions
FRange.getCellStyleData
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.
getCellStyleData(type?: GetStyleType): IStyleData | nullParameters
type— Optional. Default:'row'. 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
The cell style data
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCellStyleData())Types: IStyleData · GetStyleType
Package: @univerjs/sheets · Type definitions
FRange.getCellStyles
Returns the cell styles for the cells in the range.
getCellStyles(type?: GetStyleType): Array<Array<TextStyleValue | null>>Parameters
type— Optional. Default:'row'. 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
A two-dimensional array of cell styles.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCellStyles())Types: Array · TextStyleValue · GetStyleType
Package: @univerjs/sheets · Type definitions
FRange.getColumn
Gets the starting column index of the range. index starts at 0.
getColumn(): numberReturns
The starting column index of the range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getColumn()) // 0Package: @univerjs/sheets · Type definitions
FRange.getCustomMetaData
Returns the custom meta data for the cell at the start of this range.
getCustomMetaData(): CustomData | nullReturns
The custom meta data
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCustomMetaData())Types: CustomData
Package: @univerjs/sheets · Type definitions
FRange.getCustomMetaDatas
Returns the custom meta data for the cells in the range.
getCustomMetaDatas(): Nullable<CustomData>[][]Returns
A two-dimensional array of custom metadata, with null for cells without metadata.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCustomMetaDatas())Types: Nullable · CustomData
Package: @univerjs/sheets · Type definitions
FRange.getDataRegion
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.
getDataRegion(dimension?: Dimension): FRangeParameters
dimension— Optional. The dimension along which to expand the range. If not provided, the range will be expanded in both dimensions.
Returns
The range's data region or a range covering each column or each row spanned by the original range.
Examples
// Assume the active sheet is a new sheet with no data.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// 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:D4const 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:D3const 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:D4const range3 = fWorksheet.getRange('C3').getDataRegion()console.log(range3.getA1Notation()) // B2:D4Package: @univerjs/sheets · Type definitions
FRange.getDisplayValue
Returns the displayed value of the top-left cell in the range. The value is a String. Empty cells return an empty string.
getDisplayValue(): stringReturns
The displayed value of the cell. Returns an empty string if the cell is empty.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setValueForCell({ v: 0.2, s: { n: { pattern: '0%', }, },})console.log(fRange.getDisplayValue()) // 20%Package: @univerjs/sheets · Type definitions
FRange.getDisplayValues
Returns a two-dimensional array of the range displayed values. Empty cells return an empty string.
getDisplayValues(): string[][]Returns
A two-dimensional array of values.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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', '']]Package: @univerjs/sheets · Type definitions
FRange.getFontFamily
Get the font family of the cell.
getFontFamily(type?: GetStyleType): string | nullParameters
type— Optional. Default:'row'. 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
The font family of the cell
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getFontFamily())Types: GetStyleType
Package: @univerjs/sheets · Type definitions
FRange.getFontSize
Get the font size of the cell.
getFontSize(type?: GetStyleType): number | nullParameters
type— Optional. Default:'row'. 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
The font size of the cell
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getFontSize())Types: GetStyleType
Package: @univerjs/sheets · Type definitions
FRange.getFormula
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.
getFormula(): stringReturns
The formula for the cell.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getFormula())Package: @univerjs/sheets · Type definitions
FRange.getFormulas
Returns the formulas (A1 notation) for the cells in the range. Entries in the 2D array are empty strings for cells with no formula.
getFormulas(): string[][]Returns
A two-dimensional array of formulas in string format.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getFormulas())Package: @univerjs/sheets · Type definitions
FRange.getHeight
Returns the number of rows in this range.
getHeight(): numberReturns
The row count, not a size in pixels.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getHeight())Package: @univerjs/sheets · Type definitions
FRange.getHorizontalAlignment
Returns the horizontal alignment of the top-left cell as 'left', 'center', or 'normal' (right alignment). Default and other core alignment values return 'general', which is not accepted by setHorizontalAlignment().
getHorizontalAlignment(): stringReturns
The horizontal alignment of the text in the cell.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getHorizontalAlignment())Package: @univerjs/sheets · Type definitions
FRange.getHorizontalAlignments
Returns a two-dimensional array of horizontal alignments: 'left', 'center', or 'normal' (right alignment). Default and other core alignment values return 'general', which is not accepted by setHorizontalAlignment().
getHorizontalAlignments(): string[][]Returns
A two-dimensional array of horizontal alignments of text associated with cells in the range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getHorizontalAlignments())Package: @univerjs/sheets · Type definitions
FRange.getLastColumn
Gets the ending column index of the range. index starts at 0.
getLastColumn(): numberReturns
The ending column index of the range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getLastColumn()) // 1Package: @univerjs/sheets · Type definitions
FRange.getLastRow
Gets the ending row index of the range. index starts at 0.
getLastRow(): numberReturns
The ending row index of the range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getLastRow()) // 1Package: @univerjs/sheets · Type definitions
FRange.getRange
Gets the area where the statement is applied
getRange(): IRangeReturns
The area where the statement is applied
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')const range = fRange.getRange()const { startRow, startColumn, endRow, endColumn } = rangeconsole.log(range)Types: IRange
Package: @univerjs/sheets · Type definitions
FRange.getRangePermission
Get the RangePermission instance for managing range-level permissions. This is the new permission API that provides range-specific permission control.
getRangePermission(): FRangePermissionReturns
- The RangePermission instance.
Examples
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B10')const permission = fRange.getRangePermission()// Protect the rangeawait permission.protect({ name: 'Protected Area', allowEdit: false })// Check if range is protectedconst isProtected = permission.isProtected()// Check if current user can editconst canEdit = permission.canEdit()// Unprotect the rangeawait permission.unprotect()// Subscribe to protection changespermission.protectionChange$.subscribe((change) => { console.log('Protection changed:', change)})Types: FRangePermission
Package: @univerjs/sheets · Type definitions
FRange.getRawValue
Returns the raw value of the top-left cell in the range. Empty cells return null.
getRawValue(): Nullable<CellValue>Returns
The raw value of the cell. Returns null if the cell is empty.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setValueForCell({ v: 0.2, s: { n: { pattern: '0%', }, },})console.log(fRange.getRawValue()) // 0.2Package: @univerjs/sheets · Type definitions
FRange.getRawValues
Returns a two-dimensional array of the range raw values. Empty cells return null.
getRawValues(): Array<Array<Nullable<CellValue>>>Returns
The raw value of the cell. Returns null if the cell is empty.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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]]Types: Array · Nullable · CellValue
Package: @univerjs/sheets · Type definitions
FRange.getRow
Gets the starting row index of the range. index starts at 0.
getRow(): numberReturns
The starting row index of the range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getRow()) // 0Package: @univerjs/sheets · Type definitions
FRange.getSheetId
Gets the ID of the worksheet
getSheetId(): stringReturns
The ID of the worksheet
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getSheetId())Package: @univerjs/sheets · Type definitions
FRange.getSheetName
Gets the name of the worksheet
getSheetName(): stringReturns
The name of the worksheet
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getSheetName())Package: @univerjs/sheets · Type definitions
FRange.getShrinkToFit
Gets whether the top-left cell shrinks its font size to fit the cell width.
getShrinkToFit(): booleanReturns
Whether shrink-to-fit is enabled for the top-left cell.
Package: @univerjs/sheets · Type definitions
FRange.getUnitId
Get the unit ID of the current workbook
getUnitId(): stringReturns
The unit ID of the workbook
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getUnitId())Package: @univerjs/sheets · Type definitions
FRange.getUsedThemeStyle
Gets the theme style applied to the range.
getUsedThemeStyle(): string | undefinedReturns
The name of the theme style applied to the range or not exist.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:E20')console.log(fRange.getUsedThemeStyle()) // undefinedfRange.useThemeStyle('default')console.log(fRange.getUsedThemeStyle()) // 'default'Package: @univerjs/sheets · Type definitions
FRange.getValue
Return first cell value in this range
getValue(): CellValue | nullgetValue(includeRichText: true): Nullable<CellValue | RichTextValue>Parameters
includeRichText— Optional. Passtrueto return aRichTextValuefor rich-text content instead of plain text.
Returns
The cell value
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getValue())// set the first cell value to 123fRange.setValueForCell(123)console.log(fRange.getValue()) // 123const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getValue(true))// set the first cell value to 123const richText = univerAPI .newRichText() .text('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 WorldTypes: CellValue · RichTextValue · Nullable
Package: @univerjs/sheets · Type definitions
FRange.getValueAndRichTextValues
Returns the value and rich text value for the cells in the range.
getValueAndRichTextValues(): Nullable<CellValue | RichTextValue>[][]Returns
A two-dimensional array of value and rich text value
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getValueAndRichTextValues())Types: Nullable · CellValue · RichTextValue
Package: @univerjs/sheets · Type definitions
FRange.getValues
Returns the cell values for the cells in the range.
getValues(): Nullable<CellValue>[][]getValues(includeRichText: true): (Nullable<RichTextValue | CellValue>)[][]Parameters
includeRichText— Optional. Passtrueto returnRichTextValueentries for rich-text content instead of plain text.
Returns
A two-dimensional array of cell values.
Examples
// Get plain valuesconst fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getValues())// Get values with rich text if availableconst fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getValues(true))Types: Nullable · CellValue · RichTextValue
Package: @univerjs/sheets · Type definitions
FRange.getVerticalAlignment
Returns top, middle, or bottom for the top-left cell; unspecified alignment returns general.
general is a getter result and is not accepted by setVerticalAlignment().
getVerticalAlignment(): stringReturns
The vertical alignment of the text in the cell.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getVerticalAlignment())Package: @univerjs/sheets · Type definitions
FRange.getVerticalAlignments
Returns a two-dimensional array of top, middle, or bottom values; unspecified alignment returns general.
general is a getter result and is not accepted by setVerticalAlignment().
getVerticalAlignments(): string[][]Returns
A two-dimensional array of vertical alignments of text associated with cells in the range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getVerticalAlignments())Package: @univerjs/sheets · Type definitions
FRange.getWidth
Returns the number of columns in this range.
getWidth(): numberReturns
The column count, not a size in pixels.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getWidth())Package: @univerjs/sheets · Type definitions
FRange.getWrap
Gets whether text wrapping is enabled for top-left cell in the range.
getWrap(): booleanReturns
whether text wrapping is enabled for the cell.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getWrap())Package: @univerjs/sheets · Type definitions
FRange.getWraps
Gets whether text wrapping is enabled for cells in the range.
getWraps(): boolean[][]Returns
A two-dimensional array of whether text wrapping is enabled for each cell in the range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getWraps())Package: @univerjs/sheets · Type definitions
FRange.getWrapStrategy
Returns the text wrapping strategy for the top left cell of the range.
getWrapStrategy(): WrapStrategyReturns
The text wrapping strategy
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getWrapStrategy())Types: WrapStrategy
Package: @univerjs/sheets · Type definitions
FRange.insertCells
Inserts empty cells into this range. Existing data in the sheet along the provided dimension is shifted away from the inserted range.
insertCells(shiftDimension: Dimension): voidParameters
shiftDimension— Required. The dimension along which to shift existing data.
Examples
// Assume the active sheet empty sheet.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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 | 8const 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 | 8const 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 | 8fRange.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 | 8const 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]]Types: Dimension
Package: @univerjs/sheets · Type definitions
FRange.isBlank
Returns true if the range is totally blank.
isBlank(): booleanReturns
true if the range is blank; false otherwise.
Examples
// Assume the active sheet is a new sheet with no data.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.isBlank()) // true// Set the range A1:B2 with some valuesfRange.setValueForCell(123)console.log(fRange.isBlank()) // falsePackage: @univerjs/sheets · Type definitions
FRange.isMerged
Checks whether this range exactly matches a merged cell range.
isMerged(): booleanReturns
true only for an exact merged range match. Use isPartOfMerge() to check overlap.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.isMerged())// merge cells A1:B2fRange.merge()console.log(fRange.isMerged())Package: @univerjs/sheets · Type definitions
FRange.isPartOfMerge
Returns true if cells in the current range overlap a merged cell.
isPartOfMerge(): booleanReturns
is overlap with a merged cell
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.merge()const anchor = fWorksheet.getRange('A1')console.log(anchor.isPartOfMerge()) // truePackage: @univerjs/sheets · Type definitions
FRange.merge
Merge cells in a range into one merged cell
merge(options?: IMergeCellsUtilOptions): FRangeParameters
options— Optional. The options for merging cells.
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.merge()console.log(fRange.isMerged())const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('B1:C2')// Assume A1:B2 is already merged.fRange.merge({ isForceMerge: true })Types: FRange · IMergeCellsUtilOptions
Package: @univerjs/sheets · Type definitions
FRange.mergeAcross
Merges cells in a range horizontally.
mergeAcross(options?: IMergeCellsUtilOptions): FRangeParameters
options— Optional. The options for merging cells.
Returns
This range, for chaining
Examples
// Assume the active sheet is a new sheet with no merged cells.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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())})const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('B1:C2')// Assume A1:B2 is already merged.fRange.mergeAcross({ isForceMerge: true })Types: FRange · IMergeCellsUtilOptions
Package: @univerjs/sheets · Type definitions
FRange.mergeVertically
Merges cells in a range vertically.
mergeVertically(options?: IMergeCellsUtilOptions): FRangeParameters
options— Optional. The options for merging cells.
Returns
This range, for chaining
Examples
// Assume the active sheet is a new sheet with no merged cells.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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())})const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('B1:C2')// Assume A1:B2 is already merged.fRange.mergeVertically({ isForceMerge: true })Types: FRange · IMergeCellsUtilOptions
Package: @univerjs/sheets · Type definitions
FRange.offset
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.
offset(rowOffset: number, columnOffset: number): FRangeoffset(rowOffset: number, columnOffset: number, numRows: number): FRangeParameters
rowOffset— Required. The number of rows down from the range's top-left cell; negative values represent rows up from the range's top-left cell.columnOffset— Required. The number of columns right from the range's top-left cell; negative values represent columns left from the range's top-left cell.numRows— Optional. The height in rows of the new range.
Returns
The new range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getA1Notation()) // A1:B2// Offset the range by 1 row and 1 columnconst newRange = fRange.offset(1, 1)console.log(newRange.getA1Notation()) // B2:C3const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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 3const newRange = fRange.offset(1, 1, 3)console.log(newRange.getA1Notation()) // B2:C4const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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 and the width to 3const newRange = fRange.offset(1, 1, 3, 3)console.log(newRange.getA1Notation()) // B2:D4Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.removeThemeStyle
Remove the theme style for the range.
removeThemeStyle(themeName: string): voidParameters
themeName— Required. The name of the theme style to remove.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:E20')fRange.removeThemeStyle('default')Package: @univerjs/sheets · Type definitions
FRange.setBackground
Set background color for current range.
setBackground(color: string): FRangeParameters
color— Required. The background color
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setBackground('red')Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.setBackgroundColor
Set background color for current range.
setBackgroundColor(color: string): FRangeParameters
color— Required. The background color
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setBackgroundColor('red')Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.setBorder
Sets basic border properties for the current range.
setBorder(type: BorderType, style: BorderStyleTypes, color?: string): FRangeParameters
type— Required. The type of border to applystyle— Required. The border stylecolor— Optional. Optional border color in CSS notation
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setBorder(univerAPI.Enum.BorderType.ALL, univerAPI.Enum.BorderStyleTypes.THIN, '#ff0000')Types: FRange · BorderType · BorderStyleTypes
Package: @univerjs/sheets · Type definitions
FRange.setCustomMetaData
Set custom meta data for first cell in current range.
setCustomMetaData(data: CustomData): FRangeParameters
data— Required. The custom meta data
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setCustomMetaData({ key: 'value' })console.log(fRange.getCustomMetaData())Types: FRange · CustomData
Package: @univerjs/sheets · Type definitions
FRange.setCustomMetaDatas
Set custom meta data for current range.
setCustomMetaDatas(datas: CustomData[][]): FRangeParameters
datas— Required. The custom meta data
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setCustomMetaDatas([ [{ key: 'value' }, { key: 'value2' }], [{ key: 'value3' }, { key: 'value4' }],])console.log(fRange.getCustomMetaDatas())Types: FRange · CustomData
Package: @univerjs/sheets · Type definitions
FRange.setFontColor
Sets the font color in CSS notation (such as '#ffffff' or 'white').
setFontColor(color: string | null): thisParameters
color— Required. The font color in CSS notation (such as '#ffffff' or 'white'); a null value resets the color.
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setFontColor('#ff0000')Package: @univerjs/sheets · Type definitions
FRange.setFontFamily
Sets the font family, such as "Arial" or "Helvetica".
setFontFamily(fontFamily: string | null): thisParameters
fontFamily— Required. The font family to set; a null value resets the font family.
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setFontFamily('Arial')Package: @univerjs/sheets · Type definitions
FRange.setFontLine
Sets the font line style of the given range ('underline', 'line-through', or 'none').
setFontLine(fontLine: FontLine | null): thisParameters
fontLine— Required. The font line style, either 'underline', 'line-through', or 'none'; a null value resets the font line style.
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setFontLine('underline')Types: FontLine
Package: @univerjs/sheets · Type definitions
FRange.setFontSize
Sets the font size, with the size being the point size to use.
setFontSize(size: number | null): thisParameters
size— Required. A font size in point size. A null value resets the font size.
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setFontSize(24)Package: @univerjs/sheets · Type definitions
FRange.setFontStyle
Sets the font style for the given range ('italic' or 'normal').
setFontStyle(fontStyle: FontStyle | null): thisParameters
fontStyle— Required. The font style, either 'italic' or 'normal'; a null value resets the font style.
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setFontStyle('italic')Types: FontStyle
Package: @univerjs/sheets · Type definitions
FRange.setFontWeight
Sets the font weight for the given range (normal/bold),
setFontWeight(fontWeight: FontWeight | null): thisParameters
fontWeight— Required. The font weight, either 'normal' or 'bold'; a null value resets the font weight.
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setFontWeight('bold')Types: FontWeight
Package: @univerjs/sheets · Type definitions
FRange.setFormula
Updates the formula for this range. The given formula must be in A1 notation.
setFormula(formula: string): FRangeParameters
formula— Required. A string representing the formula to set for the cell.
Returns
This range instance for chaining.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1')fRange.setFormula('=SUM(A2:A5)')console.log(fRange.getFormula()) // '=SUM(A2:A5)'Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.setFormulas
Sets a rectangular grid of formulas (must match dimensions of this range). The given formulas must be in A1 notation.
setFormulas(formulas: string[][]): FRangeParameters
formulas— Required. A two-dimensional string array of formulas.
Returns
This range instance for chaining.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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)']]Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.setHorizontalAlignment
Sets the horizontal alignment for the range. Accepts 'left', 'center', or 'normal', following the Google Apps Script parameter names. In Univer, 'normal' means right alignment; 'right' is not an accepted value.
fRange.setHorizontalAlignment('normal') // Align rightsetHorizontalAlignment(alignment: FHorizontalAlignment): FRangeParameters
alignment— Required. The horizontal alignment:left,center, ornormal(right alignment).
Returns
this range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setHorizontalAlignment('normal') // Align rightTypes: FRange · FHorizontalAlignment
Package: @univerjs/sheets · Type definitions
FRange.setRichTextValueForCell
Set the rich text value for the cell at the start of this range.
setRichTextValueForCell(value: RichTextValue | IDocumentData): FRangeParameters
value— Required. The rich text value
Returns
The range
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getValue(true))// Set A1 cell value to rich textconst 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 WorldTypes: FRange · RichTextValue · IDocumentData
Package: @univerjs/sheets · Type definitions
FRange.setRichTextValues
Set the rich text value for the cells in the range.
setRichTextValues(values: (RichTextValue | IDocumentData)[][]): FRangeParameters
values— Required. A two-dimensional array of rich-text values or document data matching this range's dimensions.
Returns
The range
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getValue(true))// Set A1:B2 cell value to rich textconst 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], [richText, richText],])console.log(fRange.getValue(true).toPlainText()) // Hello WorldTypes: FRange · RichTextValue · IDocumentData
Package: @univerjs/sheets · Type definitions
FRange.setShrinkToFit
Sets whether cells shrink their font size to fit the cell width.
setShrinkToFit(enabled: boolean): FRangeParameters
enabled— Required. Whether to enable shrink-to-fit for this range.
Returns
This range, for chaining.
Examples
univerAPI.getActiveWorkbook()?.getActiveSheet().getRange('A1:B2').setShrinkToFit(true)Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.setTextRotation
Set rotation for text in current range.
setTextRotation(rotation: number): FRangeParameters
rotation— Required. The rotation angle in degrees
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setTextRotation(45)Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.setValue
Sets the value or specified cell properties for every cell in this range.
There are two input modes:
CellValue(number,string, orboolean): replaces the cell content. A string starting with=and containing at least one more character is written as a formula (f), clearing the previous value (v) and rich text (p). Other values clear the previous formula and rich text. Strings recognized as formatted numbers (for example, percentages, dates, or currencies) are converted to numeric values and apply the parsed number format. Existing formatting is otherwise preserved.ICellData: updates cell-data fields directly, for explicit control overv(value),f(formula),p(rich text),t(value type), ands(style). The object bypasses the formula and formatted-number parsing above:{ v: '=SUM(A1:A2)' }does not set a formula; use{ f: '=SUM(A1:A2)', v: null, p: null }instead. Omitted content fields are not automatically cleared, so usef: nullandp: nullwhen replacing a formula or rich text withv. Usev: nullto clear the stored value. Supplied style properties are merged into the existing style;s: nullclears the style.
In both modes, the stored value is converted according to its cell type. Unless an ICellData
input supplies t, the type is inferred from the value, number format, and existing cell type.
Consequently, passing { v: '00123' } alone does not guarantee that the value stays a string;
supply t: CellValueType.STRING to store it as text.
setValue(value: CellValue | ICellData): FRangeParameters
value— Required. The scalar content or cell-data update to apply throughout the range.
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('B2:B3')// Replace the content of both cells, preserving their formatting.fRange.setValue(123)// Parse a percentage and apply its number format to both cells.fRange.setValue('25%')// Write the same formula to both cells.fRange.setValue('=SUM(A1:A2)')// Explicitly replace content and update the background color.fRange.setValue({ v: 234, f: null, p: null, s: { bg: { rgb: '#ff0000' } } })// Store numeric-looking text (CellValueType is imported from '@univerjs/core').fRange.setValue({ v: '00123', t: CellValueType.STRING, f: null, p: null })// Clear value, formula, and rich text while preserving formatting.fRange.setValue({ v: null, f: null, p: null })Types: FRange · CellValue · ICellData
Package: @univerjs/sheets · Type definitions
FRange.setValueForCell
Sets the value or specified cell properties of the top-left cell in this range.
Uses the same scalar parsing and cell-data update rules as FRange.setValue.
setValueForCell(value: CellValue | ICellData): FRangeParameters
value— Required. The scalar content or cell-data update to apply to the top-left cell only.
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setValueForCell(123)// orfRange.setValueForCell({ v: 234, s: { bg: { rgb: '#ff0000' } } })Types: FRange · CellValue · ICellData
Package: @univerjs/sheets · Type definitions
FRange.setValues
Sets cell values or specified cell properties using an array or a sparse matrix.
Each entry follows the scalar parsing and cell-data update rules of FRange.setValue.
A two-dimensional array is relative to this range's top-left cell and must match its dimensions. A sparse matrix uses absolute, zero-based worksheet row and column keys. Only supplied entries are updated; matrix coordinates are not offset by or clipped to this range.
setValues(value: CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>): FRangeParameters
value— Required. An array relative to this range, or a sparse matrix using absolute worksheet coordinates.
Returns
This range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setValues([ [1, { v: 2, s: { bg: { rgb: '#ff0000' } } }], [3, 4],])// Update only B2 and C3 using absolute worksheet coordinates.fWorksheet.getRange('B2:C3').setValues({ 1: { 1: 'B2' }, 2: { 2: { v: 10, f: null, p: null } },})Types: FRange · CellValue · IObjectMatrixPrimitiveType · ICellData
Package: @univerjs/sheets · Type definitions
FRange.setVerticalAlignment
Set the vertical (top to bottom) alignment for the given range (top/middle/bottom).
setVerticalAlignment(alignment: FVerticalAlignment): FRangeParameters
alignment— Required. The vertical alignment
Returns
this range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setVerticalAlignment('top')Types: FRange · FVerticalAlignment
Package: @univerjs/sheets · Type definitions
FRange.setWrap
Set the cell wrap of the given range.
Pass true to set WrapStrategy.WRAP, or false to reset to WrapStrategy.UNSPECIFIED.
Use setWrapStrategy() to explicitly select clipping or overflow behavior.
setWrap(isWrapEnabled: boolean): FRangeParameters
isWrapEnabled— Required. Whether to enable wrap
Returns
this range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setWrap(true)console.log(fRange.getWrap())Types: FRange
Package: @univerjs/sheets · Type definitions
FRange.setWrapStrategy
Sets the text wrapping strategy for the cells in the range.
setWrapStrategy(strategy: WrapStrategy): FRangeParameters
strategy— Required. The text wrapping strategy
Returns
this range, for chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setWrapStrategy(univerAPI.Enum.WrapStrategy.WRAP)console.log(fRange.getWrapStrategy())Types: FRange · WrapStrategy
Package: @univerjs/sheets · Type definitions
FRange.splitTextToColumns
Splits a column of text into multiple columns based on an auto-detected delimiter.
splitTextToColumns(treatMultipleDelimitersAsOne?: boolean): voidsplitTextToColumns(treatMultipleDelimitersAsOne?: boolean, delimiter?: SplitDelimiterEnum): voidParameters
treatMultipleDelimitersAsOne— Optional. Whether to treat multiple continuous delimiters as one. The default value is false.delimiter— Optional. The delimiter to use to split the text. The default delimiter is Tab(1)、Comma(2)、Semicolon(4)、Space(8)、Custom(16).A delimiter like 6 (SplitDelimiterEnum.Comma|SplitDelimiterEnum.Semicolon) means using Comma and Semicolon to split the text.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// 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 | 6fRange.splitTextToColumns(true)// After calling splitTextToColumns(false), the range will be:// A | | |// 1 | 2 | 3 |// 4 | | 5 | 6fRange.splitTextToColumns(false)Show how to split text to columns with combined delimiter. The bit operations are used to combine the delimiters.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// A1:A3 has following values:// A |// 1;;2;3 |// 1;,2;3 |const fRange = fWorksheet.getRange('A1:A3')fRange.setValues([['A'], ['1;;2;3'], ['1;,2;3']])// After calling splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Semicolon|univerAPI.Enum.SplitDelimiterType.Comma), the range will be:// A | | |// 1 | | 2 | 3// 1 | | 2 | 3fRange.splitTextToColumns( false, univerAPI.Enum.SplitDelimiterType.Semicolon | univerAPI.Enum.SplitDelimiterType.Comma,)// After calling splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Semicolon|univerAPI.Enum.SplitDelimiterType.Comma), the range will be:// A | |// 1 | 2 | 3// 1 | 2 | 3fRange.splitTextToColumns( true, univerAPI.Enum.SplitDelimiterType.Semicolon | univerAPI.Enum.SplitDelimiterType.Comma,)Show how to split text to columns with custom delimiter
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// 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(false, univerAPI.Enum.SplitDelimiterType.Custom, '#'), the range will be:// A | | |// 1 | 2 | 3 |// 4 | | 5 | 6fRange.splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Custom, '#')// After calling splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Custom, '#'), the range will be:// A | |// 1 | 2 | 3// 4 | 5 | 6fRange.splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Custom, '#')Types: SplitDelimiterEnum
Package: @univerjs/sheets · Type definitions
FRange.useThemeStyle
Set the theme style for the range.
useThemeStyle(themeName: string | undefined): voidParameters
themeName— Required. The name of the theme style to apply.If a undefined value is passed, the theme style will be removed if it exist.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:E20')fRange.useThemeStyle('default')Package: @univerjs/sheets · Type definitions
@univerjs/sheets-conditional-formatting
FRange.clearConditionalFormatRules
Clear the conditional rules for the range.
clearConditionalFormatRules(): FRangeReturns
Returns the current range instance for method chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:T100')// Clear all conditional format rules for the rangefRange.clearConditionalFormatRules()console.log(fRange.getConditionalFormattingRules()) // []Types: FRange
Package: @univerjs/sheets-conditional-formatting · Type definitions
FRange.createConditionalFormattingRule
Creates a constructor for conditional formatting
createConditionalFormattingRule(): FConditionalFormattingBuilderReturns
The conditional formatting builder
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a conditional formatting rule that sets the cell format to italic, red background, and green font color when the cell is not empty.const fRange = fWorksheet.getRange('A1:T100')const rule = fRange .createConditionalFormattingRule() .whenCellNotEmpty() .setItalic(true) .setBackground('red') .setFontColor('green') .build()fWorksheet.addConditionalFormattingRule(rule)console.log(fRange.getConditionalFormattingRules())Types: FConditionalFormattingBuilder
Package: @univerjs/sheets-conditional-formatting · Type definitions
FRange.getConditionalFormattingRules
Gets all the conditional formatting for the current range.
getConditionalFormattingRules(): IConditionFormattingRule[]Returns
conditional formatting rules for the current range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a conditional formatting rule that sets the cell format to italic, red background, and green font color when the cell is not empty.const fRange = fWorksheet.getRange('A1:T100')const rule = fWorksheet .newConditionalFormattingRule() .whenCellNotEmpty() .setRanges([fRange.getRange()]) .setItalic(true) .setBackground('red') .setFontColor('green') .build()fWorksheet.addConditionalFormattingRule(rule)// Get all the conditional formatting rules for the range F6:H8.const targetRange = fWorksheet.getRange('F6:H8')const rules = targetRange.getConditionalFormattingRules()console.log(rules)Types: IConditionFormattingRule
Package: @univerjs/sheets-conditional-formatting · Type definitions
@univerjs/sheets-data-validation
FRange.getDataValidation
Get first data validation rule in current range.
getDataValidation(): Nullable<FDataValidation>Returns
data validation rule
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a data validation rule that requires a number equal to 20 for the range A1:B10const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation().requireNumberEqualTo(20).build()fRange.setDataValidation(rule)console.log(fRange.getDataValidation().getCriteriaValues())// Change the rule criteria to require a number between 1 and 10fRange .getDataValidation() .setCriteria(univerAPI.Enum.DataValidationType.DECIMAL, [ univerAPI.Enum.DataValidationOperator.BETWEEN, '1', '10', ])// Print the new rule criteria valuesconsole.log(fRange.getDataValidation().getCriteriaValues())Types: FDataValidation · Nullable
Package: @univerjs/sheets-data-validation · Type definitions
FRange.getDataValidationErrorAsync
Get data validation errors for a specific range in current worksheet.
getDataValidationErrorAsync(): Promise<IDataValidationError[]>Returns
A promise that resolves to an array of validation errors in the specified range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B10')const errors = await fRange.getDataValidationErrorAsync()console.log(errors)Types: IDataValidationError · Promise
Package: @univerjs/sheets-data-validation · Type definitions
FRange.getDataValidations
Get all data validation rules in current range.
getDataValidations(): FDataValidation[]Returns
all data validation rules
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a data validation rule that requires a number equal to 20 for the range A1:B10const fRange1 = fWorksheet.getRange('A1:B10')const rule1 = univerAPI.newDataValidation().requireNumberEqualTo(20).build()fRange1.setDataValidation(rule1)// Create a data validation rule that requires a number between 1 and 10 for the range C1:D10const fRange2 = fWorksheet.getRange('C1:D10')const rule2 = univerAPI.newDataValidation().requireNumberBetween(1, 10).build()fRange2.setDataValidation(rule2)// Get all data validation rules in the range A1:D10const range = fWorksheet.getRange('A1:D10')const rules = range.getDataValidations()console.log(rules.length) // 2Types: FDataValidation
Package: @univerjs/sheets-data-validation · Type definitions
FRange.getValidatorStatus
Get data validation validator status for current range.
getValidatorStatus(): Promise<DataValidationStatus[][]>Returns
matrix of validator status
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Set some values in the range A1:B10const fRange = fWorksheet.getRange('A1:B10')fRange.setValues([ [1, 2], [3, 4], [5, 6], [7, 8], [9, 10], [11, 12], [13, 14], [15, 16], [17, 18], [19, 20],])// Create a data validation rule that requires a number between 1 and 10 for the range A1:B10const rule = univerAPI.newDataValidation().requireNumberBetween(1, 10).build()fRange.setDataValidation(rule)// Get the validator status for the cell B2const status = await fWorksheet.getRange('B2').getValidatorStatus()console.log(status?.[0]?.[0]) // 'valid'// Get the validator status for the cell B10const status2 = await fWorksheet.getRange('B10').getValidatorStatus()console.log(status2?.[0]?.[0]) // 'invalid'Types: DataValidationStatus · Promise
Package: @univerjs/sheets-data-validation · Type definitions
FRange.setDataValidation
Set a data validation rule to current range. if rule is null, clear data validation rule.
setDataValidation(rule: Nullable<FDataValidation>): FRangeParameters
rule— Required. data validation rule, built byuniverAPI.newDataValidation()
Returns
current range
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a data validation rule that requires a number between 1 and 10 for the range A1:B10const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI .newDataValidation() .requireNumberBetween(1, 10) .setOptions({ allowBlank: true, showErrorMessage: true, error: 'Please enter a number between 1 and 10', }) .build()fRange.setDataValidation(rule)Types: FRange · Nullable · FDataValidation
Package: @univerjs/sheets-data-validation · Type definitions
@univerjs/sheets-drawing-ui
FRange.insertCellImageAsync
Inserts an image into the current cell.
insertCellImageAsync(file: File | string): Promise<boolean>Parameters
file— Required. File or URL string
Returns
True if the image is inserted successfully, otherwise false
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Insert an image into the cell A10const fRange = fWorksheet.getRange('A10')const result = await fRange.insertCellImageAsync( 'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',)console.log(result)Package: @univerjs/sheets-drawing-ui · Type definitions
FRange.saveCellImagesAsync
Save all cell images in this range to the file system. This method will open a directory picker dialog and save all images to the selected directory.
saveCellImagesAsync(options?: ISaveCellImagesOptions): Promise<boolean>Parameters
options— Optional. Options for saving images
Returns
True if images are saved successfully, otherwise false
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Save all cell images in range A1:D10const fRange = fWorksheet.getRange('A1:D10')// Save with default options (using cell address as file name)await fRange.saveCellImagesAsync()// Save with custom optionsawait fRange.saveCellImagesAsync({ useCellAddress: true, useColumnIndex: 0, // Use values from column A for file names})Types: Promise · ISaveCellImagesOptions
Package: @univerjs/sheets-drawing-ui · Type definitions
@univerjs/sheets-filter
FRange.createFilter
Create a filter for the current range. If the worksheet already has a filter, this method would return null.
createFilter(): FFilter | nullReturns
The FFilter instance to handle the filter.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:D14')let fFilter = fRange.createFilter()// If the worksheet already has a filter, remove it and create a new filter.if (!fFilter) { fWorksheet.getFilter().remove() fFilter = fRange.createFilter()}console.log(fFilter, fFilter.getRange().getA1Notation())Types: FFilter
Package: @univerjs/sheets-filter · Type definitions
FRange.getFilter
Get the filter in the worksheet to which the range belongs. If the worksheet does not have a filter, this method would return null.
Normally, you can directly call getFilter on FWorksheet.
getFilter(): FFilter | nullReturns
The FFilter instance to handle the filter.
The interface class to handle the filter. If the worksheet does not have a filter,
this method would return null.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:D14')let fFilter = fRange.getFilter()// If the worksheet does not have a filter, create a new filter.if (!fFilter) { fFilter = fRange.createFilter()}console.log(fFilter, fFilter.getRange().getA1Notation())Types: FFilter
Package: @univerjs/sheets-filter · Type definitions
@univerjs/sheets-formula
FRange.getFormulaError
Get formula errors in the current range
getFormulaError(): ISheetFormulaError[]Returns
Array of formula errors in the range
Examples
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const range = fWorksheet.getRange('A1:B10')const errors = range.getFormulaError()console.log('Formula errors in range:', errors)Types: ISheetFormulaError
Package: @univerjs/sheets-formula · Type definitions
@univerjs/sheets-hyper-link
FRange.cancelHyperLink
Cancel all hyperlinks in this range. If a hyperlink is provided, only cancel the specified hyperlink.
cancelHyperLink(hyperlink?: ICellHyperLink): booleanParameters
hyperlink— Optional. The hyperlink to be cancelled. If not provided, all hyperlinks in this range will be cancelled.
Returns
True if the hyperlink(s) is cancelled successfully, otherwise false.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Cancel the hyperlink in cell A1const fRange = fWorksheet.getRange('A1')fRange.cancelHyperLink()// Cancel all hyperlinks in range A2:B4const fRange2 = fWorksheet.getRange('A2:B4')fRange2.cancelHyperLink()// Cancel a specific hyperlink in range A1:T100const fRange3 = fWorksheet.getRange('A1:T100')const hyperlinks = fRange3.getHyperLinks()if (hyperlinks.length > 1) { fRange3.cancelHyperLink(hyperlinks[1])}Types: ICellHyperLink
Package: @univerjs/sheets-hyper-link · Type definitions
FRange.getHyperLinks
Gets the first hyperlink from each cell containing hyperlinks in this range.
getHyperLinks(): ICellHyperLink[]Returns
At most one hyperlink per cell, with absolute, zero-based worksheet coordinates.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')console.log(fWorksheet.getRange('A1:T100').getHyperLinks())Types: ICellHyperLink
Package: @univerjs/sheets-hyper-link · Type definitions
FRange.getUrl
Create a hyperlink url to this range
getUrl(): stringReturns
The hyperlink url of this range
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1')const url = fRange.getUrl()console.log(url)Package: @univerjs/sheets-hyper-link · Type definitions
FRange.setHyperLink
Set a hyperlink for this range top left cell. The hyperlink can be a URL, a range link, or a sheet link. When the hyperlink is a range link or a sheet link, the url should be the url of the target range or sheet.
setHyperLink(url: string, label?: string, tooltip?: string): Promise<boolean>Parameters
url— Required. The hyperlink url, can be a URL, a range link, or a sheet link.label— Optional. The display text of the hyperlink. If omitted, the existing cell text is linked. Supply a label when linking an empty cell.tooltip— Optional. Optional text shown inside the hyperlink popup.
Returns
A promise that resolves to true if the hyperlink is set successfully, otherwise false.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a hyperlink to Univer on cell A1const fRange = fWorksheet.getRange('A1')await fRange.setHyperLink('https://univer.ai/', 'Univer')// Create a hyperlink to Sheet1 range B2:D4 on cell A2const fRange2 = fWorksheet.getRange('A2')const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()await fRange2.setHyperLink(rangeUrl, 'Link to B2:D4')// Create a hyperlink to another sheet range on cell A3const anotherSheet = fWorkbook.getSheetByName('Another Sheet')if (anotherSheet) { const anotherSheetUrl = anotherSheet.getUrl() const fRange3 = fWorksheet.getRange('A3') await fRange3.setHyperLink(anotherSheetUrl, 'Link to Another Sheet')}// Create a hyperlink to a defined name on cell A4const fRange4 = fWorksheet.getRange('A4')const definedNameHyperlinkUrl = fWorkbook.getUrlOfDefineName('MyDefinedName')await fRange4.setHyperLink(definedNameHyperlinkUrl, 'Link to MyDefinedName')Types: Promise
Package: @univerjs/sheets-hyper-link · Type definitions
FRange.updateHyperLink
Update the hyperlink of this range top left cell.
updateHyperLink(url: string, label?: string, tooltip?: string): Promise<boolean>Parameters
url— Required. The new hyperlink url, can be a URL, a range link, or a sheet link.label— Optional. The new display text of the hyperlink. If omitted, the existing hyperlink label is preserved.tooltip— Optional. Omit to preserve the current tooltip; use an empty string to clear it.
Returns
A promise resolving to whether the update succeeded.
Throws
The promise rejects if the top-left cell contains no hyperlink.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a hyperlink to Univer on cell A1const fRange = fWorksheet.getRange('A1')await fRange.setHyperLink('https://univer.ai/', 'Univer')// Update hyperlink after 3 secondsawait new Promise((resolve) => setTimeout(resolve, 3000))const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()await fRange.updateHyperLink(rangeUrl, 'Link to B2:D4')Types: Promise
Package: @univerjs/sheets-hyper-link · Type definitions
@univerjs/sheets-note
FRange.createOrUpdateNote
Create or update the annotation of the top-left cell in the range
createOrUpdateNote(note: ICreateOrUpdateNoteOptions): FRangeParameters
note— Required. The annotation to create or update
Returns
This range for method chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1')fRange.createOrUpdateNote({ note: 'This is a note', width: 160, height: 100, show: true,})Types: FRange · ICreateOrUpdateNoteOptions
Package: @univerjs/sheets-note · Type definitions
FRange.deleteNote
Delete the annotation of the top-left cell in the range
deleteNote(): FRangeReturns
This range for method chaining
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const notes = fWorksheet.getNotes()console.log(notes)if (notes.length > 0) { // Delete the first note const { row, col } = notes[0] fWorksheet.getRange(row, col).deleteNote()}Types: FRange
Package: @univerjs/sheets-note · Type definitions
FRange.getNote
Get the annotation of the top-left cell in the range
getNote(): Nullable<ISheetNote>Returns
The annotation of the top-left cell in the range
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:D10')const note = fRange.getNote()console.log(note)Types: ISheetNote · Nullable
Package: @univerjs/sheets-note · Type definitions
@univerjs/sheets-numfmt
FRange.getNumberFormat
Get the number formatting of the top-left cell of the given range. Returns an empty string when no number format is set, even if the cell contains a value.
getNumberFormat(): stringReturns
The number format of the top-left cell of the range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Get the number format of the top-left cell of the A1:B2 range.const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getNumberFormat())Package: @univerjs/sheets-numfmt · Type definitions
FRange.getNumberFormats
Returns the number formats for the cells in the range.
getNumberFormats(): string[][]Returns
A two-dimensional array of number formats.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Get the number formats of the A1:B2 range.const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getNumberFormats())Package: @univerjs/sheets-numfmt · Type definitions
FRange.setNumberFormat
Set the number format of the range.
setNumberFormat(pattern: string): FRangeParameters
pattern— Required. The number format pattern.
Returns
The FRange instance for chaining.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Set the number format of the A1 cell to '#,##0.00'.const fRange = fWorksheet.getRange('A1')fRange.setValue(1234.567).setNumberFormat('#,##0.00')console.log(fRange.getDisplayValue()) // 1,234.57Types: FRange
Package: @univerjs/sheets-numfmt · Type definitions
FRange.setNumberFormats
Sets a rectangular grid of number formats (must match dimensions of this range).
setNumberFormats(patterns: string[][]): FRangeParameters
patterns— Required. A two-dimensional array of number formats.
Returns
The FRange instance for chaining.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Set the number formats of the A1:B2 range.const fRange = fWorksheet.getRange('A1:B2')fRange .setValues([ [1234.567, 0.1234], [45658, 0.9876], ]) .setNumberFormats([ ['#,##0.00', '0.00%'], ['yyyy-MM-DD', ''], ])console.log(fRange.getDisplayValues()) // [['1,234.57', '12.34%'], ['2025-01-01', '0.9876']]Types: FRange
Package: @univerjs/sheets-numfmt · Type definitions
@univerjs/sheets-sort
FRange.sort
Sorts the cells in the given range, by column(s) and order specified.
sort(column: SortColumnSpec | SortColumnSpec[]): FRangeParameters
column— Required. The column index with order or an array of column indexes with order. The range first column index is 0.
Returns
The range itself for chaining.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('D1:G10')// Sorts the range by the first column in ascending order.fRange.sort(0)// Sorts the range by the first column in descending order.fRange.sort({ column: 0, ascending: false })// Sorts the range by the first column in descending order and the second column in ascending order.fRange.sort([{ column: 0, ascending: false }, 1])Types: FRange · SortColumnSpec
Package: @univerjs/sheets-sort · Type definitions
@univerjs/sheets-thread-comment
FRange.addCommentAsync
Add a comment to the start cell in the current range.
addCommentAsync(content: ThreadComment.ThreadCommentContent | FTheadCommentBuilder, options?: ISheetCellCommentCreateOptions): Promise<boolean>Parameters
content— Required. The content of the comment.options— Optional. Default:{}. Optional stable IDs, author, attachments, and creation time.
Returns
Whether the comment is added successfully.
Throws
If the content is empty.
Examples
await univerAPI .getActiveWorkbook() .getActiveSheet() .getRange('A1') .addCommentAsync('Verify this value.', { id: 'review-a1' })// Create a new commentconst richText = univerAPI.newRichText().insertText('hello univer')const commentBuilder = univerAPI.newTheadComment().setContent(richText)console.log(commentBuilder.content.toPlainText())// Add the comment to the cell A1const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const cell = fWorksheet.getRange('A1')const result = await cell.addCommentAsync(commentBuilder)console.log(result)Types: Promise · ThreadComment.ThreadCommentContent · FTheadCommentBuilder · ISheetCellCommentCreateOptions
Package: @univerjs/sheets-thread-comment · Type definitions
FRange.clearCommentAsync
Clear the comment of the start cell in the current range.
clearCommentAsync(): Promise<boolean>Returns
Whether the comment is cleared successfully.
Examples
const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1')const success = await range.clearCommentAsync()console.log(success)Types: Promise
Package: @univerjs/sheets-thread-comment · Type definitions
FRange.clearCommentsAsync
Clear all of the comments in the current range.
clearCommentsAsync(): Promise<boolean>Returns
Whether the comments are cleared successfully.
Examples
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const range = fWorksheet.getActiveRange()const success = await range.clearCommentsAsync()Types: Promise
Package: @univerjs/sheets-thread-comment · Type definitions
FRange.getComment
Get the comment of the start cell in the current range.
getComment(): UniverCore.Nullable<FThreadComment>Returns
The comment of the start cell in the current range. If the cell does not have a comment, return null.
Examples
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const range = fWorksheet.getActiveRange()const comment = range.getComment()Types: FThreadComment · UniverCore.Nullable
Package: @univerjs/sheets-thread-comment · Type definitions
FRange.getComments
Get the comments in the current range.
getComments(): FThreadComment[]Returns
The comments in the current range.
Examples
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const range = fWorksheet.getActiveRange()const comments = range.getComments()comments.forEach((comment) => { console.log(comment.getRichText())})Types: FThreadComment
Package: @univerjs/sheets-thread-comment · Type definitions
@univerjs/sheets-ui
FRange.attachAlertPopup
Attach an alert popup to the start cell of current range.
attachAlertPopup(alert: Omit<ICellAlert, 'location'>): IDisposableParameters
alert— Required. The alert to attach
Returns
The disposable object to detach the alert.
Examples
// Attach an alert popup to the start cell of range C3:E5const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('C3:E5')const disposable = fRange.attachAlertPopup({ title: 'Warning', message: 'This is an warning message', type: 1,})// Detach the alert after 5 secondssetTimeout(() => { disposable.dispose()}, 5000)Types: IDisposable · Omit · ICellAlert
Package: @univerjs/sheets-ui · Type definitions
FRange.attachPopup
Attach a popup to the start cell of current range. If current worksheet is not active, the popup will not be shown. Be careful to manager the detach disposable object, if not dispose correctly, it might memory leaks.
attachPopup(popup: IFCanvasPopup): Nullable<IDisposable>Parameters
popup— Required. The popup to attach
Returns
The disposable object to detach the popup, if the popup is not attached, return null.
Examples
// Register a custom popup componentuniverAPI.registerComponent('myPopup', () => React.createElement( 'div', { style: { color: 'red', fontSize: '14px', }, }, 'Custom Popup', ),)// Attach the popup to the start cell of range C3:E5const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('C3:E5')const disposable = fRange.attachPopup({ componentKey: 'myPopup',})// Detach the popup after 5 secondssetTimeout(() => { disposable.dispose()}, 5000)Types: IDisposable · Nullable · IFCanvasPopup
Package: @univerjs/sheets-ui · Type definitions
FRange.attachRangePopup
Attach a DOM popup to the current range.
attachRangePopup(popup: IFCanvasPopup): Nullable<IDisposable>Parameters
popup— Required. The popup to attach.
Returns
A disposable that detaches the popup, or null if the popup cannot be attached.
Examples
// Register a custom popup componentuniverAPI.registerComponent('myPopup', () => React.createElement( 'div', { style: { background: 'red', fontSize: '14px', }, }, 'Custom Popup', ),)// Attach the popup to the range C3:E5const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('C3:E5')const disposable = fRange.attachRangePopup({ componentKey: 'myPopup', direction: 'top', // 'vertical' | 'horizontal' | 'top' | 'right' | 'left' | 'bottom' | 'bottom-center' | 'top-center'})let fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')let range = fWorksheet.getRange(2, 2, 3, 3)univerAPI.getActiveWorkbook().setActiveRange(range)let disposable = range.attachRangePopup({ componentKey: 'univer.sheet.single-dom-popup', extraProps: { alert: { type: 0, title: 'This is an Info', message: 'This is an info message' } },})Types: IDisposable · Nullable · IFCanvasPopup
Package: @univerjs/sheets-ui · Type definitions
FRange.generateHTML
Generate HTML content for the range.
generateHTML(): stringReturns
HTML content of the range.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B2')fRange.setValues([ [1, 2], [3, 4],])console.log(fRange.generateHTML())Types: FRange
Package: @univerjs/sheets-ui · Type definitions
FRange.getCell
Return this cell information, including whether it is merged and cell coordinates
getCell(): ICellWithCoordReturns
cell location and coordinate.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('H6')console.log(fRange.getCell())Types: ICellWithCoord · FRange
Package: @univerjs/sheets-ui · Type definitions
FRange.getCellRect
Returns the coordinates of this cell,does not include units
getCellRect(): DOMRectReturns
coordinates of the cell， top, right, bottom, left
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('H6')console.log(fRange.getCellRect())Package: @univerjs/sheets-ui · Type definitions
FRange.highlight
Highlight the range with the specified style and primary cell.
highlight(style?: Nullable<Partial<ISelectionStyle>>, primary?: Nullable<ISelectionCell>): IDisposableParameters
style— Optional. style for highlight range.primary— Optional. primary cell for highlight range.
Returns
The disposable object to remove the highlight.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Highlight the range C3:E5 with default styleconst fRange = fWorksheet.getRange('C3:E5')fRange.highlight()// Highlight the range C7:E9 with custom style and primary cell D8const fRange2 = fWorksheet.getRange('C7:E9')const primaryCell = fWorksheet.getRange('D8').getRange()const disposable = fRange2.highlight( { stroke: 'red', fill: 'yellow', }, { ...primaryCell, actualRow: primaryCell.startRow, actualColumn: primaryCell.startColumn, },)// Remove the range C7:E9 highlight after 5 secondssetTimeout(() => { disposable.dispose()}, 5000)Types: IDisposable · Nullable · Partial · ISelectionStyle · ISelectionCell
Package: @univerjs/sheets-ui · Type definitions
FRange.showDropdown
Show a dropdown at the current range.
showDropdown(param: IDropdownParam): IDisposableParameters
param— Required. The parameters for the dropdown.
Returns
The disposable object to hide the dropdown.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('C3:E5')fRange.showDropdown({ type: 'list', props: { options: [ { label: 'Option 1', value: 'option1' }, { label: 'Option 2', value: 'option2' }, ], },})Types: IDisposable · IDropdownParam
Package: @univerjs/sheets-ui · Type definitions
@univerjs-pro/sheets-print
FRange.getScreenshot
Get screenshot of this range. This API is only available with a license. Users without a license will face usage restrictions. On failure, it returns false, and on success, it returns the image's base64 string.
getScreenshot(options?: IRangeScreenshotOptions): string | falseParameters
options— Optional. Screenshot options.
Returns
- The base64 encoded image string, or false if the user does not have permission.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:D10')// Screenshot without headersconsole.log(fRange.getScreenshot())// Screenshot with row and column headersconsole.log(fRange.getScreenshot({ includeHeaders: true }))Types: IRangeScreenshotOptions
Package: @univerjs-pro/sheets-print · Type definitions
How is this guide?