# スパークライン

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

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

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.1.0`

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

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/ja-JP",
      "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/ja-JP",
      "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 SheetsSparklineUIJaJP from '@univerjs-pro/sheets-sparkline-ui/locale/ja-JP' // [!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.JA_JP,
  locales: {
    [LocaleType.JA_JP]: mergeLocales(
      SheetsSparklineUIJaJP, // [!code ++]
    ),
  },
})

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

Univer に商用ライセンスをお持ちの場合は、設定方法については [クライアントでのライセンスの使用](https://docs.univer.ai/ja-JP/server/license.md#in-plugin-mode) を参照してください。

## モバイル対応

まず[モバイルエディター](https://docs.univer.ai/ja-JP/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 UniverPresetSheetsAdvancedJaJP from '@univerjs/preset-sheets-advanced/locales/ja-JP' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreJaJP from '@univerjs/preset-sheets-core/locales/ja-JP'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingJaJP from '@univerjs/preset-sheets-drawing/locales/ja-JP' // [!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.JA_JP,
  locales: {
    [LocaleType.JA_JP]: mergeLocales(
      UniverPresetSheetsCoreJaJP,
      UniverPresetSheetsDrawingJaJP, // [!code ++]
      UniverPresetSheetsAdvancedJaJP, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

Univer に商用ライセンスをお持ちの場合は、設定方法については [クライアントでのライセンスの使用](https://docs.univer.ai/ja-JP/server/license.md#in-preset-mode) を参照してください。

## Facade API

### インポート

> [!INFO: プラグインモード注意]
> Facade パッケージの手動 import が必要なのはプラグインモードのみです。プリセットモードには対応する Facade パッケージが内蔵されているため、追加の import は不要です。

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

### スパークラインの追加

[`FWorksheet.addSparkline`](https://docs.univer.ai/ja-JP/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/ja-JP/reference/facade/worksheet.md#composesparkline) と [`FWorksheet.unComposeSparkline`](https://docs.univer.ai/ja-JP/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/ja-JP/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/ja-JP/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/ja-JP/reference/facade/sparkline.md) インスタンスは、スパークラインを操作する次のメソッドを持ちます:

| Method           | Description                    |
| ---------------- | ------------------------------ |
| changeDataSource | 現在のセル内のスパークラインのデータソースと配置を変更します |
| removeSparkline  | 現在のセル内のスパークラインを削除します           |

[`FSparklineGroup`](https://docs.univer.ai/ja-JP/reference/facade/sparkline-group.md) インスタンスは、スパークライングループを操作する次のメソッドを持ちます:

| Method               | Description                        |
| -------------------- | ---------------------------------- |
| changeDataSource     | 現在のセル内のスパークライングループのデータソースと配置を変更します |
| removeSparklineGroup | 現在のセル内のスパークライングループを削除します           |
| setConfig            | 現在のセル内のスパークライングループの構成を変更します        |

### イベントリスナー

完全なイベント型定義は、[Events](https://docs.univer.ai/ja-JP/reference/facade/events.md) で確認できます。

`univerAPI.Event.SheetSparklineChanged` イベントは、スパークラインが変更されたときにトリガーします。

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

// イベントリスナーを削除するには、`disposable.dispose()` を使用します。
```

## 色と表示オプション

色や表示オプションは `FSparklineGroup.setConfig()` で設定し、グループ全体に適用します。独立した `FSparkline.setColor()` メソッドはありません。色を指定する場合は、`seriesColor` と `themeType: SparklineThemeTypeEnum.CUSTOM` を設定してください。マーカー、軸、最大値・最小値、空のセル、非表示のセル、線幅を含む設定一覧と例は、[スパークライングループの設定](https://docs.univer.ai/ja-JP/reference/facade/sparkline-group.md)を参照してください。