# Range > Language fallback: requested `zh-CN`; content is `en-US`. - Human documentation: [https://docs.univer.ai/zh-CN/reference/facade/range](https://docs.univer.ai/zh-CN/reference/facade/range) - Agent Markdown: [https://docs.univer.ai/zh-CN/reference/facade/range.md](https://docs.univer.ai/zh-CN/reference/facade/range.md) - Requested language: `zh-CN` - Content language: `en-US` - Documentation version: `1.0.0-rc.0` - Source: [facade/range.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/range.mdx) --- | Packages | `@univerjs/sheets`, `@univerjs/sheets-thread-comment`, `@univerjs/sheets-conditional-formatting`, `@univerjs/sheets-ui`, `@univerjs/sheets-hyper-link`, `@univerjs/sheets-filter`, `@univerjs/sheets-note`, `@univerjs/sheets-data-validation`, `@univerjs/sheets-formula`, `@univerjs/sheets-numfmt`, `@univerjs-pro/sheets-print`, `@univerjs/sheets-drawing-ui`, `@univerjs/sheets-sort` | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | Represents a range of cells in a sheet. You can call methods on this Facade API object to read contents or manipulate the range. > This class should not be instantiated directly. Use factory methods on `univerAPI` instead. ## Overview ### @univerjs/sheets | Method | Description | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`activate`](#activate) | Sets the specified range as the active range, with the top left cell in the range as the current cell | | [`activateAsCurrentCell`](#activateascurrentcell) | Sets the specified cell as the current cell | | [`autoFill`](#autofill) | Fills the target range with data based on the data in the current range | | [`breakApart`](#breakapart) | Break all horizontally- or vertically-merged cells contained within the range list into individual cells again | | [`clear`](#clear) | Clears content and formatting information of the range | | [`clearContent`](#clearcontent) | Clears content of the range, while preserving formatting information | | [`clearFormat`](#clearformat) | Clears formatting information of the range, while preserving contents | | [`deleteCells`](#deletecells) | Deletes this range of cells | | [`forEach`](#foreach) | Iterate cells in this range | | [`getA1Notation`](#geta1notation) | Returns a string description of the range, in A1 notation | | [`getBackground`](#getbackground) | Returns the background color of the top-left cell in the range | | [`getBackgrounds`](#getbackgrounds) | Returns the background colors of the cells in the range | | [`getCellData`](#getcelldata) | Return first cell model data in this range | | [`getCellDataGrid`](#getcelldatagrid) | Returns the cell data for the cells in the range | | [`getCellDatas`](#getcelldatas) | Alias for getCellDataGrid | | [`getCellStyle`](#getcellstyle) | Return first cell style in this range | | [`getCellStyleData`](#getcellstyledata) | Return first cell style data in this range | | [`getCellStyles`](#getcellstyles) | Returns the cell styles for the cells in the range | | [`getColumn`](#getcolumn) | Gets the starting column index of the range | | [`getCustomMetaData`](#getcustommetadata) | Returns the custom meta data for the cell at the start of this range | | [`getCustomMetaDatas`](#getcustommetadatas) | Returns the custom meta data for the cells in the range | | [`getDataRegion`](#getdataregion) | Expands the range to adjacent data along the requested row or column dimension | | [`getDisplayValue`](#getdisplayvalue) | Returns the displayed value of the top-left cell in the range | | [`getDisplayValues`](#getdisplayvalues) | Returns a two-dimensional array of the range displayed values | | [`getFontFamily`](#getfontfamily) | Get the font family of the cell | | [`getFontSize`](#getfontsize) | Get the font size of the cell | | [`getFormula`](#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 | | [`getFormulas`](#getformulas) | Returns the formulas (A1 notation) for the cells in the range | | [`getHeight`](#getheight) | Gets the height of the applied area | | [`getHorizontalAlignment`](#gethorizontalalignment) | Returns the horizontal alignment of the text (left/center/right) of the top-left cell in the range | | [`getHorizontalAlignments`](#gethorizontalalignments) | Returns the horizontal alignments of the cells in the range | | [`getLastColumn`](#getlastcolumn) | Gets the ending column index of the range | | [`getLastRow`](#getlastrow) | Gets the ending row index of the range | | [`getRange`](#getrange) | Gets the area where the statement is applied | | [`getRangePermission`](#getrangepermission) | Get the RangePermission instance for managing range-level permissions | | [`getRawValue`](#getrawvalue) | Returns the raw value of the top-left cell in the range | | [`getRawValues`](#getrawvalues) | Returns a two-dimensional array of the range raw values | | [`getRow`](#getrow) | Gets the starting row index of the range | | [`getSheetId`](#getsheetid) | Gets the ID of the worksheet | | [`getSheetName`](#getsheetname) | Gets the name of the worksheet | | [`getShrinkToFit`](#getshrinktofit) | Gets whether the top-left cell shrinks its font size to fit the cell width | | [`getUnitId`](#getunitid) | Get the unit ID of the current workbook | | [`getUsedThemeStyle`](#getusedthemestyle) | Gets the theme style applied to the range | | [`getValue`](#getvalue) | - | | [`getValueAndRichTextValues`](#getvalueandrichtextvalues) | Returns the value and rich text value for the cells in the range | | [`getValues`](#getvalues) | - | | [`getVerticalAlignment`](#getverticalalignment) | Returns the vertical alignment (top/middle/bottom) of the top-left cell in the range | | [`getVerticalAlignments`](#getverticalalignments) | Returns the vertical alignments of the cells in the range | | [`getWidth`](#getwidth) | Gets the width of the applied area | | [`getWrap`](#getwrap) | Gets whether text wrapping is enabled for top-left cell in the range | | [`getWraps`](#getwraps) | Gets whether text wrapping is enabled for cells in the range | | [`getWrapStrategy`](#getwrapstrategy) | Returns the text wrapping strategy for the top left cell of the range | | [`insertCells`](#insertcells) | Inserts empty cells into this range | | [`isBlank`](#isblank) | Returns true if the range is totally blank | | [`isMerged`](#ismerged) | Return range whether this range is merged | | [`isPartOfMerge`](#ispartofmerge) | Returns true if cells in the current range overlap a merged cell | | [`merge`](#merge) | Merge cells in a range into one merged cell | | [`mergeAcross`](#mergeacross) | Merges cells in a range horizontally | | [`mergeVertically`](#mergevertically) | Merges cells in a range vertically | | [`offset`](#offset) | Returns a new range that is relative to the current range, whose upper left point is offset from the current range by the given rows and columns, and with the given height and width in cells | | [`removeThemeStyle`](#removethemestyle) | Remove the theme style for the range | | [`setBackground`](#setbackground) | Set background color for current range | | [`setBackgroundColor`](#setbackgroundcolor) | Set background color for current range | | [`setBorder`](#setborder) | Sets basic border properties for the current range | | [`setCustomMetaData`](#setcustommetadata) | Set custom meta data for first cell in current range | | [`setCustomMetaDatas`](#setcustommetadatas) | Set custom meta data for current range | | [`setFontColor`](#setfontcolor) | Sets the font color in CSS notation (such as '#ffffff' or 'white') | | [`setFontFamily`](#setfontfamily) | Sets the font family, such as "Arial" or "Helvetica" | | [`setFontLine`](#setfontline) | Sets the font line style of the given range ('underline', 'line-through', or 'none') | | [`setFontSize`](#setfontsize) | Sets the font size, with the size being the point size to use | | [`setFontStyle`](#setfontstyle) | Sets the font style for the given range ('italic' or 'normal') | | [`setFontWeight`](#setfontweight) | Sets the font weight for the given range (normal/bold), | | [`setFormula`](#setformula) | Updates the formula for this range | | [`setFormulas`](#setformulas) | Sets a rectangular grid of formulas (must match dimensions of this range) | | [`setHorizontalAlignment`](#sethorizontalalignment) | Set the horizontal (left to right) alignment for the given range (left/center/right) | | [`setRichTextValueForCell`](#setrichtextvalueforcell) | Set the rich text value for the cell at the start of this range | | [`setRichTextValues`](#setrichtextvalues) | Set the rich text value for the cells in the range | | [`setShrinkToFit`](#setshrinktofit) | Sets whether cells shrink their font size to fit the cell width | | [`setTextRotation`](#settextrotation) | Set rotation for text in current range | | [`setValue`](#setvalue) | Sets the value of the range | | [`setValueForCell`](#setvalueforcell) | Set new value for current cell, first cell in this range | | [`setValues`](#setvalues) | Sets a different value for each cell in the range | | [`setVerticalAlignment`](#setverticalalignment) | Set the vertical (top to bottom) alignment for the given range (top/middle/bottom) | | [`setWrap`](#setwrap) | Set the cell wrap of the given range | | [`setWrapStrategy`](#setwrapstrategy) | Sets the text wrapping strategy for the cells in the range | | [`splitTextToColumns`](#splittexttocolumns) | Splits a column of text into multiple columns based on a custom specified delimiter | | [`useThemeStyle`](#usethemestyle) | Set the theme style for the range | ### @univerjs/sheets-conditional-formatting | Method | Description | | --------------------------------------------------------------------- | ----------- | | [`clearConditionalFormatRules`](#clearconditionalformatrules) | - | | [`createConditionalFormattingRule`](#createconditionalformattingrule) | - | | [`getConditionalFormattingRules`](#getconditionalformattingrules) | - | ### @univerjs/sheets-data-validation | Method | Description | | ------------------------------------------------------------- | ----------- | | [`getDataValidation`](#getdatavalidation) | - | | [`getDataValidationErrorAsync`](#getdatavalidationerrorasync) | - | | [`getDataValidations`](#getdatavalidations) | - | | [`getValidatorStatus`](#getvalidatorstatus) | - | | [`setDataValidation`](#setdatavalidation) | - | ### @univerjs/sheets-drawing-ui | Method | Description | | ----------------------------------------------- | ----------- | | [`insertCellImageAsync`](#insertcellimageasync) | - | | [`saveCellImagesAsync`](#savecellimagesasync) | - | ### @univerjs/sheets-filter | Method | Description | | ------------------------------- | ------------------------------------------------ | | [`createFilter`](#createfilter) | - | | [`getFilter`](#getfilter) | Get the filter for the current range's worksheet | ### @univerjs/sheets-formula | Method | Description | | ------------------------------------- | ----------- | | [`getFormulaError`](#getformulaerror) | - | ### @univerjs/sheets-hyper-link | Method | Description | | ------------------------------------- | ------------------------------------------------ | | [`cancelHyperLink`](#cancelhyperlink) | Cancel all hyperlinks in this range | | [`getHyperLinks`](#gethyperlinks) | Get all hyperlinks in this range | | [`getUrl`](#geturl) | Generate a hyperlink URL for the current range | | [`setHyperLink`](#sethyperlink) | Set a hyperlink for this range top left cell | | [`updateHyperLink`](#updatehyperlink) | Update the hyperlink of this range top left cell | ### @univerjs/sheets-note | Method | Description | | ------------------------------------------- | ----------- | | [`createOrUpdateNote`](#createorupdatenote) | - | | [`deleteNote`](#deletenote) | - | | [`getNote`](#getnote) | - | ### @univerjs/sheets-numfmt | Method | Description | | --------------------------------------- | ------------------------------------------------------------------ | | [`getNumberFormat`](#getnumberformat) | Returns the number format string of the top-left cell in the range | | [`getNumberFormats`](#getnumberformats) | Returns the number format strings for the cells in the range | | [`setNumberFormat`](#setnumberformat) | Sets the number format for the cells in the range | | [`setNumberFormats`](#setnumberformats) | Sets different number formats for each cell in the range | ### @univerjs/sheets-sort | Method | Description | | --------------- | ----------- | | [`sort`](#sort) | - | ### @univerjs/sheets-thread-comment | Method | Description | | ------------------------------------------- | ----------- | | [`addCommentAsync`](#addcommentasync) | - | | [`clearCommentAsync`](#clearcommentasync) | - | | [`clearCommentsAsync`](#clearcommentsasync) | - | | [`getComment`](#getcomment) | - | | [`getComments`](#getcomments) | - | ### @univerjs/sheets-ui | Method | Description | | --------------------------------------- | -------------- | | [`attachAlertPopup`](#attachalertpopup) | - | | [`attachPopup`](#attachpopup) | - | | [`attachRangePopup`](#attachrangepopup) | attachDOMPopup | | [`generateHTML`](#generatehtml) | - | | [`getCell`](#getcell) | - | | [`getCellRect`](#getcellrect) | - | | [`highlight`](#highlight) | - | | [`showDropdown`](#showdropdown) | - | ### @univerjs-pro/sheets-print | Method | Description | | --------------------------------- | ----------- | | [`getScreenshot`](#getscreenshot) | - | ## APIs ### Value & Formula ### `getCellData` Return first cell model data in this range **Signature** ```typescript getCellData(): ICellData | null ``` **Returns** * `ICellData` — The cell model data **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getCellData()); ``` Source: `@univerjs/sheets` ### `getCellDataGrid` Returns the cell data for the cells in the range. **Signature** ```typescript getCellDataGrid(): Nullable[][] ``` **Returns** * `Nullable[][]` — A two-dimensional array of cell data. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getCellDataGrid()); ``` Source: `@univerjs/sheets` ### `getCellDatas` Alias for getCellDataGrid. **Signature** ```typescript getCellDatas(): Nullable[][] ``` **Returns** * `Nullable[][]` — A two-dimensional array of cell data. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getCellDatas()); ``` Source: `@univerjs/sheets` ### `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. **Signature** ```typescript getCellStyleData(type: GetStyleType = 'row'): IStyleData | null ``` **Parameters** * `type` `GetStyleType` *(optional)* — *No description* **Returns** * `IStyleData` — The cell style data **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getCellStyleData()); ``` Source: `@univerjs/sheets` ### `getCustomMetaData` Returns the custom meta data for the cell at the start of this range. **Signature** ```typescript getCustomMetaData(): CustomData | null ``` **Returns** * `CustomData` — The custom meta data **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getCustomMetaData()); ``` Source: `@univerjs/sheets` ### `getCustomMetaDatas` Returns the custom meta data for the cells in the range. **Signature** ```typescript getCustomMetaDatas(): Nullable[][] ``` **Returns** * `Nullable[][]` — A two-dimensional array of custom meta data **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getCustomMetaDatas()); ``` Source: `@univerjs/sheets` ### `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. **Signature** ```typescript getDataRegion(dimension?: Dimension): FRange ``` **Parameters** * `dimension` `Dimension` *(optional)* — *No description* **Returns** * `FRange` — The range's data region or a range covering each column or each row spanned by the original range. **Examples** ```ts // Assume the active sheet is a new sheet with no data. const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Set the range A1:D4 with some values, the range A1:D4 will be: // | | | // | | 100 | // | 100 | | 100 // | | 100 | fWorksheet.getRange('C2').setValue(100); fWorksheet.getRange('B3').setValue(100); fWorksheet.getRange('D3').setValue(100); fWorksheet.getRange('C4').setValue(100); // Get C3 data region along the rows dimension, the range will be C2:D4 const range = fWorksheet.getRange('C3').getDataRegion(univerAPI.Enum.Dimension.ROWS); console.log(range.getA1Notation()); // C2:C4 // Get C3 data region along the columns dimension, the range will be B3:D3 const range2 = fWorksheet.getRange('C3').getDataRegion(univerAPI.Enum.Dimension.COLUMNS); console.log(range2.getA1Notation()); // B3:D3 // Get C3 data region along the both dimension, the range will be B2:D4 const range3 = fWorksheet.getRange('C3').getDataRegion(); console.log(range3.getA1Notation()); // B2:D4 ``` Source: `@univerjs/sheets` ### `getDataValidation` **Signature** ```typescript getDataValidation(): Nullable ``` **Returns** * `Nullable` — See signature above. Source: `@univerjs/sheets-data-validation` ### `getDataValidationErrorAsync` **Signature** ```typescript async getDataValidationErrorAsync(): Promise ``` **Returns** * `Promise` — See signature above. Source: `@univerjs/sheets-data-validation` ### `getDataValidations` **Signature** ```typescript getDataValidations(): FDataValidation[] ``` **Returns** * `FDataValidation[]` — See signature above. Source: `@univerjs/sheets-data-validation` ### `getDisplayValue` Returns the displayed value of the top-left cell in the range. The value is a String. Empty cells return an empty string. **Signature** ```typescript getDisplayValue(): string ``` **Returns** * `string` — The displayed value of the cell. Returns an empty string if the cell is empty. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setValueForCell({ v: 0.2, s: { n: { pattern: '0%', }, }, }); console.log(fRange.getDisplayValue()); // 20% ``` Source: `@univerjs/sheets` ### `getDisplayValues` Returns a two-dimensional array of the range displayed values. Empty cells return an empty string. **Signature** ```typescript getDisplayValues(): string[][] ``` **Returns** * `string[][]` — A two-dimensional array of values. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setValues([ [ { v: 0.2, s: { n: { pattern: '0%', }, }, }, { v: 45658, s: { n: { pattern: 'yyyy-mm-dd', }, }, } ], [ { v: 1234.567, s: { n: { pattern: '#,##0.00', } } }, null, ], ]); console.log(fRange.getDisplayValues()); // [['20%', '2025-01-01'], ['1,234.57', '']] ``` Source: `@univerjs/sheets` ### `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. **Signature** ```typescript getFormula(): string ``` **Returns** * `string` — The formula for the cell. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getFormula()); ``` Source: `@univerjs/sheets` ### `getFormulaError` **Signature** ```typescript getFormulaError(): ISheetFormulaError[] ``` **Returns** * `ISheetFormulaError[]` — See signature above. Source: `@univerjs/sheets-formula` ### `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. **Signature** ```typescript getFormulas(): string[][] ``` **Returns** * `string[][]` — A two-dimensional array of formulas in string format. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getFormulas()); ``` Source: `@univerjs/sheets` ### `getRawValue` Returns the raw value of the top-left cell in the range. Empty cells return `null`. **Signature** ```typescript getRawValue(): Nullable ``` **Returns** * `Nullable` — The raw value of the cell. Returns `null` if the cell is empty. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setValueForCell({ v: 0.2, s: { n: { pattern: '0%', }, }, }); console.log(fRange.getRawValue()); // 0.2 ``` Source: `@univerjs/sheets` ### `getRawValues` Returns a two-dimensional array of the range raw values. Empty cells return `null`. **Signature** ```typescript getRawValues(): Array>> ``` **Returns** * `Nullable[][]` — The raw value of the cell. Returns `null` if the cell is empty. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setValues([ [ { v: 0.2, s: { n: { pattern: '0%', }, }, }, { v: 45658, s: { n: { pattern: 'yyyy-mm-dd', }, }, } ], [ { v: 1234.567, s: { n: { pattern: '#,##0.00', } } }, null, ], ]); console.log(fRange.getRawValues()); // [[0.2, 45658], [1234.567, null]] ``` Source: `@univerjs/sheets` ### `getValue` **Signature** ```typescript getValue(includeRichText?: boolean): Nullable ``` **Parameters** * `includeRichText` `boolean` *(optional)* — *No description* **Returns** * `Nullable` — See signature above. Source: `@univerjs/sheets` ### `getValueAndRichTextValues` Returns the value and rich text value for the cells in the range. **Signature** ```typescript getValueAndRichTextValues(): Nullable[][] ``` **Returns** * `Nullable[][]` — A two-dimensional array of value and rich text value **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getValueAndRichTextValues()); ``` Source: `@univerjs/sheets` ### `getValues` **Signature** ```typescript getValues(includeRichText?: true): (Nullable)[][] ``` **Parameters** * `includeRichText` `true` *(optional)* — *No description* **Returns** * `Nullable[][]` — See signature above. Source: `@univerjs/sheets` ### `setCustomMetaData` Set custom meta data for first cell in current range. **Signature** ```typescript setCustomMetaData(data: CustomData): FRange ``` **Parameters** * `data` `CustomData` — *No description* **Returns** * `FRange` — This range, for chaining ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setCustomMetaData({ key: 'value' }); console.log(fRange.getCustomMetaData()); ``` Source: `@univerjs/sheets` ### `setCustomMetaDatas` Set custom meta data for current range. **Signature** ```typescript setCustomMetaDatas(datas: CustomData[][]): FRange ``` **Parameters** * `datas` `CustomData[][]` — *No description* **Returns** * `FRange` — This range, for chaining ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setCustomMetaDatas([ [{ key: 'value' }, { key: 'value2' }], [{ key: 'value3' }, { key: 'value4' }], ]); console.log(fRange.getCustomMetaDatas()); ``` Source: `@univerjs/sheets` ### `setDataValidation` **Signature** ```typescript setDataValidation(rule: Nullable): FRange ``` **Parameters** * `rule` `Nullable` — *No description* **Returns** * `FRange` — See signature above. Source: `@univerjs/sheets-data-validation` ### `setFormula` Updates the formula for this range. The given formula must be in A1 notation. **Signature** ```typescript setFormula(formula: string): FRange ``` **Parameters** * `formula` `string` — *No description* **Returns** * `FRange` — This range instance for chaining. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1'); fRange.setFormula('=SUM(A2:A5)'); console.log(fRange.getFormula()); // '=SUM(A2:A5)' ``` Source: `@univerjs/sheets` ### `setFormulas` Sets a rectangular grid of formulas (must match dimensions of this range). The given formulas must be in A1 notation. **Signature** ```typescript setFormulas(formulas: string[][]): FRange ``` **Parameters** * `formulas` `string[][]` — *No description* **Returns** * `FRange` — This range instance for chaining. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setFormulas([ ['=SUM(A2:A5)', '=SUM(B2:B5)'], ['=SUM(A6:A9)', '=SUM(B6:B9)'], ]); console.log(fRange.getFormulas()); // [['=SUM(A2:A5)', '=SUM(B2:B5)'], ['=SUM(A6:A9)', '=SUM(B6:B9)']] ``` Source: `@univerjs/sheets` ### `setRichTextValueForCell` Set the rich text value for the cell at the start of this range. **Signature** ```typescript setRichTextValueForCell(value: RichTextValue | IDocumentData): FRange ``` **Parameters** * `value` `IDocumentData | RichTextValue` — *No description* **Returns** * `FRange` — The range **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getValue(true)); // Set A1 cell value to rich text const richText = univerAPI.newRichText() .insertText('Hello World') .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } }) .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } }); fRange.setRichTextValueForCell(richText); console.log(fRange.getValue(true).toPlainText()); // Hello World ``` Source: `@univerjs/sheets` ### `setRichTextValues` Set the rich text value for the cells in the range. **Signature** ```typescript setRichTextValues(values: (RichTextValue | IDocumentData)[][]): FRange ``` **Parameters** * `values` `(IDocumentData | RichTextValue)[][]` — *No description* **Returns** * `FRange` — The range **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getValue(true)); // Set A1:B2 cell value to rich text const richText = univerAPI.newRichText() .insertText('Hello World') .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } }) .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } }); fRange.setRichTextValues([ [richText, richText], [null, null] ]); console.log(fRange.getValue(true).toPlainText()); // Hello World ``` Source: `@univerjs/sheets` ### `setValue` Sets the value of the range. **Signature** ```typescript setValue(value: CellValue | ICellData): FRange ``` **Parameters** * `value` `CellValue | ICellData` — *No description* **Returns** * `FRange` — This range, for chaining ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('B2'); fRange.setValue(123); // or fRange.setValue({ v: 234, s: { bg: { rgb: '#ff0000' } } }); ``` Source: `@univerjs/sheets` ### `setValueForCell` Set new value for current cell, first cell in this range. **Signature** ```typescript setValueForCell(value: CellValue | ICellData): FRange ``` **Parameters** * `value` `CellValue | ICellData` — *No description* **Returns** * `FRange` — This range, for chaining ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setValueForCell(123); // or fRange.setValueForCell({ v: 234, s: { bg: { rgb: '#ff0000' } } }); ``` Source: `@univerjs/sheets` ### `setValues` Sets a different value for each cell in the range. The value can be a two-dimensional array or a standard range matrix (must match the dimensions of this range), consisting of numbers, strings, Boolean values or Composed of standard cell formats. If a value begins with `=`, it is interpreted as a formula. **Signature** ```typescript setValues(value: | CellValue[][] | IObjectMatrixPrimitiveType | ICellData[][] | IObjectMatrixPrimitiveType): FRange ``` **Parameters** * `value` `CellValue[][] | IObjectMatrixPrimitiveType | ICellData[][] | IObjectMatrixPrimitiveType` — *No description* **Returns** * `FRange` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setValues([ [1, { v: 2, s: { bg: { rgb: '#ff0000' } } }], [3, 4] ]); ``` Source: `@univerjs/sheets` ### Style & Format ### `clearConditionalFormatRules` **Signature** ```typescript clearConditionalFormatRules(): FRange ``` **Returns** * `FRange` — See signature above. Source: `@univerjs/sheets-conditional-formatting` ### `clearFormat` Clears formatting information of the range, while preserving contents. **Signature** ```typescript clearFormat(): FRange ``` **Returns** * `FRange` — Returns the current worksheet instance for method chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); const fRange = fWorkSheet.getRange('A1:D10'); // clear the format only of the range A1:D10 fRange.clearFormat(); ``` Source: `@univerjs/sheets` ### `createConditionalFormattingRule` **Signature** ```typescript createConditionalFormattingRule(): FConditionalFormattingBuilder ``` **Returns** * `FConditionalFormattingBuilder` — See signature above. Source: `@univerjs/sheets-conditional-formatting` ### `getBackground` Returns the background color of the top-left cell in the range. **Signature** ```typescript getBackground(): string ``` **Returns** * `string` — The color code of the background. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getBackground()); ``` Source: `@univerjs/sheets` ### `getBackgrounds` Returns the background colors of the cells in the range. **Signature** ```typescript getBackgrounds(): string[][] ``` **Returns** * `string[][]` — A two-dimensional array of color codes of the backgrounds. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getBackgrounds()); ``` Source: `@univerjs/sheets` ### `getCellStyle` Return first cell style in this range. **Signature** ```typescript getCellStyle(type: GetStyleType = 'row'): TextStyleValue | null ``` **Parameters** * `type` `GetStyleType` *(optional)* — *No description* **Returns** * `TextStyleValue` — The cell style **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getCellStyle()); ``` Source: `@univerjs/sheets` ### `getCellStyles` Returns the cell styles for the cells in the range. **Signature** ```typescript getCellStyles(type: GetStyleType = 'row'): Array> ``` **Parameters** * `type` `GetStyleType` *(optional)* — *No description* **Returns** * `TextStyleValue[][]` — A two-dimensional array of cell styles. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getCellStyles()); ``` Source: `@univerjs/sheets` ### `getConditionalFormattingRules` **Signature** ```typescript getConditionalFormattingRules(): IConditionFormattingRule[] ``` **Returns** * `IConditionFormattingRule[]` — See signature above. Source: `@univerjs/sheets-conditional-formatting` ### `getFontFamily` Get the font family of the cell. **Signature** ```typescript getFontFamily(type: GetStyleType = 'row'): string | null ``` **Parameters** * `type` `GetStyleType` *(optional)* — *No description* **Returns** * `string` — The font family of the cell **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getFontFamily()); ``` Source: `@univerjs/sheets` ### `getFontSize` Get the font size of the cell. **Signature** ```typescript getFontSize(type: GetStyleType = 'row'): number | null ``` **Parameters** * `type` `GetStyleType` *(optional)* — *No description* **Returns** * `number` — The font size of the cell **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getFontSize()); ``` Source: `@univerjs/sheets` ### `getNumberFormat` Returns the number format string of the top-left cell in the range. **Signature** ```typescript getNumberFormat(): string ``` **Returns** * `string` — The number format pattern (e.g. `'0.00%'`, `'yyyy-mm-dd'`). **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1'); fRange.setNumberFormat('0.00%'); console.log(fRange.getNumberFormat()); // 0.00% ``` Source: `@univerjs/sheets-numfmt` ### `getNumberFormats` Returns the number format strings for the cells in the range. **Signature** ```typescript getNumberFormats(): string[][] ``` **Returns** * `string[][]` — A two-dimensional array of number format patterns. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); const formats = fRange.getNumberFormats(); console.log(formats); ``` Source: `@univerjs/sheets-numfmt` ### `getUsedThemeStyle` Gets the theme style applied to the range. **Signature** ```typescript getUsedThemeStyle(): string | undefined ``` **Returns** * `string` — The name of the theme style applied to the range or not exist. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:E20'); console.log(fRange.getUsedThemeStyle()); // undefined fRange.useThemeStyle('default'); console.log(fRange.getUsedThemeStyle()); // 'default' ``` Source: `@univerjs/sheets` ### `removeThemeStyle` Remove the theme style for the range. **Signature** ```typescript removeThemeStyle(themeName: string): void ``` **Parameters** * `themeName` `string` — *No description* **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:E20'); fRange.removeThemeStyle('default'); ``` Source: `@univerjs/sheets` ### `setBackground` Set background color for current range. **Signature** ```typescript setBackground(color: string): FRange ``` **Parameters** * `color` `string` — *No description* **Returns** * `FRange` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setBackground('red'); ``` Source: `@univerjs/sheets` ### `setBackgroundColor` Set background color for current range. **Signature** ```typescript setBackgroundColor(color: string): FRange ``` **Parameters** * `color` `string` — *No description* **Returns** * `FRange` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setBackgroundColor('red'); ``` Source: `@univerjs/sheets` ### `setBorder` Sets basic border properties for the current range. **Signature** ```typescript setBorder(type: BorderType, style: BorderStyleTypes, color?: string): FRange ``` **Parameters** * `type` `BorderType` — *No description* * `style` `BorderStyleTypes` — *No description* * `color` `string` *(optional)* — *No description* **Returns** * `FRange` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setBorder(univerAPI.Enum.BorderType.ALL, univerAPI.Enum.BorderStyleTypes.THIN, '#ff0000'); ``` Source: `@univerjs/sheets` ### `setFontColor` Sets the font color in CSS notation (such as '#ffffff' or 'white'). **Signature** ```typescript setFontColor(color: string | null): this ``` **Parameters** * `color` `string` — *No description* **Returns** * `this` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setFontColor('#ff0000'); ``` Source: `@univerjs/sheets` ### `setFontFamily` Sets the font family, such as "Arial" or "Helvetica". **Signature** ```typescript setFontFamily(fontFamily: string | null): this ``` **Parameters** * `fontFamily` `string` — *No description* **Returns** * `this` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setFontFamily('Arial'); ``` Source: `@univerjs/sheets` ### `setFontLine` Sets the font line style of the given range ('underline', 'line-through', or 'none'). **Signature** ```typescript setFontLine(fontLine: FontLine | null): this ``` **Parameters** * `fontLine` `FontLine` — *No description* **Returns** * `this` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setFontLine('underline'); ``` Source: `@univerjs/sheets` ### `setFontSize` Sets the font size, with the size being the point size to use. **Signature** ```typescript setFontSize(size: number | null): this ``` **Parameters** * `size` `number` — *No description* **Returns** * `this` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setFontSize(24); ``` Source: `@univerjs/sheets` ### `setFontStyle` Sets the font style for the given range ('italic' or 'normal'). **Signature** ```typescript setFontStyle(fontStyle: FontStyle | null): this ``` **Parameters** * `fontStyle` `FontStyle` — *No description* **Returns** * `this` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setFontStyle('italic'); ``` Source: `@univerjs/sheets` ### `setFontWeight` Sets the font weight for the given range (normal/bold), **Signature** ```typescript setFontWeight(fontWeight: FontWeight | null): this ``` **Parameters** * `fontWeight` `FontWeight` — *No description* **Returns** * `this` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setFontWeight('bold'); ``` Source: `@univerjs/sheets` ### `setNumberFormat` Sets the number format for the cells in the range. **Signature** ```typescript setNumberFormat(pattern: string): FRange ``` **Parameters** * `pattern` `string` — The number format pattern (e.g. `'0.00'`, `'yyyy-mm-dd'`, `'$#,##0.00'`). **Returns** * `FRange` — This range, for chaining. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setNumberFormat('0.00%'); ``` Source: `@univerjs/sheets-numfmt` ### `setNumberFormats` Sets different number formats for each cell in the range. The size of the `patterns` array must match the dimensions of the range. **Signature** ```typescript setNumberFormats(patterns: string[][]): FRange ``` **Parameters** * `patterns` `string[][]` — A two-dimensional array of number format patterns. **Returns** * `FRange` — This range, for chaining. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setNumberFormats([ ['0.00', '$#,##0.00'], ['yyyy-mm-dd', '0.00%'], ]); ``` Source: `@univerjs/sheets-numfmt` ### `useThemeStyle` Set the theme style for the range. **Signature** ```typescript useThemeStyle(themeName: string | undefined): void ``` **Parameters** * `themeName` `string` — *No description* **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:E20'); fRange.useThemeStyle('default'); ``` Source: `@univerjs/sheets` ### Geometry & Size ### `getCellRect` **Signature** ```typescript getCellRect(): DOMRect ``` **Returns** * `DOMRect` — See signature above. Source: `@univerjs/sheets-ui` ### `getColumn` Gets the starting column index of the range. index starts at 0. **Signature** ```typescript getColumn(): number ``` **Returns** * `number` — The starting column index of the range. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getColumn()); // 0 ``` Source: `@univerjs/sheets` ### `getHeight` Gets the height of the applied area **Signature** ```typescript getHeight(): number ``` **Returns** * `number` — The height of the area **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getHeight()); ``` Source: `@univerjs/sheets` ### `getLastColumn` Gets the ending column index of the range. index starts at 0. **Signature** ```typescript getLastColumn(): number ``` **Returns** * `number` — The ending column index of the range. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getLastColumn()); // 1 ``` Source: `@univerjs/sheets` ### `getLastRow` Gets the ending row index of the range. index starts at 0. **Signature** ```typescript getLastRow(): number ``` **Returns** * `number` — The ending row index of the range. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getLastRow()); // 1 ``` Source: `@univerjs/sheets` ### `getRow` Gets the starting row index of the range. index starts at 0. **Signature** ```typescript getRow(): number ``` **Returns** * `number` — The starting row index of the range. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getRow()); // 0 ``` Source: `@univerjs/sheets` ### `getWidth` Gets the width of the applied area **Signature** ```typescript getWidth(): number ``` **Returns** * `number` — The width of the area **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getWidth()); ``` Source: `@univerjs/sheets` ### `splitTextToColumns` Splits a column of text into multiple columns based on a custom specified delimiter. **Signature** ```typescript splitTextToColumns(treatMultipleDelimitersAsOne?: boolean, delimiter?: SplitDelimiterEnum, customDelimiter?: string): void ``` **Parameters** * `treatMultipleDelimitersAsOne` `boolean` *(optional)* — *No description* * `delimiter` `SplitDelimiterEnum` *(optional)* — *No description* * `customDelimiter` `string` *(optional)* — *No description* **Examples** ````ts Show how to split text to columns with custom delimiter ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // A1:A3 has following values: // A | // 1#2#3 | // 4##5#6 | const fRange = fWorksheet.getRange('A1:A3'); fRange.setValues([ ['A'], ['1#2#3'], ['4##5#6'] ]); // After calling splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Custom, '#'), the range will be: // A | | | // 1 | 2 | 3 | // 4 | | 5 | 6 fRange.splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Custom, '#'); // After calling splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Custom, '#'), the range will be: // A | | // 1 | 2 | 3 // 4 | 5 | 6 fRange.splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Custom, '#'); ```` Source: `@univerjs/sheets` ### Merge & Clear ### `breakApart` Break all horizontally- or vertically-merged cells contained within the range list into individual cells again. **Signature** ```typescript breakApart(): FRange ``` **Returns** * `FRange` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.merge(); const anchor = fWorksheet.getRange('A1'); console.log(anchor.isPartOfMerge()); // true fRange.breakApart(); console.log(anchor.isPartOfMerge()); // false ``` Source: `@univerjs/sheets` ### `clear` Clears content and formatting information of the range. Or Optionally clears only the contents or only the formatting. **Signature** ```typescript clear(options?: IFacadeClearOptions): FRange ``` **Parameters** * `options` `IFacadeClearOptions` *(optional)* — *No description* **Returns** * `FRange` — Returns the current worksheet instance for method chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); const fRange = fWorkSheet.getRange('A1:D10'); // clear the content and format of the range A1:D10 fRange.clear(); // clear the content only of the range A1:D10 fRange.clear({ contentsOnly: true }); ``` Source: `@univerjs/sheets` ### `clearCommentAsync` **Signature** ```typescript clearCommentAsync(): Promise ``` **Returns** * `Promise` — See signature above. Source: `@univerjs/sheets-thread-comment` ### `clearCommentsAsync` **Signature** ```typescript clearCommentsAsync(): Promise ``` **Returns** * `Promise` — See signature above. Source: `@univerjs/sheets-thread-comment` ### `clearContent` Clears content of the range, while preserving formatting information. **Signature** ```typescript clearContent(): FRange ``` **Returns** * `FRange` — Returns the current worksheet instance for method chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); const fRange = fWorkSheet.getRange('A1:D10'); // clear the content only of the range A1:D10 fRange.clearContent(); ``` Source: `@univerjs/sheets` ### `deleteCells` Deletes this range of cells. Existing data in the sheet along the provided dimension is shifted towards the deleted range. **Signature** ```typescript deleteCells(shiftDimension: Dimension): void ``` **Parameters** * `shiftDimension` `Dimension` — *No description* **Examples** ```ts // Assume the active sheet empty sheet. const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const values = [ [1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8], ]; // Set the range A1:D5 with some values, the range A1:D5 will be: // 1 | 2 | 3 | 4 // 2 | 3 | 4 | 5 // 3 | 4 | 5 | 6 // 4 | 5 | 6 | 7 // 5 | 6 | 7 | 8 const fRange = fWorksheet.getRange('A1:D5'); fRange.setValues(values); console.log(fWorksheet.getRange('A1:D5').getValues()); // [[1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]] // Delete the range A1:B2 along the columns dimension, the range A1:D5 will be: // 3 | 4 | | // 4 | 5 | | // 3 | 4 | 5 | 6 // 4 | 5 | 6 | 7 // 5 | 6 | 7 | 8 const fRange2 = fWorksheet.getRange('A1:B2'); fRange2.deleteCells(univerAPI.Enum.Dimension.COLUMNS); console.log(fWorksheet.getRange('A1:D5').getValues()); // [[3, 4, null, null], [4, 5, null, null], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]] // Set the range A1:D5 values again, the range A1:D5 will be: // 1 | 2 | 3 | 4 // 2 | 3 | 4 | 5 // 3 | 4 | 5 | 6 // 4 | 5 | 6 | 7 // 5 | 6 | 7 | 8 fRange.setValues(values); // Delete the range A1:B2 along the rows dimension, the range A1:D5 will be: // 3 | 4 | 3 | 4 // 4 | 5 | 4 | 5 // 5 | 6 | 5 | 6 // | | 6 | 7 // | | 7 | 8 const fRange3 = fWorksheet.getRange('A1:B2'); fRange3.deleteCells(univerAPI.Enum.Dimension.ROWS); console.log(fWorksheet.getRange('A1:D5').getValues()); // [[3, 4, 3, 4], [4, 5, 4, 5], [5, 6, 5, 6], [null, null, 6, 7], [null, null, 7, 8]] ``` Source: `@univerjs/sheets` ### `deleteNote` **Signature** ```typescript deleteNote(): FRange ``` **Returns** * `FRange` — See signature above. Source: `@univerjs/sheets-note` ### `isMerged` Return range whether this range is merged **Signature** ```typescript isMerged(): boolean ``` **Returns** * `boolean` — if true is merged **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.isMerged()); // merge cells A1:B2 fRange.merge(); console.log(fRange.isMerged()); ``` Source: `@univerjs/sheets` ### `isPartOfMerge` Returns true if cells in the current range overlap a merged cell. **Signature** ```typescript isPartOfMerge(): boolean ``` **Returns** * `boolean` — is overlap with a merged cell **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.merge(); const anchor = fWorksheet.getRange('A1'); console.log(anchor.isPartOfMerge()); // true ``` Source: `@univerjs/sheets` ### `merge` Merge cells in a range into one merged cell **Signature** ```typescript merge(options?: IMergeCellsUtilOptions): FRange ``` **Parameters** * `options` `IMergeCellsUtilOptions` *(optional)* — *No description* **Returns** * `FRange` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.merge(); console.log(fRange.isMerged()); ``` ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('B1:C2'); // Assume A1:B2 is already merged. fRange.merge({ isForceMerge: true }); ``` Source: `@univerjs/sheets` ### `mergeAcross` Merges cells in a range horizontally. **Signature** ```typescript mergeAcross(options?: IMergeCellsUtilOptions): FRange ``` **Parameters** * `options` `IMergeCellsUtilOptions` *(optional)* — *No description* **Returns** * `FRange` — This range, for chaining **Examples** ```ts // Assume the active sheet is a new sheet with no merged cells. const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.mergeAcross(); // There will be two merged cells. A1:B1 and A2:B2. const mergeData = fWorksheet.getMergeData(); mergeData.forEach((item) => { console.log(item.getA1Notation()); }); ``` ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('B1:C2'); // Assume A1:B2 is already merged. fRange.mergeAcross({ isForceMerge: true }); ``` Source: `@univerjs/sheets` ### `mergeVertically` Merges cells in a range vertically. **Signature** ```typescript mergeVertically(options?: IMergeCellsUtilOptions): FRange ``` **Parameters** * `options` `IMergeCellsUtilOptions` *(optional)* — *No description* **Returns** * `FRange` — This range, for chaining **Examples** ```ts // Assume the active sheet is a new sheet with no merged cells. const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.mergeVertically(); // There will be two merged cells. A1:A2 and B1:B2. const mergeData = fWorksheet.getMergeData(); mergeData.forEach((item) => { console.log(item.getA1Notation()); }); ``` ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('B1:C2'); // Assume A1:B2 is already merged. fRange.mergeVertically({ isForceMerge: true }); ``` Source: `@univerjs/sheets` ### Analysis ### Miscellaneous ### `activate` Sets the specified range as the active range, with the top left cell in the range as the current cell. **Signature** ```typescript activate(): FRange ``` **Returns** * `FRange` — This range, for chaining. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.activate(); // the active cell will be A1 ``` Source: `@univerjs/sheets` ### `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. **Signature** ```typescript activateAsCurrentCell(): FRange ``` **Returns** * `FRange` — This range, for chaining. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Set the range A1:B2 as the active range, default active cell is A1 const fRange = fWorksheet.getRange('A1:B2'); fRange.activate(); console.log(fWorksheet.getActiveRange().getA1Notation()); // A1:B2 console.log(fWorksheet.getActiveCell().getA1Notation()); // A1 // Set the cell B2 as the active cell // Because B2 is in the active range A1:B2, the active range will not change, and the active cell will be changed to B2 const cell = fWorksheet.getRange('B2'); cell.activateAsCurrentCell(); console.log(fWorksheet.getActiveRange().getA1Notation()); // A1:B2 console.log(fWorksheet.getActiveCell().getA1Notation()); // B2 // Set the cell C3 as the active cell // Because C3 is not in the active range A1:B2, a new active range C3:C3 will be created, and the active cell will be changed to C3 const cell2 = fWorksheet.getRange('C3'); cell2.activateAsCurrentCell(); console.log(fWorksheet.getActiveRange().getA1Notation()); // C3:C3 console.log(fWorksheet.getActiveCell().getA1Notation()); // C3 ``` Source: `@univerjs/sheets` ### `addCommentAsync` **Signature** ```typescript addCommentAsync(content: IDocumentBody | FTheadCommentBuilder): Promise ``` **Parameters** * `content` `IDocumentBody | FTheadCommentBuilder` — *No description* **Returns** * `Promise` — See signature above. Source: `@univerjs/sheets-thread-comment` ### `attachAlertPopup` **Signature** ```typescript attachAlertPopup(alert: Omit): IDisposable ``` **Parameters** * `alert` `Omit` — *No description* **Returns** * `IDisposable` — See signature above. Source: `@univerjs/sheets-ui` ### `attachPopup` **Signature** ```typescript attachPopup(popup: IFCanvasPopup): Nullable ``` **Parameters** * `popup` `IFCanvasPopup` — *No description* **Returns** * `any` — See signature above. Source: `@univerjs/sheets-ui` ### `attachRangePopup` attachDOMPopup **Signature** ```typescript attachRangePopup(popup: IFCanvasPopup): Nullable ``` **Parameters** * `popup` `IFCanvasPopup` — *No description* **Returns** * `any` — disposable let sheet = univerAPI.getActiveWorkbook().getActiveSheet(); let range = sheet.getRange(2, 2, 3, 3); univerAPI.getActiveWorkbook().setActiveRange(range); let disposable = range.attachDOMPopup(\{ componentKey: 'univer.sheet.single-dom-popup', extraProps: \{ alert: \{ type: 0, title: 'This is an Info', message: 'This is an info message' } }, }); Source: `@univerjs/sheets-ui` ### `autoFill` Fills the target range with data based on the data in the current range. **Signature** ```typescript autoFill(targetRange: FRange, applyType?: AUTO_FILL_APPLY_TYPE): Promise ``` **Parameters** * `targetRange` `FRange` — *No description* * `applyType` `AUTO_FILL_APPLY_TYPE` *(optional)* — *No description* **Returns** * `Promise` — A promise that resolves to true if the fill operation was successful, false otherwise. **Examples** ```ts // Auto-fill the range D1:D10 based on the data in the range C1:C2 const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:A4'); // Auto-fill without specifying applyType (default behavior) await fRange.autoFill(fWorksheet.getRange('A1:A20')) // Auto-fill with 'COPY' type await fRange.autoFill(fWorksheet.getRange('A1:A20'), 'COPY') // Auto-fill with 'SERIES' type await fRange.autoFill(fWorksheet.getRange('A1:A20'), 'SERIES') ``` ```ts // Operate on a specific worksheet const 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' type await fRange.autoFill(fWorksheet.getRange('A1:A20'), 'COPY') // Auto-fill with 'SERIES' type await fRange.autoFill(fWorksheet.getRange('A1:A20'), 'SERIES') ``` Source: `@univerjs/sheets` ### `createFilter` **Signature** ```typescript createFilter(): FFilter | null ``` **Returns** * `FFilter` — See signature above. Source: `@univerjs/sheets-filter` ### `createOrUpdateNote` **Signature** ```typescript createOrUpdateNote(note: ISheetNote): FRange ``` **Parameters** * `note` `ISheetNote` — *No description* **Returns** * `FRange` — See signature above. Source: `@univerjs/sheets-note` ### `forEach` Iterate cells in this range. Merged cells will be respected. **Signature** ```typescript forEach(callback: (row: number, col: number, cell: ICellData) => void): void ``` **Parameters** * `callback` `(row: number, col: number, cell: ICellData) => void` — *No description* Source: `@univerjs/sheets` ### `generateHTML` **Signature** ```typescript generateHTML(): string ``` **Returns** * `string` — See signature above. Source: `@univerjs/sheets-ui` ### `getA1Notation` Returns a string description of the range, in A1 notation. **Signature** ```typescript getA1Notation(withSheet?: boolean, startAbsoluteRefType?: AbsoluteRefType, endAbsoluteRefType?: AbsoluteRefType): string ``` **Parameters** * `withSheet` `boolean` *(optional)* — *No description* * `startAbsoluteRefType` `AbsoluteRefType` *(optional)* — *No description* * `endAbsoluteRefType` `AbsoluteRefType` *(optional)* — *No description* **Returns** * `string` — The A1 notation of the range. ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // By default, the A1 notation is returned without the sheet name and without absolute reference types. const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getA1Notation()); // A1:B2 // By setting withSheet to true, the sheet name is included in the A1 notation. fWorksheet.setName('Sheet1'); console.log(fRange.getA1Notation(true)); // Sheet1!A1:B2 // By setting startAbsoluteRefType, the absolute reference type for the start cell is included in the A1 notation. console.log(fRange.getA1Notation(false, univerAPI.Enum.AbsoluteRefType.ROW)); // A$1:B2 console.log(fRange.getA1Notation(false, univerAPI.Enum.AbsoluteRefType.COLUMN)); // $A1:B2 console.log(fRange.getA1Notation(false, univerAPI.Enum.AbsoluteRefType.ALL)); // $A$1:B2 // By setting endAbsoluteRefType, the absolute reference type for the end cell is included in the A1 notation. console.log(fRange.getA1Notation(false, null, univerAPI.Enum.AbsoluteRefType.ROW)); // A1:B$2 console.log(fRange.getA1Notation(false, null, univerAPI.Enum.AbsoluteRefType.COLUMN)); // A1:$B2 console.log(fRange.getA1Notation(false, null, univerAPI.Enum.AbsoluteRefType.ALL)); // A1:$B$2 // By setting all parameters example console.log(fRange.getA1Notation(true, univerAPI.Enum.AbsoluteRefType.ALL, univerAPI.Enum.AbsoluteRefType.ALL)); // Sheet1!$A$1:$B$2 ``` Source: `@univerjs/sheets` ### `getCell` **Signature** ```typescript getCell(): ICellWithCoord ``` **Returns** * `ICellWithCoord` — See signature above. Source: `@univerjs/sheets-ui` ### `getComment` **Signature** ```typescript getComment(): Nullable ``` **Returns** * `Nullable` — See signature above. Source: `@univerjs/sheets-thread-comment` ### `getComments` **Signature** ```typescript getComments(): FThreadComment[] ``` **Returns** * `FThreadComment[]` — See signature above. Source: `@univerjs/sheets-thread-comment` ### `getFilter` Get the filter for the current range's worksheet. **Signature** ```typescript getFilter(): FFilter | null ``` **Returns** * `FFilter` — The interface class to handle the filter. If the worksheet does not have a filter, this method would return `null`. Source: `@univerjs/sheets-filter` ### `getHorizontalAlignment` Returns the horizontal alignment of the text (left/center/right) of the top-left cell in the range. **Signature** ```typescript getHorizontalAlignment(): string ``` **Returns** * `string` — The horizontal alignment of the text in the cell. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getHorizontalAlignment()); ``` Source: `@univerjs/sheets` ### `getHorizontalAlignments` Returns the horizontal alignments of the cells in the range. **Signature** ```typescript getHorizontalAlignments(): string[][] ``` **Returns** * `string[][]` — A two-dimensional array of horizontal alignments of text associated with cells in the range. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getHorizontalAlignments()); ``` Source: `@univerjs/sheets` ### `getNote` **Signature** ```typescript getNote(): Nullable ``` **Returns** * `any` — See signature above. Source: `@univerjs/sheets-note` ### `getRange` Gets the area where the statement is applied **Signature** ```typescript getRange(): IRange ``` **Returns** * `IRange` — The area where the statement is applied **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); const range = fRange.getRange(); const { startRow, startColumn, endRow, endColumn } = range; console.log(range); ``` Source: `@univerjs/sheets` ### `getRangePermission` Get the RangePermission instance for managing range-level permissions. This is the new permission API that provides range-specific permission control. **Signature** ```typescript getRangePermission(): FRangePermission ``` **Returns** * `FRangePermission` — - The RangePermission instance. **Examples** ```ts const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const fRange = fWorksheet.getRange('A1:B10'); const permission = fRange.getRangePermission(); // Protect the range await permission.protect({ name: 'Protected Area', allowViewByOthers: false }); // Check if range is protected const isProtected = permission.isProtected(); // Check if current user can edit const canEdit = permission.canEdit(); // Unprotect the range await permission.unprotect(); // Subscribe to protection changes permission.protectionChange$.subscribe(change => { console.log('Protection changed:', change); }); ``` Source: `@univerjs/sheets` ### `getScreenshot` **Signature** ```typescript getScreenshot(options?: IRangeScreenshotOptions): string | false ``` **Parameters** * `options` `IRangeScreenshotOptions` *(optional)* — *No description* **Returns** * `string | false` — See signature above. Source: `@univerjs-pro/sheets-print` ### `getSheetId` Gets the ID of the worksheet **Signature** ```typescript getSheetId(): string ``` **Returns** * `string` — The ID of the worksheet **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getSheetId()); ``` Source: `@univerjs/sheets` ### `getSheetName` Gets the name of the worksheet **Signature** ```typescript getSheetName(): string ``` **Returns** * `string` — The name of the worksheet **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getSheetName()); ``` Source: `@univerjs/sheets` ### `getUnitId` Get the unit ID of the current workbook **Signature** ```typescript getUnitId(): string ``` **Returns** * `string` — The unit ID of the workbook **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getUnitId()); ``` Source: `@univerjs/sheets` ### `getUrl` Generate a hyperlink URL for the current range. The returned URL can be used to navigate to this range within the workbook. **Signature** ```typescript getUrl(): string ``` **Returns** * `string` — The generated URL string (e.g. `#gid=sheet1&range=A1:B2`). **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getUrl()); // #gid=...&range=A1:B2 ``` Source: `@univerjs/sheets-hyper-link` ### `cancelHyperLink` Cancel all hyperlinks in this range. If a hyperlink is provided, only cancel the specified hyperlink. **Signature** ```typescript cancelHyperLink(hyperlink?: ICellHyperLink): boolean ``` **Parameters** * `hyperlink` `ICellHyperLink` *(optional)* — The hyperlink to be cancelled. If not provided, all hyperlinks in this range will be cancelled. **Returns** * `boolean` — True if the hyperlink(s) is cancelled successfully, otherwise false. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Cancel the hyperlink in cell A1 const fRange = fWorksheet.getRange('A1'); fRange.cancelHyperLink(); // Cancel all hyperlinks in range A2:B4 const fRange2 = fWorksheet.getRange('A2:B4'); fRange2.cancelHyperLink(); // Cancel a specific hyperlink in range A1:T100 const fRange3 = fWorksheet.getRange('A1:T100'); const hyperlinks = fRange3.getHyperLinks(); if (hyperlinks.length > 1) { fRange3.cancelHyperLink(hyperlinks[1]); } ``` Source: `@univerjs/sheets-hyper-link` ### `getHyperLinks` Get all hyperlinks in this range. **Signature** ```typescript getHyperLinks(): ICellHyperLink[] ``` **Returns** * `ICellHyperLink[]` — An array of hyperlinks in this range. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); console.log(fWorksheet.getRange('A1:T100').getHyperLinks()); ``` Source: `@univerjs/sheets-hyper-link` ### `setHyperLink` Set a hyperlink for this range top left cell. The hyperlink can be a URL, a range link, or a sheet link. **Signature** ```typescript setHyperLink(url: string, label?: string): Promise ``` **Parameters** * `url` `string` — The hyperlink url, can be a URL, a range link, or a sheet link. * `label` `string` *(optional)* — The display text of the hyperlink. If not provided, the url will be used as the display text. **Returns** * `Promise` — A promise that resolves to true if the hyperlink is set successfully, otherwise false. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a hyperlink to Univer on cell A1 const fRange = fWorksheet.getRange('A1'); await fRange.setHyperLink('//', 'Univer'); // Create a hyperlink to active sheet range B2:D4 on cell A2 const 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 A3 const 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 A4 const fRange4 = fWorksheet.getRange('A4'); const definedNameHyperlinkUrl = fWorkbook.getUrlOfDefineName('MyDefinedName'); await fRange4.setHyperLink(definedNameHyperlinkUrl, 'Link to MyDefinedName'); ``` Source: `@univerjs/sheets-hyper-link` ### `updateHyperLink` Update the hyperlink of this range top left cell. **Signature** ```typescript updateHyperLink(url: string, label?: string): Promise ``` **Parameters** * `url` `string` — The new hyperlink url, can be a URL, a range link, or a sheet link. * `label` `string` *(optional)* — The new display text of the hyperlink. If not provided, the url will be used as the display text. **Returns** * `Promise` — A promise that resolves to true if the hyperlink is updated successfully, otherwise false. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a hyperlink to Univer on cell A1 const fRange = fWorksheet.getRange('A1'); await fRange.setHyperLink('//', 'Univer'); // Update hyperlink after 3 seconds await new Promise((resolve) => setTimeout(resolve, 3000)); const rangeUrl = fWorksheet.getRange('B2:D4').getUrl(); await fRange.updateHyperLink(rangeUrl, 'Link to B2:D4'); ``` Source: `@univerjs/sheets-hyper-link` ### `getValidatorStatus` **Signature** ```typescript async getValidatorStatus(): Promise ``` **Returns** * `Promise` — See signature above. Source: `@univerjs/sheets-data-validation` ### `getVerticalAlignment` Returns the vertical alignment (top/middle/bottom) of the top-left cell in the range. **Signature** ```typescript getVerticalAlignment(): string ``` **Returns** * `string` — The vertical alignment of the text in the cell. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getVerticalAlignment()); ``` Source: `@univerjs/sheets` ### `getVerticalAlignments` Returns the vertical alignments of the cells in the range. **Signature** ```typescript getVerticalAlignments(): string[][] ``` **Returns** * `string[][]` — A two-dimensional array of vertical alignments of text associated with cells in the range. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getVerticalAlignments()); ``` Source: `@univerjs/sheets` ### `getWrap` Gets whether text wrapping is enabled for top-left cell in the range. **Signature** ```typescript getWrap(): boolean ``` **Returns** * `boolean` — whether text wrapping is enabled for the cell. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getWrap()); ``` Source: `@univerjs/sheets` ### `getShrinkToFit` Gets whether the top-left cell shrinks its font size to fit the cell width. **Signature** ```typescript getShrinkToFit(): boolean ``` **Returns** * `boolean` — whether shrink-to-fit is enabled for the cell. **Examples** ```ts const fRange = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1') console.log(fRange.getShrinkToFit()) ``` Source: `@univerjs/sheets` ### `getWraps` Gets whether text wrapping is enabled for cells in the range. **Signature** ```typescript getWraps(): boolean[][] ``` **Returns** * `boolean[][]` — A two-dimensional array of whether text wrapping is enabled for each cell in the range. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getWraps()); ``` Source: `@univerjs/sheets` ### `getWrapStrategy` Returns the text wrapping strategy for the top left cell of the range. **Signature** ```typescript getWrapStrategy(): WrapStrategy ``` **Returns** * `WrapStrategy` — The text wrapping strategy **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getWrapStrategy()); ``` Source: `@univerjs/sheets` ### `highlight` **Signature** ```typescript highlight(style?: Nullable>, primary?: Nullable): IDisposable ``` **Parameters** * `style` `Nullable>` *(optional)* — *No description* * `primary` `Nullable` *(optional)* — *No description* **Returns** * `IDisposable` — See signature above. Source: `@univerjs/sheets-ui` ### `insertCellImageAsync` **Signature** ```typescript async insertCellImageAsync(file: File | string): Promise ``` **Parameters** * `file` `string | File` — *No description* **Returns** * `Promise` — See signature above. Source: `@univerjs/sheets-drawing-ui` ### `insertCells` Inserts empty cells into this range. Existing data in the sheet along the provided dimension is shifted away from the inserted range. **Signature** ```typescript insertCells(shiftDimension: Dimension): void ``` **Parameters** * `shiftDimension` `Dimension` — *No description* **Examples** ```ts // Assume the active sheet empty sheet. const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const values = [ [1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8], ]; // Set the range A1:D5 with some values, the range A1:D5 will be: // 1 | 2 | 3 | 4 // 2 | 3 | 4 | 5 // 3 | 4 | 5 | 6 // 4 | 5 | 6 | 7 // 5 | 6 | 7 | 8 const fRange = fWorksheet.getRange('A1:D5'); fRange.setValues(values); console.log(fWorksheet.getRange('A1:D5').getValues()); // [[1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]] // Insert the empty cells into the range A1:B2 along the columns dimension, the range A1:D5 will be: // | | 1 | 2 // | | 2 | 3 // 3 | 4 | 5 | 6 // 4 | 5 | 6 | 7 // 5 | 6 | 7 | 8 const fRange2 = fWorksheet.getRange('A1:B2'); fRange2.insertCells(univerAPI.Enum.Dimension.COLUMNS); console.log(fWorksheet.getRange('A1:D5').getValues()); // [[null, null, 1, 2], [null, null, 2, 3], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]] // Set the range A1:D5 values again, the range A1:D5 will be: // 1 | 2 | 3 | 4 // 2 | 3 | 4 | 5 // 3 | 4 | 5 | 6 // 4 | 5 | 6 | 7 // 5 | 6 | 7 | 8 fRange.setValues(values); // Insert the empty cells into the range A1:B2 along the rows dimension, the range A1:D5 will be: // | | 3 | 4 // | | 4 | 5 // 1 | 2 | 5 | 6 // 2 | 3 | 6 | 7 // 3 | 4 | 7 | 8 const fRange3 = fWorksheet.getRange('A1:B2'); fRange3.insertCells(univerAPI.Enum.Dimension.ROWS); console.log(fWorksheet.getRange('A1:D5').getValues()); // [[null, null, 3, 4], [null, null, 4, 5], [1, 2, 5, 6], [2, 3, 6, 7], [3, 4, 7, 8]] ``` Source: `@univerjs/sheets` ### `isBlank` Returns true if the range is totally blank. **Signature** ```typescript isBlank(): boolean ``` **Returns** * `boolean` — true if the range is blank; false otherwise. **Examples** ```ts // Assume the active sheet is a new sheet with no data. const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.isBlank()); // true // Set the range A1:B2 with some values fRange.setValueForCell(123); console.log(fRange.isBlank()); // false ``` Source: `@univerjs/sheets` ### `offset` Returns a new range that is relative to the current range, whose upper left point is offset from the current range by the given rows and columns, and with the given height and width in cells. **Signature** ```typescript offset(rowOffset: number, columnOffset: number, numRows?: number, numColumns?: number): FRange ``` **Parameters** * `rowOffset` `number` — *No description* * `columnOffset` `number` — *No description* * `numRows` `number` *(optional)* — *No description* * `numColumns` `number` *(optional)* — *No description* **Returns** * `FRange` — The new range. **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); console.log(fRange.getA1Notation()); // A1:B2 // Offset the range by 1 row and 1 column, and set the height of the new range to 3 and the width to 3 const newRange = fRange.offset(1, 1, 3, 3); console.log(newRange.getA1Notation()); // B2:D4 ``` Source: `@univerjs/sheets` ### `saveCellImagesAsync` **Signature** ```typescript async saveCellImagesAsync(options?: ISaveCellImagesOptions): Promise ``` **Parameters** * `options` `ISaveCellImagesOptions` *(optional)* — *No description* **Returns** * `Promise` — See signature above. Source: `@univerjs/sheets-drawing-ui` ### `setHorizontalAlignment` Set the horizontal (left to right) alignment for the given range (left/center/right). **Signature** ```typescript setHorizontalAlignment(alignment: FHorizontalAlignment): FRange ``` **Parameters** * `alignment` `FHorizontalAlignment` — *No description* **Returns** * `FRange` — this range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setHorizontalAlignment('left'); ``` Source: `@univerjs/sheets` ### `setTextRotation` Set rotation for text in current range. **Signature** ```typescript setTextRotation(rotation: number): FRange ``` **Parameters** * `rotation` `number` — *No description* **Returns** * `FRange` — This range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setTextRotation(45); ``` Source: `@univerjs/sheets` ### `setVerticalAlignment` Set the vertical (top to bottom) alignment for the given range (top/middle/bottom). **Signature** ```typescript setVerticalAlignment(alignment: FVerticalAlignment): FRange ``` **Parameters** * `alignment` `FVerticalAlignment` — *No description* **Returns** * `FRange` — this range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setVerticalAlignment('top'); ``` Source: `@univerjs/sheets` ### `setWrap` Set the cell wrap of the given range. Cells with wrap enabled (the default) resize to display their full content. Cells with wrap disabled display as much as possible in the cell without resizing or running to multiple lines. **Signature** ```typescript setWrap(isWrapEnabled: boolean): FRange ``` **Parameters** * `isWrapEnabled` `boolean` — *No description* **Returns** * `FRange` — this range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setWrap(true); console.log(fRange.getWrap()); ``` Source: `@univerjs/sheets` ### `setShrinkToFit` Sets whether cells shrink their font size to fit the cell width. **Signature** ```typescript setShrinkToFit(enabled: boolean): FRange ``` **Parameters** * `enabled` `boolean` — whether to shrink text to fit the cell width. **Returns** * `FRange` — this range, for chaining. **Examples** ```ts const fRange = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1:B2') fRange.setShrinkToFit(true) ``` Source: `@univerjs/sheets` ### `setWrapStrategy` Sets the text wrapping strategy for the cells in the range. **Signature** ```typescript setWrapStrategy(strategy: WrapStrategy): FRange ``` **Parameters** * `strategy` `WrapStrategy` — *No description* **Returns** * `FRange` — this range, for chaining **Examples** ```ts const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:B2'); fRange.setWrapStrategy(univerAPI.Enum.WrapStrategy.WRAP); console.log(fRange.getWrapStrategy()); ``` Source: `@univerjs/sheets` ### `showDropdown` **Signature** ```typescript showDropdown(param: IDropdownParam): IDisposable ``` **Parameters** * `param` `IDropdownParam` — *No description* **Returns** * `IDisposable` — See signature above. Source: `@univerjs/sheets-ui` ### `sort` **Signature** ```typescript sort(column: SortColumnSpec | SortColumnSpec[]): FRange ``` **Parameters** * `column` `SortColumnSpec | SortColumnSpec[]` — *No description* **Returns** * `FRange` — See signature above. Source: `@univerjs/sheets-sort`