두 단 챕터가 왼쪽 열의 끝에서 두 번째 줄에 각주 참조를 놓았다고 하자. 한 줄짜리 각주는 그 열 바닥에 대략 14포인트가 필요한데 남은 것은 9포인트다. 뻔한 두 결과 모두 틀리다. 어차피 각주를 그리면 본문 위에 덧인쇄되고, 각주만 다음으로 밀면 오른쪽 열 아래, 아무 상관 없는 텍스트 옆에 놓인다. 브라우저는 이 판단을 할 필요가 아예 없다. 웹 페이지에는 바닥이 없기 때문이다. Flexbox와 CSS Grid도 같은 가정 아래 설계됐으므로, 리포트 HTML이 고정 크기 페이지에 떨어져야 하는 순간부터 둘 각각에 상자의 높이가 다 삭았을 때 무슨 일이 일어나는지에 대한 규칙이 필요하다
고정 폭 상자 안의 flex 대시보드 행
PDF Library for Delphi는 display: flex나 display: inline-flex 스타일이 먹은 엘리먼트를 진짜 flex 컨테이너로 다루므로, 카드 한 행은 쌓인 블록으로 무너지는 대신 행으로 남는다. 그리기는 DrawHTMLTextBox(Left, Top, Width, Height, HTMLText)로 하며 이것은 WideString을 반환한다. 전부 들어갔으면 빈 문자열, 아니라면 아직 다른 곳에 그려야 하는 부분이다
행 방향에서는 각 아이템이 basis를 받고, basis 값들과 아이템 사이 간격이 합산되며, 선에 남는 것은 나눠 준다. 양수 공간은 flex-grow대로 간다. 음수 공간은 flex-shrink에 아이템의 basis를 곱한 만큼 거둬들이는데, 이것이 CSS 규칙이고 잠시 후 보일 쓸모 있는 부작용이 있다. flex-wrap이 설정되어 있으면 다음 basis가 더 들어가지 않는 순간 아이템이 새 줄로 옮겨 가고 각 줄은 자기 빈 공간을 배분한다. justify-content, align-items, align-content, gap, -reverse 방향은 이미 측정된 상자들을 움직일 뿐이다
uses
SysUtils, PDFlibrary;
var
Lib: TPDFlib;
Html, Remainder: WideString;
begin
Lib := TPDFlib.Create;
try
Lib.SetOrigin(1); // 왼쪽 위 원점: Top이 페이지 아래로 자람
Lib.SetPageSize('A4');
// 백분율 basis는 2:1:1 비율을 간격까지 정확히 유지한다
Html :=
'<div style="display:flex; gap:12px;">' +
'<div style="flex:0 1 50%; background:#f4f6f8; padding:8px;">' +
'<b>Revenue</b><br/>EUR 4,182,300</div>' +
'<div style="flex:0 1 25%; background:#f4f6f8; padding:8px;">' +
'<b>Margin</b><br/>18.4%</div>' +
'<div style="flex:0 1 25%; background:#f4f6f8; padding:8px;">' +
'<b>Backlog</b><br/>92 days</div>' +
'</div>';
Remainder := Lib.DrawHTMLTextBox(40, 40, 515, 120, Html);
if Remainder <> '' then
raise Exception.Create('Dashboard row needs more than 120 pt');
Lib.SaveToFile('dashboard.pdf');
finally
Lib.Free;
end;
end;
515포인트 상자로 계산해 보자. 12px 간격은 9포인트로 환산되므로 간격 둘이 18을 먹는다. basis의 합은 꽉 찬 515이고, 정확히 그 18포인트만큼 넘친다. shrink는 basis로 가중되므로 50% 카드는 9포인트를 돌려주고 25% 카드 각각은 4.5를 돌려주어 248.5, 124.25, 124.25가 남는다. 비율은 여전히 정확히 2:1:1이고 코드는 간격을 손으로 뺄 필요가 한 번도 없었다
같은 flex: 1인데 왜 크기가 다르게 나오는가?
basis가 콘텐츠의 폭이기 때문이다. 렌더러는 flex-basis에서, flex 축약형 안의 길이(pt, px, em, %가 붙은 값)에서, 또는 width에서 basis를 가져온다. 이중 아무것도 양수 길이를 내지 않으면 아이템의 측정된 콘텐츠 폭이 basis가 된다. 맨 flex: 1과 브라우저 관용구 flex: 1 1 0은 모두 거기로 끝난다. 단위 없는 0은 길이로 읽히지 않기 때문이다. 그 후 같은 grow 계수는 같은 양의 빈 공간을 서로 다른 시작 폭 위에 얹는다
같은 대시보드를 모든 카드에 flex: 1을 주고 쓰면, 일곱 자리 숫자 때문에 콘텐츠가 셋 중 가장 넓은 Revenue 카드가 Margin 카드보다 넓게 시작하고 성장 후에도 정확히 그만큼 더 넓은 채로 남는다. 각 카드가 남는 빈 공간의 3분의 1씩을 똑같이 받기 때문이다. 툴바나 태그 목록, 버튼 행에는 흔히 그게 원하는 모습이기도 하다. 대시보드는 아니다. 위아래 테이블과 맞춰야 하는 것은 grow를 0으로 둔 명시적인 백분율이나 포인트 basis를 받을 자격이 있다. 이것이 우리의 권장이자 예제가 정확히 하는 일이다. 그러면 세 카드는 안에 든 숫자가 무엇이든 매 페이지 248.5, 124.25, 124.25포인트에 떨어진다
열 방향은 수직 축에서 같은 논리를 따른다. basis는 flex-basis나 height에서 오고, 없으면 측정된 콘텐츠 높이에서 온다. 빈 공간은 컨테이너가 height를 선언했을 때만 존재한다. 없다면 컨테이너는 아이템들과 똑같은 높이이고 justify-content는 배분할 것이 없다
그리드 트랙, 배치, 스팬
display: grid에는 PDF Library for Delphi가 grid-template-columns와 grid-template-rows를 고정 길이, 백분율, fr 단위, repeat(n, track), minmax(a, b)로 읽는다. 고정 트랙과 간격을 가용 폭에서 빼고 나머지를 fr 가중치로 나눈다. minmax() 트랙은 두 번째 인수로 크기가 정해지므로 minmax(120px, 1fr)은 1fr처럼 동작하고, auto, min-content, max-content 트랙은 각각 빈 공간 몫 하나를 가져간다
배치는 결정론적이다. 자동 배치 아이템은 그리드를 행마다(또는 grid-auto-flow: column이면 열마다) 걸어 가며 이미 점유된 셀을 건너뛴다. 행만 주어진 아이템은 그 행에서 빈 열을 찾고, 열만 주어진 아이템은 그 열을 아래로 찾는다. 두 좌표를 모두 가진 아이템은 다른 아이템 위에서조차 말한 자리 그대로 간다. 배지가 카드 위에 겹쳐 놓이는 방식이 이것이다
스팬에는 하나의 습관이 필요하다. 렌더러는 스팬을 슬래시 뒤 부분, 곧 grid-row: 1 / span 2에서, 또는 grid-row-end: span 2와 grid-column-end: span 2에서 읽는다. 브라우저가 통째 값으로 받아 주는 맨 grid-row: span 2는 그 철자들에 속하지 않으므로 시작 라인과 슬래시를 유지하라
// 점검 시트: 고정 라벨 열, 유연한 열 두 개
Html :=
'<div style="display:grid; ' +
'grid-template-columns:120pt repeat(2, 1fr); gap:6pt;">' +
'<div style="grid-row:1 / span 2; background:#eef2ff;">' +
'Site plan</div>' +
'<div>Inspector</div>' +
'<div>Date</div>' +
'<div style="grid-column:2 / span 2;">Findings summary</div>' +
'</div>';
Remainder := Lib.DrawHTMLTextBox(40, 180, 515, 260, Html);
그 515포인트 상자에서 라벨 열은 120포인트, 간격 둘이 12를 먹고 1fr 열 각각은 191.5를 받는다. Site plan 셀은 행은 있지만 열이 없으므로 열 1에 떨어져 행 1과 2를 커버한다. Inspector와 Date가 행 1의 나머지를 채운다. 요약 셀은 열은 있지만 행이 없으므로 배치가 열 2를 아래로 찾고, 행 1이 점유된 것을 확인한 뒤 두 유연 열에 걸친 행 2에 자리 잡는다
행 높이는 콘텐츠에서 나온다. 스팬 아이템이 자기 측정 높이를 커버하는 행들에 고르게 나눠 주고, 각 행은 그 안의 어떤 아이템이든 요구하는 가장 큰 몫을 취하기 때문에, 키 큰 셀의 초과 높이는 첫 행에 떨궈지는 대신 닿는 모든 행에 퍼진다. 그래서 키 큰 Site plan 셀은 첫 행만 늘려 Findings summary를 공중에 띄워 두는 대신 두 행을 조금씩 올린다
컨테이너는 상자 사이를 조각 나지 않고 이동한다
flex나 grid 컨테이너는 두 상자에 걸쳐 쪼개지지 않는다. 결코. 컨테이너 전체가 남은 공간에 들어가지 않으면 컨테이너와 그 뒤의 모든 것이 반환되는 remainder로 들어가고, 그 remainder가 다음 상자나 다음 페이지에 넘기는 그것과 정확히 같으므로 카드 행은 측정된 기하를 온전히 가진 채 다음 프레임을 연다. 3페이지 바닥의 KPI 타일 절반이 4페이지에 나머지 절반으로 이어지는 것은 빈 공간보다 못하며, 이 규칙이 감수하는 trade-off가 그것이다. 빈 상자 하나보다 키가 큰 컨테이너가 예외다. 그 상자의 맨 위에 어차피 그려지고 바닥을 넘어 흘러나온다. 이후의 어떤 상자도 더 클 수는 없기 때문이다
실용적 귀결은 페이지에 커밋하기 전에 컨테이너의 높이를 알아야 한다는 것이다. GetHTMLTextHeight(Width, HTMLText)는 그리지 않고 측정하며 flex와 grid도 포함된다
// GridHtml, Y, PageBottom은 여러분의 리포트 코드 소유
Needed := Lib.GetHTMLTextHeight(515, GridHtml);
if Y + Needed > PageBottom then
begin
Lib.NewPage;
Lib.SetPageSize('A4');
Y := 40;
end;
Lib.DrawHTMLTextBox(40, Y, 515, Needed, GridHtml);
Y := Y + Needed + 12;
측정은 의도적으로 유한하다. 고객이 템플릿을 편집할 때 중요해지는 부분이다. flex나 grid 컨테이너는 직계 자식 첫 256개를 받고, grid 배치는 64행 안에서 동작하며, 트랙 목록은 최대 64개 트랙을 담는다. repeat() 개수도 맞춰 제한된다. 자식 수백 개짜리 flex 컨테이너는 거의 항상 변장한 데이터 테이블이고, 자체 열 측정과 rowspan 지원을 갖춘 테이블 경로가 어차피 더 잘 배치한다
각주는 어떻게 참조와 함께 다니는가?
PDF Library for Delphi는 참조를 만나는 순간 각 각주를 측정하고 그 높이를 현재 상자의 본문 예산에서 뺀다. 각주는 <aside style="float:footnote">, <aside role="doc-footnote"> 또는 <footnote> 엘리먼트로 쓴다. 참조는 주변 글꼴 크기의 3분의 2인 윗첨자 숫자가 되고, 각주 텍스트는 같은 숫자를 접두어로 10포인트 리딩에 8포인트로 짜인다
지금까지의 본문에 새 각주를 더했을 때 더 들어가지 않으면 마커와 그 뒤의 모든 것이 함께 remainder로 옮겨 간다. 각주와 참조는 한 쌍으로 이동한다. 도입부 시나리오의 해답이 이것이다. 참조 줄과 그 각주가 다음 열을 열고, 덧인쇄도 홀로 남은 각주도 일어나지 않는다. 유한한 상자에서 각주 영역은 상자 폭 4분의 1 길이의 얇은 회색 선 아래 바닥에 고정된다. GetHTMLTextHeight 같은 무한 측정에서는 고정할 바닥이 없으므로 각주는 본문 바로 뒤를 따른다
새 HTML 문자열마다 번호는 1부터 시작한다. 다음 번호는 remainder 문자열 안에 저장되므로, remainder를 반환된 그대로 정확히 되돌려 주는 한 DrawHTMLTextBox 체인과 DrawHTMLStory는 열과 페이지를 넘어 하나의 연속 번호열을 유지한다. 자기 소스 텍스트에서 이어짐을 다시 만들면 번호는 처음부터 다시 시작된다
Chapter :=
'<p>The bearing stayed within tolerance for the full six hours' +
'<aside style="float:footnote">Ambient temperature held at ' +
'21 °C throughout the run.</aside> of the load test.</p>' +
MoreChapterHtml; // 챕터의 나머지 부분
// 2열, 16pt 거터, 최대 20페이지. 스토리가 알아서 페이지를 추가한다
Rest := Lib.DrawHTMLStory(40, 40, 515, 760, 2, 16, 20, Chapter);
Err := Lib.LastErrorCode; // 한 번만 읽기. 읽으면 리셋된다
if Err = PDFLIB_ERROR_HTML_STORY_INVALID then
// 잘못된 기하: Columns 1..64, MaxPages 1..10000, Width보다 좁은 거터
else if Err = PDFLIB_ERROR_HTML_STORY then
// 연속 두 프레임이 진전 없음
else if Rest <> '' then
// 20페이지 소진, 텍스트 남음. 나중에 Rest로 계속
;
DrawHTMLStory(Left, Top, Width, Height, Columns, Gutter, MaxPages, HTMLText)는 현재 페이지에서 시작해 열을 왼쪽에서 오른쪽으로 채우고, 텍스트가 떨어지거나 MaxPages에 닿을 때까지 같은 크기의 페이지를 추가한다. 반환 문자열을 검사하기 전에 LastErrorCode를 읽어야 하는 이유가 세 결과를 가르기 위해서다. 잘못된 인수는 입력을 그대로 돌려주는데, 그게 아니면 페이지가 다 떨어진 스토리와 똑같이 보인다
레이아웃에 실제 콘텐츠 먹이기
다단 본문 텍스트에서는 하이픈네기와 균형 잡힌 텍스트 열에서 기술한 열과 하이픈네기 동작이 각 열 안에서 흐름이 어떻게 보이는지를 결정한다. 마크업이 손으로 쓴 템플릿이 아니라 데이터에서 나온다면, flex와 grid가 페이지에 배치하기 전에 그것을 생성하는 경로는 데이터셋 리포트 엔진이다. 나중에 다시 PDF 밖으로 나가야 하는 콘텐츠는 PDF를 Markdown과 DOCX로 내보내기를 거친다
flex와 grid, 각주를 갖춘 HTML 레이아웃, 리포트 생성, 시맨틱 내보내기는 Delphi, C++Builder, Free Pascal용 하나의 라이브러리로 함께 제공된다. PDF Library for Delphi 제품 페이지에 HTML 렌더러의 나머지와 드로잉 API가 정리되어 있다