# Univer Sheets API

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

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

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.1.0`

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

---

Univer Sheets は プロフェッショナル グレード の スプレッドシート 機能を提供し、Microsoft Excel と可能な限り一貫性のある概念で設計されています。

## インポート

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

## ワークブック

ワークブックは複数のワークシートを含み、Excel ファイルとして考えることができます。

`unitId` はワークブックの一意識別子として使用できます。

### ワークブックの作成

[`univerAPI.createWorkbook(data, options)`](https://docs.univer.ai/ja-JP/reference/facade/univer.md#createworkbook) メソッドは `FWorkbook` オブジェクトを作成して返します。

[`IWorkbookData`](https://docs.univer.ai/ja-JP/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)

// 3 秒後にこのワークブックに切り替えたい場合
setTimeout(() => {
  univerAPI.setCurrent(fWorkbook.getId())
}, 3000)
```

### ワークブックデータの取得

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

### ワークブックのアンロード

`Workbook` が不要になった場合、API インスタンスの `disposeUnit` メソッドを呼び出してアンロードできます。

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

> [!WARNING]
> Univer インスタンスをホストしているページ全体が破棄されるか、ルートがアンロードされる場合は、`univerAPI.disposeUnit` ではなく、`univer.dispose()` メソッドを呼び出してクリーンアップを行ってください。
> また、`univer` と `univerAPI` は異なるインスタンスであることに注意してください。これらのインスタンスの取得方法については、[インストールと基本的な使用法](https://docs.univer.ai/ja-JP/guides/sheets/getting-started/installation.md)を参照してください。

### ワークブック ID の取得

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

## ワークシート

ワークシートはテーブルデータを格納し、ワークブックに属します。

ワークブックは複数のワークシートを含むことができ、同じワークブック内のワークシートの名前は重複できません。

`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/ja-JP/reference/facade/workbook.md#create) メソッドを使用してワークシートを作成する方法を示しています。

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

// 10 行 10 列の 'Sheet2' という名前のワークシートを作成
const newSheet = fWorkbook.create('Sheet2', 10, 10)

// 10 行 10 列の 'MyNewSheetWithData' という名前の新しいシートを作成し、いくつかのデータを含め、最初のシートとして設定します
const sheetData = {
  // ... その他のプロパティは省略
  cellData: {
    0: {
      0: {
        v: 'Hello Univer!',
      },
    },
  },
  // ... その他のプロパティは省略
}
const newSheetWithData = fWorkbook.create('MyNewSheetWithData', 10, 10, {
  index: 0,
  sheet: sheetData,
})
console.log(newSheetWithData)
```

### ワークシートの削除

ワークシートインスタンスまたはワークシート ID を渡してワークシートを削除

```typescript
// 2 番目のワークシートを削除
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.deleteSheet(sheet)

// 以下のコードは ID で指定されたワークシートを削除します
// fWorkbook.deleteSheet(sheet.getSheetId());
```

### ワークシートのアクティブ化

ワークシートインスタンスまたはワークシート ID を渡してワークシートをアクティブ化するか、`FWorksheet.activate()` メソッドを使用します。

```typescript
// 2 番目のワークシートをアクティブ化
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% に設定
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/ja-JP/guides/sheets/features/core/permission.md)

### 数式

参考：[数式](https://docs.univer.ai/ja-JP/guides/sheets/features/core/formula.md)

### 行と列

参考：[行と列](https://docs.univer.ai/ja-JP/guides/sheets/features/core/row-col.md)

### 範囲

参考：[範囲](https://docs.univer.ai/ja-JP/guides/sheets/features/core/range-selection.md#range)

### 選択

参考：[選択](https://docs.univer.ai/ja-JP/guides/sheets/features/core/range-selection.md#selection)

### セル

参考：[セル](https://docs.univer.ai/ja-JP/guides/sheets/features/core/range-selection.md#cell)

### 固定

参考：[固定](https://docs.univer.ai/ja-JP/guides/sheets/features/core/freeze.md)

### カスタムコンポーネントの Univer への統合

参考：[カスタムコンポーネントの Univer への統合](https://docs.univer.ai/ja-JP/guides/sheets/ui/components.md)

## リファレンス

詳細については、以下の API ドキュメントを参照してください：

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