# Спарклайн

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

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

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.2.0`

- Source: [sheets/features/sparkline.ru-RU.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/sparkline.ru-RU.mdx)

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/ru-RU",
      "style": "@univerjs/preset-sheets-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/sheets-sparkline",
      "facade": "@univerjs-pro/sheets-sparkline/facade"
    },
    {
      "client": "@univerjs-pro/sheets-sparkline-ui",
      "locale": "@univerjs-pro/sheets-sparkline-ui/locale/ru-RU",
      "style": "@univerjs-pro/sheets-sparkline-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

Спарклайн — это компактная встроенная диаграмма, которая наглядно показывает тенденции данных или ключевые показатели и обычно размещается прямо в ячейке таблицы.

## Режим плагинов

### Установка

#### npm

```bash
npm install @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-ui
```

#### yarn

```bash
yarn add @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-ui
```

#### bun

```bash
bun add @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-ui
```

### Использование

```typescript
import { UniverSheetSparklinePlugin } from '@univerjs-pro/sheets-sparkline' // [!code ++]
import { UniverSheetSparklineUIPlugin } from '@univerjs-pro/sheets-sparkline-ui' // [!code ++]
import SheetsSparklineUIEnUS from '@univerjs-pro/sheets-sparkline-ui/locale/en-US' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/sheets-sparkline/facade' // [!code ++]

import '@univerjs-pro/sheets-sparkline-ui/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      SheetsSparklineUIEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetSparklinePlugin)
univer.registerPlugin(UniverSheetSparklineUIPlugin)
```

Если у вас есть коммерческая лицензия Univer, инструкции по настройке см. в разделе [Использование лицензии в клиенте](https://docs.univer.ai/ru-RU/server/license.md#in-plugin-mode).

## Поддержка мобильных устройств

Сначала настройте [мобильный редактор](https://docs.univer.ai/ru-RU/guides/sheets/getting-started/installation.md#mobile-support). В коде инициализации режима плагинов на этой странице замените указанные настольные регистрации мобильными экспортами тех же пакетов **до открытия документа**. Сохраните модели, стили, локализации и импорты Facade; не регистрируйте оба варианта.

| Пакет                               | Настольная регистрация         | Мобильная регистрация                |
| ----------------------------------- | ------------------------------ | ------------------------------------ |
| `@univerjs-pro/sheets-sparkline-ui` | `UniverSheetSparklineUIPlugin` | `UniverSheetSparklineMobileUIPlugin` |

## Режим предустановки

Функция спарклайнов входит в предустановку `@univerjs/preset-sheets-advanced`.

### Установка

> [!NOTE]
> Во время выполнения предустановка `UniverSheetsAdvancedPreset` из `@univerjs/preset-sheets-advanced` зависит от `UniverSheetsDrawingPreset`. Сначала установите `@univerjs/preset-sheets-drawing`.

#### npm

```bash
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### bun

```bash
bun add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

### Использование

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced' // [!code ++]
import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-sheets-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDrawingEnUS, // [!code ++]
      UniverPresetSheetsAdvancedEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

Если у вас есть коммерческая лицензия Univer, инструкции по настройке см. в разделе [Использование лицензии в клиенте](https://docs.univer.ai/ru-RU/server/license.md#in-preset-mode).

## Facade API

### Импорт

> [!INFO: Примечание о режиме плагинов]
> Вручную импортировать пакет Facade нужно только в режиме плагинов. В режиме предустановки соответствующий пакет Facade уже подключён, поэтому дополнительный импорт не требуется.

```typescript
import '@univerjs-pro/sheets-sparkline/facade'
```

### Добавление спарклайна

Метод [`FWorksheet.addSparkline`](https://docs.univer.ai/ru-RU/reference/facade/worksheet.md#addsparkline) добавляет спарклайн в указанный диапазон и возвращает экземпляр `FSparkline`.

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

// Create a sparkline with data source from A1:A7, placed in cell A10.
const sourceRanges = [fWorksheet.getRange('A1:A7').getRange()]
const targetRanges = [fWorksheet.getRange('A10').getRange()]
const sparkline = fWorksheet.addSparkline(sourceRanges, targetRanges, univerAPI.Enum.SparklineTypeEnum.LINE_CHART)
```

### Объединение и разделение спарклайнов

Методы [`FWorksheet.composeSparkline`](https://docs.univer.ai/ru-RU/reference/facade/worksheet.md#composesparkline) и [`FWorksheet.unComposeSparkline`](https://docs.univer.ai/ru-RU/reference/facade/worksheet.md#uncomposesparkline) используются для объединения и разделения спарклайнов.

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

// Create a sparkline with data source from A1:A7, placed in cell A10.
const firstSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('A1:A7').getRange()],
  [fWorksheet.getRange('A10').getRange()],
)

// Create a sparkline with data source from B1:B7, placed in cell B10.
const secondSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('B1:B7').getRange()],
  [fWorksheet.getRange('B10').getRange()],
)

// Compose the two sparklines into a sparkline group
fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])
console.log(fWorksheet.getAllSubSparkline().size) // 1

// After 3 seconds, uncompose the sparkline group
setTimeout(() => {
  fWorksheet.unComposeSparkline([fWorksheet.getRange('A10:B10').getRange()])
  console.log(fWorksheet.getAllSubSparkline().size) // 2
}, 3000)
```

### Получение экземпляров спарклайна и группы спарклайнов

Метод [`FWorksheet.getSparklineByCell`](https://docs.univer.ai/ru-RU/reference/facade/worksheet.md#getsparklinebycell) получает спарклайн в указанной ячейке и возвращает экземпляр `FSparkline`.

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

// Create a sparkline with data source from A1:A7, placed in cell A10.
const sourceRanges = [fWorksheet.getRange('A1:A7').getRange()]
const targetRanges = [fWorksheet.getRange('A10').getRange()]
const sparkline = fWorksheet.addSparkline(sourceRanges, targetRanges)

console.log('Cell A10: ', fWorksheet.getSparklineByCell(9, 0))
console.log('Cell A11: ', fWorksheet.getSparklineByCell(10, 0))
```

Метод [`FWorksheet.getSparklineGroupByCell`](https://docs.univer.ai/ru-RU/reference/facade/worksheet.md#getsparklinegroupbycell) получает группу спарклайнов в указанной ячейке и возвращает экземпляр `FSparklineGroup`.

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

// Create a sparkline with data source from A1:A7, placed in cell A10.
const firstSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('A1:A7').getRange()],
  [fWorksheet.getRange('A10').getRange()],
)

// Create a sparkline with data source from B1:B7, placed in cell B10.
const secondSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('B1:B7').getRange()],
  [fWorksheet.getRange('B10').getRange()],
)
console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))

// After 3 seconds, compose the two sparklines into a sparkline group
setTimeout(() => {
  fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])
  console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))
}, 3000)
```

Экземпляр [`FSparkline`](https://docs.univer.ai/ru-RU/reference/facade/sparkline.md) предоставляет следующие методы для работы со спарклайном:

| Метод            | Описание                                                            |
| ---------------- | ------------------------------------------------------------------- |
| changeDataSource | Изменить источник данных и расположение спарклайна в текущей ячейке |
| removeSparkline  | Удалить спарклайн из текущей ячейки                                 |

Экземпляр [`FSparklineGroup`](https://docs.univer.ai/ru-RU/reference/facade/sparkline-group.md) предоставляет следующие методы для работы с группой спарклайнов:

| Метод                | Описание                                                                    |
| -------------------- | --------------------------------------------------------------------------- |
| changeDataSource     | Изменить источник данных и расположение группы спарклайнов в текущей ячейке |
| removeSparklineGroup | Удалить группу спарклайнов из текущей ячейки                                |
| setConfig            | Изменить конфигурацию группы спарклайнов в текущей ячейке                   |

### Обработчики событий

Полные определения типов событий доступны в разделе [События](https://docs.univer.ai/ru-RU/reference/facade/events.md).

Событие `univerAPI.Event.SheetSparklineChanged` срабатывает при изменении спарклайна.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetSparklineChanged, (params) => {
  const { workbook, worksheet, sparklines } = params
})

// Remove the event listener, use `disposable.dispose()`
```

## Цвета и параметры отображения

Для настройки цветов и отображения всей группы используйте `FSparklineGroup.setConfig()`. Отдельного метода `FSparkline.setColor()` нет. Для собственного цвета задайте `seriesColor` и `themeType: SparklineThemeTypeEnum.CUSTOM`. Полный список параметров и примеры настройки маркеров, осей, максимума и минимума, пустых и скрытых ячеек, а также толщины линии приведены в разделе [настройки группы спарклайнов](https://docs.univer.ai/ru-RU/reference/facade/sparkline-group.md).