# Univer Sheets API

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [sheets/features/core/sheets-api.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/core/sheets-api.zh-TW.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-TW/reference/facade/univer.md#createworkbook) 方法會建立並回傳 `FWorkbook` 實例。

[`IWorkbookData`](https://docs.univer.ai/zh-TW/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-TW/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-TW/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-TW/guides/sheets/features/core/permission.md)

### 公式

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

### 行列操作

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

### 範圍 Range

參考：[範圍 Range](https://docs.univer.ai/zh-TW/guides/sheets/features/core/range-selection.md#range)

### 選取區域 Selection

參考：[選取區域 Selection](https://docs.univer.ai/zh-TW/guides/sheets/features/core/range-selection.md#selection)

### 儲存格 Cell

參考：[儲存格 Cell](https://docs.univer.ai/zh-TW/guides/sheets/features/core/range-selection.md#cell)

### 凍結

參考：[凍結](https://docs.univer.ai/zh-TW/guides/sheets/features/core/freeze.md)

### 整合自訂元件

參考：[整合自訂元件](https://docs.univer.ai/zh-TW/guides/sheets/ui/components.md)

## 參考

更多 API 請查看：

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