# FRange

> Language fallback: requested `ko-KR`; content is `en-US`.

- Human documentation: [https://docs.univer.ai/ko-KR/reference/facade/range](https://docs.univer.ai/ko-KR/reference/facade/range)

- Agent Markdown: [https://docs.univer.ai/ko-KR/reference/facade/range.md](https://docs.univer.ai/ko-KR/reference/facade/range.md)

- Requested language: `ko-KR`

- Content language: `en-US`

- Documentation version: `1.0.4`

- Source: [facade/range.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/range.mdx)

---

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.

```ts
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()`](https://docs.univer.ai/ko-KR/reference/facade/thread-comment.md#getrange)
* [`FTextFinder.findAll()`](https://docs.univer.ai/ko-KR/reference/facade/text-finder.md#findall)
* [`FTextFinder.findNext()`](https://docs.univer.ai/ko-KR/reference/facade/text-finder.md#findnext)
* [`FTextFinder.findPrevious()`](https://docs.univer.ai/ko-KR/reference/facade/text-finder.md#findprevious)
* [`FTextFinder.getCurrentMatch()`](https://docs.univer.ai/ko-KR/reference/facade/text-finder.md#getcurrentmatch)
* [`FFilter.getRange()`](https://docs.univer.ai/ko-KR/reference/facade/filter.md#getrange)
* [`FDataValidation.getRanges()`](https://docs.univer.ai/ko-KR/reference/facade/data-validation.md#getranges)
* [`FWorkbook.getActiveRange()`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#getactiverange)

## Setup

Register [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) or a preset that includes it. In plugin mode, import `@univerjs/sheets/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/facade.md).

## `@univerjs/sheets`

### `FRange.activate`

Sets the specified range as the active range, with the top left cell in the range as the current cell.

```typescript
activate(): FRange
```

**Returns**

This range, for chaining.

**Examples**

```ts
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 A1
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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.

```typescript
activateAsCurrentCell(): FRange
```

**Returns**

This range, for chaining.

**Examples**

```ts
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 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
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.autoFill`

Fills the target range with data based on the data in the current range.

```typescript
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**

```ts
// Auto-fill the range D1:D10 based on the data in the range C1:C2
const 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' 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')
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`AUTO_FILL_APPLY_TYPE`](https://unpkg.com/@univerjs/sheets/lib/types/services/auto-fill/type.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.breakApart`

Break all horizontally- or vertically-merged cells contained within the range list into individual cells again.

```typescript
breakApart(): FRange
```

**Returns**

This range, for chaining

**Examples**

```ts
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()) // true
fRange.breakApart()
console.log(anchor.isPartOfMerge()) // false
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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.

```typescript
clear(options?: IFacadeClearOptions): FRange
```

**Parameters**

* `options` — Optional. Options for clearing the range. If not provided, the contents and formatting are cleared both.

**Returns**

This range, for chaining.

**Examples**

```ts
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:D10
fRange.clear()

// clear the content only of the range A1:D10
fRange.clear({ contentsOnly: true })
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`IFacadeClearOptions`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-worksheet.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.clearContent`

Clears content of the range, while preserving formatting information.

```typescript
clearContent(): FRange
```

**Returns**

This range, for chaining.

**Examples**

```ts
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:D10
fRange.clearContent()
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.clearFormat`

Clears formatting information of the range, while preserving contents.

```typescript
clearFormat(): FRange
```

**Returns**

This range, for chaining.

**Examples**

```ts
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:D10
fRange.clearFormat()
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.deleteCells`

Deletes this range of cells. Existing data in the sheet along the provided dimension is shifted towards the deleted range.

```typescript
deleteCells(shiftDimension: Dimension): void
```

**Parameters**

* `shiftDimension` — Required. The dimension along which to shift existing data.

**Examples**

```ts
// 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 | 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]]
```

**Types:** [`Dimension`](https://unpkg.com/@univerjs/core/lib/types/types/enum/dimension.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.forEach`

Iterate cells in this range. Merged cells will be respected.

```typescript
forEach(callback: (row: number, col: number, cell: ICellData) => void): void
```

**Parameters**

* `callback` — Required. the callback function to be called for each cell in the range

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/types/cell-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getA1Notation`

Returns a string description of the range, in A1 notation.

```typescript
getA1Notation(withSheet?: boolean, startAbsoluteRefType?: AbsoluteRefType, endAbsoluteRefType?: AbsoluteRefType): string
```

**Parameters**

* `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**

```ts
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: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
```

**Types:** [`AbsoluteRefType`](https://unpkg.com/@univerjs/core/lib/types/sheets/typedef.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getBackground`

Returns the background color of the top-left cell in the range.

```typescript
getBackground(): string
```

**Returns**

The color code of the background.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getBackgrounds`

Returns the background colors of the cells in the range.

```typescript
getBackgrounds(): string[][]
```

**Returns**

A two-dimensional array of color codes of the backgrounds.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getCellData`

Return first cell model data in this range

```typescript
getCellData(): ICellData | null
```

**Returns**

The cell model data

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/types/cell-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getCellDataGrid`

Returns the cell data for the cells in the range.

```typescript
getCellDataGrid(): Nullable<ICellData>[][]
```

**Returns**

A two-dimensional array of cell data.

**Examples**

```ts
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())
```

**Types:** [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`ICellData`](https://docs.univer.ai/ko-KR/reference/types/cell-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getCellDatas`

Alias for getCellDataGrid.

```typescript
getCellDatas(): Nullable<ICellData>[][]
```

**Returns**

A two-dimensional array of cell data.

**Examples**

```ts
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())
```

**Types:** [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`ICellData`](https://docs.univer.ai/ko-KR/reference/types/cell-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getCellStyle`

Return first cell style in this range.

```typescript
getCellStyle(type?: GetStyleType): 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**

The cell style

**Examples**

```ts
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`](https://unpkg.com/@univerjs/core/lib/types/docs/data-model/rich-text-builder.d.ts) · [`GetStyleType`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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.

```typescript
getCellStyleData(type?: GetStyleType): IStyleData | 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**

The cell style data

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/types/style-data.md) · [`GetStyleType`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getCellStyles`

Returns the cell styles for the cells in the range.

```typescript
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**

```ts
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`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`TextStyleValue`](https://unpkg.com/@univerjs/core/lib/types/docs/data-model/rich-text-builder.d.ts) · [`GetStyleType`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getColumn`

Gets the starting column index of the range. index starts at 0.

```typescript
getColumn(): number
```

**Returns**

The starting column index of the range.

**Examples**

```ts
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()) // 0
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getCustomMetaData`

Returns the custom meta data for the cell at the start of this range.

```typescript
getCustomMetaData(): CustomData | null
```

**Returns**

The custom meta data

**Examples**

```ts
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`](https://unpkg.com/@univerjs/core/lib/types/sheets/typedef.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getCustomMetaDatas`

Returns the custom meta data for the cells in the range.

```typescript
getCustomMetaDatas(): Nullable<CustomData>[][]
```

**Returns**

A two-dimensional array of custom metadata, with `null` for cells without metadata.

**Examples**

```ts
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`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`CustomData`](https://unpkg.com/@univerjs/core/lib/types/sheets/typedef.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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.

```typescript
getDataRegion(dimension?: Dimension): FRange
```

**Parameters**

* `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**

```ts
// 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: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
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`Dimension`](https://unpkg.com/@univerjs/core/lib/types/types/enum/dimension.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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.

```typescript
getDisplayValue(): string
```

**Returns**

The displayed value of the cell. Returns an empty string if the cell is empty.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getDisplayValues`

Returns a two-dimensional array of the range displayed values. Empty cells return an empty string.

```typescript
getDisplayValues(): string[][]
```

**Returns**

A two-dimensional array of values.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getFontFamily`

Get the font family of the cell.

```typescript
getFontFamily(type?: GetStyleType): string | 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**

The font family of the cell

**Examples**

```ts
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`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getFontSize`

Get the font size of the cell.

```typescript
getFontSize(type?: GetStyleType): number | 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**

The font size of the cell

**Examples**

```ts
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`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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.

```typescript
getFormula(): string
```

**Returns**

The formula for the cell.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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.

```typescript
getFormulas(): string[][]
```

**Returns**

A two-dimensional array of formulas in string format.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getHeight`

Returns the number of rows in this range.

```typescript
getHeight(): number
```

**Returns**

The row count, not a size in pixels.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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()`.

```typescript
getHorizontalAlignment(): string
```

**Returns**

The horizontal alignment of the text in the cell.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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()`.

```typescript
getHorizontalAlignments(): string[][]
```

**Returns**

A two-dimensional array of horizontal alignments of text associated with cells in the range.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getLastColumn`

Gets the ending column index of the range. index starts at 0.

```typescript
getLastColumn(): number
```

**Returns**

The ending column index of the range.

**Examples**

```ts
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()) // 1
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getLastRow`

Gets the ending row index of the range. index starts at 0.

```typescript
getLastRow(): number
```

**Returns**

The ending row index of the range.

**Examples**

```ts
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()) // 1
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getRange`

Gets the area where the statement is applied

```typescript
getRange(): IRange
```

**Returns**

The area where the statement is applied

**Examples**

```ts
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 } = range
console.log(range)
```

**Types:** [`IRange`](https://docs.univer.ai/ko-KR/reference/types/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getRangePermission`

Get the RangePermission instance for managing range-level permissions.
This is the new permission API that provides range-specific permission control.

```typescript
getRangePermission(): FRangePermission
```

**Returns**

* The RangePermission instance.

**Examples**

```ts
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 range
await permission.protect({ name: 'Protected Area', allowEdit: 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)
})
```

**Types:** [`FRangePermission`](https://docs.univer.ai/ko-KR/reference/facade/range-permission.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getRawValue`

Returns the raw value of the top-left cell in the range. Empty cells return `null`.

```typescript
getRawValue(): Nullable<CellValue>
```

**Returns**

The raw value of the cell. Returns `null` if the cell is empty.

**Examples**

```ts
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.2
```

**Types:** [`CellValue`](https://docs.univer.ai/ko-KR/reference/types/cell-value.md) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getRawValues`

Returns a two-dimensional array of the range raw values. Empty cells return `null`.

```typescript
getRawValues(): Array<Array<Nullable<CellValue>>>
```

**Returns**

The raw value of the cell. Returns `null` if the cell is empty.

**Examples**

```ts
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`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`CellValue`](https://docs.univer.ai/ko-KR/reference/types/cell-value.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getRow`

Gets the starting row index of the range. index starts at 0.

```typescript
getRow(): number
```

**Returns**

The starting row index of the range.

**Examples**

```ts
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()) // 0
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getSheetId`

Gets the ID of the worksheet

```typescript
getSheetId(): string
```

**Returns**

The ID of the worksheet

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getSheetName`

Gets the name of the worksheet

```typescript
getSheetName(): string
```

**Returns**

The name of the worksheet

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getShrinkToFit`

Gets whether the top-left cell shrinks its font size to fit the cell width.

```typescript
getShrinkToFit(): boolean
```

**Returns**

Whether shrink-to-fit is enabled for the top-left cell.

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getUnitId`

Get the unit ID of the current workbook

```typescript
getUnitId(): string
```

**Returns**

The unit ID of the workbook

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getUsedThemeStyle`

Gets the theme style applied to the range.

```typescript
getUsedThemeStyle(): string | undefined
```

**Returns**

The name of the theme style applied to the range or not exist.

**Examples**

```ts
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()) // undefined
fRange.useThemeStyle('default')
console.log(fRange.getUsedThemeStyle()) // 'default'
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getValue`

Return first cell value in this range

```typescript
getValue(): CellValue | null
getValue(includeRichText: true): Nullable<CellValue | RichTextValue>
```

**Parameters**

* `includeRichText` — Optional. Pass `true` to return a `RichTextValue` for rich-text content instead of plain text.

**Returns**

The cell value

**Examples**

```ts
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 123
fRange.setValueForCell(123)
console.log(fRange.getValue()) // 123
```

```ts
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 the first cell value to 123
const 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 World
```

**Types:** [`CellValue`](https://docs.univer.ai/ko-KR/reference/types/cell-value.md) · [`RichTextValue`](https://unpkg.com/@univerjs/core/lib/types/docs/data-model/rich-text-builder.d.ts) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getValueAndRichTextValues`

Returns the value and rich text value for the cells in the range.

```typescript
getValueAndRichTextValues(): Nullable<CellValue | RichTextValue>[][]
```

**Returns**

A two-dimensional array of value and rich text value

**Examples**

```ts
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`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`CellValue`](https://docs.univer.ai/ko-KR/reference/types/cell-value.md) · [`RichTextValue`](https://unpkg.com/@univerjs/core/lib/types/docs/data-model/rich-text-builder.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getValues`

Returns the cell values for the cells in the range.

```typescript
getValues(): Nullable<CellValue>[][]
getValues(includeRichText: true): (Nullable<RichTextValue | CellValue>)[][]
```

**Parameters**

* `includeRichText` — Optional. Pass `true` to return `RichTextValue` entries for rich-text content instead of plain text.

**Returns**

A two-dimensional array of cell values.

**Examples**

```ts
// Get plain values
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.getValues())
```

```ts
// Get values with rich text if available
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.getValues(true))
```

**Types:** [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`CellValue`](https://docs.univer.ai/ko-KR/reference/types/cell-value.md) · [`RichTextValue`](https://unpkg.com/@univerjs/core/lib/types/docs/data-model/rich-text-builder.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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()`.

```typescript
getVerticalAlignment(): string
```

**Returns**

The vertical alignment of the text in the cell.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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()`.

```typescript
getVerticalAlignments(): string[][]
```

**Returns**

A two-dimensional array of vertical alignments of text associated with cells in the range.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getWidth`

Returns the number of columns in this range.

```typescript
getWidth(): number
```

**Returns**

The column count, not a size in pixels.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getWrap`

Gets whether text wrapping is enabled for top-left cell in the range.

```typescript
getWrap(): boolean
```

**Returns**

whether text wrapping is enabled for the cell.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getWraps`

Gets whether text wrapping is enabled for cells in the range.

```typescript
getWraps(): boolean[][]
```

**Returns**

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.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const fRange = fWorksheet.getRange('A1:B2')
console.log(fRange.getWraps())
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.getWrapStrategy`

Returns the text wrapping strategy for the top left cell of the range.

```typescript
getWrapStrategy(): WrapStrategy
```

**Returns**

The text wrapping strategy

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/enums/wrap-strategy.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.insertCells`

Inserts empty cells into this range. Existing data in the sheet along the provided dimension is shifted away from the inserted range.

```typescript
insertCells(shiftDimension: Dimension): void
```

**Parameters**

* `shiftDimension` — Required. The dimension along which to shift existing data.

**Examples**

```ts
// 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 | 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]]
```

**Types:** [`Dimension`](https://unpkg.com/@univerjs/core/lib/types/types/enum/dimension.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.isBlank`

Returns true if the range is totally blank.

```typescript
isBlank(): boolean
```

**Returns**

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.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 values
fRange.setValueForCell(123)
console.log(fRange.isBlank()) // false
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.isMerged`

Checks whether this range exactly matches a merged cell range.

```typescript
isMerged(): boolean
```

**Returns**

`true` only for an exact merged range match. Use `isPartOfMerge()` to check overlap.

**Examples**

```ts
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:B2
fRange.merge()
console.log(fRange.isMerged())
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.isPartOfMerge`

Returns true if cells in the current range overlap a merged cell.

```typescript
isPartOfMerge(): boolean
```

**Returns**

is overlap with a merged cell

**Examples**

```ts
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()) // true
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.merge`

Merge cells in a range into one merged cell

```typescript
merge(options?: IMergeCellsUtilOptions): FRange
```

**Parameters**

* `options` — Optional. The options for merging cells.

**Returns**

This range, for chaining

**Examples**

```ts
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())
```

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`IMergeCellsUtilOptions`](https://unpkg.com/@univerjs/sheets/lib/types/commands/commands/add-worksheet-merge.command.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.mergeAcross`

Merges cells in a range horizontally.

```typescript
mergeAcross(options?: IMergeCellsUtilOptions): FRange
```

**Parameters**

* `options` — Optional. The options for merging cells.

**Returns**

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.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())
})
```

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`IMergeCellsUtilOptions`](https://unpkg.com/@univerjs/sheets/lib/types/commands/commands/add-worksheet-merge.command.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.mergeVertically`

Merges cells in a range vertically.

```typescript
mergeVertically(options?: IMergeCellsUtilOptions): FRange
```

**Parameters**

* `options` — Optional. The options for merging cells.

**Returns**

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.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())
})
```

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`IMergeCellsUtilOptions`](https://unpkg.com/@univerjs/sheets/lib/types/commands/commands/add-worksheet-merge.command.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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.

```typescript
offset(rowOffset: number, columnOffset: number): FRange
offset(rowOffset: number, columnOffset: number, numRows: number): FRange
```

**Parameters**

* `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**

```ts
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 column
const newRange = fRange.offset(1, 1)
console.log(newRange.getA1Notation()) // B2:C3
```

```ts
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 column, and set the height of the new range to 3
const newRange = fRange.offset(1, 1, 3)
console.log(newRange.getA1Notation()) // B2:C4
```

```ts
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 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
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.removeThemeStyle`

Remove the theme style for the range.

```typescript
removeThemeStyle(themeName: string): void
```

**Parameters**

* `themeName` — Required. The name of the theme style to remove.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setBackground`

Set background color for current range.

```typescript
setBackground(color: string): FRange
```

**Parameters**

* `color` — Required. The background color

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setBackgroundColor`

Set background color for current range.

```typescript
setBackgroundColor(color: string): FRange
```

**Parameters**

* `color` — Required. The background color

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setBorder`

Sets basic border properties for the current range.

```typescript
setBorder(type: BorderType, style: BorderStyleTypes, color?: string): FRange
```

**Parameters**

* `type` — Required. The type of border to apply
* `style` — Required. The border style
* `color` — Optional. Optional border color in CSS notation

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`BorderType`](https://unpkg.com/@univerjs/core/lib/types/types/enum/border-style-types.d.ts) · [`BorderStyleTypes`](https://docs.univer.ai/ko-KR/reference/enums/border-style-types.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setCustomMetaData`

Set custom meta data for first cell in current range.

```typescript
setCustomMetaData(data: CustomData): FRange
```

**Parameters**

* `data` — Required. The custom meta data

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`CustomData`](https://unpkg.com/@univerjs/core/lib/types/sheets/typedef.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setCustomMetaDatas`

Set custom meta data for current range.

```typescript
setCustomMetaDatas(datas: CustomData[][]): FRange
```

**Parameters**

* `datas` — Required. The custom meta data

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`CustomData`](https://unpkg.com/@univerjs/core/lib/types/sheets/typedef.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setFontColor`

Sets the font color in CSS notation (such as '#ffffff' or 'white').

```typescript
setFontColor(color: string | null): this
```

**Parameters**

* `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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setFontFamily`

Sets the font family, such as "Arial" or "Helvetica".

```typescript
setFontFamily(fontFamily: string | null): this
```

**Parameters**

* `fontFamily` — Required. The font family to set; a null value resets the font family.

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setFontLine`

Sets the font line style of the given range ('underline', 'line-through', or 'none').

```typescript
setFontLine(fontLine: FontLine | null): this
```

**Parameters**

* `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**

```ts
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`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setFontSize`

Sets the font size, with the size being the point size to use.

```typescript
setFontSize(size: number | null): this
```

**Parameters**

* `size` — Required. A font size in point size. A null value resets the font size.

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setFontStyle`

Sets the font style for the given range ('italic' or 'normal').

```typescript
setFontStyle(fontStyle: FontStyle | null): this
```

**Parameters**

* `fontStyle` — Required. The font style, either 'italic' or 'normal'; a null value resets the font style.

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setFontWeight`

Sets the font weight for the given range (normal/bold),

```typescript
setFontWeight(fontWeight: FontWeight | null): this
```

**Parameters**

* `fontWeight` — Required. The font weight, either 'normal' or 'bold'; a null value resets the font weight.

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setFormula`

Updates the formula for this range. The given formula must be in A1 notation.

```typescript
setFormula(formula: string): FRange
```

**Parameters**

* `formula` — Required. A string representing the formula to set for the cell.

**Returns**

This range instance for chaining.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setFormulas`

Sets a rectangular grid of formulas (must match dimensions of this range). The given formulas must be in A1 notation.

```typescript
setFormulas(formulas: string[][]): FRange
```

**Parameters**

* `formulas` — Required. A two-dimensional string array of formulas.

**Returns**

This range instance for chaining.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setHorizontalAlignment`

Sets the horizontal alignment for the range. Accepts `'left'`, `'center'`, or `'normal'`, following the [Google Apps Script parameter names](https://developers.google.com/apps-script/reference/spreadsheet/range#setHorizontalAlignment\(String\)). In Univer, `'normal'` means right alignment; `'right'` is not an accepted value.

```ts
fRange.setHorizontalAlignment('normal') // Align right
```

```typescript
setHorizontalAlignment(alignment: FHorizontalAlignment): FRange
```

**Parameters**

* `alignment` — Required. The horizontal alignment: `left`, `center`, or `normal` (right alignment).

**Returns**

this range, for chaining

**Examples**

```ts
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 right
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`FHorizontalAlignment`](https://unpkg.com/@univerjs/sheets/lib/types/facade/utils.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setRichTextValueForCell`

Set the rich text value for the cell at the start of this range.

```typescript
setRichTextValueForCell(value: RichTextValue | IDocumentData): FRange
```

**Parameters**

* `value` — Required. The rich text value

**Returns**

The range

**Examples**

```ts
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 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
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`RichTextValue`](https://unpkg.com/@univerjs/core/lib/types/docs/data-model/rich-text-builder.d.ts) · [`IDocumentData`](https://docs.univer.ai/ko-KR/reference/types/document-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setRichTextValues`

Set the rich text value for the cells in the range.

```typescript
setRichTextValues(values: (RichTextValue | IDocumentData)[][]): FRange
```

**Parameters**

* `values` — Required. A two-dimensional array of rich-text values or document data matching this range's dimensions.

**Returns**

The range

**Examples**

```ts
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 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],
  [richText, richText],
])
console.log(fRange.getValue(true).toPlainText()) // Hello World
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`RichTextValue`](https://unpkg.com/@univerjs/core/lib/types/docs/data-model/rich-text-builder.d.ts) · [`IDocumentData`](https://docs.univer.ai/ko-KR/reference/types/document-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setShrinkToFit`

Sets whether cells shrink their font size to fit the cell width.

```typescript
setShrinkToFit(enabled: boolean): FRange
```

**Parameters**

* `enabled` — Required. Whether to enable shrink-to-fit for this range.

**Returns**

This range, for chaining.

**Examples**

```ts
univerAPI.getActiveWorkbook()?.getActiveSheet().getRange('A1:B2').setShrinkToFit(true)
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setTextRotation`

Set rotation for text in current range.

```typescript
setTextRotation(rotation: number): FRange
```

**Parameters**

* `rotation` — Required. The rotation angle in degrees

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setValue`

Sets the value or specified cell properties for every cell in this range.

There are two input modes:

* `CellValue` (`number`, `string`, or `boolean`): 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 over `v` (value),
  `f` (formula), `p` (rich text), `t` (value type), and `s` (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 use `f: null` and `p: null` when replacing a formula or rich text
  with `v`. Use `v: null` to clear the stored value. Supplied style properties are merged into
  the existing style; `s: null` clears 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.

```typescript
setValue(value: CellValue | ICellData): FRange
```

**Parameters**

* `value` — Required. The scalar content or cell-data update to apply throughout the range.

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`CellValue`](https://docs.univer.ai/ko-KR/reference/types/cell-value.md) · [`ICellData`](https://docs.univer.ai/ko-KR/reference/types/cell-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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`.

```typescript
setValueForCell(value: CellValue | ICellData): FRange
```

**Parameters**

* `value` — Required. The scalar content or cell-data update to apply to the top-left cell only.

**Returns**

This range, for chaining

**Examples**

```ts
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)

// or
fRange.setValueForCell({ v: 234, s: { bg: { rgb: '#ff0000' } } })
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`CellValue`](https://docs.univer.ai/ko-KR/reference/types/cell-value.md) · [`ICellData`](https://docs.univer.ai/ko-KR/reference/types/cell-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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.

```typescript
setValues(value: CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>): FRange
```

**Parameters**

* `value` — Required. An array relative to this range, or a sparse matrix using absolute worksheet coordinates.

**Returns**

This range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`CellValue`](https://docs.univer.ai/ko-KR/reference/types/cell-value.md) · [`IObjectMatrixPrimitiveType`](https://unpkg.com/@univerjs/core/lib/types/shared/object-matrix.d.ts) · [`ICellData`](https://docs.univer.ai/ko-KR/reference/types/cell-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setVerticalAlignment`

Set the vertical (top to bottom) alignment for the given range (top/middle/bottom).

```typescript
setVerticalAlignment(alignment: FVerticalAlignment): FRange
```

**Parameters**

* `alignment` — Required. The vertical alignment

**Returns**

this range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`FVerticalAlignment`](https://unpkg.com/@univerjs/sheets/lib/types/facade/utils.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `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.

```typescript
setWrap(isWrapEnabled: boolean): FRange
```

**Parameters**

* `isWrapEnabled` — Required. Whether to enable wrap

**Returns**

this range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.setWrapStrategy`

Sets the text wrapping strategy for the cells in the range.

```typescript
setWrapStrategy(strategy: WrapStrategy): FRange
```

**Parameters**

* `strategy` — Required. The text wrapping strategy

**Returns**

this range, for chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`WrapStrategy`](https://docs.univer.ai/ko-KR/reference/enums/wrap-strategy.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.splitTextToColumns`

Splits a column of text into multiple columns based on an auto-detected delimiter.

```typescript
splitTextToColumns(treatMultipleDelimitersAsOne?: boolean): void
splitTextToColumns(treatMultipleDelimitersAsOne?: boolean, delimiter?: SplitDelimiterEnum): void
```

**Parameters**

* `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**

```ts
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 | 6
fRange.splitTextToColumns(true)

// After calling splitTextToColumns(false), the range will be:
//  A |   |   |
//  1 | 2 | 3 |
//  4 |   | 5 | 6
fRange.splitTextToColumns(false)
```

Show how to split text to columns with combined delimiter. The bit operations are used to combine the delimiters.

```ts
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 | 3
fRange.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 | 3
fRange.splitTextToColumns(
  true,
  univerAPI.Enum.SplitDelimiterType.Semicolon | univerAPI.Enum.SplitDelimiterType.Comma,
)
```

Show how to split text to columns with custom delimiter

```ts
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 | 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, '#')
```

**Types:** [`SplitDelimiterEnum`](https://unpkg.com/@univerjs/sheets/lib/types/basics/split-range-text.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

### `FRange.useThemeStyle`

Set the theme style for the range.

```typescript
useThemeStyle(themeName: string | undefined): void
```

**Parameters**

* `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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-range.d.ts)

## `@univerjs/sheets-conditional-formatting`

### `FRange.clearConditionalFormatRules`

Clear the conditional rules for the range.

```typescript
clearConditionalFormatRules(): FRange
```

**Returns**

Returns the current range instance for method chaining

**Examples**

```ts
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 range
fRange.clearConditionalFormatRules()
console.log(fRange.getConditionalFormattingRules()) // []
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets-conditional-formatting`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-conditional-formatting.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-conditional-formatting/lib/types/facade/f-range.d.ts)

### `FRange.createConditionalFormattingRule`

Creates a constructor for conditional formatting

```typescript
createConditionalFormattingRule(): FConditionalFormattingBuilder
```

**Returns**

The conditional formatting builder

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/conditional-formatting-builder.md)

**Package:** [`@univerjs/sheets-conditional-formatting`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-conditional-formatting.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-conditional-formatting/lib/types/facade/f-range.d.ts)

### `FRange.getConditionalFormattingRules`

Gets all the conditional formatting for the current range.

```typescript
getConditionalFormattingRules(): IConditionFormattingRule[]
```

**Returns**

conditional formatting rules for the current range.

**Examples**

```ts
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`](https://unpkg.com/@univerjs/sheets-conditional-formatting/lib/types/models/type.d.ts)

**Package:** [`@univerjs/sheets-conditional-formatting`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-conditional-formatting.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-conditional-formatting/lib/types/facade/f-range.d.ts)

## `@univerjs/sheets-data-validation`

### `FRange.getDataValidation`

Get first data validation rule in current range.

```typescript
getDataValidation(): Nullable<FDataValidation>
```

**Returns**

data validation rule

**Examples**

```ts
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:B10
const 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 10
fRange
  .getDataValidation()
  .setCriteria(univerAPI.Enum.DataValidationType.DECIMAL, [
    univerAPI.Enum.DataValidationOperator.BETWEEN,
    '1',
    '10',
  ])

// Print the new rule criteria values
console.log(fRange.getDataValidation().getCriteriaValues())
```

**Types:** [`FDataValidation`](https://docs.univer.ai/ko-KR/reference/facade/data-validation.md) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts)

**Package:** [`@univerjs/sheets-data-validation`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-data-validation.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-data-validation/lib/types/facade/f-range.d.ts)

### `FRange.getDataValidationErrorAsync`

Get data validation errors for a specific range in current worksheet.

```typescript
getDataValidationErrorAsync(): Promise<IDataValidationError[]>
```

**Returns**

A promise that resolves to an array of validation errors in the specified range.

**Examples**

```ts
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`](https://unpkg.com/@univerjs/sheets-data-validation/lib/types/facade/f-workbook.d.ts) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-data-validation`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-data-validation.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-data-validation/lib/types/facade/f-range.d.ts)

### `FRange.getDataValidations`

Get all data validation rules in current range.

```typescript
getDataValidations(): FDataValidation[]
```

**Returns**

all data validation rules

**Examples**

```ts
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:B10
const 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:D10
const 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:D10
const range = fWorksheet.getRange('A1:D10')
const rules = range.getDataValidations()
console.log(rules.length) // 2
```

**Types:** [`FDataValidation`](https://docs.univer.ai/ko-KR/reference/facade/data-validation.md)

**Package:** [`@univerjs/sheets-data-validation`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-data-validation.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-data-validation/lib/types/facade/f-range.d.ts)

### `FRange.getValidatorStatus`

Get data validation validator status for current range.

```typescript
getValidatorStatus(): Promise<DataValidationStatus[][]>
```

**Returns**

matrix of validator status

**Examples**

```ts
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:B10
const 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:B10
const rule = univerAPI.newDataValidation().requireNumberBetween(1, 10).build()
fRange.setDataValidation(rule)

// Get the validator status for the cell B2
const status = await fWorksheet.getRange('B2').getValidatorStatus()
console.log(status?.[0]?.[0]) // 'valid'

// Get the validator status for the cell B10
const status2 = await fWorksheet.getRange('B10').getValidatorStatus()
console.log(status2?.[0]?.[0]) // 'invalid'
```

**Types:** [`DataValidationStatus`](https://unpkg.com/@univerjs/core/lib/types/types/enum/data-validation-status.d.ts) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-data-validation`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-data-validation.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-data-validation/lib/types/facade/f-range.d.ts)

### `FRange.setDataValidation`

Set a data validation rule to current range. if rule is null, clear data validation rule.

```typescript
setDataValidation(rule: Nullable<FDataValidation>): FRange
```

**Parameters**

* `rule` — Required. data validation rule, built by `univerAPI.newDataValidation()`

**Returns**

current range

**Examples**

```ts
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:B10
const 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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`FDataValidation`](https://docs.univer.ai/ko-KR/reference/facade/data-validation.md)

**Package:** [`@univerjs/sheets-data-validation`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-data-validation.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-data-validation/lib/types/facade/f-range.d.ts)

## `@univerjs/sheets-drawing-ui`

### `FRange.insertCellImageAsync`

Inserts an image into the current cell.

```typescript
insertCellImageAsync(file: File | string): Promise<boolean>
```

**Parameters**

* `file` — Required. File or URL string

**Returns**

True if the image is inserted successfully, otherwise false

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')

// Insert an image into the cell A10
const fRange = fWorksheet.getRange('A10')
const result = await fRange.insertCellImageAsync(
  'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
)
console.log(result)
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`File`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.dom.d.ts)

**Package:** [`@univerjs/sheets-drawing-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-drawing-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing-ui/lib/types/facade/f-range.d.ts)

### `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.

```typescript
saveCellImagesAsync(options?: ISaveCellImagesOptions): Promise<boolean>
```

**Parameters**

* `options` — Optional. Options for saving images

**Returns**

True if images are saved successfully, otherwise false

**Examples**

```ts
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:D10
const fRange = fWorksheet.getRange('A1:D10')

// Save with default options (using cell address as file name)
await fRange.saveCellImagesAsync()

// Save with custom options
await fRange.saveCellImagesAsync({
  useCellAddress: true,
  useColumnIndex: 0, // Use values from column A for file names
})
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ISaveCellImagesOptions`](https://unpkg.com/@univerjs/sheets-drawing-ui/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets-drawing-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-drawing-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing-ui/lib/types/facade/f-range.d.ts)

## `@univerjs/sheets-filter`

### `FRange.createFilter`

Create a filter for the current range. If the worksheet already has a filter, this method would return `null`.

```typescript
createFilter(): FFilter | null
```

**Returns**

The FFilter instance to handle the filter.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/filter.md)

**Package:** [`@univerjs/sheets-filter`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-filter.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-filter/lib/types/facade/f-range.d.ts)

### `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`.

```typescript
getFilter(): FFilter | null
```

**Returns**

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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/filter.md)

**Package:** [`@univerjs/sheets-filter`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-filter.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-filter/lib/types/facade/f-range.d.ts)

## `@univerjs/sheets-formula`

### `FRange.getFormulaError`

Get formula errors in the current range

```typescript
getFormulaError(): ISheetFormulaError[]
```

**Returns**

Array of formula errors in the range

**Examples**

```ts
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`](https://unpkg.com/@univerjs/engine-formula/lib/types/basics/error-type.d.ts)

**Package:** [`@univerjs/sheets-formula`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-formula.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-formula/lib/types/facade/f-range.d.ts)

## `@univerjs/sheets-hyper-link`

### `FRange.cancelHyperLink`

Cancel all hyperlinks in this range. If a hyperlink is provided, only cancel the specified hyperlink.

```typescript
cancelHyperLink(hyperlink?: ICellHyperLink): boolean
```

**Parameters**

* `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**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')

// 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])
}
```

**Types:** [`ICellHyperLink`](https://unpkg.com/@univerjs/sheets-hyper-link/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets-hyper-link`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-hyper-link.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-hyper-link/lib/types/facade/f-range.d.ts)

### `FRange.getHyperLinks`

Gets the first hyperlink from each cell containing hyperlinks in this range.

```typescript
getHyperLinks(): ICellHyperLink[]
```

**Returns**

At most one hyperlink per cell, with absolute, zero-based worksheet coordinates.

**Examples**

```ts
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`](https://unpkg.com/@univerjs/sheets-hyper-link/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets-hyper-link`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-hyper-link.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-hyper-link/lib/types/facade/f-range.d.ts)

### `FRange.getUrl`

Create a hyperlink url to this range

```typescript
getUrl(): string
```

**Returns**

The hyperlink url of this range

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-hyper-link.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-hyper-link/lib/types/facade/f-range.d.ts)

### `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.

```typescript
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**

```ts
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 A1
const fRange = fWorksheet.getRange('A1')
await fRange.setHyperLink('https://univer.ai/', 'Univer')

// Create a hyperlink to Sheet1 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')
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-hyper-link`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-hyper-link.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-hyper-link/lib/types/facade/f-range.d.ts)

### `FRange.updateHyperLink`

Update the hyperlink of this range top left cell.

```typescript
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**

```ts
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 A1
const fRange = fWorksheet.getRange('A1')
await fRange.setHyperLink('https://univer.ai/', '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')
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-hyper-link`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-hyper-link.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-hyper-link/lib/types/facade/f-range.d.ts)

## `@univerjs/sheets-note`

### `FRange.createOrUpdateNote`

Create or update the annotation of the top-left cell in the range

```typescript
createOrUpdateNote(note: ICreateOrUpdateNoteOptions): FRange
```

**Parameters**

* `note` — Required. The annotation to create or update

**Returns**

This range for method chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`ICreateOrUpdateNoteOptions`](https://unpkg.com/@univerjs/sheets-note/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets-note`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-note.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-note/lib/types/facade/f-range.d.ts)

### `FRange.deleteNote`

Delete the annotation of the top-left cell in the range

```typescript
deleteNote(): FRange
```

**Returns**

This range for method chaining

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets-note`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-note.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-note/lib/types/facade/f-range.d.ts)

### `FRange.getNote`

Get the annotation of the top-left cell in the range

```typescript
getNote(): Nullable<ISheetNote>
```

**Returns**

The annotation of the top-left cell in the range

**Examples**

```ts
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`](https://unpkg.com/@univerjs/sheets-note/lib/types/models/sheets-note.model.d.ts) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts)

**Package:** [`@univerjs/sheets-note`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-note.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-note/lib/types/facade/f-range.d.ts)

## `@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.

```typescript
getNumberFormat(): string
```

**Returns**

The number format of the top-left cell of the range.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-numfmt.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-numfmt/lib/types/facade/f-range.d.ts)

### `FRange.getNumberFormats`

Returns the number formats for the cells in the range.

```typescript
getNumberFormats(): string[][]
```

**Returns**

A two-dimensional array of number formats.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-numfmt.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-numfmt/lib/types/facade/f-range.d.ts)

### `FRange.setNumberFormat`

Set the number format of the range.

```typescript
setNumberFormat(pattern: string): FRange
```

**Parameters**

* `pattern` — Required. The number format pattern.

**Returns**

The FRange instance for chaining.

**Examples**

```ts
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.57
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets-numfmt`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-numfmt.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-numfmt/lib/types/facade/f-range.d.ts)

### `FRange.setNumberFormats`

Sets a rectangular grid of number formats (must match dimensions of this range).

```typescript
setNumberFormats(patterns: string[][]): FRange
```

**Parameters**

* `patterns` — Required. A two-dimensional array of number formats.

**Returns**

The FRange instance for chaining.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets-numfmt`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-numfmt.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-numfmt/lib/types/facade/f-range.d.ts)

## `@univerjs/sheets-sort`

### `FRange.sort`

Sorts the cells in the given range, by column(s) and order specified.

```typescript
sort(column: SortColumnSpec | SortColumnSpec[]): FRange
```

**Parameters**

* `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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`SortColumnSpec`](https://unpkg.com/@univerjs/sheets-sort/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets-sort`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-sort.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-sort/lib/types/facade/f-range.d.ts)

## `@univerjs/sheets-thread-comment`

### `FRange.addCommentAsync`

Add a comment to the start cell in the current range.

```typescript
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**

```ts
await univerAPI
  .getActiveWorkbook()
  .getActiveSheet()
  .getRange('A1')
  .addCommentAsync('Verify this value.', { id: 'review-a1' })

// Create a new comment
const richText = univerAPI.newRichText().insertText('hello univer')
const commentBuilder = univerAPI.newTheadComment().setContent(richText)
console.log(commentBuilder.content.toPlainText())

// Add the comment to the cell A1
const 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`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ThreadComment.ThreadCommentContent`](https://unpkg.com/@univerjs/thread-comment/lib/types/services/thread-comment-api.service.d.ts) · [`FTheadCommentBuilder`](https://docs.univer.ai/ko-KR/reference/facade/thead-comment-builder.md) · [`ISheetCellCommentCreateOptions`](https://unpkg.com/@univerjs/sheets-thread-comment/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets-thread-comment`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-thread-comment/lib/types/facade/f-range.d.ts)

### `FRange.clearCommentAsync`

Clear the comment of the start cell in the current range.

```typescript
clearCommentAsync(): Promise<boolean>
```

**Returns**

Whether the comment is cleared successfully.

**Examples**

```ts
const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1')
const success = await range.clearCommentAsync()
console.log(success)
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-thread-comment`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-thread-comment/lib/types/facade/f-range.d.ts)

### `FRange.clearCommentsAsync`

Clear all of the comments in the current range.

```typescript
clearCommentsAsync(): Promise<boolean>
```

**Returns**

Whether the comments are cleared successfully.

**Examples**

```ts
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`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-thread-comment`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-thread-comment/lib/types/facade/f-range.d.ts)

### `FRange.getComment`

Get the comment of the start cell in the current range.

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/thread-comment.md) · [`UniverCore.Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts)

**Package:** [`@univerjs/sheets-thread-comment`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-thread-comment/lib/types/facade/f-range.d.ts)

### `FRange.getComments`

Get the comments in the current range.

```typescript
getComments(): FThreadComment[]
```

**Returns**

The comments in the current range.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/thread-comment.md)

**Package:** [`@univerjs/sheets-thread-comment`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-thread-comment/lib/types/facade/f-range.d.ts)

## `@univerjs/sheets-ui`

### `FRange.attachAlertPopup`

Attach an alert popup to the start cell of current range.

```typescript
attachAlertPopup(alert: Omit<ICellAlert, 'location'>): IDisposable
```

**Parameters**

* `alert` — Required. The alert to attach

**Returns**

The disposable object to detach the alert.

**Examples**

```ts
// Attach an alert popup to the start cell of range C3:E5
const 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 seconds
setTimeout(() => {
  disposable.dispose()
}, 5000)
```

**Types:** [`IDisposable`](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ICellAlert`](https://unpkg.com/@univerjs/sheets-ui/lib/types/services/cell-alert-manager.service.d.ts)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts)

### `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.

```typescript
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**

```ts
// Register a custom popup component
univerAPI.registerComponent('myPopup', () =>
  React.createElement(
    'div',
    {
      style: {
        color: 'red',
        fontSize: '14px',
      },
    },
    'Custom Popup',
  ),
)

// Attach the popup to the start cell of range C3:E5
const 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 seconds
setTimeout(() => {
  disposable.dispose()
}, 5000)
```

**Types:** [`IDisposable`](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`IFCanvasPopup`](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts)

### `FRange.attachRangePopup`

Attach a DOM popup to the current range.

```typescript
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**

```ts
// Register a custom popup component
univerAPI.registerComponent('myPopup', () =>
  React.createElement(
    'div',
    {
      style: {
        background: 'red',
        fontSize: '14px',
      },
    },
    'Custom Popup',
  ),
)

// Attach the popup to the range C3:E5
const 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'
})
```

```ts
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`](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`IFCanvasPopup`](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts)

### `FRange.generateHTML`

Generate HTML content for the range.

```typescript
generateHTML(): string
```

**Returns**

HTML content of the range.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts)

### `FRange.getCell`

Return this cell information, including whether it is merged and cell coordinates

```typescript
getCell(): ICellWithCoord
```

**Returns**

cell location and coordinate.

**Examples**

```ts
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`](https://unpkg.com/@univerjs/core/lib/types/sheets/typedef.d.ts) · [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts)

### `FRange.getCellRect`

Returns the coordinates of this cell,does not include units

```typescript
getCellRect(): DOMRect
```

**Returns**

coordinates of the cell， top, right, bottom, left

**Examples**

```ts
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())
```

**Types:** [`DOMRect`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.dom.d.ts) · [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts)

### `FRange.highlight`

Highlight the range with the specified style and primary cell.

```typescript
highlight(style?: Nullable<Partial<ISelectionStyle>>, primary?: Nullable<ISelectionCell>): IDisposable
```

**Parameters**

* `style` — Optional. style for highlight range.
* `primary` — Optional. primary cell for highlight range.

**Returns**

The disposable object to remove the highlight.

**Examples**

```ts
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 style
const fRange = fWorksheet.getRange('C3:E5')
fRange.highlight()

// Highlight the range C7:E9 with custom style and primary cell D8
const 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 seconds
setTimeout(() => {
  disposable.dispose()
}, 5000)
```

**Types:** [`IDisposable`](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ISelectionStyle`](https://unpkg.com/@univerjs/sheets/lib/types/basics/selection.d.ts) · [`ISelectionCell`](https://unpkg.com/@univerjs/core/lib/types/sheets/typedef.d.ts)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts)

### `FRange.showDropdown`

Show a dropdown at the current range.

```typescript
showDropdown(param: IDropdownParam): IDisposable
```

**Parameters**

* `param` — Required. The parameters for the dropdown.

**Returns**

The disposable object to hide the dropdown.

**Examples**

```ts
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`](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts) · [`IDropdownParam`](https://unpkg.com/@univerjs/sheets-ui/lib/types/services/cell-dropdown-manager.service.d.ts)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-range.d.ts)

## `@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.

```typescript
getScreenshot(options?: IRangeScreenshotOptions): string | false
```

**Parameters**

* `options` — Optional. Screenshot options.

**Returns**

* The base64 encoded image string, or false if the user does not have permission.

**Examples**

```ts
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 headers
console.log(fRange.getScreenshot())
// Screenshot with row and column headers
console.log(fRange.getScreenshot({ includeHeaders: true }))
```

**Types:** [`IRangeScreenshotOptions`](https://unpkg.com/@univerjs-pro/sheets-print/lib/types/facade/f-range.d.ts)

**Package:** [`@univerjs-pro/sheets-print`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/sheets-print.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-print/lib/types/facade/f-range.d.ts)