HotXLS Delphi Component: Delphi에서 merged cells and layout-driven report templates

방금 연 보고서 템플릿의 셀을 순회하다 보면 병합된 제목이 마치 누수처럼 동작합니다. A1을 읽으면 "Quarterly Statement"가 나오는데, 같은 배너 아래 눈으로 보이는 B1부터 F1까지 읽으면 아무것도 나오지 않습니다. 헤더를 고치려고 C1에 값을 써 넣어도 화면에는 결코 나타나지 않습니다. 그리드가 데이터를 잃어버린 것이 아닙니다. 병합이 의미하는 바를 정확히 수행하고 있는 것입니다. XLS와 XLSX 모두에서 병합된 직사각형은 좌측 상단 앵커인 하나의 셀의 내용만 렌더링하고, 나머지는 값을 지니고는 있지만 결코 보여주지 않는 덮인 공간으로 취급합니다. Excel 사용자는 시행착오를 통해 이를 몸으로 익힙니다. 보고서 생성기는 이를 규칙으로 부호화해야 합니다. 생성된 코드에서는 이 증상이 추적할 예외도 없이 그냥 빈 영역으로만 나타나기 때문입니다. Delphi와 C++Builder에서 두 Excel 형식을 모두 읽고 쓰는 네이티브 Object Pascal 라이브러리인 HotXLS는 병합 테이블을 충분히 명시적으로 드러내므로, 지원 티켓에서 규칙을 다시 발견하는 대신 그 규칙에 맞춰 프로그래밍할 수 있습니다

하나의 값, 하나의 앵커

병합은 형태를 바꾸지 않는 그리드 위에 얹힌 표시 지시일 뿐입니다. 덮인 모든 셀은 파일 안에서 여전히 자신만의 슬롯으로 존재하며, 병합 레코드는 소비자에게 앵커의 내용을 그 직사각형 전체에 걸쳐 그리라고 알려줄 뿐입니다. 이 구분은 레이아웃 코드를 작성하기 전에 체화해 둘 가치가 있는 세 가지 동작을 낳습니다. 덮인 셀을 읽으면 자신에게 저장된 값이 반환되는데, 직접 만든 배너의 경우 대개 비어 있으므로, 병합된 제목을 살피는 코드는 반드시 앵커를 해석해서 읽어야 합니다. 덮인 셀에 쓰기를 하면 파일 수준에서는 성공하지만 어디에도 나타나지 않으며, 이것이 앞서 나온 보이지 않는 헤더 함정입니다. 그리고 어떤 영역의 병합을 해제하면 그 아래에 줄곧 있던 것이 그대로 드러나므로, 덮인 공간에 잘못 써 넣은 값은 언젠가 누군가 병합을 해제하는 날 눈에 보이는 결함으로 바뀝니다

XLSX 쪽에서는 이 테이블이 일급 객체입니다. Sheet.MergedCells는 Add('A1:C1'), FindAt(Row, Col), DeleteAt, Items를 제공하며, 가장 자주 쓰게 되는 것은 FindAt입니다. 임의의 좌표를 건네주면 그 셀을 덮고 있는 병합 영역을 반환하고, 셀이 홀로 있으면 nil을 반환합니다. 이 단일 조회가 올바른 병합 처리의 두 축, 즉 안전한 읽기와 쓰기 가드 모두의 기반이 되며, 둘 다 뒤에서 다시 등장합니다

두 파사드, 두 병합 관용구

HotXLS는 전통적인 BIFF8 .xls 엔진과 OOXML .xlsx 엔진을 별도의 객체 모델로 유지하며, 서로 다른 관례에서 유래했기 때문에 병합을 표현하는 방식도 다릅니다. XLS 파사드는 Excel COM 관용구를 따릅니다. 두 인수를 받는 인덱스 속성으로 범위를 가져온 다음, 값에 따라 결과 기하가 결정되는 OleVariant를 인수로 Merge를 호출합니다

var
  Book: IXLSWorkbook;   // 인터페이스 참조 카운트: 수동으로 Free하지 않음
  Sh: IXLSWorksheet;
begin
  Book := TXLSWorkbook.Create;
  Sh := Book.Sheets[1];                 // XLS 시트 컬렉션은 1부터 시작
  Sh.Range['A1', 'F1'].Merge(False);    // False = 하나의 병합 블록
  Sh.Cells.Item[1, 1].Value := 'Quarterly Statement';
  Sh.Range['A3', 'F4'].Merge(True);     // True = 가로 병합: 행마다 하나씩 병합
  Book.SaveAs('layout.xls');
end;

Merge에 넘기는 인수가 사람들이 흔히 잘못 이해하는 부분입니다. 두 개 행에 걸친 범위에서 Merge(True)는 서로 독립된 두 개의 한 행짜리 병합을 만듭니다. 이는 Excel의 "가로 병합"이며, 행을 계속 구분할 수 있어야 하는 다단 헤더 밴드에 정확히 필요한 동작입니다. Merge(False)는 전체 직사각형을 하나의 블록으로 융합합니다. 이 범위는 또한 상태 플래그로 MergeCells를 보고하고, 자신을 포함하는 영역을 MergeArea로 반환하며, Unmerge로 스스로를 해제합니다. XLSX 파사드는 같은 연산을 다른 이름으로 노출합니다. Sheet.MergeCells(Row1, Col1, Row2, Col2)는 정수 범위를 인수로 받고, TXLSXRange.Merge는 이에 대응하는 Across 변형을 받아들이며, 결과는 MergedCells 컬렉션에 담깁니다

데이터와 함께 자라나는 템플릿

실제 보고서 템플릿은 고정된 그리드가 아닙니다. 헤더와 합계는 고정되어 있지만, 그 사이의 명세 구역은 쿼리가 반환하는 만큼 늘어납니다. 이를 잘 견디는 패턴은 완전히 스타일을 갖춘 명세 행 하나를 템플릿에 유지하고, 레코드마다 이를 한 번씩 복제한 다음, 합계 블록 앞에 틈을 열어 그 아래에 고정된 모든 것이 서식을 잃지 않고 밀려 내려가게 합니다

Sheet.Range['A1:F1'].Merge;
Sheet.Cells[1, 1].Value := 'INVOICE #2026-0611';    // 값은 앵커인 A1로 감
Sheet.RowHeight[1] := 28;
TitleFont := Book.Fonts.Add('Calibri', 16, True, False);
Sheet.Cells[1, 1].FontIndex := TitleFont + 1;        // 풀 인덱스는 0부터, 셀 쪽은 1부터

// 5행이 스타일을 갖춘 명세 템플릿 라인
for I := 0 to ItemCount - 1 do
  Sheet.CopyRange(5, 1, 5, 6, 6 + I, 1);             // 스타일과 수식도 함께 이동

// 합계 블록 위에 틈을 엽니다; 그 아래 내용은 아래로 밀려남
Sheet.InsertRows(6 + ItemCount, 1);
Sheet.Range['A1:F1'].SetBorders(xlsxEdgeOutline, xlsxBorderMedium);

다시 한번 눈여겨봐야 할 줄이 둘 있습니다. 글꼴 대입에는 조용히 무는 1씩 어긋난 계산이 숨어 있습니다. Fonts.Add는 0부터 시작하는 풀 위치를 반환하지만, 셀은 0이 기본 글꼴을 의미하는 1부터 시작하는 글꼴 참조를 저장하므로, + 1을 빠뜨려도 아무 예외도 발생하지 않고 그저 제목이 잘못된 서체로 스타일링될 뿐입니다. 다른 하나는 CopyRange로, 값과 함께 서식과 수식도 옮깁니다. 이것이 코드로 모양을 재구성하는 대신 직접 만든 템플릿 행을 복제하는 이유 전부입니다. 디자이너는 템플릿 안에서 외관을 딱 한 번 소유하고, 생성기는 그 복제본에 데이터를 부어 넣기만 하면 됩니다

재사용 가능한 레이아웃이 자신만의 워크북에 담겨 있을 때, 이를테면 여러 보고서가 공유하는 헤더와 푸터 밴드 시트가 있을 때 이 분리는 더 크게 확장됩니다. CopyRangeTo는 워크시트 경계를 넘어 동일한 복제를 수행하며, 대상 시트와 목적지 좌표를 인수로 받으므로, 생성기는 하나의 순수한 템플릿 시트를 유지하면서 작업이 필요로 하는 만큼 여러 출력 시트에 그 영역을 찍어 넣을 수 있습니다. 대안, 즉 템플릿을 제자리에서 변형한 뒤 나중에 복원하려는 방식은 실행이 중간에 중단되는 날까지만 작동하는 종류의 방식입니다

InsertRows가 옮기는 것과 옮기지 않는 것

템플릿을 늘려가는 패턴이 통하는 이유는 XLSX InsertRows가 단순한 셀 이동이 아니라 구조적 편집이기 때문입니다. 틈을 열 때 이 메서드는 삽입 지점 아래에 있는 병합 영역, 행 높이, 하이퍼링크, 코멘트, 고정 창, 자동 필터 범위, 조건부 서식, 데이터 유효성 검사, 표, 정의된 이름, 이미지 앵커, 차트 앵커를 재배치하며, 셀 값만 옮기는 것이 아닙니다. 이것이 합계 블록이 병합과 숫자 서식을 잃지 않은 채 새 행에 도착할 수 있는 이유입니다

문서화된 두 가지 한계는 설계 시 고려해야 합니다. 수식 조정은 편집 중인 시트로 범위가 한정됩니다. 그 시트 안의 참조는 다시 기록되며, 이동된 영역을 가리키는 다른 시트의 수식도 다시 기록되지만, 이 조정은 편집 중인 시트를 대상으로 하는 참조만 따라가므로, 워크북 간 참조 체계가 있다면 맹목적으로 신뢰하기보다 별도로 감사해야 합니다. 두 번째 한계는 더 날카로우며 XLS 쪽에 있습니다. 피벗 테이블은 열기-저장 주기를 HotXLS가 이동시킬 수 있는 모델링된 객체가 아니라 원시 상태 그대로 보존된 레코드로서 살아남으므로, 행을 삽입해도 피벗의 영역은 재배치되지 않습니다. .xls 형식을 위해 구축하는 어떤 템플릿이든 늘어나는 밴드로부터 피벗 영역을 확실히 떨어뜨려 놓아야 합니다

레이아웃 공간에 데이터를 쓰지 않도록 거부하기

실제로 운영 환경까지 도달하는 병합 셀 실패는 겉모습만의 문제가 아닙니다. 이는 구조적입니다. 명세 행이 병합된 레이아웃 밴드로 흘러 들어가면, 그 값들은 덮인 셀에 안착해 보이지 않게 되고, 열 합계는 시트를 보는 누구에게나 조용히 어긋나기 시작합니다. FindAt이 임의의 좌표에 대한 덮임 영역 질문에 답할 수 있으므로, 생성기는 잘못 어긋난 합계를 담은 보고서를 내보내는 대신 그 쓰기가 일어나려는 바로 그 순간에 거부할 수 있습니다

// 명세 데이터를 병합된 레이아웃 영역에 쓰는 것을 거부합니다
if Sheet.MergedCells.FindAt(Row, 1) <> nil then
  raise Exception.CreateFmt('row %d overlaps a merged layout region', [Row]);
Sheet.Cells[Row, 1].Value := Detail.Description;

같은 경계 검사는 사용자가 나중에 출력물을 정렬하거나 필터링할 곳 어디에나 필요합니다. 병합이 포함된 범위는 깔끔하게 정렬될 수 없습니다. 정렬은 행을 독립적으로 이동시키는데, 여러 행에 걸친 병합에는 함께 움직일 단일 행이 없기 때문입니다. Excel은 오류를 내거나 뒤엉킨 레이아웃으로 응답합니다. 보고서를 올바르게 유지하는 규율은 지리적입니다. 병합은 제목 밴드, 구획 구분선, 서명 블록에만 한정하고, 시트의 표 형태 중심부는 평평하게 유지하십시오. 템플릿 보고서 생성 문서는 이 레이아웃-대-데이터 구분을 완전한 플레이스홀더 기반 워크플로로 발전시키며, 조건부 서식과 리치 텍스트 문서는 그 평평한 데이터 밴드를 스타일링하는 방법을 다룹니다

내보내는 과정에서 병합이 저하되는 방식

병합은 워크북 개념이며, 텍스트 지향 내보내기 형식마다 이를 존중하는 정도가 다릅니다. 미리 세 가지 동작을 알아두면 QA 사이클 하나를 아낄 수 있습니다. HTML 내보내기는 병합을 충실하게 재현하여, 하나의 테이블 위에 colspan과 rowspan을 내보내므로, 브라우저 기반 보고서는 밴드 모양을 그대로 유지합니다. RTF 내보내기는 열 방향으로는 전혀 걸치지 않습니다. 앵커 텍스트는 자신의 셀 안에 안착하고, 병합의 나머지 너비는 빈 셀로 나오는데, 이는 워드 프로세서에서 넓은 제목이 시각적으로 왼쪽으로 밀린 것처럼 보이게 만듭니다. CSV에는 병합이라는 개념 자체가 없으므로, 앵커 값이 하나의 필드를 차지하고 덮인 모든 셀은 빈 필드로 나옵니다. 구분자 기반 내보내기도 함께 공급하는 워크북이라면, 얻을 수 있는 교훈은 무엇이든 하중을 지는 내용은 병합 기하 밖에 두라는 것입니다. CSV, TSV, HTML 내보내기 문서가 각 형식을 자세히 다룹니다

파일 크기와 견주어 이를 저울질하는 이들을 위한 안심할 만한 사실이 하나 있습니다. 병합은 보고서 규모에서는 거의 아무 비용도 들지 않습니다. 병합 테이블은 셀 데이터에 비하면 아주 작고, 덮인 셀을 읽는 것도 전체를 스캔하는 대신 여전히 FindAt을 거칩니다. 대규모 워크북에서 실제 성능 압박은 다른 곳, 주로 스타일 풀의 증가와 저장 경로가 붙잡고 있는 메모리에서 비롯되며, 이는 대규모 워크북 성능 문서가 직접 다룹니다. 두 병합 API, 구조적 편집 연산, 템플릿 데모 모두 HotXLS Delphi Component와 함께 제공됩니다