# FWorksheet

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

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

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

- Requested language: `ko-KR`

- Content language: `en-US`

- Documentation version: `1.0.4`

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

---

A Facade API object bounded to a worksheet. It provides a set of methods to interact with the worksheet.

Get this object from the initialized `univerAPI` instance. The example assumes a workbook is already open.

```ts
const sheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
if (!sheet) throw new Error('No active worksheet')
sheet.getRange('A1').setValue('Hello, Univer!')
```

## Access

Access through:

* [`FWorkbook.getActiveSheet()`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#getactivesheet)
* [`FWorkbook.getSheets()`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#getsheets)
* [`FWorkbook.create()`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#create)
* [`FWorkbook.getSheetBySheetId()`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#getsheetbysheetid)
* [`FWorkbook.getSheetByName()`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#getsheetbyname)
* [`FWorkbook.setActiveSheet()`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#setactivesheet)
* [`FWorkbook.insertSheet()`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#insertsheet)
* [`FWorkbook.duplicateSheet()`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#duplicatesheet)

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

### `FWorksheet.activate`

Activates this sheet. Does not alter the sheet itself, only the parent's notion of the active sheet.

```typescript
activate(): FWorksheet
```

**Returns**

Current sheet, for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheets = fWorkbook.getSheets()
// activate the last sheet
fWorkSheets[fWorkSheets.length - 1].activate()
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.appendRow`

Appends a row to the bottom of the current data region in the sheet. If the destination row is already within the worksheet capacity,
this method writes into that row without increasing `getMaxRows()`. If a cell's content begins with =, it's interpreted as a formula.

```typescript
appendRow(rowContents: CellValue[]): FWorksheet
```

**Parameters**

* `rowContents` — Required. An array of values for the new row.

**Returns**

Returns the current worksheet instance for method chaining.

**Examples**

```ts
// Appends a new row with 4 columns to the bottom of the current
// data region in the sheet containing the values in the array.
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
fWorkSheet.appendRow([1, 'Hello Univer', true, '=A1'])
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`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-worksheet.d.ts)

### `FWorksheet.autoFitRow`

Make certain row wrap and auto height.

```typescript
autoFitRow(rowPosition: number, auto?: BooleanNumber): FWorksheet
```

**Parameters**

* `rowPosition` — Required. The row position to change.
* `auto` — Optional. Default: `BooleanNumber.TRUE`. Whether to auto fit the row height.

**Returns**

This worksheet instance for chaining

**Examples**

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

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`BooleanNumber`](https://docs.univer.ai/ko-KR/reference/enums/boolean-number.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-worksheet.d.ts)

### `FWorksheet.cancelFreeze`

Cancels the frozen state of the current sheet.

```typescript
cancelFreeze(): FWorksheet
```

**Returns**

This worksheet instance for chaining

**Examples**

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

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.clear`

Clears the sheet 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): FWorksheet
```

**Parameters**

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

**Returns**

Returns the current worksheet instance for method chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// clear the sheet of content and formatting information
fWorkSheet.clear()
// clear the sheet of content only
fWorkSheet.clear({ contentsOnly: true })
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.clearContents`

Clears the sheet of contents, while preserving formatting information.

```typescript
clearContents(): FWorksheet
```

**Returns**

Returns the current worksheet instance for method chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// clear the sheet of content only
fWorkSheet.clearContents()
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.clearFormats`

Clears the sheet of formatting, while preserving contents.

```typescript
clearFormats(): FWorksheet
```

**Returns**

Returns the current worksheet instance for method chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// clear the sheet of formatting only
fWorkSheet.clearFormats()
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.deleteColumn`

Deletes the column at the given column position.

```typescript
deleteColumn(columnPosition: number): FWorksheet
```

**Parameters**

* `columnPosition` — Required. The position of the column, starting at 0 for the first column

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Delete column C
fWorksheet.deleteColumn(2)
// Delete column A
fWorksheet.deleteColumn(0)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.deleteColumns`

Deletes a number of columns starting at the given column position.

```typescript
deleteColumns(columnPosition: number, howMany: number): FWorksheet
```

**Parameters**

* `columnPosition` — Required. The position of the first column to delete, starting at 0 for the first column
* `howMany` — Required. The number of columns to delete

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Delete 3 columns at column index 2 (columns C, D, E)
fWorksheet.deleteColumns(2, 3)
// Delete 1 column at column index 0 (column A)
fWorksheet.deleteColumns(0, 1)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.deleteColumnsByPoints`

Deletes the columns specified by the given column points. Each point can be a single column index or a tuple representing a range of columns.

```typescript
deleteColumnsByPoints(columnPoints: Array<number | [number, number]>): FWorksheet
```

**Parameters**

* `columnPoints` — Required. An array of column points to delete. Each point can be a single column index or a tuple representing a range of columns.

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Delete columns at index 2, and range from index 4 to 6 (columns C, E-G)
fWorksheet.deleteColumnsByPoints([2, [4, 6]])
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`Array`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.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-worksheet.d.ts)

### `FWorksheet.deleteRow`

Deletes the row at the given row position.

```typescript
deleteRow(rowPosition: number): FWorksheet
```

**Parameters**

* `rowPosition` — Required. The position of the row, starting at 0 for the first row.

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Delete the third row
fWorksheet.deleteRow(2)
// Delete the first row
fWorksheet.deleteRow(0)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.deleteRows`

Deletes a number of rows starting at the given row position.

```typescript
deleteRows(rowPosition: number, howMany: number): FWorksheet
```

**Parameters**

* `rowPosition` — Required. The position of the first row to delete, starting at 0 for the first row.
* `howMany` — Required. The number of rows to delete.

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Delete 3 rows at row index 2 (rows 3-5)
fWorksheet.deleteRows(2, 3)
// Delete 1 row at row index 0 (first row)
fWorksheet.deleteRows(0, 1)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.deleteRowsByPoints`

Deletes the rows specified by the given row points. Each point can be a single row index or a tuple representing a range of rows.

```typescript
deleteRowsByPoints(rowPoints: Array<number | [number, number]>): FWorksheet
```

**Parameters**

* `rowPoints` — Required. An array of row points to delete. Each point can be a single row index or a tuple representing a range of rows.

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Delete rows at index 2, and range from index 4 to 6 (rows 3, 5-7)
fWorksheet.deleteRowsByPoints([2, [4, 6]])
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`Array`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.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-worksheet.d.ts)

### `FWorksheet.dispose`

Releases this facade's resources. Use `univerAPI.disposeUnit()` to unload the owning unit.

```typescript
dispose(): void
```

**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-worksheet.d.ts)

### `FWorksheet.equalTo`

Judge whether provided FWorksheet is equal to current.

```typescript
equalTo(other: FWorksheet): boolean
```

**Parameters**

* `other` — Required. the FWorksheet to compare with.

**Returns**

true if the FWorksheet is equal to the current FWorksheet, false otherwise.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const sheets = fWorkbook.getSheets()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
console.log(fWorkSheet.equalTo(sheets[0])) // true, if the active sheet is the first sheet.
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.getActiveCell`

Returns the active cell in this sheet.

```typescript
getActiveCell(): FRange | null
```

**Returns**

The active cell

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
console.log(fWorkSheet.getActiveCell().getA1Notation())
```

**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-worksheet.d.ts)

### `FWorksheet.getActiveRange`

Returns the selected range in the active sheet, or null if there is no active range.

```typescript
getActiveRange(): FRange | null
```

**Returns**

the active range

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Get the currently active range
const activeRange = fWorksheet.getActiveRange()
if (activeRange) {
  console.log('Active range:', activeRange.getA1Notation())
}
```

**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-worksheet.d.ts)

### `FWorksheet.getCellMergeData`

Get the merged cell data of the specified row and column.

```typescript
getCellMergeData(row: number, column: number): FRange | undefined
```

**Parameters**

* `row` — Required. The row index
* `column` — Required. The column index

**Returns**

The merged cell data, or undefined if the cell is not merged

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
const merge = fWorkSheet.getCellMergeData(0, 0)
if (merge) {
  console.log('Merged range:', merge.getA1Notation())
}
```

**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-worksheet.d.ts)

### `FWorksheet.getColumnCustomMetadata`

Get custom metadata of column

```typescript
getColumnCustomMetadata(index: number): CustomData | undefined
```

**Parameters**

* `index` — Required. column index

**Returns**

custom metadata

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
const custom = fWorkSheet.getColumnCustomMetadata(0)
console.log(custom)
```

**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-worksheet.d.ts)

### `FWorksheet.getColumnDefaultStyle`

Get the default style of the worksheet column

```typescript
getColumnDefaultStyle(index: number, keepRaw?: boolean): Nullable<IStyleData> | string
```

**Parameters**

* `index` — Required. The column index
* `keepRaw` — Optional. Default: `false`. If true, return the raw style data maybe the style name or style data, otherwise return the data from col manager

**Returns**

The default style of the worksheet column name or style data

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Get default style for column 0 (A)
const colStyle = fWorksheet.getColumnDefaultStyle(0)
console.log(colStyle)
// Get raw style data for column 0
const rawColStyle = fWorksheet.getColumnDefaultStyle(0, true)
console.log(rawColStyle)
```

**Types:** [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`IStyleData`](https://docs.univer.ai/ko-KR/reference/types/style-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-worksheet.d.ts)

### `FWorksheet.getColumnWidth`

Gets the width in pixels of the given column.

```typescript
getColumnWidth(columnPosition: number): number
```

**Parameters**

* `columnPosition` — Required. The position of the column to examine. index starts at 0.

**Returns**

The width of the column in pixels

**Examples**

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

// Set the long text value in cell A1
const fRange = fWorksheet.getRange('A1')
fRange.setValue('Whenever it is a damp, drizzly November in my soul...')

// Set the column A to a width which fits the text
fWorksheet.autoResizeColumns(0)

// Get the width of the column A
console.log(fWorksheet.getColumnWidth(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-worksheet.d.ts)

### `FWorksheet.getCustomMetadata`

Get custom metadata of worksheet

```typescript
getCustomMetadata(): CustomData | undefined
```

**Returns**

custom metadata

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
const custom = fWorkSheet.getCustomMetadata()
console.log(custom)
```

**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-worksheet.d.ts)

### `FWorksheet.getDataRange`

Returns a Range corresponding to the dimensions in which data is present.
Empty cells with style or formatting will also be included in the data range. If there is no data on the sheet, returns a Range corresponding to the top-left cell of the sheet (A1).

```typescript
getDataRange(): FRange
```

**Returns**

The range of the data in the sheet.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// Assume the sheet is a empty sheet
const cellRange = fWorkSheet.getRange('J50')
cellRange.setValue('Hello World')
console.log(fWorkSheet.getDataRange().getA1Notation()) // A1:J50
```

**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-worksheet.d.ts)

### `FWorksheet.getDefaultStyle`

Get the default style of the worksheet.

```typescript
getDefaultStyle(): Nullable<IStyleData> | string
```

**Returns**

The default style object or style ID, or a nullish value when no default style is set.

**Examples**

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

**Types:** [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`IStyleData`](https://docs.univer.ai/ko-KR/reference/types/style-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-worksheet.d.ts)

### `FWorksheet.getDefinedNames`

Get all the defined names in the worksheet.

```typescript
getDefinedNames(): FDefinedName[]
```

**Returns**

All the defined names in the worksheet

**Examples**

```ts
// The code below gets all the defined names in the worksheet
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const definedNames = fWorksheet.getDefinedNames()
console.log(definedNames, definedNames[0]?.getFormulaOrRefString())
```

**Types:** [`FDefinedName`](https://docs.univer.ai/ko-KR/reference/facade/defined-name.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-worksheet.d.ts)

### `FWorksheet.getFreeze`

Get the freeze state of the current sheet.

```typescript
getFreeze(): IFreeze
```

**Returns**

The freeze state of the current sheet

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Get the freeze state of the current sheet
const freeze = fWorksheet.getFreeze()
console.log(freeze)
```

**Types:** [`IFreeze`](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-worksheet.d.ts)

### `FWorksheet.getFrozenColumnRange`

Get freezed columns

```typescript
getFrozenColumnRange(): IColumnRange
```

**Returns**

The range of the frozen columns.

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// Get the range of the frozen columns
const frozenColumns = fWorkSheet.getFrozenColumnRange()
console.log(frozenColumns)
```

**Types:** [`IColumnRange`](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-worksheet.d.ts)

### `FWorksheet.getFrozenColumns`

Get the number of frozen columns.

```typescript
getFrozenColumns(): number
```

**Returns**

The number of frozen columns, returns 0 if no columns are frozen.

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// Get the number of frozen columns
const frozenColumns = fWorkSheet.getFrozenColumns()
console.log(frozenColumns)
```

**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-worksheet.d.ts)

### `FWorksheet.getFrozenRowRange`

Get freezed rows.

```typescript
getFrozenRowRange(): IRowRange
```

**Returns**

The range of the frozen rows.

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// Get the range of the frozen rows
const frozenRows = fWorkSheet.getFrozenRowRange()
console.log(frozenRows)
```

**Types:** [`IRowRange`](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-worksheet.d.ts)

### `FWorksheet.getFrozenRows`

Get the number of frozen rows.

```typescript
getFrozenRows(): number
```

**Returns**

The number of frozen rows. returns 0 if no rows are frozen.

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// Get the number of frozen rows
const frozenRows = fWorkSheet.getFrozenRows()
console.log(frozenRows)
```

**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-worksheet.d.ts)

### `FWorksheet.getGridLinesColor`

Get the color of the gridlines in the sheet.

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

**Returns**

The color of the gridlines in the sheet or undefined. The default color is 'rgb(214, 216, 219)'.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// get the gridlines color of the sheet
console.log(fWorkSheet.getGridLinesColor())
```

**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-worksheet.d.ts)

### `FWorksheet.getHiddenState`

Returns 0 (visible), 1 (hidden), or 2 (very hidden).

```typescript
getHiddenState(): WorksheetHiddenState
```

**Examples**

fWorksheet.getHiddenState() === univerAPI.Enum.WorksheetHiddenState.VERY_HIDDEN

**Types:** [`WorksheetHiddenState`](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-worksheet.d.ts)

### `FWorksheet.getIndex`

Gets the position of the sheet in its parent spreadsheet. Starts at 0.

```typescript
getIndex(): number
```

**Returns**

The position of the sheet in its parent spreadsheet.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// get the position of the active sheet
const position = fWorkSheet.getIndex()
console.log(position)
```

**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-worksheet.d.ts)

### `FWorksheet.getInject`

Get the injector instance.

```typescript
getInject(): Injector
```

**Returns**

The injector instance.

**Examples**

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

**Types:** [`Injector`](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-worksheet.d.ts)

### `FWorksheet.getLastColumn`

Returns the zero-based index of the last column with stored cell data, including formatting-only cells.

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

**Returns**

The last stored column index, or 0 for an empty sheet.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// Assume the sheet is a empty sheet
const cellRange = fWorkSheet.getRange('J50')
cellRange.setValue('Hello World')
console.log(fWorkSheet.getLastColumn()) // 9
```

**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-worksheet.d.ts)

### `FWorksheet.getLastRow`

Returns the zero-based index of the last row with stored cell data, including formatting-only cells.

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

**Returns**

The last stored row index, or 0 for an empty sheet.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// Assume the sheet is a empty sheet
const cellRange = fWorkSheet.getRange('J50')
cellRange.setValue('Hello World')
console.log(fWorkSheet.getLastRow()) // 49
```

**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-worksheet.d.ts)

### `FWorksheet.getMaxColumns`

Returns the current number of columns in the sheet, regardless of content.

```typescript
getMaxColumns(): number
```

**Returns**

The maximum columns count of the sheet

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const totalColumns = fWorksheet.getMaxColumns()
console.log(`Sheet has ${totalColumns} columns`)
```

**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-worksheet.d.ts)

### `FWorksheet.getMaxRows`

Returns the current number of rows in the sheet, regardless of content.

```typescript
getMaxRows(): number
```

**Returns**

The maximum rows count of the sheet

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const totalRows = fWorksheet.getMaxRows()
console.log(`Sheet has ${totalRows} rows`)
```

**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-worksheet.d.ts)

### `FWorksheet.getMergeData`

Get all merged cells in the current worksheet

```typescript
getMergeData(): FRange[]
```

**Returns**

All the merged cells in the worksheet

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Get all merged ranges in the sheet
const mergedData = fWorksheet.getMergeData()
// Process each merged range
mergedData.forEach((range) => {
  console.log(range.getA1Notation())
})
```

**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-worksheet.d.ts)

### `FWorksheet.getMergedRanges`

Get all merged cells in the current sheet

```typescript
getMergedRanges(): FRange[]
```

**Returns**

all merged cells

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Get all merged ranges in the sheet
const mergedRanges = fWorksheet.getMergedRanges()
// Process each merged range
mergedRanges.forEach((range) => {
  console.log(range.getA1Notation())
})
```

**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-worksheet.d.ts)

### `FWorksheet.getRange`

Returns a Range object representing a single cell at the specified row and column.

```typescript
getRange(row: number, column: number): FRange
getRange(row: number, column: number, numRows: number): FRange
getRange(row: number, column: number, numRows: number, numColumns: number): FRange
getRange(a1Notation: string): FRange
getRange(range: IRange): FRange
```

**Parameters**

* `row` — Optional. The row index of the cell.
* `column` — Optional. The column index of the cell.
* `numRows` — Optional. The number of rows in the range.
* `numColumns` — Optional. The number of columns in the range.
* `a1Notation` — Optional. A string representing a range in A1 notation.
* `range` — Optional. The range specification.

**Returns**

A Range object representing the specified cell.

A Range object representing the specified range.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Get range for cell at row 0, column 0 (A1)
const range = fWorksheet.getRange(0, 0)
console.log(range)
```

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Get range for cells A1:C3
const range = fWorksheet.getRange(0, 0, 3, 3)
console.log(range)
```

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Get range for cells A1:C3
const range = fWorksheet.getRange('A1:C3')
console.log(range)
// Get range for a single cell
const cell = fWorksheet.getRange('B2')
console.log(cell)
// Get range with sheet name
const sheetName = fWorksheet.getSheetName()
const rangeWithSheet = fWorksheet.getRange(`${sheetName}!A1:C3`)
console.log(rangeWithSheet)
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`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-worksheet.d.ts)

### `FWorksheet.getRowCustomMetadata`

Get custom metadata of row

```typescript
getRowCustomMetadata(index: number): CustomData | undefined
```

**Parameters**

* `index` — Required. row index

**Returns**

custom metadata

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
const custom = fWorkSheet.getRowCustomMetadata(0)
console.log(custom)
```

**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-worksheet.d.ts)

### `FWorksheet.getRowDefaultStyle`

Get the default style of the worksheet row

```typescript
getRowDefaultStyle(index: number, keepRaw?: boolean): Nullable<IStyleData> | string
```

**Parameters**

* `index` — Required. The row index
* `keepRaw` — Optional. Default: `false`. If true, return the raw style data maybe the style name or style data, otherwise return the data from row manager

**Returns**

The default style of the worksheet row name or style data

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Get default style for row 0 (1)
const rowStyle = fWorksheet.getRowDefaultStyle(0)
console.log(rowStyle)
// Get raw style data for row 0
const rawRowStyle = fWorksheet.getRowDefaultStyle(0, true)
console.log(rawRowStyle)
```

**Types:** [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`IStyleData`](https://docs.univer.ai/ko-KR/reference/types/style-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-worksheet.d.ts)

### `FWorksheet.getRowHeight`

Gets the height in pixels of the given row.

```typescript
getRowHeight(rowPosition: number): number
```

**Parameters**

* `rowPosition` — Required. The position of the row to examine. index starts at 0.

**Returns**

The height in pixels of the given row.

**Examples**

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

// Set the value of the cell A1 to 'Hello, Univer!', set the font size to 30 and font weight to bold
const fRange = fWorksheet.getRange('A1')
fRange.setValue('Hello, Univer!').setFontSize(30).setFontWeight('bold')

// Get the height of the first row
console.log(fWorksheet.getRowHeight(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-worksheet.d.ts)

### `FWorksheet.getSelection`

Get the current selection of the worksheet.

```typescript
getSelection(): FSelection | null
```

**Returns**

The current selections, or `null` when no selection data is available.

**Examples**

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

**Types:** [`FSelection`](https://docs.univer.ai/ko-KR/reference/facade/selection.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-worksheet.d.ts)

### `FWorksheet.getSheet`

Get the worksheet instance.

```typescript
getSheet(): Worksheet
```

**Returns**

The worksheet instance.

**Examples**

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

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

### `FWorksheet.getSheetId`

Get the worksheet id.

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

**Returns**

The id of the worksheet.

**Examples**

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

**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-worksheet.d.ts)

### `FWorksheet.getSheetName`

Get the worksheet name.

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

**Returns**

The name of the worksheet.

**Examples**

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

**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-worksheet.d.ts)

### `FWorksheet.getTabColor`

Get the tab color of the sheet.

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

**Returns**

The tab color, or `undefined` when no color is set.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// get the tab color of the sheet
console.log(fWorkSheet.getTabColor())
```

**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-worksheet.d.ts)

### `FWorksheet.getWorkbook`

Get the workbook instance.

```typescript
getWorkbook(): Workbook
```

**Returns**

The workbook instance.

**Examples**

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

**Types:** [`Workbook`](https://unpkg.com/@univerjs/core/lib/types/sheets/workbook.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-worksheet.d.ts)

### `FWorksheet.getWorksheetPermission`

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

```typescript
getWorksheetPermission(): FWorksheetPermission
```

**Returns**

* The WorksheetPermission instance.

**Examples**

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

// Set worksheet to read-only mode
await permission.setMode('readOnly')

// Check if a specific cell can be edited
const canEdit = permission.canEditCell(0, 0)

// Protect multiple ranges at once
const range1 = fWorksheet.getRange('A1:B10')
const range2 = fWorksheet.getRange('D1:E10')
await permission.protectRanges([
  { ranges: [range1], options: { name: 'Range 1', allowEdit: false } },
  { ranges: [range2], options: { name: 'Range 2', allowEdit: false } },
])

// Subscribe to permission changes
permission.permission$.subscribe((snapshot) => {
  console.log('Worksheet permissions changed:', snapshot)
})
```

**Types:** [`FWorksheetPermission`](https://docs.univer.ai/ko-KR/reference/facade/worksheet-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-worksheet.d.ts)

### `FWorksheet.hasHiddenGridLines`

Returns true if the sheet's gridlines are hidden; otherwise returns false. Gridlines are visible by default.

```typescript
hasHiddenGridLines(): boolean
```

**Returns**

True if the sheet's gridlines are hidden; otherwise false.

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// check if the gridlines are hidden
if (fWorkSheet.hasHiddenGridLines()) {
  console.log('Gridlines are hidden')
}
```

**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-worksheet.d.ts)

### `FWorksheet.hideColumn`

Hides the column or columns in the given range.

```typescript
hideColumn(column: FRange): FWorksheet
```

**Parameters**

* `column` — Required. The column range to hide

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Hide columns C, D, E
const column1 = fWorksheet.getRange('C:E')
fWorksheet.hideColumn(column1)
// Hide column A
const column2 = fWorksheet.getRange('A:A')
fWorksheet.hideColumn(column2)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`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-worksheet.d.ts)

### `FWorksheet.hideColumns`

Hides one or more consecutive columns starting at the given index. Use 0-index for this method

```typescript
hideColumns(columnIndex: number, numColumn?: number): FWorksheet
```

**Parameters**

* `columnIndex` — Required. The starting index of the columns to hide
* `numColumn` — Optional. Default: `1`. The number of columns to hide

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Hide columns C, D, E
fWorksheet.hideColumns(2, 3)
// Hide column A
fWorksheet.hideColumns(0, 1)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.hideRow`

Hides the rows in the given range.

```typescript
hideRow(row: FRange): FWorksheet
```

**Parameters**

* `row` — Required. The row range to hide.

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Hide 3 rows starting from row index 1 (rows 2-4)
const row1 = fWorksheet.getRange('2:4')
fWorksheet.hideRow(row1)
// Hide single row at index 0 (first row)
const row2 = fWorksheet.getRange('1:1')
fWorksheet.hideRow(row2)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`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-worksheet.d.ts)

### `FWorksheet.hideRows`

Hides one or more consecutive rows starting at the given index. Use 0-index for this method

```typescript
hideRows(rowIndex: number, numRow?: number): FWorksheet
```

**Parameters**

* `rowIndex` — Required. The starting index of the rows to hide
* `numRow` — Optional. Default: `1`. The number of rows to hide

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Hide 3 rows starting from row index 1 (rows 2-4)
fWorksheet.hideRows(1, 3)
// Hide single row at index 0 (first row)
fWorksheet.hideRows(0)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.hideSheet`

Hides this sheet. Has no effect if the sheet is already hidden. If this method is called on the only visible sheet, it throws an exception.

```typescript
hideSheet(): FWorksheet
```

**Returns**

Returns the current worksheet instance for method chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// hide the active sheet
fWorkSheet.hideSheet()
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.insertColumnAfter`

Inserts a column after the given column position.

```typescript
insertColumnAfter(afterPosition: number): FWorksheet
```

**Parameters**

* `afterPosition` — Required. The column after which the new column should be added, starting at 0 for the first column

**Returns**

This worksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Insert a column after column C
fWorksheet.insertColumnAfter(2)
// Insert a column after column A
fWorksheet.insertColumnAfter(0)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.insertColumnBefore`

Inserts a column before the given column position.

```typescript
insertColumnBefore(beforePosition: number): FWorksheet
```

**Parameters**

* `beforePosition` — Required. The column before which the new column should be added, starting at 0 for the first column

**Returns**

This worksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Insert a column before column C
fWorksheet.insertColumnBefore(2)
// Insert a column before column A
fWorksheet.insertColumnBefore(0)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.insertColumns`

Inserts one or more consecutive blank columns in a sheet starting at the specified location.

```typescript
insertColumns(columnIndex: number, numColumns?: number): FWorksheet
```

**Parameters**

* `columnIndex` — Required. The index indicating where to insert a column, starting at 0 for the first column
* `numColumns` — Optional. Default: `1`. The number of columns to insert

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Insert 3 columns before column C
fWorksheet.insertColumns(2, 3)
// Insert 1 column before column A
fWorksheet.insertColumns(0)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.insertColumnsAfter`

Inserts a given number of columns after the given column position.

```typescript
insertColumnsAfter(afterPosition: number, howMany: number): FWorksheet
```

**Parameters**

* `afterPosition` — Required. The column after which the new columns should be added, starting at 0 for the first column
* `howMany` — Required. The number of columns to insert

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Insert 3 columns after column C
fWorksheet.insertColumnsAfter(2, 3)
// Insert 1 column after column A
fWorksheet.insertColumnsAfter(0, 1)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.insertColumnsBefore`

Inserts a number of columns before the given column position.

```typescript
insertColumnsBefore(beforePosition: number, howMany: number): FWorksheet
```

**Parameters**

* `beforePosition` — Required. The column before which the new columns should be added, starting at 0 for the first column
* `howMany` — Required. The number of columns to insert

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Insert 3 columns before column C
fWorksheet.insertColumnsBefore(2, 3)
// Insert 1 column before column A
fWorksheet.insertColumnsBefore(0, 1)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.insertDefinedName`

Insert a defined name for worksheet.

```typescript
insertDefinedName(name: string, formulaOrRefString: string): void
```

**Parameters**

* `name` — Required. The name of the defined name to insert
* `formulaOrRefString` — Required. The formula(=sum(A2:b10)) or reference(A1) string of the defined name to insert

**Examples**

```ts
// The code below inserts a defined name
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
fWorksheet.insertDefinedName('MyDefinedName', 'Sheet1!$A$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-worksheet.d.ts)

### `FWorksheet.insertRowAfter`

Inserts a row after the given row position.

```typescript
insertRowAfter(afterPosition: number): FWorksheet
```

**Parameters**

* `afterPosition` — Required. The existing row after which the new row should be added. The index is zero-based and must be between 0 and `getMaxRows() - 1`.

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Insert a row after the third row
fWorksheet.insertRowAfter(2)
// Insert a row after the first row
fWorksheet.insertRowAfter(0)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.insertRowBefore`

Inserts a row before the given row position.

```typescript
insertRowBefore(beforePosition: number): FWorksheet
```

**Parameters**

* `beforePosition` — Required. The existing row before which the new row should be added. The index is zero-based and must be between 0 and `getMaxRows() - 1`.

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Insert a row before the third row
fWorksheet.insertRowBefore(2)
// Insert a row before the first row
fWorksheet.insertRowBefore(0)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.insertRows`

Inserts one or more consecutive blank rows in a sheet starting at the specified location.

```typescript
insertRows(rowIndex: number, numRows?: number): FWorksheet
```

**Parameters**

* `rowIndex` — Required. The existing row before which rows are inserted. The index is zero-based and must be between 0 and `getMaxRows() - 1`.
* `numRows` — Optional. Default: `1`. The positive number of rows to insert.

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Insert 3 rows before the third row
fWorksheet.insertRows(2, 3)
// Insert 1 row before the first row
fWorksheet.insertRows(0)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.insertRowsAfter`

Inserts a number of rows after the given row position.

```typescript
insertRowsAfter(afterPosition: number, howMany: number): FWorksheet
```

**Parameters**

* `afterPosition` — Required. The existing row after which the new rows should be added. The index is zero-based and must be between 0 and `getMaxRows() - 1`.
* `howMany` — Required. The positive number of rows to insert.

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Insert 3 rows after the third row
fWorksheet.insertRowsAfter(2, 3)
// Insert 1 row after the first row
fWorksheet.insertRowsAfter(0, 1)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.insertRowsBefore`

Inserts a number of rows before the given row position.

```typescript
insertRowsBefore(beforePosition: number, howMany: number): FWorksheet
```

**Parameters**

* `beforePosition` — Required. The existing row before which the new rows should be added. The index is zero-based and must be between 0 and `getMaxRows() - 1`.
* `howMany` — Required. The positive number of rows to insert.

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Insert 3 rows before the third row
fWorksheet.insertRowsBefore(2, 3)
// Insert 1 row before the first row
fWorksheet.insertRowsBefore(0, 1)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.isSheetHidden`

Returns true for both HIDDEN and VERY_HIDDEN sheets.

```typescript
isSheetHidden(): boolean
```

**Returns**

True if the sheet is hidden; otherwise, false.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheets = fWorkbook.getSheets()
// check if the last sheet is hidden
console.log(fWorkSheets[fWorkSheets.length - 1].isSheetHidden())
```

**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-worksheet.d.ts)

### `FWorksheet.moveColumns`

Moves the columns selected by the given range to the position indicated by the destinationIndex. The columnSpec itself does not have to exactly represent an entire column or group of columns to move—it selects all columns that the range spans.

```typescript
moveColumns(columnSpec: FRange, destinationIndex: number): FWorksheet
```

**Parameters**

* `columnSpec` — Required. A range spanning the columns that should be moved
* `destinationIndex` — Required. The index that the columns should be moved to. Note that this index is based on the coordinates before the columns are moved. Existing data is shifted right to make room for the moved columns while the source columns are removed from the grid. Therefore, the data may end up at a different index than originally specified. Use 0-index for this method

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Move columns C, D, E to column index 2 (columns B, C, D)
const columnSpec1 = fWorksheet.getRange('C:E')
fWorksheet.moveColumns(columnSpec1, 1)
// Move column F to column index 0 (column A)
const columnSpec2 = fWorksheet.getRange('F:F')
fWorksheet.moveColumns(columnSpec2, 0)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`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-worksheet.d.ts)

### `FWorksheet.moveRows`

Moves the rows selected by the given range to the position indicated by the destinationIndex. The rowSpec itself does not have to exactly represent an entire row or group of rows to move—it selects all rows that the range spans.

```typescript
moveRows(rowSpec: FRange, destinationIndex: number): FWorksheet
```

**Parameters**

* `rowSpec` — Required. A range spanning the rows that should be moved.
* `destinationIndex` — Required. The index that the rows should be moved to. Note that this index is based on the coordinates before the rows are moved. Existing data is shifted down to make room for the moved rows while the source rows are removed from the grid. Therefore, the data may end up at a different index than originally specified. Use 0-index for this method.

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Move 3 rows at row index 2 (rows 3-5) to row index 0
const rowSpec1 = fWorksheet.getRange('3:5')
fWorksheet.moveRows(rowSpec1, 0)
// Move 1 row at row index 0 (first row) to row index 2
const rowSpec2 = fWorksheet.getRange('1:1')
fWorksheet.moveRows(rowSpec2, 2)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`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-worksheet.d.ts)

### `FWorksheet.setActiveRange`

Sets the active selection region for this sheet.

```typescript
setActiveRange(range: FRange): FWorksheet
```

**Parameters**

* `range` — Required. The range to set as the active selection

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
fWorkSheet.setActiveRange(fWorkSheet.getRange('A10:B10'))
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`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-worksheet.d.ts)

### `FWorksheet.setActiveSelection`

Sets the active selection region for this sheet.

```ts
setActiveSelection: (range: FRange) => FWorksheet
```

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
fWorkSheet.setActiveSelection(fWorkSheet.getRange('A10:B10'))
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setColumnCount`

Sets the number of columns in the worksheet.

```typescript
setColumnCount(columnCount: number): FWorksheet
```

**Parameters**

* `columnCount` — Required. The number of columns to set.

**Returns**

Returns the current worksheet instance for method chaining.

**Examples**

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

// Set the number of columns in the worksheet to 10
fWorkSheet.setColumnCount(10)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setColumnCustom`

Set custom properties for given columns.

```typescript
setColumnCustom(custom: IObjectArrayPrimitiveType<CustomData>): FWorksheet
```

**Parameters**

* `custom` — Required. The custom properties to set

**Returns**

This worksheet instance for chaining

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
fWorkSheet.setColumnCustom({ 0: { key: 'value' } })
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`IObjectArrayPrimitiveType`](https://unpkg.com/@univerjs/core/lib/types/shared/object-matrix.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-worksheet.d.ts)

### `FWorksheet.setColumnCustomMetadata`

Set custom metadata of column

```typescript
setColumnCustomMetadata(index: number, custom: CustomData | undefined): FWorksheet
```

**Parameters**

* `index` — Required. column index
* `custom` — Required. custom metadata

**Returns**

Current worksheet, for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
fWorkSheet.setColumnCustomMetadata(0, { key: 'value' })
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setColumnDefaultStyle`

Set the default style of the worksheet column

```typescript
setColumnDefaultStyle(index: number, style: string | Nullable<IStyleData>): FWorksheet
```

**Parameters**

* `index` — Required. The zero-based column index
* `style` — Required. The style name or style data

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
fWorksheet.setColumnDefaultStyle(0, 'default')
// or
// fWorksheet.setColumnDefaultStyle(0, {fs: 12, ff: 'Arial'});
```

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

### `FWorksheet.setColumnWidth`

Sets the width of the given column in pixels.

```typescript
setColumnWidth(columnPosition: number, width: number): FWorksheet
```

**Parameters**

* `columnPosition` — Required. The position of the given column to set
* `width` — Required. The width in pixels to set it to

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Set width of column B to 100 pixels
fWorksheet.setColumnWidth(1, 100)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setColumnWidths`

Sets the width of the given columns in pixels.

```typescript
setColumnWidths(startColumn: number, numColumn: number, width: number): FWorksheet
```

**Parameters**

* `startColumn` — Required. The starting column position to change
* `numColumn` — Required. The number of columns to change
* `width` — Required. The width in pixels to set it to

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Set width of columns B-D (index 1-3) to 100 pixels
fWorksheet.setColumnWidths(1, 3, 100)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setCustomMetadata`

Set custom metadata of worksheet

```typescript
setCustomMetadata(custom: CustomData | undefined): FWorksheet
```

**Parameters**

* `custom` — Required. custom metadata

**Returns**

Current worksheet, for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
fWorkSheet.setCustomMetadata({ key: 'value' })
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setDefaultStyle`

Set the default style of the worksheet

```typescript
setDefaultStyle(style: string | Nullable<IStyleData>): FWorksheet
```

**Parameters**

* `style` — Required. A style ID or style object, or `null` to clear the default style.

**Returns**

This worksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
fWorksheet.setDefaultStyle('default')
// or
// fWorksheet.setDefaultStyle({fs: 12, ff: 'Arial'});
```

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

### `FWorksheet.setFreeze`

Sets the frozen state of the current sheet.

```typescript
setFreeze(freeze: IFreeze): FWorksheet
```

**Parameters**

* `freeze` — Required. the scrolling viewport start range and count of freezed rows and columns.
  that means if you want to freeze the first 3 rows and 2 columns, you should set freeze as \{ startRow: 3, startColumn: 2, xSplit: 2, ySplit: 3 }

**Returns**

This worksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Freeze first 3 rows and 2 columns
fWorksheet.setFreeze({
  startRow: 3,
  startColumn: 2,
  xSplit: 2,
  ySplit: 3,
})
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`IFreeze`](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-worksheet.d.ts)

### `FWorksheet.setFrozenColumns`

Set the number of frozen columns.

```typescript
setFrozenColumns(columns: number): FWorksheet
setFrozenColumns(startColumn: number, endColumn: number): FWorksheet
```

**Parameters**

* `columns` — Optional. The number of columns to freeze.
  To unfreeze all columns, set this value to 0.
* `startColumn` — Optional. The start column of the range to freeze
* `endColumn` — Optional. The end column of the range to freeze

**Returns**

This FWorksheet instance.

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// freeze the first 3 columns.
fWorkSheet.setFrozenColumns(3)
```

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// freeze the column B and C, and column A will be invisible.
fWorkSheet.setFrozenColumns(1, 2)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setFrozenRows`

Set the number of frozen rows.

```typescript
setFrozenRows(rows: number): FWorksheet
setFrozenRows(startRow: number, endRow: number): FWorksheet
```

**Parameters**

* `rows` — Optional. The number of rows to freeze.
  To unfreeze all rows, set this value to 0.
* `startRow` — Optional. The start row of the range to freeze
* `endRow` — Optional. The end row of the range to freeze

**Returns**

This FWorksheet instance.

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// freeze the first 3 rows.
fWorkSheet.setFrozenRows(3)
```

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// freeze the second and third rows, and the first row will be invisible.
fWorkSheet.setFrozenRows(1, 2)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setGridLinesColor`

Set the color of the gridlines in the sheet.

```typescript
setGridLinesColor(color: string | undefined): FWorksheet
```

**Parameters**

* `color` — Required. The color to set for the gridlines.Undefined or null to reset to the default color.

**Returns**

Returns the current worksheet instance for method chaining

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// set the gridlines color to red
fWorkSheet.setGridLinesColor('#ff0000')
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setHiddenGridlines`

Hides or reveals the sheet gridlines.

```typescript
setHiddenGridlines(hidden: boolean): FWorksheet
```

**Parameters**

* `hidden` — Required. If `true`, hide gridlines in this sheet; otherwise show the gridlines.

**Returns**

Returns the current worksheet instance for method chaining

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// hide the gridlines
fWorkSheet.setHiddenGridlines(true)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setHiddenState`

Changes the persisted hiding state through an undoable command.
VERY_HIDDEN removes the sheet from Unhide UI; showSheet() can reveal it through the API.
The last visible sheet cannot be hidden. Existing isSheetHidden() stays a boolean predicate.

```typescript
setHiddenState(hidden: WorksheetHiddenState): FWorksheet
```

**Parameters**

* `hidden` — Required.

**Examples**

fWorksheet.setHiddenState(univerAPI.Enum.WorksheetHiddenState.VERY_HIDDEN)

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`WorksheetHiddenState`](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-worksheet.d.ts)

### `FWorksheet.setName`

Sets the sheet name.

```typescript
setName(name: string): FWorksheet
```

**Parameters**

* `name` — Required. The new name for the sheet.

**Returns**

Returns the current worksheet instance for method chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// set the sheet name to 'Sheet1'
fWorkSheet.setName('NewSheet1')
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setRangesAutoHeight`

Sets the height of the given ranges to auto.

```typescript
setRangesAutoHeight(ranges: IRange[]): FWorksheet
```

**Parameters**

* `ranges` — Required. The ranges to change

**Returns**

This worksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const ranges = [
  { startRow: 1, endRow: 10, startColumn: 0, endColumn: 10 },
  { startRow: 11, endRow: 20, startColumn: 0, endColumn: 10 },
]
fWorksheet.setRangesAutoHeight(ranges)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`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-worksheet.d.ts)

### `FWorksheet.setRowAutoHeight`

Sets the height of the given rows to auto.

```typescript
setRowAutoHeight(startRow: number, numRows: number): FWorksheet
```

**Parameters**

* `startRow` — Required. The starting row position to change
* `numRows` — Required. The number of rows to change

**Returns**

This worksheet instance for chaining

**Examples**

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

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setRowCount`

Sets the number of rows in the worksheet.

```typescript
setRowCount(rowCount: number): FWorksheet
```

**Parameters**

* `rowCount` — Required. The number of rows to set.

**Returns**

Returns the current worksheet instance for method chaining.

**Examples**

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

// Set the number of rows in the worksheet to 40
fWorkSheet.setRowCount(40)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setRowCustom`

Set custom properties for given rows.

```typescript
setRowCustom(custom: IObjectArrayPrimitiveType<CustomData>): FWorksheet
```

**Parameters**

* `custom` — Required. The custom properties to set

**Returns**

This worksheet instance for chaining

**Examples**

```ts
const fWorkSheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
fWorkSheet.setRowCustom({ 0: { key: 'value' } })
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`IObjectArrayPrimitiveType`](https://unpkg.com/@univerjs/core/lib/types/shared/object-matrix.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-worksheet.d.ts)

### `FWorksheet.setRowCustomMetadata`

Set custom metadata of row

```typescript
setRowCustomMetadata(index: number, custom: CustomData | undefined): FWorksheet
```

**Parameters**

* `index` — Required. row index
* `custom` — Required. custom metadata

**Returns**

Current worksheet, for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
fWorkSheet.setRowCustomMetadata(0, { key: 'value' })
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setRowDefaultStyle`

Set the default style of the worksheet row

```typescript
setRowDefaultStyle(index: number, style: string | Nullable<IStyleData>): FWorksheet
```

**Parameters**

* `index` — Required. The zero-based row index
* `style` — Required. The style name or style data

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
fWorksheet.setRowDefaultStyle(0, 'default')
// or
// fWorksheet.setRowDefaultStyle(0, {fs: 12, ff: 'Arial'});
```

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

### `FWorksheet.setRowHeight`

Sets the row height of the given row in pixels. By default, rows grow to fit cell contents. If you want to force rows to a specified height, use setRowHeightsForced(startRow, numRows, height).

```typescript
setRowHeight(rowPosition: number, height: number): FWorksheet
```

**Parameters**

* `rowPosition` — Required. The row position to change.
* `height` — Required. The height in pixels to set it to.

**Returns**

This worksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Set the height of the second row to 30 pixels
fWorksheet.setRowHeight(1, 30)
// Set the height of the first row to 20 pixels
fWorksheet.setRowHeight(0, 20)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setRowHeights`

Sets the height of the given rows in pixels.
By default, rows grow to fit cell contents. If you want to force rows to a specified height, use setRowHeightsForced(startRow, numRows, height).

```typescript
setRowHeights(startRow: number, numRows: number, height: number): FWorksheet
```

**Parameters**

* `startRow` — Required. The starting row position to change
* `numRows` — Required. The number of rows to change
* `height` — Required. The height in pixels to set it to

**Returns**

This worksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
fWorksheet.setRowHeights(1, 10, 30)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setRowHeightsForced`

Sets the height of the given rows in pixels. By default, rows grow to fit cell contents. When you use setRowHeightsForced, rows are forced to the specified height even if the cell contents are taller than the row height.

```typescript
setRowHeightsForced(startRow: number, numRows: number, height: number): FWorksheet
```

**Parameters**

* `startRow` — Required. The starting row position to change
* `numRows` — Required. The number of rows to change
* `height` — Required. The height in pixels to set it to

**Returns**

This worksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
fWorksheet.setRowHeightsForced(1, 10, 30)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setTabColor`

Sets the sheet tab color.

```typescript
setTabColor(color: string): FWorksheet
```

**Parameters**

* `color` — Required. A color in CSS notation, such as '#ffffff' or 'white'.

**Returns**

Returns the current worksheet instance for method chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorkSheet) throw new Error('fWorkSheet is not available')
// set the tab color to red
fWorkSheet.setTabColor('#ff0000')
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.showColumns`

Show one or more consecutive columns starting at the given index. Use 0-index for this method

```typescript
showColumns(columnIndex: number, numColumns?: number): FWorksheet
```

**Parameters**

* `columnIndex` — Required. The starting index of the columns to unhide
* `numColumns` — Optional. Default: `1`. The number of columns to unhide

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Unhide columns C, D, E
fWorksheet.showColumns(2, 3)
// Unhide column A
fWorksheet.showColumns(0, 1)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.showRows`

Unhides one or more consecutive rows starting at the given zero-based index.

```typescript
showRows(rowIndex: number, numRows?: number): FWorksheet
```

**Parameters**

* `rowIndex` — Required. The starting index of the rows
* `numRows` — Optional. Default: `1`. The number of rows

**Returns**

This worksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Show 3 rows starting from row index 1 (rows 2-4)
fWorksheet.showRows(1, 3)
// Show single row at index 0 (first row)
fWorksheet.showRows(0)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.showSheet`

Shows this sheet. Has no effect if the sheet is already visible.

```typescript
showSheet(): FWorksheet
```

**Returns**

Returns the current worksheet instance for method chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheets = fWorkbook.getSheets()
// show the last sheet
fWorkSheets[fWorkSheets.length - 1].showSheet()
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.unhideColumn`

Show the column in the given range.

```typescript
unhideColumn(column: FRange): FWorksheet
```

**Parameters**

* `column` — Required. The range to unhide, if hidden

**Returns**

This sheet, for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Unhide columns C, D, E
const column1 = fWorksheet.getRange('C:E')
fWorksheet.unhideColumn(column1)
// Unhide column A
const column2 = fWorksheet.getRange('A:A')
fWorksheet.unhideColumn(column2)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`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-worksheet.d.ts)

### `FWorksheet.unhideRow`

Make the row in the given range visible.

```typescript
unhideRow(row: FRange): FWorksheet
```

**Parameters**

* `row` — Required. The range to unhide, if hidden.

**Returns**

This sheet, for chaining.

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
// Unhide 3 rows starting from row index 1 (rows 2-4)
const row1 = fWorksheet.getRange('2:4')
fWorksheet.unhideRow(row1)
// Unhide single row at index 0 (first row)
const row2 = fWorksheet.getRange('1:1')
fWorksheet.unhideRow(row2)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`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-worksheet.d.ts)

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

### `FWorksheet.addConditionalFormattingRule`

Add a new conditional format

```typescript
addConditionalFormattingRule(rule: IConditionFormattingRule): FWorksheet
```

**Parameters**

* `rule` — Required. The conditional formatting rule to add

**Returns**

Returns the current worksheet instance for method chaining

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

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`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-worksheet.d.ts)

### `FWorksheet.clearConditionalFormatRules`

Removes all conditional format rules from the sheet.

```typescript
clearConditionalFormatRules(): FWorksheet
```

**Returns**

Returns the current worksheet instance for method chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
fWorksheet.clearConditionalFormatRules()
console.log(fWorksheet.getConditionalFormattingRules()) // []
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.deleteConditionalFormattingRule`

Delete conditional format according to `cfId`

```typescript
deleteConditionalFormattingRule(cfId: string): FWorksheet
```

**Parameters**

* `cfId` — Required. The conditional formatting rule id to delete

**Returns**

Returns the current worksheet 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 rules = fWorksheet.getConditionalFormattingRules()

// Delete the first rule
fWorksheet.deleteConditionalFormattingRule(rules[0]?.cfId)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.getConditionalFormattingRules`

Gets all the conditional formatting for the current sheet

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

**Returns**

conditional formatting rules for the current sheet

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const rules = fWorksheet.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-worksheet.d.ts)

### `FWorksheet.moveConditionalFormattingRule`

Modify the priority of the conditional format

```typescript
moveConditionalFormattingRule(cfId: string, toCfId: string, type?: IAnchor['type']): FWorksheet
```

**Parameters**

* `cfId` — Required. The conditional formatting rule id to move
* `toCfId` — Required. Target rule
* `type` — Optional. Default: `'after'`. After the default move to the destination rule, if type = before moves to the front, the default value is after

**Returns**

Returns the current worksheet 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 rules = fWorksheet.getConditionalFormattingRules()

// Move the third rule before the first rule
const rule = rules[2]
const targetRule = rules[0]
fWorksheet.moveConditionalFormattingRule(rule?.cfId, targetRule?.cfId, 'before')
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`IAnchor`](https://unpkg.com/@univerjs/sheets-conditional-formatting/lib/types/utils/anchor.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-worksheet.d.ts)

### `FWorksheet.newConditionalFormattingRule`

Creates a constructor for conditional formatting

```typescript
newConditionalFormattingRule(): 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 = fWorksheet
  .newConditionalFormattingRule()
  .whenCellNotEmpty()
  .setRanges([fRange.getRange()])
  .setItalic(true)
  .setBackground('red')
  .setFontColor('green')
  .build()
fWorksheet.addConditionalFormattingRule(rule)
```

**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-worksheet.d.ts)

### `FWorksheet.setConditionalFormattingRule`

Set the conditional format according to `cfId`

```typescript
setConditionalFormattingRule(cfId: string, rule: IConditionFormattingRule): FWorksheet
```

**Parameters**

* `cfId` — Required. The conditional formatting rule id to set
* `rule` — Required. The conditional formatting rule to set

**Returns**

Returns the current worksheet instance for method chaining

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

// Modify the first rule to apply to a new range
const rules = fWorksheet.getConditionalFormattingRules()
const newRuleRange = fWorksheet.getRange('A1:D10')
fWorksheet.setConditionalFormattingRule(rules[0]?.cfId, {
  ...rules[0],
  ranges: [newRuleRange.getRange()],
})
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`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-worksheet.d.ts)

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

### `FWorksheet.getAllDataValidationErrorAsync`

Get all data validation errors for current worksheet.

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

**Returns**

A promise that resolves to an array of validation errors.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const errors = await fWorksheet.getAllDataValidationErrorAsync()
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-worksheet.d.ts)

### `FWorksheet.getDataValidation`

get data validation rule by rule id

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

**Parameters**

* `ruleId` — Required. the rule id

**Returns**

data validation rule

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const rules = fWorksheet.getDataValidations()
console.log(fWorksheet.getDataValidation(rules[0]?.rule.uid))
```

**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-worksheet.d.ts)

### `FWorksheet.getDataValidations`

Get all data validation rules in current sheet.

```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')
const rules = fWorksheet.getDataValidations()
console.log(rules)
```

**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-worksheet.d.ts)

### `FWorksheet.getValidatorStatusAsync`

Get data validation validator status for current sheet.

```typescript
getValidatorStatusAsync(): Promise<ObjectMatrix<Nullable<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')
const status = await fWorksheet.getValidatorStatusAsync()
console.log(status)
```

**Types:** [`ObjectMatrix`](https://unpkg.com/@univerjs/core/lib/types/shared/object-matrix.d.ts) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`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-worksheet.d.ts)

## `@univerjs/sheets-drawing`

### `FWorksheet.deleteBackgroundImage`

Deletes the image tiled behind the worksheet grid.

```typescript
deleteBackgroundImage(): this
```

**Returns**

The current worksheet instance for chaining.

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

### `FWorksheet.deleteImages`

Delete images from the sheet

```typescript
deleteImages(sheetImages: FOverGridImage[]): FWorksheet
```

**Parameters**

* `sheetImages` — Required. The images to delete

**Returns**

The FWorksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const image = fWorksheet.getImages()[0]

// Delete the first image of the sheet
fWorksheet.deleteImages([image])
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`FOverGridImage`](https://docs.univer.ai/ko-KR/reference/facade/over-grid-image.md)

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

### `FWorksheet.getActiveImages`

Get the current selected images.

```typescript
getActiveImages(): FOverGridImage[]
```

**Returns**

The FOverGridImage instances

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const images = fWorksheet.getActiveImages()
images.forEach((image) => {
  console.log(image, image.getId())
})
```

**Types:** [`FOverGridImage`](https://docs.univer.ai/ko-KR/reference/facade/over-grid-image.md)

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

### `FWorksheet.getBackgroundImage`

Returns the image tiled behind the worksheet grid.

```typescript
getBackgroundImage(): Nullable<IWorksheetBackgroundImage>
```

**Returns**

The worksheet background image, or `null` when absent.

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

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

### `FWorksheet.getDrawingGroupChildren`

Get children of a drawing group on the current sheet.

```typescript
getDrawingGroupChildren(groupId: string, recursive?: boolean): ISheetDrawing[]
```

**Parameters**

* `groupId` — Required. The group drawing id.
* `recursive` — Optional. Default: `false`. Whether to return all descendants.

**Returns**

The child drawings.

**Examples**

```ts
// Get the direct children of a drawing group.
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const image1 = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(1)
  .setRow(1)
  .setWidth(100)
  .setHeight(100)
  .buildAsync()
const image2 = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(3)
  .setRow(1)
  .setWidth(100)
  .setHeight(100)
  .buildAsync()
fWorksheet.insertImages([image1, image2])
const groupId = fWorksheet.groupDrawings([image1.drawingId, image2.drawingId])
if (groupId) {
  const children = fWorksheet.getDrawingGroupChildren(groupId)
  console.log(children.map((drawing) => drawing.drawingId))
}
```

**Types:** [`ISheetDrawing`](https://unpkg.com/@univerjs/sheets-drawing/lib/types/services/sheet-drawing.service.d.ts)

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

### `FWorksheet.getDrawingLayout`

Get the Sheet host layout in model coordinates.

This API is available in Node/headless and does not include viewport,
scroll, zoom, frozen-pane clipping, or screen coordinates.

```typescript
getDrawingLayout(): ISheetDrawingLayout
```

**Returns**

Grid, data, and ordered Drawing bounds.

**Examples**

```ts
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()
const layout = sheet.getDrawingLayout()
console.log(layout.gridBounds, layout.dataBounds)
for (const drawing of layout.drawings) {
  console.log(drawing.drawingId, drawing.bounds)
}
```

**Types:** [`ISheetDrawingLayout`](https://unpkg.com/@univerjs/sheets-drawing/lib/types/facade/f-worksheet.d.ts)

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

### `FWorksheet.getDrawingParentGroup`

Get the parent group of a drawing on the current sheet.

```typescript
getDrawingParentGroup(drawingId: string): ISheetDrawing | null
```

**Parameters**

* `drawingId` — Required. The child drawing id.

**Returns**

The parent group drawing, or null if the drawing is not grouped.

**Examples**

```ts
// Get the parent group of a drawing.
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const image1 = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(1)
  .setRow(1)
  .setWidth(100)
  .setHeight(100)
  .buildAsync()
const image2 = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(3)
  .setRow(1)
  .setWidth(100)
  .setHeight(100)
  .buildAsync()
fWorksheet.insertImages([image1, image2])
fWorksheet.groupDrawings([image1.drawingId, image2.drawingId])
const parentGroup = fWorksheet.getDrawingParentGroup(image1.drawingId)
console.log(parentGroup?.drawingId)
```

**Types:** [`ISheetDrawing`](https://unpkg.com/@univerjs/sheets-drawing/lib/types/services/sheet-drawing.service.d.ts)

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

### `FWorksheet.getDrawingPlacement`

Get the placement of any drawing on this sheet.

Image, Shape, Chart, and Group use the same placement contract.

```typescript
getDrawingPlacement(drawingId: string): ISheetDrawingPlacement | null
```

**Parameters**

* `drawingId` — Required. Drawing id.

**Returns**

The placement, or `null` when the drawing does not exist.

**Examples**

```ts
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()
const placement = sheet.getDrawingPlacement('drawing-id')
if (placement?.kind === univerAPI.Enum.SheetDrawingAnchorType.Both) {
  console.log(placement.from, placement.to)
}
```

**Types:** [`ISheetDrawingPlacement`](https://unpkg.com/@univerjs/sheets-drawing/lib/types/services/sheet-drawing-placement.d.ts)

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

### `FWorksheet.getImageById`

Get image by drawing id

```typescript
getImageById(id: string): FOverGridImage | null
```

**Parameters**

* `id` — Required. The drawing id of the image

**Returns**

The FOverGridImage instance

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const image = fWorksheet.getImageById('xxxx')
console.log(image)
```

**Types:** [`FOverGridImage`](https://docs.univer.ai/ko-KR/reference/facade/over-grid-image.md)

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

### `FWorksheet.getImages`

Get all images of the sheet.

```typescript
getImages(): FOverGridImage[]
```

**Returns**

The FOverGridImage instances

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const images = fWorksheet.getImages()
images.forEach((image) => {
  console.log(image, image.getId())
})
```

**Types:** [`FOverGridImage`](https://docs.univer.ai/ko-KR/reference/facade/over-grid-image.md)

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

### `FWorksheet.groupDrawings`

Group drawings on the current sheet.

```typescript
groupDrawings(drawingIds: string[], groupId?: string): string | null
```

**Parameters**

* `drawingIds` — Required. The drawing ids to group. At least two drawings are required.
* `groupId` — Optional. Default: `generateRandomId(10)`. Optional group drawing id. If omitted, a new id will be generated.

**Returns**

The group id if the operation succeeds, otherwise null.

**Examples**

```ts
// Group two over-grid images on the active sheet.
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const image1 = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(1)
  .setRow(1)
  .setWidth(100)
  .setHeight(100)
  .buildAsync()
const image2 = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(3)
  .setRow(1)
  .setWidth(100)
  .setHeight(100)
  .buildAsync()
fWorksheet.insertImages([image1, image2])
const groupId = fWorksheet.groupDrawings([image1.drawingId, image2.drawingId])
console.log(groupId)
```

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

### `FWorksheet.insertImage`

Insert an image to the sheet

```typescript
insertImage(url: IFBlobSource | string, column?: number, row?: number, offsetX?: number, offsetY?: number): Promise<boolean>
```

**Parameters**

* `url` — Required. The image url
* `column` — Optional. The column index to insert the image
* `row` — Optional. The row index to insert the image
* `offsetX` — Optional. The column offset, pixel unit
* `offsetY` — Optional. The row offset, pixel unit

**Returns**

true if the image is inserted successfully

True if the image is inserted successfully

**Examples**

```ts
// Insert an image to the sheet, default position is A1
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const result = await fWorksheet.insertImage(
  'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
)
console.log(result)
```

```ts
// Insert an image to the sheet, position is F6
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const result = await fWorksheet.insertImage(
  'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
  5,
  5,
)
console.log(result)
```

```ts
// Insert an image to the sheet, position is F6, offset is 10px
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const result = await fWorksheet.insertImage(
  'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
  5,
  5,
  10,
  10,
)
console.log(result)
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IFBlobSource`](https://unpkg.com/@univerjs/core/lib/types/facade/f-blob.d.ts)

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

### `FWorksheet.insertImages`

Insert images to the sheet

```typescript
insertImages(sheetImages: ISheetImage[]): FWorksheet
```

**Parameters**

* `sheetImages` — Required. The images to insert

**Returns**

The FWorksheet instance for chaining

**Examples**

```ts
// create a new image builder and set image source.
// then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const image = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(5)
  .setRow(5)
  .setWidth(500)
  .setHeight(300)
  .buildAsync()
fWorksheet.insertImages([image])

// update the image width to 100px and height to 50px
setTimeout(async () => {
  const imageBuilder = fWorksheet.getImageById(image.drawingId).toBuilder()
  const newImage = await imageBuilder.setWidth(100).setHeight(50).buildAsync()
  fWorksheet.updateImages([newImage])
}, 4000)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`ISheetImage`](https://unpkg.com/@univerjs/sheets-drawing/lib/types/services/sheet-drawing.service.d.ts)

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

### `FWorksheet.isDrawingGrouped`

Returns whether a drawing is inside a group on the current sheet.

```typescript
isDrawingGrouped(drawingId: string): boolean
```

**Parameters**

* `drawingId` — Required. The drawing id.

**Returns**

true if the drawing has a parent group.

**Examples**

```ts
// Check whether a drawing is inside a group.
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const image1 = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(1)
  .setRow(1)
  .setWidth(100)
  .setHeight(100)
  .buildAsync()
const image2 = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(3)
  .setRow(1)
  .setWidth(100)
  .setHeight(100)
  .buildAsync()
fWorksheet.insertImages([image1, image2])
fWorksheet.groupDrawings([image1.drawingId, image2.drawingId])
const isGrouped = fWorksheet.isDrawingGrouped(image1.drawingId)
console.log(isGrouped)
```

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

### `FWorksheet.newOverGridImage`

Create a new over grid image builder.

```typescript
newOverGridImage(): FOverGridImageBuilder
```

**Returns**

The FOverGridImageBuilder instance

**Examples**

```ts
// create a new image builder and set image source.
// then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const image = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(5)
  .setRow(5)
  .setWidth(500)
  .setHeight(300)
  .buildAsync()
fWorksheet.insertImages([image])
```

**Types:** [`FOverGridImageBuilder`](https://docs.univer.ai/ko-KR/reference/facade/over-grid-image-builder.md)

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

### `FWorksheet.resolveDrawingPlacement`

Resolve exact markers or model-space bounds to a normalized Placement.

Bounds inference is usually preferable when positioning from an existing
transform. Exact markers are useful when the caller must preserve a
user-selected cell and offset. `Position` maps to OOXML OneCell,
`Both` maps to TwoCell, and `None` maps to Absolute.

```typescript
resolveDrawingPlacement(placement: ISheetDrawingPlacementInput): ISheetDrawingPlacement
```

**Parameters**

* `placement` — Required. Exact markers or bounds with an explicit anchor type.

**Returns**

The normalized Placement.

**Examples**

Infer Position and Both placements from bounds in Node/headless

```ts
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()
const positionPlacement = sheet.resolveDrawingPlacement({
  kind: univerAPI.Enum.SheetDrawingAnchorType.Position,
  bounds: { left: 120, top: 80, width: 320, height: 160 },
})
const bothPlacement = sheet.resolveDrawingPlacement({
  kind: univerAPI.Enum.SheetDrawingAnchorType.Both,
  bounds: { left: 120, top: 80, width: 320, height: 160 },
})
console.log(positionPlacement.from)
console.log(bothPlacement.from, bothPlacement.to)
```

**Types:** [`ISheetDrawingPlacement`](https://unpkg.com/@univerjs/sheets-drawing/lib/types/services/sheet-drawing-placement.d.ts) · [`ISheetDrawingPlacementInput`](https://unpkg.com/@univerjs/sheets-drawing/lib/types/services/sheet-drawing-placement.d.ts)

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

### `FWorksheet.setBackgroundImage`

Sets the image tiled behind the worksheet grid. Worksheet background images are not printed.

```typescript
setBackgroundImage(source: string, imageSourceType?: ImageSourceType): this
```

**Parameters**

* `source` — Required. Image source.
* `imageSourceType` — Optional. Default: `ImageSourceType.URL`. Image source type.

**Returns**

The current worksheet instance for chaining.

**Types:** [`ImageSourceType`](https://unpkg.com/@univerjs/core/lib/types/services/image-io/image-io.service.d.ts)

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

### `FWorksheet.setDrawingPlacement`

Set the placement of any drawing on this sheet through the drawing command.

```typescript
setDrawingPlacement(drawingId: string, placement: ISheetDrawingPlacementInput): boolean
```

**Parameters**

* `drawingId` — Required. Drawing id.
* `placement` — Required. Exact markers or model-space bounds with an explicit anchor type.

**Returns**

`true` when the command succeeds.

**Examples**

OneCell: move with cells, keep pixel size

```ts
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()
const drawingId = sheet.getImages()[0]?.getId()
if (!drawingId) throw new Error('No drawing found.')
const changed = sheet.setDrawingPlacement(drawingId, {
  kind: univerAPI.Enum.SheetDrawingAnchorType.Position,
  from: { row: 2, column: 2, rowOffset: 8, columnOffset: 8 },
  width: 240,
  height: 120,
})
console.log(changed)
```

TwoCell: move and resize with both cell markers

```ts
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()
const drawingId = sheet.getImages()[0]?.getId()
if (!drawingId) throw new Error('No drawing found.')
sheet.setDrawingPlacement(drawingId, {
  kind: univerAPI.Enum.SheetDrawingAnchorType.Both,
  from: { row: 2, column: 2, rowOffset: 8, columnOffset: 8 },
  to: { row: 8, column: 6, rowOffset: 0, columnOffset: 0 },
})
```

Absolute: do not move or resize after row or column changes

```ts
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()
const drawingId = sheet.getImages()[0]?.getId()
if (!drawingId) throw new Error('No drawing found.')
sheet.setDrawingPlacement(drawingId, {
  kind: univerAPI.Enum.SheetDrawingAnchorType.None,
  left: 640,
  top: 96,
  width: 240,
  height: 120,
})
```

**Types:** [`ISheetDrawingPlacementInput`](https://unpkg.com/@univerjs/sheets-drawing/lib/types/services/sheet-drawing-placement.d.ts)

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

### `FWorksheet.ungroupDrawings`

Ungroup drawing groups on the current sheet.

```typescript
ungroupDrawings(groupIds: string[]): boolean
```

**Parameters**

* `groupIds` — Required. The group drawing ids to ungroup.

**Returns**

true if the operation succeeds, otherwise false.

**Examples**

```ts
// Group two images, then ungroup the generated group.
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const image1 = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(1)
  .setRow(1)
  .setWidth(100)
  .setHeight(100)
  .buildAsync()
const image2 = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(3)
  .setRow(1)
  .setWidth(100)
  .setHeight(100)
  .buildAsync()
fWorksheet.insertImages([image1, image2])
const groupId = fWorksheet.groupDrawings([image1.drawingId, image2.drawingId])
if (groupId) {
  const result = fWorksheet.ungroupDrawings([groupId])
  console.log(result)
}
```

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

### `FWorksheet.updateImages`

Update images to the sheet

```typescript
updateImages(sheetImages: ISheetImage[]): FWorksheet
```

**Parameters**

* `sheetImages` — Required. The images to update

**Returns**

The FWorksheet instance for chaining

**Examples**

```ts
// create a new image builder and set image source.
// then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const image = await fWorksheet
  .newOverGridImage()
  .setSource(
    'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
    univerAPI.Enum.ImageSourceType.URL,
  )
  .setColumn(5)
  .setRow(5)
  .setWidth(500)
  .setHeight(300)
  .buildAsync()
fWorksheet.insertImages([image])

// update the image width to 100px and height to 50px after 4 seconds
setTimeout(async () => {
  const imageBuilder = fWorksheet.getImageById(image.drawingId).toBuilder()
  const newImage = await imageBuilder.setWidth(100).setHeight(50).buildAsync()
  fWorksheet.updateImages([newImage])
}, 4000)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`ISheetImage`](https://unpkg.com/@univerjs/sheets-drawing/lib/types/services/sheet-drawing.service.d.ts)

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

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

### `FWorksheet.addFloatDomToColumnHeader`

Add dom at column header, And FloatDOM is registerComponent(BuiltInUIPart.CONTENT)

```typescript
addFloatDomToColumnHeader(column: number, layer: IFICanvasFloatDom, domLayout: IDOMAnchor, id?: string): Nullable<{ id: string; dispose: () => void; }>
```

**Parameters**

* `column` — Required. The column index to add the float dom.
* `layer` — Required. The float dom layer configuration.
* `domLayout` — Required.
* `id` — Optional. The float dom id, if not given will be auto generated

**Returns**

float dom id and dispose function

**Examples**

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

// Register a float button component
const FloatButton = () => {
  const divStyle = {
    width: '100px',
    height: '30px',
    backgroundColor: '#fff',
    border: '1px solid #ccc',
    boxSizing: 'border-box' as const,
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    textAlign: 'center' as const,
    cursor: 'pointer',
  }

  const clickHandler = () => {
    console.warn('click')
  }

  return (
    <div style={divStyle} onClick={clickHandler}>
      FloatButton
    </div>
  )
}
univerAPI.registerComponent('FloatButton', FloatButton)

// Add the float button to the column D header, position is right align, width is 100px, height is 30px, margin is 0
const disposable = fWorksheet.addFloatDomToColumnHeader(
  3,
  {
    componentKey: 'FloatButton',
    allowTransform: false,
  },
  {
    width: 100,
    height: 30,
    marginX: 0,
    marginY: 0,
    horizonOffsetAlign: 'right',
  },
  'myFloatButton',
)
console.log(disposable?.id) // The id of the floating DOM

// Remove the float button after 2 seconds
setTimeout(() => {
  disposable?.dispose()
}, 2000)
```

**Types:** [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`IFICanvasFloatDom`](https://unpkg.com/@univerjs/sheets-drawing-ui/lib/types/facade/f-worksheet.d.ts) · [`IDOMAnchor`](https://unpkg.com/@univerjs/sheets-drawing-ui/lib/types/services/canvas-float-dom-manager.service.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-worksheet.d.ts)

### `FWorksheet.addFloatDomToPosition`

Add a float dom to position.

```typescript
addFloatDomToPosition(layer: IFICanvasFloatDom, id?: string): Nullable<{ id: string; dispose: () => void; }>
```

**Parameters**

* `layer` — Required. The float dom layer configuration.
* `id` — Optional. The float dom id, if not given will be auto generated.

**Returns**

float dom id and dispose function

**Examples**

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

// You should register components at an appropriate time (e.g., when Univer is loaded).
// This is a React component. For other frameworks, pass a matching adapter option, such as `{ framework: 'vue3' }`.
univerAPI.registerComponent('myFloatDom', ({ data }) => (
  <div
    style={{
      width: '100%',
      height: '100%',
      background: '#fff',
      border: '1px solid #ccc',
      boxSizing: 'border-box',
    }}
  >
    popup content: {data?.label}
  </div>
))

// Add a floating DOM
// If disposable is null, floating DOM addition failed
const disposable = fWorksheet.addFloatDomToPosition({
  componentKey: 'myFloatDom',
  initPosition: {
    startX: 100,
    endX: 300,
    startY: 100,
    endY: 200,
  },

  // Component data
  data: {
    label: 'hahah',
  },
})
console.log(disposable?.id) // The id of the floating DOM

// Remove the floating DOM after 2 seconds
setTimeout(() => {
  disposable?.dispose()
}, 2000)
```

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

### `FWorksheet.addFloatDomToRange`

Add dom over range to FloatDOM, And FloatDOM is registerComponent(BuiltInUIPart.CONTENT)

```typescript
addFloatDomToRange(fRange: FRange, layer: IFICanvasFloatDom, domLayout: IDOMAnchor, id?: string): Nullable<{ id: string; dispose: () => void; }>
```

**Parameters**

* `fRange` — Required.
* `layer` — Required. The float dom layer configuration.
* `domLayout` — Required. The anchor configuration of the float dom.
* `id` — Optional. The float dom id, if not given will be auto generated

**Returns**

float dom id and dispose function

**Examples**

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

// Register a range loading component
const RangeLoading = () => {
  const divStyle = {
    width: '100%',
    height: '100%',
    backgroundColor: '#fff',
    border: '1px solid #ccc',
    boxSizing: 'border-box' as const,
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    textAlign: 'center' as const,
    transformOrigin: 'top left',
  }

  return <div style={divStyle}>Loading...</div>
}
univerAPI.registerComponent('RangeLoading', RangeLoading)

// Add the range loading component covering the range A1:C3
const fRange = fWorksheet.getRange('A1:C3')
const disposable = fWorksheet.addFloatDomToRange(
  fRange,
  { componentKey: 'RangeLoading' },
  {},
  'myRangeLoading',
)
console.log(disposable?.id) // The id of the floating DOM

// Remove the floating DOM after 2 seconds
setTimeout(() => {
  disposable?.dispose()
}, 2000)

// another example-------------------
// Register a float button component
const FloatButton = () => {
  const divStyle = {
    width: '100px',
    height: '30px',
    backgroundColor: '#fff',
    border: '1px solid #ccc',
    boxSizing: 'border-box' as const,
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    textAlign: 'center' as const,
    cursor: 'pointer',
  }

  const clickHandler = () => {
    console.warn('click')
  }

  return (
    <div style={divStyle} onClick={clickHandler}>
      FloatButton
    </div>
  )
}
univerAPI.registerComponent('FloatButton', FloatButton)

// Add the float button to the range A5:C7, position is start from A5 cell, and width is 100px, height is 30px, margin is 100% of range width and height
const fRange2 = fWorksheet.getRange('A5:C7')
const disposable2 = fWorksheet.addFloatDomToRange(
  fRange2,
  {
    componentKey: 'FloatButton',
  },
  {
    width: 100,
    height: 30,
    marginX: '100%', // margin percent to range width, or pixel
    marginY: '100%',
  },
  'myFloatButton',
)
console.log(disposable2?.id) // The id of the floating DOM
```

**Types:** [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md) · [`IFICanvasFloatDom`](https://unpkg.com/@univerjs/sheets-drawing-ui/lib/types/facade/f-worksheet.d.ts) · [`IDOMAnchor`](https://unpkg.com/@univerjs/sheets-drawing-ui/lib/types/services/canvas-float-dom-manager.service.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-worksheet.d.ts)

### `FWorksheet.batchUpdateFloatDoms`

Batch update float doms

```typescript
batchUpdateFloatDoms(updates: Array<{ id: string; config: Partial<Omit<IFCanvasFloatDomResult, 'id'>>; }>): this
```

**Parameters**

* `updates` — Required. array of update configs

**Returns**

The worksheet instance for chaining

**Examples**

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

// Update multiple float doms at once
const allFloatDoms = fWorksheet.getAllFloatDoms()
fWorksheet.batchUpdateFloatDoms(
  allFloatDoms.map((floatDom, index) => {
    if (floatDom.id === 'MyFloatDomId') {
      return {
        id: floatDom.id,
        config: {
          position: {
            left: 100,
            top: 100,
          },
          data: {
            label: 'Updated',
          },
        },
      }
    }

    return {
      id: floatDom.id,
      config: {
        position: {
          left: 300,
          top: 100,
        },
      },
    }
  }),
)
```

**Types:** [`Array`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IFCanvasFloatDomResult`](https://unpkg.com/@univerjs/sheets-drawing-ui/lib/types/facade/f-worksheet.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-worksheet.d.ts)

### `FWorksheet.getAllFloatDoms`

Get all float doms in current worksheet

```typescript
getAllFloatDoms(): IFCanvasFloatDomResult[]
```

**Returns**

array of float dom info

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const allFloatDoms = fWorksheet.getAllFloatDoms()
allFloatDoms.forEach((floatDom) => {
  console.log('Float dom ID:', floatDom.id)
  console.log('Position:', floatDom.position)
})
```

**Types:** [`IFCanvasFloatDomResult`](https://unpkg.com/@univerjs/sheets-drawing-ui/lib/types/facade/f-worksheet.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-worksheet.d.ts)

### `FWorksheet.getFloatDomById`

Get float dom by id

```typescript
getFloatDomById(id: string): Nullable<IFCanvasFloatDomResult>
```

**Parameters**

* `id` — Required. float dom id

**Returns**

float dom info or null if not found

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const floatDom = fWorksheet.getFloatDomById('myFloatDomId')
if (floatDom) {
  console.log('Float dom position:', floatDom.position)
  console.log('Component key:', floatDom.componentKey)
  console.log('Custom data:', floatDom.data)
}
```

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

### `FWorksheet.removeFloatDom`

Remove float dom by id

```typescript
removeFloatDom(id: string): this
```

**Parameters**

* `id` — Required. float dom id

**Returns**

The worksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const firstFloatDom = fWorksheet.getAllFloatDoms()[0]

if (!firstFloatDom) throw new Error('firstFloatDom is not available')

// Remove the first float dom
fWorksheet.removeFloatDom(firstFloatDom.id)
```

**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-worksheet.d.ts)

### `FWorksheet.saveCellImagesAsync`

Save all cell images from specified ranges to the file system.
This method will open a directory picker dialog and save all images to the selected directory.

```typescript
saveCellImagesAsync(options?: ISaveCellImagesOptions, ranges?: FRange[]): Promise<boolean>
```

**Parameters**

* `options` — Optional. Options for saving images
* `ranges` — Optional. The ranges to get cell images from. If not provided, all images in the worksheet will be saved.

**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 cell images from multiple ranges
const range1 = fWorksheet.getRange('A1:B10')
const range2 = fWorksheet.getRange('D1:E10')

// Save with default options (using cell address as file name)
await fWorksheet.saveCellImagesAsync(undefined, [range1, range2])

// Save with custom options
await fWorksheet.saveCellImagesAsync(
  {
    useCellAddress: true,
    useColumnIndex: 2, // Use values from column C for file names
  },
  [range1, range2],
)
```

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

**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-worksheet.d.ts)

### `FWorksheet.updateFloatDom`

Update float dom position and properties

```typescript
updateFloatDom(id: string, config: Partial<Omit<IFCanvasFloatDomResult, 'id'>>): this
```

**Parameters**

* `id` — Required. float dom id
* `config` — Required. new float dom config

**Returns**

The worksheet instance for chaining

**Examples**

```ts
const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const firstFloatDom = fWorksheet.getAllFloatDoms()[0]

if (!firstFloatDom) throw new Error('firstFloatDom is not available')

// Update first float dom position and size
fWorksheet.updateFloatDom(firstFloatDom.id, {
  position: {
    left: 100,
    top: 100,
    width: 200,
    height: 150,
    angle: 45, // rotate 45 degrees
  },
})

// Update first float dom data
fWorksheet.updateFloatDom(firstFloatDom.id, {
  data: {
    label: 'Updated Label',
    color: '#ff0000',
  },
})

// Disable the first float dom from transform
fWorksheet.updateFloatDom(firstFloatDom.id, {
  allowTransform: false,
})
```

**Types:** [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IFCanvasFloatDomResult`](https://unpkg.com/@univerjs/sheets-drawing-ui/lib/types/facade/f-worksheet.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-worksheet.d.ts)

## `@univerjs/sheets-filter`

### `FWorksheet.getFilter`

Get the filter for the current worksheet.

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

**Returns**

The interface class to handle the filter. If the worksheet does not have a filter,
this method would return `null`.

**Examples**

```ts
const workbook = univerAPI.getActiveWorkbook()
const worksheet = workbook.getSheetByName('Sheet1')
if (!worksheet) throw new Error('worksheet is not available')
const filter = worksheet.getFilter()
console.log(filter, filter?.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-worksheet.d.ts)

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

### `FWorksheet.getUrl`

Create a hyperlink url to this sheet

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

**Returns**

The hyperlink url of this sheet

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const url = fWorksheet.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-worksheet.d.ts)

## `@univerjs/sheets-note`

### `FWorksheet.getNotes`

Get all annotations in the worksheet

```typescript
getNotes(): ISheetNote[]
```

**Returns**

An array of all annotations in the worksheet

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

notes.forEach((item) => {
  const { row, col, note } = item
  console.log(`Cell ${fWorksheet.getRange(row, col).getA1Notation()} has a note: ${note}`)
})
```

**Types:** [`ISheetNote`](https://unpkg.com/@univerjs/sheets-note/lib/types/models/sheets-note.model.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-worksheet.d.ts)

## `@univerjs/sheets-sort`

### `FWorksheet.sort`

Sort the worksheet by the specified column.

```typescript
sort(colIndex: number, asc?: boolean): FWorksheet
```

**Parameters**

* `colIndex` — Required. The column index to sort by.
* `asc` — Optional. Default: `true`. The sort order. `true` for ascending, `false` for descending. The column A index is 0.

**Returns**

The worksheet itself for chaining.

**Examples**

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

// Sorts the worksheet by the column A in ascending order.
fWorksheet.sort(0)

// Sorts the worksheet by the column A in descending order.
fWorksheet.sort(0, false)
```

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

**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-worksheet.d.ts)

## `@univerjs/sheets-table`

### `FWorksheet.addTable`

Add a table to the worksheet

```typescript
addTable(tableName: string, rangeInfo: ITableRange, tableId?: string, options?: ITableOptions): Promise<boolean> | boolean
```

**Parameters**

* `tableName` — Required. The table name
* `rangeInfo` — Required. The table range information
* `tableId` — Optional. The table id
* `options` — Optional. The table options

**Returns**

`false` for an invalid table name; otherwise, a promise resolving to whether the command succeeded.

**Examples**

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

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable('name-1', fRange.getRange(), 'id-1', {
  tableStyleId: 'table-default-4',
  columns: [{ id: 'col-1', displayName: 'Column 1' }],
  filters: [
    {
      filterType: univerAPI.Enum.TableColumnFilterTypeEnum.condition,
      filterInfo: {
        conditionType: univerAPI.Enum.TableConditionTypeEnum.Number,
        compareType: univerAPI.Enum.TableNumberCompareTypeEnum.GreaterThan,
        expectedValue: 2,
      },
    },
  ],
})

if (success) {
  const tableInfo = fWorkbook.getTableInfo('id-1')
  console.log('debugger tableInfo', tableInfo)
}
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ITableRange`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts) · [`ITableOptions`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts)

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

### `FWorksheet.addTableTheme`

Add a theme to the table

```typescript
addTableTheme(tableId: string, themeStyleJSON: IRangeThemeStyleJSON): Promise<boolean>
```

**Parameters**

* `tableId` — Required. The table id
* `themeStyleJSON` — Required. The theme style JSON

**Returns**

Whether the theme was added successfully

**Examples**

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

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable('name-1', fRange.getRange(), 'id-1', {
  tableStyleId: 'table-default-4',
})

if (success) {
  await fWorksheet.addTableTheme('id-1', {
    name: 'table-custom-1',
    headerRowStyle: {
      bg: {
        rgb: '#145f82',
      },
    },
    firstRowStyle: {
      bg: {
        rgb: '#c0e4f5',
      },
    },
  })

  const tableInfo = fWorkbook.getTableInfo('id-1')
  console.log('debugger tableInfo', tableInfo)
}
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IRangeThemeStyleJSON`](https://unpkg.com/@univerjs/sheets/lib/types/models/range-theme-util.d.ts)

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

### `FWorksheet.getSubTableInfos`

Get the list of tables in the worksheet

```typescript
getSubTableInfos(): ITableInfoWithUnitId[]
```

**Returns**

The list of tables

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const tables = fWorksheet.getSubTableInfos()
console.log('debugger tables', tables)
```

**Types:** [`ITableInfoWithUnitId`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts)

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

### `FWorksheet.getTableByCell`

Get the table information by cell position

```typescript
getTableByCell(row: number, column: number): ITableInfoWithUnitId | undefined
```

**Parameters**

* `row` — Required. The cell row index, starting from 0.
* `column` — Required. The cell column index, starting from 0.

**Returns**

The table information or undefined if not found

**Examples**

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

const cellB2 = fWorksheet.getRange('B2')
const row = cellB2.getRow()
const column = cellB2.getColumn()
console.log('debugger tableInfo', fWorksheet.getTableByCell(row, column))

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable('name-1', fRange.getRange(), 'id-1', {
  tableStyleId: 'table-default-4',
})
console.log('debugger tableInfo2', fWorksheet.getTableByCell(row, column))
```

**Types:** [`ITableInfoWithUnitId`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts)

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

### `FWorksheet.removeTable`

Remove a table from the worksheet

```typescript
removeTable(tableId: string): Promise<boolean>
```

**Parameters**

* `tableId` — Required. The table id

**Returns**

Whether the table was removed successfully

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const tableInfo = fWorkbook.getTableInfo('id-1')
console.log('debugger tableInfo', tableInfo)

if (tableInfo) {
  // Remove the table with the specified id
  await fWorksheet.removeTable('id-1')
}
```

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

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

### `FWorksheet.resetFilter`

Reset the column filter of a table

```typescript
resetFilter(tableId: string, column: number): Promise<boolean>
```

**Parameters**

* `tableId` — Required. The table id
* `column` — Required. The column index, starting from 0. For example, the first column is 0, the second column is 1, and so on.

**Returns**

Whether the table filter was reset successfully

**Examples**

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

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable('name-1', fRange.getRange(), 'id-1', {
  tableStyleId: 'table-default-4',
})

if (success) {
  // Set the filter for the second column
  await fWorksheet.setTableFilter('id-1', 1, {
    filterType: univerAPI.Enum.TableColumnFilterTypeEnum.condition,
    filterInfo: {
      conditionType: univerAPI.Enum.TableConditionTypeEnum.Number,
      compareType: univerAPI.Enum.TableNumberCompareTypeEnum.GreaterThan,
      expectedValue: 10,
    },
  })

  // Reset the filter for the second column after 3 seconds
  setTimeout(async () => {
    await fWorksheet.resetFilter('id-1', 1)
  }, 3000)

  const tableInfo = fWorkbook.getTableInfo('id-1')
  console.log('debugger tableInfo', tableInfo)
}
```

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

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

### `FWorksheet.setTableColumnFormula`

Apply a formula to every data row of a table column, excluding header and footer.
References are relative to the first data row. Empty string stops future auto-fill and preserves cells.

```typescript
setTableColumnFormula(tableId: string, columnId: string, formula: string): boolean
```

**Parameters**

* `tableId` — Required. Table ID in this worksheet.
* `columnId` — Required. Stable column ID from getSubTableInfos().
* `formula` — Required. Formula to apply, or an empty string to stop automatic filling.

**Returns**

Whether the undoable update succeeded synchronously.

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

### `FWorksheet.setTableFilter`

Set the filter for a table column

```typescript
setTableFilter(tableId: string, column: number, filter: ITableFilterItem): Promise<boolean>
```

**Parameters**

* `tableId` — Required. The table id
* `column` — Required. The table column index, starting from 0. For example, the first column is 0, the second column is 1, and so on.
* `filter` — Required. The filter item

**Returns**

Whether the table filter was set successfully

**Examples**

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

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable('name-1', fRange.getRange(), 'id-1', {
  tableStyleId: 'table-default-4',
})

if (success) {
  // Set the filter for the second column
  await fWorksheet.setTableFilter('id-1', 1, {
    filterType: univerAPI.Enum.TableColumnFilterTypeEnum.condition,
    filterInfo: {
      conditionType: univerAPI.Enum.TableConditionTypeEnum.Number,
      compareType: univerAPI.Enum.TableNumberCompareTypeEnum.GreaterThan,
      expectedValue: 10,
    },
  })

  const tableInfo = fWorkbook.getTableInfo('id-1')
  console.log('debugger tableInfo', tableInfo)
}
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ITableFilterItem`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts)

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

### `FWorksheet.setTableFilterButtons`

Update table filter button visibility without clearing filter criteria.
Column overrides use stable column IDs from getSubTableInfos().

```typescript
setTableFilterButtons(tableId: string, config: ITableFilterButtonConfig): boolean
```

**Parameters**

* `tableId` — Required. Table ID in this worksheet.
* `config` — Required. Partial table and column button visibility settings.

**Returns**

Whether the update succeeded synchronously.

**Types:** [`ITableFilterButtonConfig`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts)

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

### `FWorksheet.setTableName`

Set the name of a table

```typescript
setTableName(tableId: string, tableName: string): Promise<boolean> | boolean
```

**Parameters**

* `tableId` — Required. The table id
* `tableName` — Required. The new table name

**Returns**

`false` for an invalid table name; otherwise, a promise resolving to whether the command succeeded.

**Examples**

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

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable('name-1', fRange.getRange(), 'id-1', {
  tableStyleId: 'table-default-4',
})

if (success) {
  // Update the table name after 3 seconds
  setTimeout(async () => {
    await fWorksheet.setTableName('id-1', 'new-name')

    const tableInfo = fWorkbook.getTableInfo('id-1')
    console.log('debugger tableInfo', tableInfo)
  }, 3000)
}
```

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

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

### `FWorksheet.setTableRange`

Set the range of a table

```typescript
setTableRange(tableId: string, rangeInfo: ITableRange): Promise<boolean>
```

**Parameters**

* `tableId` — Required. The table id
* `rangeInfo` — Required. The new range information

**Returns**

Whether the table range was set successfully

**Examples**

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

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable('name-1', fRange.getRange(), 'id-1', {
  tableStyleId: 'table-default-4',
})

if (success) {
  // Update the table range to B2:F21 after 3 seconds
  setTimeout(async () => {
    const newRange = fWorksheet.getRange('B2:F21')
    await fWorksheet.setTableRange('id-1', newRange.getRange())

    const tableInfo = fWorkbook.getTableInfo('id-1')
    console.log('debugger tableInfo', tableInfo)
  }, 3000)
}
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ITableRange`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts)

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

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

### `FWorksheet.clearComments`

Clear all comments in the current sheet

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

**Returns**

Whether the comments are cleared successfully.

**Examples**

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

**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-worksheet.d.ts)

### `FWorksheet.getCommentById`

get comment by comment id

```typescript
getCommentById(commentId: string): FThreadComment | undefined
```

**Parameters**

* `commentId` — Required. comment id

**Examples**

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

// Create a new comment
const richText = univerAPI.newRichText().insertText('hello univer')
const commentBuilder = univerAPI.newTheadComment().setContent(richText).setId('mock-comment-id')
const cell = fWorksheet.getRange('A1')
await cell.addCommentAsync(commentBuilder)

const comment = fWorksheet.getCommentById('mock-comment-id')
console.log(comment, comment?.getCommentData())
```

**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-worksheet.d.ts)

### `FWorksheet.getComments`

Get all comments in the current sheet

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

**Returns**

All comments in the current sheet

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const comments = fWorksheet.getComments()
comments.forEach((comment) => {
  const isRoot = comment.getIsRoot()

  if (isRoot) {
    console.log('root comment:', comment.getCommentData())

    const replies = comment.getReplies()
    replies.forEach((reply) => {
      console.log('reply comment:', reply.getCommentData())
    })
  }
})
```

**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-worksheet.d.ts)

### `FWorksheet.onCommented`

Subscribe to comment events.

```typescript
onCommented(callback: (params: IAddCommentCommandParams) => void): IDisposable
```

**Parameters**

* `callback` — Required. Callback function, param contains comment info and target cell.

**Returns**

A disposable used to remove the listener.

**Types:** [`IDisposable`](https://unpkg.com/@univerjs/sheets-thread-comment/lib/types/facade/f-worksheet.d.ts) · [`IAddCommentCommandParams`](https://unpkg.com/@univerjs/thread-comment/lib/types/commands/commands/comment.command.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-worksheet.d.ts)

## `@univerjs/sheets-ui`

### `FWorksheet.autoResizeColumns`

Sets the width of all columns starting at the given column position to fit their contents.

```typescript
autoResizeColumns(startColumn: number, numColumns?: number): FWorksheet
```

**Parameters**

* `startColumn` — Required. The position of the first column to resize. index starts at 0.
* `numColumns` — Optional. Default: `1`. The number of columns to auto-resize. Default is 1.

**Returns**

* The FWorksheet 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 A:C columns to a width that fits their text.
fWorksheet.autoResizeColumns(0, 3)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.autoResizeRows`

Sets the height of all rows starting at the given row position to fit their contents.

```typescript
autoResizeRows(startRow: number, numRows?: number): FWorksheet
```

**Parameters**

* `startRow` — Required. The position of the first row to resize. index starts at 0.
* `numRows` — Optional. Default: `1`. The number of rows to auto-resize. Default is 1.

**Returns**

* The FWorksheet 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 first 3 rows to a height that fits their text.
fWorksheet.autoResizeRows(0, 3)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.customizeColumnHeader`

Customize the column header of the worksheet.

```typescript
customizeColumnHeader(cfg: IColumnsHeaderCfgParam): void
```

**Parameters**

* `cfg` — Required. The configuration of the column header.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
fWorksheet.customizeColumnHeader({
  headerStyle: {
    fontColor: '#fff',
    backgroundColor: '#4e69ee',
    fontSize: 9,
  },
  columnsCfg: {
    0: 'kuma II',
    3: {
      text: 'Size',
      textAlign: 'left', // CanvasTextAlign
      fontColor: '#fff',
      fontSize: 12,
      borderColor: 'pink',
      backgroundColor: 'pink',
    },
    4: 'Wow',
  },
})
```

**Types:** [`IColumnsHeaderCfgParam`](https://unpkg.com/@univerjs/engine-render/lib/types/components/sheets/extensions/column-header-layout.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-worksheet.d.ts)

### `FWorksheet.customizeRowHeader`

Customize the row header of the worksheet.

```typescript
customizeRowHeader(cfg: IRowsHeaderCfgParam): void
```

**Parameters**

* `cfg` — Required. The configuration of the row header.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
fWorksheet.customizeRowHeader({
  headerStyle: {
    backgroundColor: 'pink',
    fontSize: 12,
  },
  rowsCfg: {
    0: 'Moka II',
    3: {
      text: 'Size',
      textAlign: 'left', // CanvasTextAlign
    },
  },
})
```

**Types:** [`IRowsHeaderCfgParam`](https://unpkg.com/@univerjs/engine-render/lib/types/components/sheets/extensions/row-header-layout.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-worksheet.d.ts)

### `FWorksheet.getScrollState`

Get scroll state of current sheet.

```typescript
getScrollState(): IScrollState
```

**Returns**

curr scroll state

**Examples**

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

// Scroll to cell D10
const fRange = fWorksheet.getRange('D10')
const row = fRange.getRow()
const column = fRange.getColumn()
fWorksheet.scrollToCell(row, column)

// Get scroll state
const scrollState = fWorksheet.getScrollState()
const { offsetX, offsetY, sheetViewStartColumn, sheetViewStartRow } = scrollState
console.log(scrollState) // sheetViewStartRow: 9, sheetViewStartColumn: 3, offsetX: 0, offsetY: 0
```

**Types:** [`IScrollState`](https://unpkg.com/@univerjs/sheets-ui/lib/types/services/scroll-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-worksheet.d.ts)

### `FWorksheet.getSkeleton`

Get the skeleton service of the worksheet.

```typescript
getSkeleton(): Nullable<SpreadsheetSkeleton>
```

**Returns**

The skeleton of the worksheet.

**Examples**

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

**Types:** [`SpreadsheetSkeleton`](https://unpkg.com/@univerjs/engine-render/lib/types/components/sheets/sheet.render-skeleton.d.ts) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.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-worksheet.d.ts)

### `FWorksheet.getVisibleRange`

Get visible range of main viewport.

```typescript
getVisibleRange(): IRange | null
```

**Returns**

The visible range of the main viewport, or `null` if no sheet skeleton is available.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const visibleRange = fWorksheet.getVisibleRange()
console.log(visibleRange)
if (visibleRange) {
  console.log(fWorksheet.getRange(visibleRange).getA1Notation())
}
```

**Types:** [`IRange`](https://docs.univer.ai/ko-KR/reference/types/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-worksheet.d.ts)

### `FWorksheet.getVisibleRangesOfAllViewports`

Get visible ranges of all viewports.

```typescript
getVisibleRangesOfAllViewports(): Map<SHEET_VIEWPORT_KEY, IRange> | null
```

**Returns**

Visible ranges keyed by viewport in a `Map`, or `null` if no sheet skeleton is available.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const visibleRanges = fWorksheet.getVisibleRangesOfAllViewports()
console.log(visibleRanges)
const mainLeftTopViewportRange = visibleRanges?.get(
  univerAPI.Enum.SHEET_VIEWPORT_KEY.VIEW_MAIN_LEFT_TOP,
)
if (mainLeftTopViewportRange) {
  console.log(fWorksheet.getRange(mainLeftTopViewportRange).getA1Notation())
}
```

**Types:** [`Map`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es2015.collection.d.ts) · [`SHEET_VIEWPORT_KEY`](https://unpkg.com/@univerjs/engine-render/lib/types/components/sheets/interfaces.d.ts) · [`IRange`](https://docs.univer.ai/ko-KR/reference/types/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-worksheet.d.ts)

### `FWorksheet.getZoom`

Get the zoom ratio of the worksheet.

```typescript
getZoom(): number
```

**Returns**

The zoom ratio of the worksheet.

**Examples**

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

**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-worksheet.d.ts)

### `FWorksheet.highlightRanges`

Highlight multiple ranges on the worksheet.

```typescript
highlightRanges(ranges: FRange[], style?: Nullable<Partial<ISelectionStyle>>, primary?: Nullable<ISelectionCell>): IDisposable
```

**Parameters**

* `ranges` — Required. The ranges to highlight.
* `style` — Optional. style for highlight ranges.
* `primary` — Optional. primary cell for highlight ranges.

**Returns**

An IDisposable to remove the highlights.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const ranges = [fWorksheet.getRange('A1:B2'), fWorksheet.getRange('D4:E5')]
const disposable = fWorksheet.highlightRanges(ranges, { fill: 'yellow' })

// To remove the highlights later
disposable.dispose()
```

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

### `FWorksheet.refreshCanvas`

Refresh the canvas.

```typescript
refreshCanvas(): FWorksheet
```

**Returns**

The FWorksheet instance for chaining.

**Examples**

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

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.scrollToCell`

Scroll spreadsheet(viewMain) to cell position. Make the cell at topleft of current viewport.
Based on the limitations of viewport and the number of rows and columns, you can only scroll to the maximum scrollable range.

```typescript
scrollToCell(row: number, column: number, duration?: number): FWorksheet
```

**Parameters**

* `row` — Required. Cell row index
* `column` — Required. Cell column index
* `duration` — Optional. The duration of the scroll animation in milliseconds.

**Returns**

* The FWorksheet instance for chaining.

**Examples**

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

// Scroll to cell D10
const fRange = fWorksheet.getRange('D10')
const row = fRange.getRow()
const column = fRange.getColumn()
fWorksheet.scrollToCell(row, column)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setColumnHeaderHeight`

Sets the height of the column header in pixels.

```typescript
setColumnHeaderHeight(height: number): FWorksheet
```

**Parameters**

* `height` — Required. The height to set.

**Returns**

* The FWorksheet instance for chaining.

**Examples**

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

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.setRowHeaderWidth`

Sets the width of the row header in pixels.

```typescript
setRowHeaderWidth(width: number): FWorksheet
```

**Parameters**

* `width` — Required. The width to set.

**Returns**

* The FWorksheet instance for chaining.

**Examples**

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

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

### `FWorksheet.zoom`

Set zoom ratio of the worksheet.

```typescript
zoom(zoomRatio: number): FWorksheet
```

**Parameters**

* `zoomRatio` — Required. The zoom ratio to set.It should be in the range of 0.1 to 4.0.

**Returns**

The FWorksheet instance for chaining.

**Examples**

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

// Set zoom ratio to 200%
fWorksheet.zoom(2)
const zoomRatio = fWorksheet.getZoom()
console.log(zoomRatio) // 2
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.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-worksheet.d.ts)

## `@univerjs-pro/sheets-chart`

### `FWorksheet.getChart`

Returns a Chart on this worksheet by its stable Chart identifier.

```typescript
getChart(chartId: string): FSheetChart | null
```

**Parameters**

* `chartId` — Required. The identifier returned by `FSheetChart.getId`.

**Returns**

A live Sheet Chart facade, or `null` if the Chart does not exist on this worksheet.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')

const firstChart = fWorksheet.getCharts()[0]
const fChart = firstChart ? fWorksheet.getChart(firstChart.getId()) : null
console.log(fChart?.getInfo())
```

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

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

### `FWorksheet.getCharts`

Returns all Charts on this worksheet.

```typescript
getCharts(): FSheetChart[]
```

**Returns**

Live Sheet Chart facades in the worksheet's model order.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')

const fCharts = fWorksheet.getCharts()
fCharts.forEach((fChart) => {
  console.log(fChart.getId(), fChart.getInfo())
})
```

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

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

### `FWorksheet.insertChart`

Inserts a Chart into this worksheet from detached Chart information.

```typescript
insertChart(info: ISheetChartInfo): Promise<FSheetChart>
```

**Parameters**

* `info` — Required. The Chart configuration, Sheet data source, and optional placement produced by a Chart builder.

**Returns**

A live facade for the inserted Sheet Chart.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')

const chartInfo = fWorksheet
  .newChart(univerAPI.Enum.ChartTypeString.Pie)
  .setSource('A1:B8')
  .setPosition('D2')
  .setSize(480, 320)
  .setDoughnutHole(0.4)
  .build()

const fChart = await fWorksheet.insertChart(chartInfo)
fChart.setPosition('E3')
```

**Types:** [`FSheetChart`](https://unpkg.com/@univerjs-pro/sheets-chart/lib/types/facade/f-chart.d.ts) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ISheetChartInfo`](https://unpkg.com/@univerjs-pro/sheets-chart/lib/types/chart-builder/types.d.ts)

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

### `FWorksheet.newChart`

Creates a detached, type-specific Chart builder for this worksheet.

```typescript
newChart<T extends ChartTypeString>(type: T): FSheetChartBuilderOf<T>
```

**Parameters**

* `type` — Required. The Chart type to create.

**Returns**

A detached builder that produces insertable Sheet Chart information.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')

const chartInfo = fWorksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    range: 'A1:D8',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setPosition('F2')
  .setSize(640, 360)
  .setTitle('Quarterly sales')
  .build()

const fChart = await fWorksheet.insertChart(chartInfo)
console.log(fChart.getId())
```

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

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

## `@univerjs-pro/sheets-outline`

### `FWorksheet.addColumnOutline`

Add a column outline group to the current worksheet.

The column index is zero-based. The group covers `numColumns` columns starting at
`startColumn`, so `addColumnOutline(0, 3)` groups columns A to C.
Invalid groups are ignored and will not be added, including negative ranges,
zero or negative column counts, ranges outside the worksheet, crossing groups,
and groups that exceed the maximum outline depth.

```typescript
addColumnOutline(startColumn: number, numColumns: number): FWorksheet
```

**Parameters**

* `startColumn` — Required. The zero-based start column index of the outline group.
* `numColumns` — Required. The number of columns included in the outline group.

**Returns**

The current worksheet instance, allowing chained facade calls.

**Examples**

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

// Group columns B to E.
fWorksheet.addColumnOutline(1, 4)
```

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

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

### `FWorksheet.addRowOutline`

Add a row outline group to the current worksheet.

The row index is zero-based. The group covers `numRows` rows starting at
`startRow`, so `addRowOutline(1, 3)` groups rows 2 to 4.
Invalid groups are ignored and will not be added, including negative ranges,
zero or negative row counts, ranges outside the worksheet, crossing groups,
and groups that exceed the maximum outline depth.

```typescript
addRowOutline(startRow: number, numRows: number): FWorksheet
```

**Parameters**

* `startRow` — Required. The zero-based start row index of the outline group.
* `numRows` — Required. The number of rows included in the outline group.

**Returns**

The current worksheet instance, allowing chained facade calls.

**Examples**

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

// Group rows 2 to 6.
fWorksheet.addRowOutline(1, 5)
```

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

// Facade methods return the worksheet, so calls can be chained.
fWorksheet.addRowOutline(1, 5).addRowOutline(2, 2)
```

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

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

### `FWorksheet.clearDimensionOutlines`

Clear outline groups in a row or column range.

The range uses zero-based indexes and is inclusive: `[start, end]`. Only outline
groups on the specified axis whose ranges are fully contained in this range are removed.

```typescript
clearDimensionOutlines(axis: DimensionOutlineAxis, start: number, end: number): FWorksheet
```

**Parameters**

* `axis` — Required. The outline axis to clear.
* `start` — Required. The zero-based inclusive start index of the clear range.
* `end` — Required. The zero-based inclusive end index of the clear range.

**Returns**

The current worksheet instance, allowing chained facade calls.

**Examples**

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

// Remove row outline groups fully contained in rows 2 to 10.
fWorksheet.clearDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW, 1, 9)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`DimensionOutlineAxis`](https://unpkg.com/@univerjs-pro/sheets-outline/lib/types/common/type.d.ts)

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

### `FWorksheet.getDimensionOutlines`

Get outline groups on the current worksheet.

When `axis` is omitted, both row and column outline groups are returned. The returned
array is a snapshot of the current outline data; use command or facade methods to make
changes instead of mutating the returned objects directly.

```typescript
getDimensionOutlines(axis?: DimensionOutlineAxis): IDimensionOutline[]
```

**Parameters**

* `axis` — Optional. Optional outline axis filter.

**Returns**

The outline groups on the current worksheet.

**Examples**

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

const rowOutlines = fWorksheet.getDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW)
rowOutlines.forEach((outline) => {
  console.log(outline.id, outline.start, outline.end, outline.collapsed)
})
```

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

const allOutlines = fWorksheet.getDimensionOutlines()
const collapsedOutlines = allOutlines.filter((outline) => outline.collapsed)
console.log('Collapsed outlines:', collapsedOutlines)
```

**Types:** [`IDimensionOutline`](https://unpkg.com/@univerjs-pro/sheets-outline/lib/types/common/type.d.ts) · [`DimensionOutlineAxis`](https://unpkg.com/@univerjs-pro/sheets-outline/lib/types/common/type.d.ts)

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

### `FWorksheet.removeDimensionOutline`

Remove a row or column outline group from the current worksheet.

Use `getDimensionOutlines()` to read the current outline ids. Removing a parent outline
does not remove unrelated sibling outlines.

```typescript
removeDimensionOutline(outlineId: string): FWorksheet
```

**Parameters**

* `outlineId` — Required. The id of the outline group to remove.

**Returns**

The current worksheet instance, allowing chained facade calls.

**Examples**

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

const [firstRowOutline] = fWorksheet.getDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW)
if (firstRowOutline) {
  fWorksheet.removeDimensionOutline(firstRowOutline.id)
}
```

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

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

### `FWorksheet.setDimensionOutlineCollapsed`

Collapse or expand an existing row or column outline group.

Pass `true` to collapse the group and hide its grouped rows or columns. Pass `false`
to expand it and show the grouped rows or columns again, subject to other nested
collapsed groups.

```typescript
setDimensionOutlineCollapsed(outlineId: string, collapsed: boolean): FWorksheet
```

**Parameters**

* `outlineId` — Required. The id of the outline group to update.
* `collapsed` — Required. Whether the outline group should be collapsed.

**Returns**

The current worksheet instance, allowing chained facade calls.

**Examples**

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

const [firstColumnOutline] = fWorksheet.getDimensionOutlines(
  univerAPI.Enum.DimensionOutlineAxis.COLUMN,
)
if (firstColumnOutline) {
  // Collapse the group.
  fWorksheet.setDimensionOutlineCollapsed(firstColumnOutline.id, true)

  // Expand it later.
  fWorksheet.setDimensionOutlineCollapsed(firstColumnOutline.id, false)
}
```

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

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

## `@univerjs-pro/sheets-pivot`

### `FWorksheet.getPivotTableByCell`

Get the pivot table id by the cell in current sheet.

```typescript
getPivotTableByCell(row: number, col: number): FPivotTable | undefined
```

**Parameters**

* `row` — Required. The checked row.
* `col` — Required. The checked column.

**Returns**

The pivot table instance or undefined.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const pivotTable = fWorksheet.getPivotTableByCell(1, 1)
if (pivotTable) {
  pivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0)
}
```

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

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

## `@univerjs-pro/sheets-pivot-chart`

### `FWorksheet.getPivotChart`

Returns a PivotChart on this worksheet by its stable identifier.

```typescript
getPivotChart(pivotChartId: string): FSheetPivotChart | null
```

**Parameters**

* `pivotChartId` — Required. The identifier returned by `FSheetPivotChart.getId`.

**Returns**

A live facade, or `null` if it is absent from this worksheet.

**Types:** [`FSheetPivotChart`](https://docs.univer.ai/ko-KR/reference/facade/sheet-pivot-chart.md)

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

### `FWorksheet.getPivotCharts`

Returns every PivotChart hosted by this worksheet.

```typescript
getPivotCharts(): FSheetPivotChart[]
```

**Returns**

Live PivotChart facades in model order.

**Types:** [`FSheetPivotChart`](https://docs.univer.ai/ko-KR/reference/facade/sheet-pivot-chart.md)

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

### `FWorksheet.insertPivotChart`

Inserts a PivotChart from detached Builder information.

```typescript
insertPivotChart(info: ISheetPivotChartInfo): Promise<FSheetPivotChart>
```

**Parameters**

* `info` — Required. The PivotChart configuration, source, controls, and placement.

**Returns**

A live facade after the model and Drawing are created.

**Throws**

If the source, type, placement, or insertion is invalid.

**Types:** [`FSheetPivotChart`](https://docs.univer.ai/ko-KR/reference/facade/sheet-pivot-chart.md) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ISheetPivotChartInfo`](https://unpkg.com/@univerjs-pro/sheets-pivot-chart/lib/types/types.d.ts)

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

### `FWorksheet.newPivotChart`

Creates a detached, type-specific PivotChart Builder for this worksheet.

```typescript
newPivotChart<T extends PivotChartTypeString>(type: T): FSheetPivotChartBuilderOf<T>
```

**Parameters**

* `type` — Required. The supported Chart type.

**Returns**

A detached Builder that produces insertable PivotChart information.

**Examples**

```ts
import '@univerjs-pro/sheets-pivot-chart/facade'

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sales')
const info = fWorksheet
  .newPivotChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource('A1:G100')
  .setPosition('J2')
  .setSize(640, 360)
  .build()
const fPivotChart = await fWorksheet.insertPivotChart(info)
console.log(fPivotChart.getId())
```

**Types:** [`FSheetPivotChartBuilderOf`](https://unpkg.com/@univerjs-pro/sheets-pivot-chart/lib/types/facade/f-pivot-chart-builder.d.ts)

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

## `@univerjs-pro/sheets-shape`

### `FWorksheet.getShape`

Returns a worksheet Shape by its stable identifier.

```typescript
getShape(shapeId: string): FSheetShape | FConnectorShape | null
```

**Parameters**

* `shapeId` — Required.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fShape = fWorksheet.getShape('shape-1')
console.log(fShape)
```

**Types:** [`FSheetShape`](https://docs.univer.ai/ko-KR/reference/facade/sheet-shape.md) · [`FConnectorShape`](https://docs.univer.ai/ko-KR/reference/facade/connector-shape.md)

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

### `FWorksheet.getShapes`

Returns all Shapes and Connectors on this worksheet.

```typescript
getShapes(): Array<FSheetShape | FConnectorShape>
```

**Returns**

An array of live Sheet Shape facades.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fShapes = fWorksheet.getShapes()
console.log(fShapes)
```

**Types:** [`FSheetShape`](https://docs.univer.ai/ko-KR/reference/facade/sheet-shape.md) · [`FConnectorShape`](https://docs.univer.ai/ko-KR/reference/facade/connector-shape.md) · [`Array`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

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

### `FWorksheet.insertShape`

Inserts a Shape or Connector into this worksheet.

```typescript
insertShape(input: IShapeCreateInput): FSheetShape | FConnectorShape | null
```

**Parameters**

* `input` — Required. Common Shape creation input.

**Returns**

A live Sheet Shape facade, or `null` when creation fails.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
if (!fWorkbook) throw new Error('No active workbook.')
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('Worksheet not found.')
const fShape = fWorksheet.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,
  transform: { left: 120, top: 80, width: 240, height: 120 },
  shapeData: {
    fill: { fillType: univerAPI.Enum.ShapeFillEnum.SolidFill, color: '#dbeafe' },
    stroke: {
      lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,
      color: '#2563eb',
      width: 2,
    },
  },
})
if (!fShape) throw new Error('Shape could not be inserted.')

fShape
  .setRotation(8)
  .setStrokeLineDashType(univerAPI.Enum.ShapeLineDashEnum.Dash)
  .setAbsolutePosition(480, 160)

fShape
  .getText()
  .setText('Sheet review')
  .setHorizontalAlign(univerAPI.Enum.HorizontalAlign.CENTER)
  .setVerticalAlign(univerAPI.Enum.VerticalAlign.MIDDLE)
```

**Types:** [`FSheetShape`](https://docs.univer.ai/ko-KR/reference/facade/sheet-shape.md) · [`FConnectorShape`](https://docs.univer.ai/ko-KR/reference/facade/connector-shape.md) · [`IShapeCreateInput`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/services/shape-host-adapter.service.d.ts)

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

## `@univerjs-pro/sheets-sparkline`

### `FWorksheet.addSparkline`

Add sparkline to the worksheet.

```typescript
addSparkline(sourceRanges: IRange[], targetRanges: IRange[], type: SparklineTypeEnum.LINE_CHART): FSparkline | undefined
```

**Parameters**

* `sourceRanges` — Required. Source data location for sparklines
* `targetRanges` — Required. Where to place sparklines
* `type` — Required. The type of Sparklines

**Returns**

Returns the sparkline instance for the next call

**Examples**

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

// Create a sparkline in the range A10, with the data source in the range A1:A7.
const sourceRanges = [fWorksheet.getRange('A1:A7').getRange()]
const targetRanges = [fWorksheet.getRange('A10').getRange()]
const sparkline = fWorksheet.addSparkline(
  sourceRanges,
  targetRanges,
  univerAPI.Enum.SparklineTypeEnum.LINE_CHART,
)
console.log('sparkline instance', sparkline)
```

**Types:** [`FSparkline`](https://docs.univer.ai/ko-KR/reference/facade/sparkline.md) · [`IRange`](https://docs.univer.ai/ko-KR/reference/types/range.md) · [`SparklineTypeEnum.LINE_CHART`](https://unpkg.com/@univerjs-pro/sheets-sparkline/lib/types/common/type.d.ts)

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

### `FWorksheet.composeSparkline`

Group the sparklines in the selection into a new sparkline group

```typescript
composeSparkline(ranges: IRange[]): void
```

**Parameters**

* `ranges` — Required. The selection range to be grouped

**Examples**

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

// Create a sparkline in the range A10, with the data source in the range A1:A7.
const firstSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('A1:A7').getRange()],
  [fWorksheet.getRange('A10').getRange()],
)
// Create a sparkline in the range B10, with the data source in the range B1:B7.
const secondSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('B1:B7').getRange()],
  [fWorksheet.getRange('B10').getRange()],
)
console.log('debugger', fWorksheet.getAllSubSparkline().size) // 2

// Compose the two sparklines into one group after 3 seconds
setTimeout(() => {
  fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])
  console.log('debugger', fWorksheet.getAllSubSparkline().size) // 1
}, 3000)
```

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

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

### `FWorksheet.getAllSubSparkline`

Get all sparklines in the worksheet.

```typescript
getAllSubSparkline(): Map<string, ISparklineGroup> | undefined
```

**Returns**

* The key is sparkline group id.

**Examples**

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

// Get all sparklines in the current worksheet
const allSparkline = fWorksheet.getAllSubSparkline()
console.log('allSparkline', allSparkline)
```

**Types:** [`Map`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es2015.collection.d.ts) · [`ISparklineGroup`](https://unpkg.com/@univerjs-pro/sheets-sparkline/lib/types/common/type.d.ts)

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

### `FWorksheet.getSparklineByCell`

Get the sparkline instance of the current cell

```typescript
getSparklineByCell(row: number, col: number): FSparkline | undefined
```

**Parameters**

* `row` — Required. The row index of the cell, start at 0.
* `col` — Required. The column index of the cell, start at 0.

**Returns**

Returns the sparkline instance for the next call

**Examples**

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

// Create a sparkline in the range A10, with the data source in the range A1:A7.
const sourceRanges = [fWorksheet.getRange('A1:A7').getRange()]
const targetRanges = [fWorksheet.getRange('A10').getRange()]
const sparkline = fWorksheet.addSparkline(sourceRanges, targetRanges)

console.log('Cell A10: ', fWorksheet.getSparklineByCell(9, 0))
console.log('Cell A11: ', fWorksheet.getSparklineByCell(10, 0))
```

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

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

### `FWorksheet.getSparklineGroupByCell`

Get the sparkline groups instance of the current cell

```typescript
getSparklineGroupByCell(row: number, col: number): FSparklineGroup | undefined
```

**Parameters**

* `row` — Required. The row index of the cell, start at 0.
* `col` — Required. The column index of the cell, start at 0.

**Returns**

Returns the sparkline group instance for the next call

**Examples**

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

// Create a sparkline in the range A10, with the data source in the range A1:A7.
const firstSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('A1:A7').getRange()],
  [fWorksheet.getRange('A10').getRange()],
)
// Create a sparkline in the range B10, with the data source in the range B1:B7.
const secondSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('B1:B7').getRange()],
  [fWorksheet.getRange('B10').getRange()],
)
console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))

// Compose the two sparklines into one group after 3 seconds
setTimeout(() => {
  fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])
  console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))
}, 3000)
```

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

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

### `FWorksheet.unComposeSparkline`

Split the sparkline group within the current selection

```typescript
unComposeSparkline(ranges: IRange[]): void
```

**Parameters**

* `ranges` — Required. The selection range to be ungrouped

**Examples**

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

// Create a sparkline in the range A10, with the data source in the range A1:A7.
const firstSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('A1:A7').getRange()],
  [fWorksheet.getRange('A10').getRange()],
)
// Create a sparkline in the range B10, with the data source in the range B1:B7.
const secondSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('B1:B7').getRange()],
  [fWorksheet.getRange('B10').getRange()],
)

// Compose the two sparklines into one group
fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])
console.log('debugger', fWorksheet.getAllSubSparkline().size) // 1

// Uncompose the sparkline group after 3 seconds
setTimeout(() => {
  fWorksheet.unComposeSparkline([fWorksheet.getRange('A10:B10').getRange()])
  console.log('debugger', fWorksheet.getAllSubSparkline().size) // 2
}, 3000)
```

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

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