# Univer Sheets API

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

Univer Sheets 提供专业级电子表格能力，相关概念会尽可能与 Microsoft Excel 保持一致。

## 引入

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

## 工作簿 Workbook

一个工作簿里包含多个工作表，可以看作是一个 Excel 文件。

`unitId` 可用作工作簿的唯一标识。

### 创建工作簿

[`univerAPI.createWorkbook(data, options)`](https://docs.univer.ai/zh-CN/reference/facade/univer.md#createworkbook) 方法会创建并返回 `FWorkbook` 实例。

[`IWorkbookData`](https://docs.univer.ai/zh-CN/guides/sheets/model/workbook-data.md) 是一个对象，包含了工作簿的配置信息。

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

你可以设置一个选项，使添加的工作簿不成为活动工作簿

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

// 3s 后如果想切换到此工作簿
setTimeout(() => {
  univerAPI.setCurrent(fWorkbook.getId())
}, 3000)
```

### 获取工作簿数据

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

### 销毁工作簿

当我们不再需要工作簿时，可以调用 `FUniver` 的 `disposeUnit` 方法来销毁实例。

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

> [!WARNING]
> 当 Univer 实例挂载的整个页面被销毁或路由被卸载时，务必调用 `univer.dispose()` 方法进行清理，而不是使用 `univerAPI.disposeUnit`。
> 此外，`univer` 和 `univerAPI` 是两个不同的实例，关于如何获取它们的实例，请参考 [安装和基本使用](https://docs.univer.ai/zh-CN/guides/sheets/getting-started/installation.md)。

### 获取工作簿 ID

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

## 工作表 Worksheet

工作表中存储着表格数据，工作表属于工作薄，

一个工作薄可以包含多个工作表，同一个工作薄中工作表的名称不能重复。

`subUnitId` 可用作在工作薄中工作表的唯一标识。

### 获取工作表

获取工作薄中所有工作表

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

获取工作薄中当前激活的工作表

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

### 获取工作表数据

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

### 创建工作表

下面例子展示通过 [`FWorkbook.create`](https://docs.univer.ai/zh-CN/reference/facade/workbook.md#create) 方法创建一个工作表。

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

// 创建一个名为 'Sheet2' 的工作表，包含 10 行和 10 列
const newSheet = fWorkbook.create('Sheet2', 10, 10)

// 创建一个名为 'MyNewSheetWithData' 的新工作表，包含 10 行和 10 列，并带有一些数据，且将其设置为第一个工作表
const sheetData = {
  // ... 省略其他属性
  cellData: {
    0: {
      0: {
        v: 'Hello Univer!',
      },
    },
  },
  // ... 省略其他属性
}
const newSheetWithData = fWorkbook.create('MyNewSheetWithData', 10, 10, {
  index: 0,
  sheet: sheetData,
})
console.log(newSheetWithData)
```

### 删除工作表

通过传入工作表实例或工作表 ID 来删除工作表

```typescript
// 删除第二个工作表
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.deleteSheet(sheet)

// 下面的代码通过 id 删除指定的工作表
// fWorkbook.deleteSheet(sheet.getSheetId());
```

### 激活工作表

通过传入工作表实例或工作表 ID 来激活工作表, 或者通过 `FWorksheet.activate()` 方法激活工作表

```typescript
// 激活第二个工作表
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.setActiveSheet(sheet)

// 通过 id 激活指定的工作表
// fWorkbook.setActiveSheet(sheet.getSheetId());

// 通过 FWorksheet.activate() 方法激活工作表
// sheet.activate();
```

### 复制工作表

```typescript
// 以下代码用于复制指定的工作表
const fWorkbook = univerAPI.getActiveWorkbook()
const activeSheet = fWorkbook.getActiveSheet()
const duplicatedSheet = fWorkbook.duplicateSheet(activeSheet)
console.log(duplicatedSheet)
```

### 获取工作表 ID

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

### 设置工作表行列数

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
// 设置行数为 100000
fWorksheet.setRowCount(100000)
// 设置列数为 30
fWorksheet.setColumnCount(30)
```

### 刷新工作表

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

### 工作表缩放

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

// 200% 设置缩放比例为 200%
fWorksheet.zoom(2)
const zoomRatio = fWorksheet.getZoom()
```

### 滚动到指定位置

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

// 滚动到 D10 单元格
const fRange = fWorksheet.getRange('D10')
const row = fRange.getRow()
const column = fRange.getColumn()
fWorksheet.scrollToCell(row, column)

// 添加滚动动画持续时间
fWorksheet.scrollToCell(row, column, 1000)

// 获取滚动状态
const scrollState = fWorksheet.getScrollState()
const { offsetX, offsetY, sheetViewStartColumn, sheetViewStartRow } = scrollState
console.log(scrollState) // sheetViewStartRow: 9, sheetViewStartColumn: 3, offsetX: 0, offsetY: 0
```

## 核心功能

### 权限控制

参考：[权限控制](https://docs.univer.ai/zh-CN/guides/sheets/features/core/permission.md)

### 公式

参考：[公式](https://docs.univer.ai/zh-CN/guides/sheets/features/core/formula.md)

### 行列操作

参考：[行列操作](https://docs.univer.ai/zh-CN/guides/sheets/features/core/row-col.md)

### 范围 Range

参考：[范围 Range](https://docs.univer.ai/zh-CN/guides/sheets/features/core/range-selection.md#range)

### 选区 Selection

参考：[选区 Selection](https://docs.univer.ai/zh-CN/guides/sheets/features/core/range-selection.md#selection)

### 单元格 Cell

参考：[单元格 Cell](https://docs.univer.ai/zh-CN/guides/sheets/features/core/range-selection.md#cell)

### 冻结

参考：[冻结](https://docs.univer.ai/zh-CN/guides/sheets/features/core/freeze.md)

### 集成自定义组件

参考：[集成自定义组件](https://docs.univer.ai/zh-CN/guides/sheets/ui/components.md)

## 参考

更多 API 请查看：

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