技術文章

從 Delphi 在 PDF 中實現 Flexbox、CSS Grid 與註腳

想像一個雙欄章節,在左欄倒數第二行放了註腳參照。一行註腳在該欄底部大約需要 14 點,而那裡只剩 9 點。兩個顯而易見的結局都是錯的:硬把註腳畫上去,它會印在本文上;只把註腳本身推到後面,它會落在右欄下方,跟它毫無關係的文字並排。瀏覽器從不必做這種抉擇,因為網頁沒有底緣。Flexbox 與 CSS Grid 正是在同一個假設下設計的,所以一旦報表 HTML 得落到固定尺寸的頁面上,兩者各自都需要一條「方框高度用完時怎麼辦」的規則

固定寬度方框裡的一列 flex 儀表板

PDF Library for Delphi 把任何套用 display: flex 或 display: inline-flex 的元素當成真正的 flex 容器,所以一列卡片就是一列,不會塌成一疊區塊。用 DrawHTMLTextBox(Left, Top, Width, Height, HTMLText) 繪製,它回傳一個 WideString:全部放得下時是空字串,否則是還得畫到別處的那部分

在列方向上,每個項目先取得基準,基準值與項目間的間距加總之後,行上剩下的空間再分出去。正的空間按 flex-grow 分;負的空間按 flex-shrink 乘上項目基準收回——這是 CSS 的規則,而且有個稍後展示的愉快副作用。設了 flex-wrap 時,下一個基準放不下就把項目移到新行,每一行分配自己的剩餘空間。justify-content、align-items、align-content、gap 與 -reverse 方向接手之後,移動的都是已量測完的方框

PDF Library for Delphi 圖解:flex 列尺寸計算——量測基準與 grow 權重、每行剩餘空間的加權分配,以及只做位移的對齊步驟,產出 2:1:1 的儀表板列
Flex 尺寸計算是一次有界的量測,再對剩餘空間加權分配;對齊只移動量測好的方框,絕不觸發重新量測
uses
  SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
  Html, Remainder: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetOrigin(1);          // 左上原點:Top 沿頁面向下增長
    Lib.SetPageSize('A4');

    // 百分比基準讓 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。基準合計正好是整個 515,超出量恰好就是那 18 點。收縮按基準加權,所以 50% 的卡片交回 9 點,每張 25% 卡片交回 4.5,剩下 248.5、124.25 與 124.25。比例仍精確是 2:1:1,程式碼從頭到尾不必手工減間距

為什麼 flex: 1 的等寬項目最後不等寬?

因為它們的基準是內容的寬度。轉譯器的基準取自 flex-basis、flex 簡寫裡的長度(帶 pt、px、em 或 % 的值),或 width。這些都沒給出正長度時,項目量測出的內容寬度就成了基準。裸的 flex: 1 與瀏覽器慣用寫法 flex: 1 1 0 都落在這條路上,因為無單位的 0 不會被當成長度解讀。相同的 grow 係數之後在不等的起始寬度上,加上等量的剩餘空間

把同一個儀表板改成每張卡片都寫 flex: 1,Revenue 卡——它的七位數字讓內容成為三者最寬——起始就比 Margin 卡寬,成長之後也恰好寬那麼多,因為每張卡片拿到的都是剩餘空間的三分之一。對工具列、標籤清單與按鈕列來說,這常常正是你要的樣子。對儀表板不是。任何要跟上下表格對齊的東西,都該用明確的百分比或點數基準、grow 設 0,這是我們的建議,也正是範例的寫法:三張卡片因此在每一頁都落在 248.5、124.25 與 124.25 點,管它裡面的數字是什麼

欄方向在縱軸上走同一套邏輯。基準取自 flex-basis 或 height,否則取量測出的內容高度,而剩餘空間只在容器宣告了 height 時才存在。沒宣告的話,容器就跟它的項目一樣高,justify-content 無東西可分

Grid 軌道、放置與跨行跨列

遇到 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 軌道各拿一份剩餘空間

PDF Library for Delphi 圖解:可接受的 grid 軌道值、確定的佔位放置(允許刻意重疊),以及跨列項目回傳其涵蓋各列的平均高度
Grid 軌道接受長度、百分比、fr 單位、repeat 與 minmax,自動放置則確定性地走訪佔用矩陣

放置是確定性的。自動放置的項目逐列走訪網格(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 容器永遠不會被拆到兩個方框裡。永遠不會。整個容器放不進剩餘空間時,容器與它之後的一切都進回傳的延續字串;由於延續字串正是你傳給下一個方框或下一頁的東西,卡片列就在下一個版面用它量測好的幾何原樣開場。半塊 KPI 卡留在第 3 頁底部、另外半塊在第 4 頁,比留個空隙還糟,這條規則買的就是這個取捨。比整個空方框還高的容器是例外:無論如何都畫在該框頂端、跑出底緣,因為後面的方框不會更大

實務上的結論是:把容器送上頁面之前,先知道它的高度。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 容器幾乎都是偽裝成 flex 的資料表格,而表格路徑有它自己的欄量測與 rowspan 支援,排版效果反而更好

註腳怎麼跟參照綁在一起?

PDF Library for Delphi 在遇到參照的當下量測該註腳,並從目前方框的本文預算中扣掉那個高度。註腳寫成 <aside style="float:footnote">、<aside role="doc-footnote"> 或 <footnote> 元素。參照變成上標數字,字號為周圍文字的三分之二;註腳本文以 8 點字、10 點行距排,前面冠以同一個數字

若目前為止的本文加上新註腳放不下了,標記與其後的一切一起移進延續字串。註腳與參照成對移動。這正是開場情境的答案:參照所在行與它的註腳一起開啟下一欄,蓋印與孤兒註腳都不會發生。在有邊界的方框裡,註腳區釘在底部一條四分之一框寬的細灰線下方。在無邊界的量測(例如 GetHTMLTextHeight)裡沒有底緣可釘,註腳直接跟在本文後面

PDF Library for Delphi 圖解:註腳分頁——註腳區保留在其方框底部一條分隔線下方,放不下的註腳連同標記移入續接字串,編號跨頁連續
註腳空間在更多文字排版之前就從本文預算中劃出,編號則跨欄、跨頁延續

每一個新的 HTML 字串編號都從 1 開始。下一個號碼就存在延續字串本身裡,所以 DrawHTMLTextBox 鏈與 DrawHTMLStory 能讓序號跨欄跨頁連續,前提是延續字串原封不動地傳回。用你自己的來源文字重建延續內容,計數會重新開始

Chapter :=
  '<p>The bearing stayed within tolerance for the full six hours' +
  '<aside style="float:footnote">Ambient temperature held at ' +
  '21 &deg;C throughout the run.</aside> of the load test.</p>' +
  MoreChapterHtml;                 // 你章節的其餘部分

// 2 欄、16 點欄間距、最多 20 頁;故事會自行加頁
Rest := Lib.DrawHTMLStory(40, 40, 515, 760, 2, 16, 20, Chapter);
Err := Lib.LastErrorCode;          // 只讀一次:讀取會歸零

if Err = PDFLIB_ERROR_HTML_STORY_INVALID then
  // 幾何參數不合法:欄數 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 的其餘功能