# Univer Sheets API

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

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

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

- Source: [sheets/features/core/sheets-api.ko-KR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/core/sheets-api.ko-KR.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/ko-KR/reference/facade/univer.md#createworkbook) 메서드는 `FWorkbook` 객체를 만들어 반환합니다.

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

// If you want to switch to this workbook after 3 seconds
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/ko-KR/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/ko-KR/reference/facade/workbook.md#create) 메서드를 사용해 워크시트를 만드는 방법을 보여 줍니다.

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

### 워크시트 삭제하기

워크시트 인스턴스 또는 워크시트 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());
```

### 워크시트 활성화하기

워크시트 인스턴스 또는 워크시트 ID를 전달하거나 `FWorksheet.activate()` 메서드를 사용해 워크시트를 활성화합니다.

```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();
```

### 워크시트 복사하기

```typescript
// The code below duplicates the given worksheet
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()
// Set row count to 100000
fWorksheet.setRowCount(100000)
// Set column count to 30
fWorksheet.setColumnCount(30)
```

### 워크시트 새로 고침하기

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

### 워크시트 확대/축소

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

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

### 셀로 스크롤하기

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

## 핵심 기능

### 권한

참고: [권한](https://docs.univer.ai/ko-KR/guides/sheets/features/core/permission.md)

### 수식

참고: [수식](https://docs.univer.ai/ko-KR/guides/sheets/features/core/formula.md)

### 행과 열

참고: [행과 열](https://docs.univer.ai/ko-KR/guides/sheets/features/core/row-col.md)

### 범위

참고: [범위](https://docs.univer.ai/ko-KR/guides/sheets/features/core/range-selection.md#range)

### 선택 영역

참고: [선택 영역](https://docs.univer.ai/ko-KR/guides/sheets/features/core/range-selection.md#selection)

### 셀

참고: [셀](https://docs.univer.ai/ko-KR/guides/sheets/features/core/range-selection.md#cell)

### 틀 고정

참고: [틀 고정](https://docs.univer.ai/ko-KR/guides/sheets/features/core/freeze.md)

### Univer에 사용자 지정 컴포넌트 통합하기

참고: [Univer에 사용자 지정 컴포넌트 통합하기](https://docs.univer.ai/ko-KR/guides/sheets/ui/components.md)

## 참고 자료

자세한 내용은 다음 API 문서를 참고하세요.

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