# ピボットテーブル

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

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

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.1.0`

- Source: [sheets/features/pivot-table.ja-JP.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/pivot-table.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-pivot",
      "facade": "@univerjs-pro/sheets-pivot/facade",
      "locale": "@univerjs-pro/sheets-pivot/locale/ja-JP"
    },
    {
      "client": "@univerjs-pro/sheets-pivot-ui",
      "locale": "@univerjs-pro/sheets-pivot-ui/locale/ja-JP",
      "style": "@univerjs-pro/sheets-pivot-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

ピボットテーブルは強力なデータ分析ツールで、大量のデータを素早く要約・分析・可視化できます。多様なデータ操作や書式設定オプションをサポートし、ユーザーがデータをより深く理解し活用できるようにします。

## 概要

データピボットテーブルは一般的に次のような場面で使用されます。

* データの要約: ピボットテーブルはデータを素早く要約し、全体像の把握に役立ちます。
* データの分析: ピボットテーブルはデータを分析し、パターンや関連性を見つけるのに役立ちます。
* データの探索: ピボットテーブルはデータを探索し、規則性やトレンドを発見するのに役立ちます。
* データの可視化: ピボットテーブルはデータを可視化し、理解を助けます。

ピボットテーブルは通常、以下の要素で構成されます。

* 行ラベル: データをグループ化するために使用します。
* 列ラベル: データをグループ化するために使用します。
* 値: データを集計するために使用します。

ピボットテーブルでは、必要に応じて行ラベル・列ラベル・値を調整し、より深い分析を行えます。

![ロケールが見つかりません](https://raw.githubusercontent.com/dream-num/documentation/dev/content/guides/sheets/features/pivot-table/pivot.png)

### データソース

Univer Sheets では、ピボットテーブルのデータソースはワークシートまたはデータ範囲のいずれかを選択できます。必要に応じて異なるデータソースを選択し、データをより適切に分析できます。
データソースの最初の行をデフォルトの列ラベルとして、残りをデータソースとして扱います。したがって、データソースはできるだけ整理された状態であることが求められ、空の行や列はできるだけ避けるようにしてください。
同じ列のデータについては、ピボットテーブルの機能をより適切にサポートするために、データ型を自動的に認識します。列内のデータ型が不一致の場合、その列のデータ型は文字列にデフォルト設定されます。

Univer Sheets では、ピボットテーブルはデータの変更に自動的に対応します。データソースが変更されると、ピボットテーブルは自動的に更新され、データをより適切に分析できるようになります。

### フィルター

データピボットテーブルは、行ラベルと列ラベルに対するフィルターをサポートします。さらに、ピボットテーブルの主要な分類・集計レイアウトには参加しないものの、データの絞り込みに利用できるフィルターフィールドも提供します。

データピボットテーブルは 2 種類のフィルター方法をサポートします。

* ラベル フィルター: 現在のラベル次元の項目に直接適用されます。例えば、都道府県次元で特定の都道府県を除外できます。
* 値フィルター: 値の次元を指定し、その値フィールドの集計結果に対してフィルターします。例えば、売上が 1000 未満のデータを除外できます。

### 並べ替え

データピボットテーブルの並べ替えは行/列フィールドにのみ有効で、昇順・降順をサポートします。ソートは `localCompare` メソッドを使用します。将来的には、ピンインソートなど、より多くのソート方法をサポートする予定です。

データピボットテーブルは 2 種類の並べ替え方法をサポートします。

* ラベル ソート: 現在のラベル次元の項目に直接適用されます。例えば、都道府県名で並べ替えることができます。
* 値ソート: 値の次元を指定し、その値フィールドの集計結果で並べ替えます。例えば、売上金額で並べ替えることができます。

### 集計

データピボットテーブルは、Excel がサポートする 11 種類の集計方法（合計、件数、データ件数、平均、最大、最小、階乗、標準偏差、分散、母標準偏差、母分散）をサポートします。

データピボットテーブルは複数の値次元をサポートし、値次元のエリア（値の位置）や値の順序（値のインデックス）をカスタマイズできます。

これは複雑なレイアウトロジックであるため、現時点では表ビューのみをサポートします。今後、要望に応じてより多くのビューをサポートする予定です。

### ドリルダウン

ドリルダウンとは、ピボットテーブルの値エリア内のセルをダブルクリックして、そのセルに対応する詳細データを確認できる機能を指します。例えば、ピボットテーブル内のセルをクリックして、その裏にある元データを追跡できます。

### グループ化

データピボットテーブルはグループ化機能をサポートしますが、Univer Sheets ではまだサポートされていません。

グループ化は次の方法で行えます。

* 日付のグループ化: 年・月・日などで日付データをグループ化します。
* 数値のグループ化: 数値データを指定した範囲にグループ化します。
* 要素のグループ化: 特定のルールに従って要素データをグループ化します。

## プラグイン モード

### インストール

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

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

### 使い方

```typescript
import { UniverSheetsPivotTablePlugin } from '@univerjs-pro/sheets-pivot' // [!code ++]
import { UniverSheetsPivotTableUIPlugin } from '@univerjs-pro/sheets-pivot-ui' // [!code ++]
import SheetsPivotTableUIJaJP from '@univerjs-pro/sheets-pivot-ui/locale/ja-JP' // [!code ++]
import SheetsPivotTableJaJP from '@univerjs-pro/sheets-pivot/locale/ja-JP' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import '@univerjs-pro/sheets-pivot-ui/lib/index.css' // [!code ++]
import '@univerjs-pro/sheets-pivot/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.JA_JP,
  locales: {
    [LocaleType.JA_JP]: mergeLocales(
      SheetsPivotTableJaJP, // [!code ++]
      SheetsPivotTableUIJaJP, // [!code ++]
    ),
  },
})
```

### プラグインの登録

ピボットテーブルプラグインは、用途に応じて柔軟に登録でき、さまざまな計算ニーズに対応する 2 つのモードを提供します。

**メインプロセスのみで登録**

ピボットテーブルプラグインはメインプロセスのみに登録できます。このモードは軽量なタスクや単純な操作に適しており、追加のプラグイン設定は不要です。開発者は `UniverSheetsPivotTablePlugin` をインポートするだけで利用できます。

```typescript
univer.registerPlugin(UniverSheetsPivotTablePlugin)
univer.registerPlugin(UniverSheetsPivotTableUIPlugin)
```

**メイン/ワーカー両方で登録**

高いパフォーマンスが求められるシナリオでは、ピボットテーブルプラグインをメインプロセスとワーカー プロセスの両方に登録できます。これにより、マルチスレッド アーキテクチャを活用してデータ分配と計算処理を効率化し、メインプロセスの負荷を大幅に軽減して全体のパフォーマンスを向上させます。

このモードでは、メインプロセスが主にデータ分配・同期・レンダリングを担当し、ワーカー プロセスが複雑な計算タスクに専念します。このモードを実装するには、登録時に設定を微調整する必要があります。

```typescript
// main process file
// notExecuteFormula を true に設定すると、メインプロセスは計算を行いません。データ分配・同期・レンダリングのみを担当します。
univer.registerPlugin(UniverSheetsPivotTablePlugin, { notExecuteFormula: true })
univer.registerPlugin(UniverSheetsPivotTableUIPlugin)

// web worker process file
// notExecuteFormula を false に設定すると、ワーカー プロセスが計算を実行します。
univer.registerPlugin(UniverSheetsPivotTablePlugin, { notExecuteFormula: false })
```

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

### プラグインと設定

```typescript
interface IUniverSheetsPivotConfig {
  /**
   * 単一のピボットテーブル フィールドで表示できる最大項目数を定義します。
   * @default 1000
   */
  maxLimitItemCount?: number
}
```

## モバイル対応

まず[モバイルエディター](https://docs.univer.ai/ja-JP/guides/sheets/getting-started/installation.md#mobile-support)を設定します。このページのプラグインモードの初期化コードで、以下のデスクトップ登録を同じパッケージのモバイル版に置き換え、**文書を開く前に**完了してください。モデル、スタイル、言語ファイル、Facade は維持し、両方を同時に登録しないでください。

| パッケージ                           | デスクトップの登録                        | モバイルの登録                                |
| ------------------------------- | -------------------------------- | -------------------------------------- |
| `@univerjs-pro/sheets-pivot-ui` | `UniverSheetsPivotTableUIPlugin` | `UniverSheetsPivotTableMobileUIPlugin` |

## プリセット モード

ピボットテーブル機能は `@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) を参照してください。

### プリセットと設定

```typescript
interface IUniverSheetsAdvancedPresetConfig {
  pivot?: Pick<IUniverSheetsPivotConfig, 'maxLimitItemCount'>
}

interface IUniverSheetsPivotConfig {
  /**
   * 単一のピボットテーブル フィールドで表示できる最大項目数を定義します。
   * @default 1000
   */
  maxLimitItemCount?: number
}
```

## Facade API

完全な Facade API の型定義は [FacadeAPI](https://docs.univer.ai/ja-JP/reference/facade.md) を参照してください。

### インポート

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

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

### ピボットテーブルの追加

[`FWorkbook.addPivotTable`](https://docs.univer.ai/ja-JP/reference/facade/workbook.md#addpivottable) メソッドはピボットテーブルを追加するために使用され、成功すると `FPivotTable` インスタンスを返します。

```typescript
// シート範囲 A1:G9 が空でないことを確認してください
const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook.getId()
const fSheet = fWorkbook.getActiveSheet()
const subUnitId = fSheet.getSheetId()
const sheetName = fSheet.getSheetName()
const sourceInfo = {
  unitId,
  subUnitId,
  sheetName,
  range: {
    startRow: 0,
    startColumn: 0,
    endRow: 8,
    endColumn: 6,
  },
}
const anchorCellInfo = {
  unitId,
  subUnitId,
  row: 20,
  col: 8,
}
const fPivotTable = await fWorkbook.addPivotTable(sourceInfo, univerAPI.Enum.PositionTypeEnum.Existing, anchorCellInfo)
const pivotTableId = fPivotTable.getPivotTableId()
// 複数回フィールドを追加しないように制御するフラグ
let hasAdded = false
// addPivotTable は非同期のため、ピボットテーブル追加後にフィールドを追加できます
univerAPI.addEvent(univerAPI.Event.PivotTableRendered, (params) => {
  if (!hasAdded && params.pivotTableId === pivotTableId) {
    fPivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0)
    fPivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Value, 0)
    hasAdded = true
  }
})
```

### ピボットテーブルの取得

[`FWorkbook.getPivotTableByCell`](https://docs.univer.ai/ja-JP/reference/facade/workbook.md#getpivottablebycell) メソッドは、アンカーセルからピボットテーブルのインスタンスを取得します。対象セルがピボットテーブル内にある場合、`FPivotTable` インスタンスを返します。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook.getId()
const fSheet = fWorkbook.getActiveSheet()
const subUnitId = fSheet.getSheetId()

// FWorkbook でセルからピボットテーブルを取得
const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8)

// FWorksheet でセルからピボットテーブルを取得
const pivotTable2 = fSheet.getPivotTableByCell(0, 8)
```

[`FPivotTable`](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md) インスタンスには、ピボットテーブルを操作するためのいくつかのメソッドがあります。

| メソッド                                                                                             | 説明                                    |
| ------------------------------------------------------------------------------------------------ | ------------------------------------- |
| [remove](https://docs.univer.ai/ja-JP/reference/facade/generic-pivot-table.md#remove)                                           | ピボットテーブルをインスタンスから削除します                |
| [getConfig](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#getconfig)                       | ピボットテーブルの設定（ソース範囲情報、アンカーセル情報、設定）を返します |
| [addField](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#addfield)                         | ピボットテーブルにフィールドを追加します                  |
| [removeField](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#removefield)                   | ピボットテーブルからフィールドを削除します                 |
| [updateFieldPosition](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#updatefieldposition)   | ピボットテーブル内のフィールド位置を更新します               |
| [updateValuePosition](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#updatevalueposition)   | ∑ 値の位置を制御します                          |
| [setSubtotalType](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#setsubtotaltype)           | フィールドの小計タイプを設定します                     |
| [setLabelSort](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#setlabelsort)                 | フィールドのラベル ソートを設定します                   |
| [setLabelManualFilter](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#setlabelmanualfilter) | フィールドのラベル フィルターを設定します                 |
| [renameField](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#renamefield)                   | フィールド名を変更します                          |
| [setValueFilter](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#setvaluefilter)                                   | 値フィルターを設定します                          |
| [reset](https://docs.univer.ai/ja-JP/reference/facade/generic-pivot-table.md#reset)                                             | ピボットテーブルのフィールドをリセットします                |
| [setFieldsConfig](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#setfieldsconfig)           | ピボットテーブルのフィールド構成を設定します                |
| [getValueFilters](https://docs.univer.ai/ja-JP/reference/facade/pivot-table.md#getvaluefilters)           | ピボットテーブルのすべての値フィルターを取得します             |

```typescript
class FPivotTable {
/**
 * @description ピボットテーブル ID で構成を取得します。
 * @typedef PivotTableConfig
 * @property {TargetInfo} targetCellInfo ピボットテーブルの対象セル情報。
 * @property {SourceInfo} sourceRangeInfo ピボットテーブルのソースデータ範囲情報。
 * @property {boolean} isEmpty ピボットテーブルが空かどうか。
 * @property {object} fieldsConfig ピボットテーブル フィールド設定のスナップショット。
 * @returns {PivotTableConfig|undefined} ピボットテーブルの構成、または undefined。
 */
  getConfig(): IPivotTableConfig
  /**
   * @description ピボットテーブルをワークブックから削除します。
   */
  async remove(): void
  /**
   *@description ピボットテーブルにピボット フィールドを追加します。
   * @param {string|number} dataFieldIdOrIndex データ フィールド ID またはインデックス。
   * @param {PivotTableFiledAreaEnum} fieldArea フィールドのエリア。
   * @param {number} index 対象エリア内でのフィールドの挿入位置。
   * @returns {boolean} 追加に成功したかどうか。
   */
  async addField(dataFieldIdOrIndex: string | number, fieldArea: PivotTableFiledAreaEnum, index: number): Promise<boolean>
  /**
   * @description ピボットテーブルからピボット フィールドを削除します。
   * @param {string[]} fieldIds 削除するフィールド ID の配列。
   * @returns {boolean} 削除に成功したかどうか。
   */
  async removeField(fieldIds: string[]): Promise<boolean>
  /**
   * @description ピボットテーブルのフィールド位置を更新します。
   * @param {string} fieldId - 移動するフィールド ID。
   * @param {PivotTableFiledAreaEnum} area - 対象エリア。
   * @param {number} index - 対象エリアでの目標インデックス。インデックスが対象エリアのフィールド数より大きい場合は最後に、0 未満の場合は先頭に移動します。
   * @returns {boolean} フィールド移動に成功したかどうか。
   */
  async updateFieldPosition(fieldId: string, area: PivotTableFiledAreaEnum, index: number): Promise<boolean>
  /**
   * @description 複数の値フィールドがある場合に、値フィールドの位置（行または列）を更新できます。
   * @param {PivotTableValuePositionEnum} position - 値フィールドの位置。
   * @param {number} index - 値フィールドのインデックス。
   * @returns {boolean} 値フィールド移動に成功したかどうか。
   */
  async updateValuePosition(position: PivotTableValuePositionEnum, index: number): Promise<boolean>
  /**
   * @description 値フィールドの小計タイプを設定します。値フィールドにのみ有効です。
   * @param {string} fieldId - フィールド ID。
   * @param {PivotSubtotalTypeEnum} subtotalType - 小計タイプ。
   * @returns {boolean} 設定に成功したかどうか。
   */
  async setSubtotalType(fieldId: string, subtotalType: PivotSubtotalTypeEnum): Promise<boolean>
  /**
   * @description ピボットテーブルのソート情報を設定します。
   * @param {string} tableFieldId - ソート対象のフィールド ID。
   * @param {PivotTableSortInfo} info - ソート情報。
   * @typedef PivotTableSortInfo
   * @property {PivotDataFieldSortOperatorEnum} type フィールド項目のソート演算子。
   * @returns {boolean} 設定に成功したかどうか。
   */
  async setLabelSort(tableFieldId: string, info: IPivotTableSortInfo): Promise<boolean>
  /**
   * @description ピボットテーブルのフィルターを設定します。
   * @param {string} tableFieldId - フィルター対象のフィールド ID。
   * @param {string[]} items - フィルターの項目。
   * @returns {boolean} 設定に成功したかどうか。
   */
  async setLabelFilter(tableFieldId: string, items: string[], isAll?: boolean): Promise<boolean>
  /**
   * @description ピボットテーブルのフィールド名を変更します。
   * @param {string} fieldId - フィールド ID。
   * @param {string} name - 新しい名前。
   * @returns {boolean} 変更に成功したかどうか。
   */
  async renameField(fieldId: string, name: string): Promise<boolean>
  /**
   * @description ピボットテーブルの値フィルターを設定します。値フィルターは、フィールドの値に基づいてデータをフィルタリングします。
   * @param {string} fieldId - フィルター対象のフィールド ID。同一フィールドには 1 つの値フィルターのみ設定できます。
   * @param {Omit<IPivotTableValueFilter, 'type'>} filterInfo - フィルター情報。undefined の値は既存のフィルターから削除されます。
   * @typedef filterInfo
   * @property {valueGreaterThan} operator - フィルター演算子。フィールドの値と期待値を比較します。現在サポートされている演算子: valueBetween, valueEqual, valueGreaterThan, valueGreaterThanOrEqual, valueLessThan, valueLessThanOrEqual, valueNotBetween, valueNotEqual。
   * @property {number} expected - 期待値。
   * @property {string} valueFieldId - 値フィールド ID。
   * @returns {boolean} 設定に成功したかどうか。
   */
  async setValueFilter(fieldId: string, filterInfo: Omit<IPivotTableValueFilter, 'type'>): Promise<boolean>
  /**
   * @description 指定したフィールド エリアのフィールドをクリア、またはすべてのフィールドをクリアします。
   * @param {PivotTableFiledAreaEnum} [resetArea] リセットするエリア。未指定の場合はすべてをリセットします。
   * @returns {Promise<boolean>} リセットに成功したかどうか。
   */
  reset(resetArea?: PivotTableFiledAreaEnum): Promise<boolean>
  /**
   * @description ピボットテーブルのフィールド構成を設定します。指定の構成からフィールドを追加します。競合を避けるため、設定前にピボットテーブルが空であることを確認してください。
   * @param {IPivotTableConfig['fieldsConfig']} config ピボットテーブルのフィールド構成。
   * @returns {Promise<boolean>} 設定に成功したかどうか。
   */
  setFieldsConfig(config: IPivotTableConfig['fieldsConfig']): Promise<boolean>
  /**
   * ピボットテーブルのすべての値フィルターを取得します。値フィルターは順序通りに適用される必要があるため、順序が重要です。
   * @returns {IValueFilterInfoItem[]} 値フィルター情報のリスト。
   */
  getValueFilters(): IValueFilterInfoItem[]
}
```

### イベントリスナー

完全なイベント型定義は [Events](https://docs.univer.ai/ja-JP/reference/facade/events.md) を参照してください。

`univerAPI.Event.BeforePivotTableAdd` イベントは、ピボットテーブルを追加する前にトリガーされます。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforePivotTableAdd, (params) => {
  const { positionType, targetCellInfo } = params
  if (positionType === univerAPI.Enum.PositionTypeEnum.Existing && targetCellInfo.sheetName === 'Sheet 1') {
  // ピボットテーブルの追加操作をキャンセル
    params.cancel = true
    console.log(`The pivot table can't be added to the sheet ${targetCellInfo.sheetName}`)
  }
})

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

`univerAPI.Event.PivotTableAdded` イベントは、ピボットテーブルを追加した後にトリガーされます。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableAdded, (params) => {
  const { positionType, targetCellInfo } = params
  if (positionType === univerAPI.Enum.PositionTypeEnum.Existing) {
    console.log('A pivot table created in an existing sheet')
    console.log(`
      The target sheet name is ${targetCellInfo.sheetName},
      the target row is ${targetCellInfo.row}, the target column is ${targetCellInfo.column}
    `)
  } else {
    console.log('A pivot table created in a new sheet')
  }
})

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

`univerAPI.Event.BeforePivotTableMove` イベントは、ピボットテーブルを移動する前にトリガーされます。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforePivotTableMove, (params) => {
  const { pivotTableId, targetCellInfo } = params
  if (pivotTableId === 'pivotTable1' && targetCellInfo.sheetName === 'Sheet 1') {
  // ピボットテーブルの移動操作をキャンセル
    params.cancel = true
    console.log(`The pivot table can't be moved to the sheet ${targetCellInfo.sheetName}`)
  }
})

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

`univerAPI.Event.PivotTableMoved` イベントは、ピボットテーブルを移動した後にトリガーされます。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableMoved, (params) => {
  const { pivotTableId, targetCellInfo, originTargetInfo } = params
  if (pivotTableId === 'pivotTable1') {
    console.log(`
      The pivot table moved from row: ${originTargetInfo.row} & column: ${originTargetInfo.column}
      to the sheet ${targetCellInfo.sheetName} row: ${targetCellInfo.row} & column: ${targetCellInfo.column}
    `)
  }
})

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

`univerAPI.Event.PivotTableRendered` イベントは、ピボットテーブルをレンダリングした後にトリガーされます。

```typescript
// import { unionPivotViewRange } from '@univerjs-pro/sheets-pivot';
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableRendered, (params) => {
  const { pivotTableId, rangeInfo } = params
  console.log(`The pivot table ${pivotTableId} has been rendered`)
  if (rangeInfo) {
    console.log(unionPivotViewRange(rangeInfo))
  }
})

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

`univerAPI.Event.PivotTableRemoved` イベントは、ピボットテーブルを削除した後にトリガーされます。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableRemoved, (params) => {
  const { pivotTableId } = params
  console.log(`The pivot table ${pivotTableId} has been removed`)
})

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

`univerAPI.Event.PivotTableFieldAdded` イベントは、ピボットテーブルにフィールドを追加した後にトリガーされます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableFieldAdded, (params) => {
  const { pivotTableId, fieldId, fieldArea, fieldIndex } = params
  const pivotTable = fWorkbook.getPivotTableById(pivotTableId)
  const fieldSetting = pivotTable.getFieldSetting('fieldId')
  console.log(fieldSetting)
})

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

`univerAPI.Event.PivotTableFieldRemoved` イベントは、ピボットテーブルからフィールドを削除した後にトリガーされます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableFieldRemoved, (params) => {
  const { pivotTableId, fieldId } = params
  const pivotTable = fWorkbook.getPivotTableById(pivotTableId)
  const fieldSetting = pivotTable.getFieldSetting(fieldId)
  console.log(fieldSetting)
})

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

`univerAPI.Event.PivotTableFieldMoved` イベントは、ピボットテーブル内でフィールドを移動した後にトリガーされます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableFieldMoved, (params) => {
  const { pivotTableId, fieldId, fieldArea, fieldIndex } = params
  const pivotTable = fWorkbook.getPivotTableById(pivotTableId)
  const fieldSetting = pivotTable.getFieldSetting(fieldId)
  console.log(`The source name ${fieldSetting.sourceName} the display name ${fieldSetting.displayName}`)
})

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

`univerAPI.Event.PivotTableFieldCollapseChanged` イベントは、ピボットテーブルで次元を展開/折りたたみした後にトリガーされます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableFieldCollapseChanged, (params) => {
  const { pivotTableId, fieldId, isCollapsed } = params
  const pivotTable = fWorkbook.getPivotTableById(pivotTableId)
  const fieldSetting = pivotTable.getFieldSetting(fieldId)
  console.log(`The source name ${fieldSetting.sourceName} the display name ${fieldSetting.displayName}`)
})

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

`univerAPI.Event.PivotTableFieldFilterChanged` イベントは、ピボットテーブルで次元をフィルタリングした後にトリガーされます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableFieldFilterChanged, (params) => {
  const { pivotTableId, fieldId, filter } = params
  const pivotTable = fWorkbook.getPivotTableById(pivotTableId)
  const fieldSetting = pivotTable.getFieldSetting(fieldId)
  console.log(`The Checklist filter value is ${fieldSetting.filterInfo.checklist}`)
})

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

`univerAPI.Event.PivotTableFieldSortChanged` イベントは、ピボットテーブルで次元を並べ替えた後にトリガーされます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableFieldSortChanged, (params) => {
  const { pivotTableId, fieldId, sort } = params
  const pivotTable = fWorkbook.getPivotTableById(pivotTableId)
  const fieldSetting = pivotTable.getFieldSetting(fieldId)
  console.log(`The sort info is ${fieldSetting.sortInfo}`)
})

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

`univerAPI.Event.PivotTableFieldSettingChanged` イベントは、ピボットテーブルで次元の設定を変更した後にトリガーされます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableFieldSettingChanged, (params) => {
  const { pivotTableId, fieldId, setting } = params
  const pivotTable = fWorkbook.getPivotTableById(pivotTableId)
  const fieldSetting = pivotTable.getFieldSetting(fieldId)
  console.log(`The source name ${fieldSetting.sourceName} the display name ${fieldSetting.displayName}`)
})

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

`univerAPI.Event.PivotTableValuePositionChanged` イベントは、ピボットテーブルの値の位置を変更した後にトリガーされます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const disposable = univerAPI.addEvent(univerAPI.Event.PivotTableValuePositionChanged, (params) => {
  const { pivotTableId, valueId, position } = params
  const pivotTable = fWorkbook.getPivotTableById(pivotTableId)
  const valueSetting = pivotTable.getValueSetting(valueId)
  console.log(`The source name ${valueSetting.sourceName} the display name ${valueSetting.displayName}`)
})

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

## 値の表示方法

`setShowDataAs()` で値フィールドを行・列・総計に対する割合や基準項目との差として表示できます。表示上の計算を変更し、元データは置き換えません。`getShowDataAs()` で設定を取得し、`resetShowDataAs()` で通常の計算に戻します。

```ts
const valueId = fPivotTable.getFieldIdsByArea(
  univerAPI.Enum.PivotTableFiledAreaEnum.Value,
)[0]
if (valueId) {
  await fPivotTable.setShowDataAs(valueId, {
    type: univerAPI.Enum.PivotShowAsTypeEnum.percentOfGrandTotal,
  })
  console.log(fPivotTable.getShowDataAs(valueId))
}
```

例の `fPivotTable` は既存のピボットテーブルです。元データの列や行フィールドではなく、値フィールドの ID を指定します。差分や累計のモードでは、対応する基準フィールドと基準項目の設定も必要です。

## ワークシートと一緒にピボットテーブルをコピーする

ピボットプラグインを登録すると、ワークシートの複製時に、そのシート上のピボットテーブルとフィールド設定もコピーされます。各コピーには新しい ID が割り当てられます。データソースがコピー元のシートにある場合、参照先は新しいシートに変更されます。他のシートやブックにある場合は元の参照を維持します。コピーされたピボットテーブルも、シートの複製と一緒に元に戻す・やり直す操作の対象になります。

```ts
const workbook = univerAPI.getActiveWorkbook()
if (!workbook) throw new Error('No active workbook')

const copiedSheet = workbook.duplicateActiveSheet()
console.log(copiedSheet.getSheetName())
```