# 트리맵 차트

## Content

**트리맵 차트**는 중첩된 사각형을 사용하여 계층 구조 데이터를 시각화합니다.

* 각 사각형은 계층 구조의 노드를 나타냅니다.
* 각 사각형의 크기는 숫자 값에 의해 결정됩니다.
* 계층 구조는 `details` 인코딩의 여러 필드를 통해 정의됩니다.

트리맵은 계층형 범주 전반의 비율을 제한된 공간 안에서 비교하는 데 유용합니다.

![image-20260401.ffc763.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image-20260401.ffc763-20260529.dfe8f6.png?width=600)

## 데이터 구조 요구 사항

트리맵 차트에는 다음이 필요합니다.

* 사각형 크기를 결정하기 위한 `values`의 숫자 필드
* 계층 수준을 정의하기 위한 `details`의 하나 이상의 범주형 필드

`details`에 여러 필드를 지정하면, 지정된 순서대로 계층 구조를 형성합니다.

```javascript
details: [
  { field: 'Category' },
  { field: 'Subcategory' },
  { field: 'Product' }
]
```

* `Category` → 최상위 그룹
* `Subcategory` → Category 내부의 하위 그룹
* `Product` → 리프 노드

기본적으로 리프 노드만 표시 가능한 사각형으로 렌더링됩니다.

## 예제 데이터

```javascript
const dataManager = spread.dataManager();

function createTreemapTable(dataManager) {
    const records = [
        ['Beverages', 'Juice', 'Apple Juice', 420],
        ['Beverages', 'Juice', 'Orange Juice', 680],
        ['Beverages', 'Dairy', 'Milk', 950],
        ['Snacks', 'Chocolate', 'Dark Chocolate', 530],
        ['Snacks', 'Chocolate', 'Milk Chocolate', 610],
        ['Snacks', 'Meat', 'Beef Jerky', 720],
        ['Snacks', 'Chips', 'Potato Chips', 480],
        ['Snacks', 'Chips', 'Corn Chips', 390],
    ];

    const columns = ['Category', 'Subcategory', 'Product', 'Sales'];

    return dataManager.addTable('TreemapData', {
        data: records.map((x) => {
            const record = {};
            columns.forEach((c, i) => record[c] = x[i]);
            return record;
        })
    });
}

const TreemapData = createTreemapTable(dataManager);
await TreemapData.fetch();
```

## 트리맵 차트 만들기

```javascript
const sheet = spread.getActiveSheet();
sheet.name("Treemap Chart");

const dataChart = sheet.dataCharts.add('data-chart', 10, 10, 600, 400);

dataChart.setChartConfig({
  tableName: 'TreemapData',
  plots: [
    {
      type: GC.Spread.Sheets.DataCharts.DataChartType.treemap,
      encodings: {
        values: [
          {
            field: 'Sales',
            aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
          }
        ],
        details: [
          { field: 'Category' },
          { field: 'Subcategory' },
          { field: 'Product' }
        ]
      }
    }
  ],
  config: {
    header: {
      title: "Treemap Chart",
      textStyle: {
        fontSize: 18,
        fontWeight: 'Bold'
      }
    }
  }
});
```

![image-20260401.826fef.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image-20260401.826fef-20260529.0c5691.png?width=600)

## 리프 노드 레이블 사용자 지정

플롯의 `text` 구성을 사용하여 리프 노드 내부에 텍스트를 표시할 수 있습니다.

```javascript
config: {
  text: [{
    template: '{detailFields.value}',
  }]
}
```

**전체 예제**

```javascript
dataChart.setChartConfig({
  tableName: 'TreemapData',
  plots: [
    {
      type: GC.Spread.Sheets.DataCharts.DataChartType.treemap,
      encodings: {
        values: [
          {
            field: 'Sales',
            aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
          }
        ],
        details: [
          { field: 'Category' },
          { field: 'Subcategory' },
          { field: 'Product' }
        ]
      },
      config: {
        text: [
          {
            template: '{detailFields.value}'
          }
        ]
      }
    }
  ],
  config: {
    header: {
      title: "Treemap Chart",
      textStyle: {
        fontSize: 18,
        fontWeight: 'Bold'
      }
    }
  }
});
```

이 구성은 **리프 노드에만** 적용됩니다.

![image](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image-20260605.82751f.png?width=600)

`template` 속성은 다른 데이터 차트 레이블과 동일한 템플릿 메커니즘을 사용합니다.

## 헤더를 사용하여 비리프 노드 표시

`details`에 여러 수준이 정의된 경우 **트리맵 헤더**를 활성화하여 비리프 노드를 표시할 수 있습니다.
리프 노드에 적용되는 `text`와 달리, 트리맵 헤더는 비리프 노드에 렌더링됩니다.

### 트리맵 헤더 활성화

플롯 구성의 `treemap` 내부에 `header` 옵션을 구성합니다.

```javascript
config: {
  treemap: {
    header: {
      template: '{detailFields.value}',
      textStyle: {
        fontSize: 14,
        fontWeight: 'Bold'
      }
    }
  }
}
```

**전체 예제**

```auto
dataChart.setChartConfig({
  tableName: 'TreemapData',
  plots: [
    {
      type: GC.Spread.Sheets.DataCharts.DataChartType.treemap,
      encodings: {
        values: [
          {
            field: 'Sales',
            aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
          }
        ],
        details: [
          { field: 'Category' },
          { field: 'Subcategory' },
          { field: 'Product' }
        ]
      },
      config: {
        text: [
          {
            template: '{detailFields.value}'
          }
        ],
        treemap: {
          header: {
            template: '{detailFields.value}',
            textStyle: {
              fontSize: 14,
              fontWeight: 'Bold'
            }
          }
        }
      }
    }
  ],
  config: {
    header: {
      title: "Treemap Chart",
      textStyle: {
        fontSize: 18,
        fontWeight: 'Bold'
      }
    }
  }
});
```

![image-20260401.33378b.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image-20260401.33378b-20260529.358236.png?width=600)

`template`을 지정하지 않았거나 빈 문자열로 설정한 경우 헤더는 표시되지 않습니다.

### 헤더 동작

* 헤더는 노드 내부 공간을 차지합니다.
* 하위 트리는 남은 영역에 배치됩니다.
* 헤더 크기는 내용에 맞게 자동으로 조정됩니다.
* 헤더 크기가 부모 사각형보다 크면 헤더는 표시되지 않습니다.

## 제한 사항

* 마우스 오버 애니메이션은 지원되지 않습니다.
* `textStyle`의 `alignment` 및 `overflow` 속성은 트리맵 헤더에서 적용되지 않습니다.
* 트리맵 헤더 텍스트에서는 줄바꿈 문자를 지원하지 않습니다.