# 다단 헤더

다단 헤더는 관련 열을 하나의 상위 제목 아래 배치합니다. 행을 묶는 그룹화와 달리 데이터 개수나 집계값은 바뀌지 않습니다.

Canonical: https://grid.syidax.com/ko/docs/features/column-groups/

<a id="understand"></a>

## 동작 원리와 선택 기준

상위 그룹에는 groupId와 children을 지정하고 실제 값을 읽는 하위 열에는 field 또는 colId를 둡니다. 그룹 ID와 열 ID가 겹치지 않게 정하면 저장과 제어가 명확해집니다.

코드의 grid는 설치와 연결 장에서 준비한 Grid 요소입니다. 예제마다 필요한 데이터·설정을 확인하고, 코드에서 소개하는 앱 함수와 서버 주소는 프로젝트에 맞게 구현하세요.

- [설치와 연결 · 공통 예제 데이터](https://grid.syidax.com/ko/docs/guides/getting-started.md)

<a id="example-1"></a>

## 예제 1. 주문 정보와 금액 정보 분리

제품·수량을 같은 헤더로 묶고 단가는 별도로 표시합니다.

```javascript
grid.columnDefs = [
  { groupId: 'order', headerName: '주문 정보', children: [
    { field: 'product', headerName: '제품' },
    { field: 'quantity', headerName: '수량' }
  ] },
  { field: 'price', headerName: '단가' }
];
```

결과 확인: 상위 주문 정보 아래 두 열이 나타납니다. 원본 주문 객체는 평평한 구조 그대로 사용할 수 있습니다.

<a id="example-2"></a>

## 예제 2. 펼침 상태 제어

공간이 부족한 화면에서는 일부 그룹을 접는 흐름을 구성합니다.

```javascript
await grid.setColumnGroupOpened('order', false);
// 사용자가 자세히 보기를 선택한 뒤
await grid.setColumnGroupOpened('order', true);
```

결과 확인: 지정한 그룹의 펼침 상태가 바뀝니다. 실제 숨길 하위 열은 columnGroupShow 설정과 함께 결정됩니다.

<a id="example-3"></a>

## 예제 3. 실행 중인 그룹 조회

설정 화면에서 그룹 정보를 보여 주려면 연결된 그룹 객체를 조회합니다.

```javascript
const group = await grid.getColumnGroup('order');
const groups = await grid.getColumnGroups();
console.log(group, groups);
```

결과 확인: 그룹이 없으면 null이 반환될 수 있습니다. 단순 저장용 JSON과 실행 중인 그룹 참조를 구분하세요.

<a id="pitfalls"></a>

## 조합할 때와 문제를 해결할 때

children을 가진 그룹 자체는 행 데이터를 읽는 셀이 아닙니다. 그룹 제목에 field를 지정하는 것만으로 계산 열이 생기지 않습니다.

열 고정과 숨김을 조합하면 화면에 보이는 그룹 모양이 달라집니다. 고정 영역과 일반 영역에서 헤더를 읽을 수 있는지 확인하세요.

<a id="related-api"></a>

## 이 기능에 사용하는 API

- [columnGroupShow](https://grid.syidax.com/ko/docs/columns/columnGroupShow.md) — 부모 열 그룹이 펼쳐졌거나 접혔을 때 이 열을 보여 줄지 선택합니다.
- [setColumnGroupOpened](https://grid.syidax.com/ko/docs/methods/setColumnGroupOpened.md) — 지정한 열 그룹 머리글을 펼치거나 접습니다.
- [columnGroupToggled](https://grid.syidax.com/ko/docs/events/columnGroupToggled.md) — 열 그룹 머리글을 펼치거나 접었을 때 발생합니다. groupId와 open으로 현재 상태를 읽습니다.

<a id="next"></a>

## 함께 읽기

- [행·열·ID의 관계](https://grid.syidax.com/ko/docs/guides/concepts.md)
- [결과와 이벤트 연결](https://grid.syidax.com/ko/docs/guides/data-event-access.md)
- [Features에서 살펴보기](https://grid.syidax.com/grid/column-groups) — 직접 체험 가능한 범위는 해당 가이드에 안내되어 있습니다.