# 스파크라인

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

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

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

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

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/ko-KR",
      "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/ko-KR",
      "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/ko-KR/server/license.md#in-plugin-mode)를 참고하세요.

## 모바일 지원

먼저 [모바일 에디터](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/installation.md#mobile-support)를 구성하세요. 이 페이지의 플러그인 모드 초기화 코드에서 아래 데스크톱 등록을 같은 패키지의 모바일 버전으로 바꾸고 **문서를 열기 전에** 완료하세요. 모델 플러그인, 스타일, 언어 파일과 Facade 가져오기는 유지하며 두 버전을 동시에 등록하지 마세요.

| 패키지                                 | 데스크톱 등록                        | 모바일 등록                               |
| ----------------------------------- | ------------------------------ | ------------------------------------ |
| `@univerjs-pro/sheets-sparkline-ui` | `UniverSheetSparklineUIPlugin` | `UniverSheetSparklineMobileUIPlugin` |

## 프리셋 모드

스파크라인 기능은 `@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 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/ko-KR/server/license.md#in-preset-mode)를 참고하세요.

## Facade API

### 가져오기

> [!INFO: 플러그인 모드 참고 사항]
> Facade 패키지를 직접 가져와야 하는 것은 플러그인 모드뿐입니다. 프리셋 모드에는 해당 Facade 패키지가 이미 포함되어 있으므로 별도로 가져올 필요가 없습니다.

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

### 스파크라인 추가

[`FWorksheet.addSparkline`](https://docs.univer.ai/ko-KR/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/ko-KR/reference/facade/worksheet.md#composesparkline) 및 [`FWorksheet.unComposeSparkline`](https://docs.univer.ai/ko-KR/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/ko-KR/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/ko-KR/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/ko-KR/reference/facade/sparkline.md) 인스턴스에는 스파크라인을 조작하는 다음 메서드가 있습니다.

| 메서드              | 설명                                |
| ---------------- | --------------------------------- |
| changeDataSource | 현재 셀에 있는 스파크라인의 데이터 소스와 배치를 변경합니다 |
| removeSparkline  | 현재 셀에 있는 스파크라인을 제거합니다             |

[`FSparklineGroup`](https://docs.univer.ai/ko-KR/reference/facade/sparkline-group.md) 인스턴스에는 스파크라인 그룹을 조작하는 다음 메서드가 있습니다.

| 메서드                  | 설명                                   |
| -------------------- | ------------------------------------ |
| changeDataSource     | 현재 셀에 있는 스파크라인 그룹의 데이터 소스와 배치를 변경합니다 |
| removeSparklineGroup | 현재 셀에 있는 스파크라인 그룹을 제거합니다             |
| setConfig            | 현재 셀에 있는 스파크라인 그룹의 구성을 변경합니다         |

### 이벤트 리스너

전체 이벤트 타입 정의는 [이벤트](https://docs.univer.ai/ko-KR/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/ko-KR/reference/facade/sparkline-group.md)을 참고하세요.