JavaScript 그리드 셀 병합 구현 — Wijmo FlexGrid MergeManager 가이드
리포트나 현황판 화면을 만들다 보면 같은 부서나 지역 값이 행마다 반복되어 표가 복잡해지고, 그룹 구분이 한눈에 들어오지 않습니다. 엑셀처럼 같은 값을 하나의 셀로 합치고 싶지만, 테이블 태그를 직접 조작하면 정렬·스크롤·가상화와 충돌하기 쉽습니다.
Wijmo(위즈모) by MESCIUS(메시어스)의 FlexGrid는 allowMerging
속성과 MergeManager
클래스로 JavaScript 그리드 셀 병합을 지원합니다. 이 글에서는 처음 셀 병합을 구현하는 개발자를 위해 자동 병합, 다단 헤더 병합, 커스텀 병합 규칙을 예제 3개로 단계별로 구현합니다.
allowMerging
속성으로 병합 영역(셀, 컬럼 헤더, 행 헤더)을 정하고, 각 컬럼의 allowMerging
으로 병합할 컬럼을 고릅니다.columnHeaders.rows
에 행을 추가해 다단 헤더를 만들고 allowMerging
으로 헤더 셀을 병합할 수 있습니다.MergeManager
를 상속해 getMergedRange(panel, r, c, clip)
를 재정의하면 행과 열에 걸친 병합 규칙을 직접 정의할 수 있습니다.그리드 셀 병합은 어떻게 동작할까? FlexGrid 병합 원리
FlexGrid의 셀 병합은 내용 기반(content-driven) 입니다. 병합 대상으로 지정한 영역에서 인접한 셀의 값이 같으면, 그리드가 이를 하나의 큰 셀로 그려줍니다. 데이터 자체는 바뀌지 않고 화면 표시만 합쳐지므로 원본 데이터와 CollectionView
는 그대로 유지됩니다.
병합 설정은 두 단계로 이뤄집니다.
FlexGrid의 allowMerging
기본값은 None
이므로 병합하려면 반드시 명시해야 합니다.
예제 1: allowMerging으로 같은 값 셀을 자동으로 합치기
지역·부서별 매출 표에서 반복되는 지역과 부서 셀을 합쳐 보겠습니다.

STEP 1: 라이브러리 참조 (CDN)
예제에 필요한 모듈은 Wijmo 코어와 FlexGrid, 한글 문화권 파일입니다.
STEP 2: HTML 컨테이너 준비
STEP 3: 샘플 데이터 정의와 그리드 초기화
먼저 병합 없이 데이터를 바인딩합니다. 병합은 인접한 셀끼리만 일어나므로 CollectionView
의 sortDescriptions
로 지역과 부서를 정렬해 같은 값이 붙어 있도록 만드는 것이 핵심입니다.
STEP 4: 완성 — allowMerging으로 셀 병합 적용
그리드의 allowMerging
을 'Cells'
로 지정하고, 병합할 컬럼( region
, dept
)에만 allowMerging: true
를 설정합니다. 이름·매출 컬럼은 값이 같아도 합쳐지지 않습니다.
위 라이브 데모를 보면 같은 지역의 행들이 하나의 셀로 합쳐지고, 지역 안에서도 같은 부서끼리 다시 병합되는 것을 확인할 수 있습니다. 정렬 순서가 ['region', 'dept']
이므로 큰 그룹(지역) 안에서 작은 그룹(부서)이 이어집니다. 정렬을 빼면 같은 값이 떨어져 있어 병합되지 않습니다.
예제 2: 컬럼 헤더 병합으로 다단 헤더 만들기
분기별 실적처럼 상위 그룹 아래 세부 항목이 있는 표는 헤더를 두 줄로 만들어야 합니다. FlexGrid는 columnHeaders
패널에 행을 추가한 뒤 같은 내용을 가진 헤더 셀을 병합하는 방식으로 다단 헤더를 지원합니다.
STEP 1: 라이브러리 참조 (CDN)
STEP 2: HTML 컨테이너 준비
STEP 3: 완성 — 헤더 행 추가 후 병합하기
순서는 다음과 같습니다.
- 그리드의
allowMerging을'ColumnHeaders'로 지정합니다. -
columnHeaders.rows.insert(0, new wijmo.grid.Row())로 위쪽에 상위 헤더 행을 추가합니다. - 추가한 행의
allowMerging을true로 설정하고,setCellData로 상위 그룹명을 채웁니다. - '이름' 컬럼처럼 두 줄을 가로지르는 헤더는 컬럼의
allowMerging을true로 하고 위·아래 헤더 텍스트를 같게 지정합니다.
위 라이브 데모에서는 "1분기"와 "2분기" 헤더가 각각 두 컬럼에 걸쳐 합쳐지고, "이름" 헤더는 두 줄에 걸쳐 하나로 표시됩니다. 헤더 병합도 본문과 같은 내용 기반 규칙을 따르므로 병합하려는 셀의 텍스트를 같게 맞추는 것이 핵심입니다.
예제 3: MergeManager를 상속해 나만의 병합 규칙 만들기
기본 병합은 한 방향(주로 세로)으로만 이어집니다. 회의실 예약표나 편성표처럼 행과 열을 동시에 가로지르는 블록이 필요하면 MergeManager
를 상속해 getMergedRange
를 재정의합니다.
getMergedRange(p, r, c, clip)
는 패널( p
)의 r
행 c
열 셀이 속한 병합 범위를 CellRange
로 반환하고, 병합되지 않는 셀이면 null
을 반환합니다. 이 메서드를 직접 구현하면 병합 기준을 마음대로 바꿀 수 있습니다.

STEP 1: CDN으로 Wijmo 라이브러리 불러오기
STEP 2: 그리드를 담을 HTML 컨테이너 만들기
STEP 3: MergeManager 상속 클래스 작성하기
본문(Cell) 패널에서만 동작하도록 하고, 빈 값은 병합하지 않도록 방어합니다. 현재 셀에서 좌우로, 다시 상하로 같은 값을 따라 범위를 확장합니다. 이 단계는 예제의 일부이므로 컨테이너와 그리드 생성까지 모두 포함한 코드를 그대로 이어서 완성합니다.
STEP 4: 완성 — 그리드에 커스텀 병합 적용
작성한 클래스를 그리드의 mergeManager
에 할당합니다. 이 예제는 시간대별 회의실 예약표입니다. 같은 일정이 여러 시간·여러 회의실에 걸쳐 있으면 하나의 블록으로 합쳐집니다.
위 라이브 데모에서는 "기획 회의"와 "디자인 리뷰"가 두 시간대를 세로로, "코드 리뷰"가 두 회의실을 가로로, "점심"이 세 회의실을 가로로 병합됩니다. 기본 병합이 한 방향으로만 이어지는 것과 달리, 커스텀 병합은 한 셀의 범위를 행과 열로 동시에 확장할 수 있습니다. 같은 값이 아니라 고정된 범위 목록을 반환하도록 바꾸면 "1~2행, 1~3열은 항상 병합"과 같은 규칙도 만들 수 있습니다.
병합 셀 사용 시 선택·편집 동작과 주의할 점
내용 기반 병합은 화면 표시 방식이므로 다음 점에 유의해야 합니다.
- 정렬: 병합은 인접한 셀의 값을 비교하므로 정렬 순서에 따라 결과가 달라집니다. 병합 컬럼을 우선순위로
sortDescriptions에 포함하세요. - 선택: 병합된 셀을 클릭하면 일반적으로 병합 범위 전체가 하나의 셀처럼 선택됩니다.
- 편집: 병합 셀을 편집하면 값이 바뀌고, 인접 셀과 값이 달라지면 병합이 풀립니다. 편집이 필요 없는 보고서형 화면에서는
isReadOnly: true를 권장합니다. - 필터: 필터로 행이 걸러지면 남은 행끼리 다시 병합 여부가 계산됩니다.
- 성능: 커스텀
getMergedRange는 셀을 그릴 때마다 호출되므로, 범위를 확장하는 루프를 가볍게 유지하세요. - 폐기 속성: 줄무늬 행 설정은
showAlternatingRows가 아니라alternatingRowStep을 사용합니다 (false는 0).
자주 묻는 질문 (FAQ)
Wijmo(위즈모) FlexGrid 셀 병합 기능은 무엇인가요?
allowMerging
속성으로 활성화합니다.JavaScript 그리드에서 allowMerging으로 셀을 병합하려면 어떻게 하나요?
allowMerging: 'Cells'
를 지정하고 병합할 컬럼에 allowMerging: true
를 설정합니다. 같은 값이 인접하도록 CollectionView
의 sortDescriptions
로 정렬하세요. 헤더를 병합하려면 'ColumnHeaders'
또는 'AllHeaders'
를 사용합니다.MergeManager를 상속해 커스텀 셀 병합 규칙을 만들려면 어떻게 하나요?
wijmo.grid.MergeManager
를 상속한 클래스에서 getMergedRange(panel, r, c, clip)
를 재정의해 CellRange
또는 null
을 반환하고, 그 인스턴스를 grid.mergeManager
에 할당합니다.그리드 라이브러리별 셀 병합 방식은 어떻게 다른가요? AG Grid, RealGrid와 비교하면?
MergeManager
하나로 규칙을 확장하는 구조입니다. 다른 제품은 컬럼별 병합 옵션이나 콜백 방식을 쓰는 경우가 많아 구성 방식이 다르므로, 도입 전에 각 제품의 공식 문서를 확인하는 것이 좋습니다.합계나 그룹 헤더가 필요한 리포트 화면에는 어떤 JavaScript 그리드가 적합한가요?
CollectionView
기반 그룹핑을 함께 사용하면 엑셀 리포트 같은 화면을 구성할 수 있습니다.셀 병합을 사용하면 정렬, 필터, 편집은 어떻게 동작하나요?
isReadOnly: true
로 두는 것이 좋습니다.
