技术文章

从 Delphi 在 PDF 中实现 Flexbox、CSS Grid 和脚注

设想一个双栏章节在左栏倒数第二行放了个脚注引用。一条一行的注需要那栏底部约 14 pt,而那里只剩 9 pt。两种想得到的处理都是错的:硬画,注会压到正文上;只把注推过去,它会落到右栏底下,挨着与它毫无关系的文本。浏览器永远不必做这种裁决,因为网页没有底边。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 方向则只移动已经量好的盒子

PDF Library for Delphi 的 flex 行尺寸计算图:量得的 basis 与 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');

    // 百分比 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 pt 的盒子算一遍账。12px 的间距换算成 9 pt,两条间距花掉 18。basis 加起来正好是 515,超出量恰好是这 18 pt。收缩按 basis 加权,50% 的卡片交还 9 pt,每张 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 卡宽,增长后仍精确保持这段宽度差,因为每张卡拿到的都是剩余空间的三分之一。对工具栏、标签列表和按钮行,这往往正是想要的效果;仪表板不是。任何要与上下表格对齐的东西都值得用显式的百分比或 pt basis、grow 设 0——这是我们的建议,也正是示例的写法:三张卡片于是每一页都落在 248.5、124.25 和 124.25 pt 上,不管里面的数字是几位数

列方向在纵轴上遵循同样的逻辑。basis 来自 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 时逐列),跳过已被占的格子。只给了行的条目在该行里找空列;只给了列的条目沿该列向下找。两个坐标都给的条目精确落在它说的地方,哪怕压在另一个条目上——徽章叠在卡片上就是这么来的

跨行跨列要养成一个习惯。渲染器从斜杠后面的部分读 span,如 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 pt 的盒子里,标签列 120 pt,两条间距占 12,每个 1fr 列分得 191.5。Site plan 单元格有行没列,落到第 1 列、跨第 1、2 行。Inspector 和 Date 填满第 1 行其余部分。summary 有列没行,摆放沿第 2 列向下找,第 1 行被占,于是落进第 2 行、横跨两个弹性列

行高来自内容。跨行条目把量得的高度在所跨的行之间均摊,每行再取其中任何条目要求的最大份额,所以高单元格的额外高度摊在它碰到的每一行上,而不是全压在第一行。一个高的 Site plan 单元格因此把两行都抬一点,而不是只拉长第一行、让 Findings summary 悬在空档里

容器整块地在盒子间移动

flex 或 grid 容器永远不会被劈成两半放进两个盒子。永远不会。整个容器放不进剩余空间时,容器连同它后面的一切进入返回的余量;由于余量正是你要传给下一个盒子或下一页的东西,卡片行就在下一帧原样开场,几何量丝毫不变。第 3 页底部半块 KPI 瓦片、另一半在第 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 容器几乎总是化了装的数据表,而表格路径带着自己的列测量和 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 pt 栏间距、最多 20 页;story 自己加页
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 再测返回字符串的理由。非法参数原样返回输入,否则看起来就像一个用完页数的 story

让布局吃进真实内容

对多栏正文,连字符断行与均衡文本分栏一文中描述的栏与断字行为决定每栏内部流排的样子。标记来自数据而非手写模板时,数据集报表引擎是先生成标记、再由 flex 和 grid 在页面上排布的路线。之后还要离开 PDF 的内容走把 PDF 导出为 Markdown 与 DOCX

带 flex、grid 和脚注的 HTML 布局、报表生成与语义导出同属一个面向 Delphi、C++Builder 和 Free Pascal 的库。PDF Library for Delphi 产品页列出了 HTML 渲染器其余部分和绘图 API