# Univer Sheets API

- Human documentation: [https://docs.univer.ai/guides/sheets/features/core/sheets-api](https://docs.univer.ai/guides/sheets/features/core/sheets-api)

- Agent Markdown: [https://docs.univer.ai/guides/sheets/features/core/sheets-api.md](https://docs.univer.ai/guides/sheets/features/core/sheets-api.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [sheets/features/core/sheets-api.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/core/sheets-api.mdx)

---

Univer Sheets provides professional-grade spreadsheet capabilities, with concepts designed to be as consistent as possible with Microsoft Excel.

## Importing

```typescript
import '@univerjs/sheets/facade'
import '@univerjs/sheets-ui/facade'
```

## Workbook

A workbook contains multiple worksheets and can be thought of as an Excel file.

The `unitId` can be used as a unique identifier for the workbook.

### Create a Workbook

The [`univerAPI.createWorkbook(data, options)`](https://docs.univer.ai/reference/facade/univer.md#createworkbook) method creates and returns the `FWorkbook` object.

The [`IWorkbookData`](https://docs.univer.ai/guides/sheets/model/workbook-data.md) is an object that contains the configuration information of the workbook.

```typescript
const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' })
console.log(fWorkbook)
```

Add you can make the workbook not as the active workbook by setting options:

```typescript
const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' }, { makeCurrent: false })
console.log(fWorkbook)

// If you want to switch to this workbook after 3 seconds
setTimeout(() => {
  univerAPI.setCurrent(fWorkbook.getId())
}, 3000)
```

### Get Workbook Data

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const snapshot = fWorkbook.save()
console.log(snapshot)
```

### Unload Workbook

When you no longer need a `Workbook`, you can call the `disposeUnit` method on the API instance to unload it.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook?.getId()
if (unitId) {
  univerAPI.disposeUnit(unitId)
}
```

> [!WARNING]
> When the entire page hosting the Univer instance is destroyed or the route is unloaded, make sure to call the `univer.dispose()` method for cleanup, rather than using `univerAPI.disposeUnit`.
> Also, please note that `univer` and `univerAPI` are different instances. For instructions on how to obtain these instances, refer to the [Installation & Basic Usage](https://docs.univer.ai/guides/sheets/getting-started/installation.md).

### Get Workbook ID

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook?.getId()
```

## Worksheet

Worksheets store table data, worksheets belong to the workbook.

A workbook can contain multiple worksheets, and the names of worksheets in the same workbook cannot be duplicated.

The `subUnitId` can be used to uniquely identify a sheet in a workbook.

### Get Worksheets

Get all sheets in a sheet

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const sheets = fWorkbook.getSheets()
```

Get Active Worksheet

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
```

### Get Worksheet Data

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const sheetSnapshot = fWorksheet.getSheet().getSnapshot()
```

### Create a Worksheet

The following example shows how to create a worksheet using the [`FWorkbook.create`](https://docs.univer.ai/reference/facade/workbook.md#create) method.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()

// Create a worksheet named 'Sheet2' with 10 rows and 10 columns
const newSheet = fWorkbook.create('Sheet2', 10, 10)

// Create a new sheet named 'MyNewSheetWithData' with 10 rows and 10 columns and some data, and set it as the first sheet
const sheetData = {
  // ... Omit other properties
  cellData: {
    0: {
      0: {
        v: 'Hello Univer!',
      },
    },
  },
  // ... Omit other properties
}
const newSheetWithData = fWorkbook.create('MyNewSheetWithData', 10, 10, {
  index: 0,
  sheet: sheetData,
})
console.log(newSheetWithData)
```

### Remove Worksheet

Remove Worksheet by passing the worksheet instance or the worksheet Id

```typescript
// Delete the second worksheet
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.deleteSheet(sheet)

// The code below deletes the specified worksheet by id
// fWorkbook.deleteSheet(sheet.getSheetId());
```

### Activate Worksheet

Activate the worksheet by passing the worksheet instance or the worksheet Id, or use `FWorksheet.activate()` method.

```typescript
// Activate the second worksheet
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.setActiveSheet(sheet)

// Activates the specified worksheet by id
// fWorkbook.setActiveSheet(sheet.getSheetId());

// Activate the worksheet using the FWorksheet.activate() method
// sheet.activate();
```

### Copy Worksheet

```typescript
// The code below duplicates the given worksheet
const fWorkbook = univerAPI.getActiveWorkbook()
const activeSheet = fWorkbook.getActiveSheet()
const duplicatedSheet = fWorkbook.duplicateSheet(activeSheet)
console.log(duplicatedSheet)
```

### Get Worksheet ID

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
fWorksheet?.getSheetId()
```

### Set Worksheet Row and Column Count

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
// Set row count to 100000
fWorksheet.setRowCount(100000)
// Set column count to 30
fWorksheet.setColumnCount(30)
```

### Refresh Worksheet

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
fWorksheet.refreshCanvas()
```

### Worksheet Zoom

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Set zoom ratio to 200%
fWorksheet.zoom(2)
const zoomRatio = fWorksheet.getZoom()
```

### Scroll to Cell

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

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

// Add scroll animation duration
fWorksheet.scrollToCell(row, column, 1000)

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

## Core Features

### Permission

Reference: [Permission](https://docs.univer.ai/guides/sheets/features/core/permission.md)

### Formula

Reference: [Formula](https://docs.univer.ai/guides/sheets/features/core/formula.md)

### Row and Column

Reference: [Row and Column](https://docs.univer.ai/guides/sheets/features/core/row-col.md)

### Range

Reference: [Range](https://docs.univer.ai/guides/sheets/features/core/range-selection.md#range)

### Selection

Reference: [Selection](https://docs.univer.ai/guides/sheets/features/core/range-selection.md#selection)

### Cell

Reference: [Cell](https://docs.univer.ai/guides/sheets/features/core/range-selection.md#cell)

### Freeze

Reference: [Freeze](https://docs.univer.ai/guides/sheets/features/core/freeze.md)

### Integrating Custom Components into Univer

Reference: [Integrating Custom Components into Univer](https://docs.univer.ai/guides/sheets/ui/components.md)

## Reference

Please refer to the following API documentation for more information:

* [FWorkbook](https://docs.univer.ai/reference/facade/workbook.md)
* [FWorksheet](https://docs.univer.ai/reference/facade/worksheet.md)