# 迷你图

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/zh-CN",
      "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/zh-CN",
      "style": "@univerjs-pro/sheets-sparkline-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

迷你图是一种简洁、直观的小型图表，通常嵌入在表格单元格中，用于快速展示数据趋势或关键指标。

## 预设模式

迷你图功能被包含在 `@univerjs/preset-sheets-advanced` 预设中。

### 安装

> [!NOTE]
> @univerjs/preset-sheets-advanced 的 `UniverSheetsAdvancedPreset` 预设在运行时依赖 `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 UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN' // [!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.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetSheetsCoreZhCN,
      UniverPresetSheetsDrawingZhCN, // [!code ++]
      UniverPresetSheetsAdvancedZhCN, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

如果你拥有 Univer 的商业许可证，请参考[在客户端使用许可证](https://docs.univer.ai/zh-CN/guides/license.md#in-preset-mode)进行配置。

## 插件模式

### 安装

#### 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 SheetsSparklineUIZhCN from '@univerjs-pro/sheets-sparkline-ui/locale/zh-CN' // [!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.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      SheetsSparklineUIZhCN, // [!code ++]
    ),
  },
})

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

如果你拥有 Univer 的商业许可证，请参考[在客户端使用许可证](https://docs.univer.ai/zh-CN/guides/license.md#in-plugin-mode)进行配置。

## Facade API

### 引入

> [!INFO: 插件模式提示]
> 仅插件模式需要手动引入 Facade 包。预设模式已内置对应的 Facade 包，无需额外导入。

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

### 添加迷你图

[`FWorksheet.addSparkline`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#addsparkline) 方法用于在指定区域添加迷你图，返回一个 `FSparkline` 实例。

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

// 创建一个迷你图，数据源为 A1:A7，放置在 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/zh-CN/reference/facade/worksheet.md#composesparkline) 和 [`FWorksheet.unComposeSparkline`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#uncomposesparkline) 方法用于组合和取消组合迷你图。

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

// 创建一个迷你图，数据源为 A1:A7，放置在 A10 单元格中。
const firstSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('A1:A7').getRange()],
  [fWorksheet.getRange('A10').getRange()],
)

// 创建一个迷你图，数据源为 B1:B7，放置在 B10 单元格中。
const secondSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('B1:B7').getRange()],
  [fWorksheet.getRange('B10').getRange()],
)

// 将两个迷你图组合成一个迷你图组
fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])
console.log(fWorksheet.getAllSubSparkline().size) // 1

// 3 秒后取消组合迷你图组
setTimeout(() => {
  fWorksheet.unComposeSparkline([fWorksheet.getRange('A10:B10').getRange()])
  console.log(fWorksheet.getAllSubSparkline().size) // 2
}, 3000)
```

### 获取迷你图和迷你图组实例

[`FWorksheet.getSparklineByCell`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#getsparklinebycell) 用于获取指定单元格内的迷你图实例，返回一个 `FSparkline` 实例。

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

// 创建一个迷你图，数据源为 A1:A7，放置在 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/zh-CN/reference/facade/worksheet.md#getsparklinegroupbycell) 用于获取指定单元格内的迷你图组实例，返回一个 `FSparklineGroup` 实例。

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

// 创建一个迷你图，数据源为 A1:A7，放置在 A10 单元格中。
const firstSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('A1:A7').getRange()],
  [fWorksheet.getRange('A10').getRange()],
)

// 创建一个迷你图，数据源为 B1:B7，放置在 B10 单元格中。
const secondSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('B1:B7').getRange()],
  [fWorksheet.getRange('B10').getRange()],
)
console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))

// 3 秒后将两个迷你图组合成一个迷你图组
setTimeout(() => {
  fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])
  console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))
}, 3000)
```

[`FSparkline`](https://docs.univer.ai/zh-CN/reference/facade/sparkline.md) 实例有以下方法用来操作迷你图：

| 方法               | 描述                   |
| ---------------- | -------------------- |
| changeDataSource | 修改当前单元格内迷你图的数据源和放置位置 |
| removeSparkline  | 删除当前单元格内的迷你图         |

[`FSparklineGroup`](https://docs.univer.ai/zh-CN/reference/facade/sparkline.md) 实例有以下方法用来操作迷你图组：

| 方法                   | 描述                     |
| -------------------- | ---------------------- |
| changeDataSource     | 修改当前单元格内迷你图组的数据源和放置位置  |
| removeSparklineGroup | 删除当前单元格内的迷你图所在的迷你图组    |
| setConfig            | 更改当前单元格内的迷你图所在的迷你图组的配置 |

### 事件监听

完整事件类型定义，请查看 [Events](https://docs.univer.ai/zh-CN/reference/facade/events.md)。

`univerAPI.Event.SheetSparklineChanged` 事件在迷你图发生变化时触发。

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

// 移除事件监听器，使用 `disposable.dispose()`
```