# API Univer Sheets

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

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

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.2.0`

- Source: [sheets/features/core/sheets-api.ru-RU.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/core/sheets-api.ru-RU.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/ru-RU/reference/facade/univer.md#createworkbook) создаёт и возвращает объект `FWorkbook`.

Объект [`IWorkbookData`](https://docs.univer.ai/ru-RU/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` больше не нужна, вызовите метод `disposeUnit` экземпляра API, чтобы выгрузить её.

```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/ru-RU/guides/sheets/getting-started/installation.md).

### Получение идентификатора книги

```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/ru-RU/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)
```

### Удаление листа

Удалите лист, передав его экземпляр или идентификатор.

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

### Активация листа

Чтобы активировать лист, передайте его экземпляр или идентификатор либо вызовите метод `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)
```

### Получение идентификатора листа

```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/ru-RU/guides/sheets/features/core/permission.md).

### Формулы

См. раздел [Формулы](https://docs.univer.ai/ru-RU/guides/sheets/features/core/formula.md).

### Строки и столбцы

См. раздел [Строки и столбцы](https://docs.univer.ai/ru-RU/guides/sheets/features/core/row-col.md).

### Диапазон

См. раздел [Диапазон](https://docs.univer.ai/ru-RU/guides/sheets/features/core/range-selection.md#range).

### Выделение

См. раздел [Выделение](https://docs.univer.ai/ru-RU/guides/sheets/features/core/range-selection.md#selection).

### Ячейка

См. раздел [Ячейка](https://docs.univer.ai/ru-RU/guides/sheets/features/core/range-selection.md#cell).

### Закрепление

См. раздел [Закрепление](https://docs.univer.ai/ru-RU/guides/sheets/features/core/freeze.md).

### Интеграция пользовательских компонентов в Univer

См. раздел [Интеграция пользовательских компонентов в Univer](https://docs.univer.ai/ru-RU/guides/sheets/ui/components.md).

## Справочник

Дополнительные сведения см. в следующей документации по API:

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