# 그룹과 집계

행 그룹은 같은 지역이나 팀에 속한 원본 행을 접고 펼칠 수 있게 묶습니다. 열 그룹이 머리글을 묶는 것과 달리, 행 그룹은 표시 행과 집계 결과를 바꿉니다.

Canonical: https://grid.syidax.com/ko/docs/features/row-grouping/

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

## 동작 원리와 선택 기준

원본 데이터에는 그룹 행을 직접 추가하지 않습니다. groupBy에 기준 필드를 지정하고 숫자 열의 aggFunc로 합계·평균 등을 구성합니다. 그룹 기준이 여러 개이면 배열의 앞 항목이 바깥 그룹입니다.

이 기능을 제품에서 사용하려면 Pro 패키지와 유효한 라이선스가 필요합니다. 설정 이름이 같더라도 Community에서 Pro 기능이 활성화되는 것은 아닙니다.

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

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

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

## 예제 1. 지역별 수량 합계

지역을 기준으로 주문을 묶고 수량 열에 합계를 표시합니다.

```javascript
grid.columnDefs = [
  { field: 'region', headerName: '지역' },
  { field: 'quantity', headerName: '수량', aggFunc: 'sum' },
];
grid.groupBy = 'region';
```

결과 확인: 지역 그룹을 접어 요약을 읽고 펼쳐 개별 주문을 확인합니다.

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

## 예제 2. 지역 안에서 팀별로 분류

그룹 패널을 열어 사용자가 기준을 살펴보고 변경하게 합니다.

```javascript
grid.groupBy = ['region', 'team'];
grid.groupPanel = true;
await grid.collapseAllRowGroups();
```

결과 확인: 지역 → 팀의 두 단계가 생깁니다. expandAllRowGroups()로 전체 상세 행을 다시 펼칠 수 있습니다.

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

## 예제 3. 필터와 페이지를 함께 사용

먼저 상태 필터로 완료 주문만 남긴 뒤 그룹을 펼쳐 봅니다. 페이지 크기를 작게 바꾸어 그룹 제목도 표시 행 수에 포함되는지 확인합니다.

결과 확인: 집계 대상과 원본 전체 주문 수를 혼동하지 않도록 화면에 현재 필터 조건을 함께 표시하세요. 그룹 선택 상태는 getGroupCheckStates()의 거절 사유까지 확인합니다.

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

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

다단계 그룹의 키를 표시 라벨을 이어 붙여 만들지 마세요. 이벤트가 제공한 실제 키로 setRowGroupExpanded()를 호출합니다.

피벗·트리와 동시에 설정했을 때는 같은 행 목록을 모두 만들 수 없습니다. 원하는 분석 방식을 하나 선택하고 조합 보고서를 확인하세요.

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

## 이 기능에 사용하는 API

- [groupBy](https://grid.syidax.com/ko/docs/options/groupBy.md) — 같은 값의 행을 그룹으로 묶습니다. 문자열 배열은 앞 항목부터 다단계 그룹을 만듭니다.
- [groupPanel](https://grid.syidax.com/ko/docs/options/groupPanel.md) — 열을 끌어 넣어 행 그룹 기준을 구성하는 패널을 표시합니다.
- [aggFunc](https://grid.syidax.com/ko/docs/columns/aggFunc.md) — 행 그룹·분석에서 사용할 기본 또는 등록된 사용자 집계 함수 이름입니다.
- [registerAggFunc](https://grid.syidax.com/ko/docs/methods/registerAggFunc.md) — 이름으로 사용자 집계 함수를 등록합니다. 같은 이름의 기존 함수를 덮어쓸 수 있으므로 고유한 이름을 사용하세요.
- [unregisterAggFunc](https://grid.syidax.com/ko/docs/methods/unregisterAggFunc.md) — 등록한 사용자 집계 함수를 제거합니다. 사용 중인 열의 aggFunc 설정도 함께 정리합니다.
- [getRegisteredAggFuncNames](https://grid.syidax.com/ko/docs/methods/getRegisteredAggFuncNames.md) — 현재 등록된 집계 함수 이름을 확인합니다.
- [setRowGroupExpanded](https://grid.syidax.com/ko/docs/methods/setRowGroupExpanded.md) — 실제 그룹 키에 해당하는 행 그룹을 펼치거나 접습니다. 없는 그룹이나 이미 같은 상태이면 변경하지 않습니다.
- [expandAllRowGroups](https://grid.syidax.com/ko/docs/methods/expandAllRowGroups.md) — 현재 행 그룹을 모두 펼칩니다. 실제로 바뀐 그룹마다 토글 이벤트가 발생합니다.
- [collapseAllRowGroups](https://grid.syidax.com/ko/docs/methods/collapseAllRowGroups.md) — 현재 데이터에서 접을 수 있는 행 그룹을 모두 접습니다.
- [getDisplayRowInfo](https://grid.syidax.com/ko/docs/methods/getDisplayRowInfo.md) — 지정한 표시 행이 일반 데이터·그룹·상세 등 어떤 종류인지 읽습니다.
- [getGroupCheckStates](https://grid.syidax.com/ko/docs/methods/getGroupCheckStates.md) — 행 그룹의 선택 상태를 계산합니다. 접힌 그룹·행 ID 없음·다른 행 모델 등 확실히 판단할 수 없는 경우 거절 사유를 반환합니다.
- [rowGroupToggled](https://grid.syidax.com/ko/docs/events/rowGroupToggled.md) — 행 그룹을 펼치거나 접었을 때 발생합니다. 표시 라벨 대신 detail의 실제 key를 재사용합니다.
- [rowGroupChanged](https://grid.syidax.com/ko/docs/events/rowGroupChanged.md) — 행 그룹 기준이 바뀌었을 때 발생합니다. 기준 필드와 그룹 해제 상태를 확인합니다.

<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/row-grouping) — 직접 체험 가능한 범위는 해당 가이드에 안내되어 있습니다.