技术文章

使用 HotPDF 图元在 PDF 中绘制图表 (Delphi)

把屏幕图表控件以 96 DPI 位图拷出的图表放进 PDF,100% 缩放下看着挺好。放大到 400%,或者把页面送到 600 DPI 激光打印机,条形边缘发软,轴标签糊成灰斑,文件里还背着几百 KB 的像素——而真相不过是一打矩形。改成矢量路径绘制,同一张图在任何缩放级别和打印分辨率下都保持锐利,因为条形、坐标轴和标签都是 PDF 路径和文本操作符,查看器需要多大比例就按多大比例重渲

矢量输出把布局工作挪进你的代码。总得有什么东西算出每根条、每个刻度和每个标签落在哪里;对条形图、折线图和饼图,这个计算就是一次坐标映射加上几段对矩形、线段和弧的循环。映射一次做对,循环都很短

HotPDF 里用 DrawChart 还是手绘图元?

HotPDF 自带一个现成的图表渲染器,标准报表图表先试它就对了。建一个 THPDFChart,用 AddSeries 加系列(种类有 hckLine、hckBar、hckArea、hckPie 和 hckScatter),用 AddPoint 填数据,再带一个目标矩形调 THPDFPage.DrawChart。渲染器自己搞定轴范围、网格、刻度标签、图例和主题色;带结构父节点的重载还会把图表写成带标签的插图,备用文本从数据生成——文档要过无障碍检查时这一点很要紧

var
  Chart: THPDFChart;
  Sales: THPDFChartSeries;
begin
  Chart := THPDFChart.Create;
  try
    Chart.Title := 'Quarterly sales';
    Chart.LegendPosition := hclBottom;
    Sales := Chart.AddSeries(hckBar, 'Sales');
    Sales.AddPoint(1, 420, 'Q1');
    Sales.AddPoint(2, 515, 'Q2');
    Sales.AddPoint(3, 388, 'Q3');
    Sales.AddPoint(4, 610, 'Q4');
    // 页面单位的 Rectangle:left、top、width、height
    HotPDF1.CurrentPage.DrawChart(Chart, 60, 120, 470, 280);
  finally
    Chart.Free;
  end;
end;

不过渲染器的词汇量是固定的。多组条形系列在各类别里并排,饼图必须是其图表里唯一的系列,外观来自三套主题加每系列配色。堆叠条形、条形后面的目标带阴影、单一系列里每根条不同的品牌色、从十二点方向顺时针起始的饼图:设计一旦提出其中任何一条,用页面画布自己画反而比掰弯渲染器省事。那些图元是 Rectangle、MoveTo、LineTo、Pie、Fill、Stroke 和 TextOut,与 画布绘制走查一文里讲的是同一批调用

为什么我的条形图是倒挂的?

HotPDF 页面坐标把原点放在左上角、Y 向下增长,和 VCL 画布同一个框架。PDF 用户空间本身方向相反(原点在左下、Y 向上,ISO 32000-1 §8.3.2.3),HotPDF 写内容流时把每个坐标都翻进那个空间。而图表数值向上增长。把缩放后的值直接当 Y 喂进去,最高的条就会像冰柱一样从绘图区顶部吊下来

修正只要一个表达式。选好绘图矩形,把零映到底边、刻度顶端映到顶边,每个值碰页面之前先过这道映射。对 0 到 MaxValue 刻度上的值 V,页面 Y 是 Plot.Bottom - (V / Plot.MaxValue) * Plot.Height,其中 Plot.Bottom 是基线。后文的条形图代码把它包进一个小小的 ValueToY 辅助函数,其他例程全部复用

HotPDF:屏幕坐标与 HotPDF 页面坐标共享左上原点、Y 向下增长,而图表数值向上增长;ValueToY 把数据值翻转进该 Y 向下的页面空间
HotPDF 保留了熟悉的屏幕坐标系:原点在左上、Y 向下增长,一个 ValueToY 表达式即可把每个向上增长的数据值翻转进页面空间

那个表达式里藏着两个选择。MaxValue 应取比最大数据点高一档的整数,比如下一个 10 或 100 的倍数,这样最高的条不碰顶边,网格线标签读起来是 0、200、400 而不是 0、203.5、407。刻度从零开始是刻意的:条长就是数值,从 350 起刻的值轴会让 388 的条看起来只比 420 的条高一半出头,而真实差距不到 8%。内建渲染器对条形和面积系列把零拉进范围,正是这个原因;手绘代码请保持同一条规则

单位是映射的另一半。默认 Resolution 为 72 时,一个页面单位就是一个 PDF 点(1/72 英寸)。改了分辨率,你的坐标、线宽和文字测量全部切换到新单位,Resolution 与绘图单位一文有详细说明。DrawChart 的目标矩形用页面单位,但自己的边距、字号和线宽在任何分辨率下都按点排布

条形图是对矩形的循环

映射就位后,条形图就是一个循环。把绘图宽按类别切成槽位,留出间隙让相邻的条不贴在一起,每根条画成从 ValueToY 顶端到基线的填充矩形。Rectangle 接受左上角、宽、高,正好配这个映射:

HotPDF:条形图解剖图:按绘图区宽度划分槽位并在条间留隙,每根条是从 Plot.Bottom 向上生长的填充 Rectangle,类别标签位于基线下方,数值标签随条高,轴刻度复用 ValueToY
每根柱是在其槽位内从 Plot.Bottom 向上生长的一个实心 Rectangle,四分之一槽宽的间隔随宽度缩放,坐标轴刻度复用 ValueToY,柱体与网格线因此对齐
type
  TPlotArea = record
    Left, Bottom, Width, Height: Single;  // 页面单位;Bottom 是基线 Y
    MaxValue: Single;                     // 数值刻度的顶端
  end;

// 你自己的辅助函数:值越大位置越高,在 Y 向下的页面上
// 意味着更小的 Y
function ValueToY(const Plot: TPlotArea; V: Single): Single;
begin
  Result := Plot.Bottom - (V / Plot.MaxValue) * Plot.Height;
end;

procedure DrawBarChart(Page: THPDFPage; const Plot: TPlotArea;
  const Values: array of Single; const Labels: array of string;
  const BarColors: array of TColor);
var
  I, Count: Integer;
  SlotW, BarW, BarX, BarTop, Gap, GridV, GridY: Single;
begin
  Count := Length(Values);
  SlotW := Plot.Width / Count;
  Gap := SlotW * 0.25;              // 槽位的四分之一,左右各一半
  BarW := SlotW - Gap;

  // 先画虚线网格,条形随后盖在它们上面
  Page.SetLineWidth(0.5);
  Page.SetRGBStrokeColor(RGB(200, 200, 200));
  Page.SetDash([2, 2], 0);
  GridV := Plot.MaxValue / 4;
  while GridV <= Plot.MaxValue do
  begin
    GridY := ValueToY(Plot, GridV);
    Page.MoveTo(Plot.Left, GridY);
    Page.LineTo(Plot.Left + Plot.Width, GridY);
    Page.Stroke;
    GridV := GridV + Plot.MaxValue / 4;
  end;
  Page.NoDash;

  Page.SetFont('Arial', [], 9);
  for I := 0 to Count - 1 do
  begin
    BarX := Plot.Left + I * SlotW + Gap / 2;
    BarTop := ValueToY(Plot, Values[I]);

    Page.SetRGBFillColor(BarColors[I mod Length(BarColors)]);
    Page.Rectangle(BarX, BarTop, BarW, Plot.Bottom - BarTop);
    Page.Fill;

    // TextOut 把文本顶边放在 Y 处
    Page.SetRGBFillColor(clBlack);
    Page.TextOut(BarX, Plot.Bottom + 4, 0, Labels[I]);
    Page.TextOut(BarX, BarTop - 12, 0, FormatFloat('0', Values[I]));
  end;

  // 基线最后画,压在条形底部之上
  Page.SetLineWidth(1.0);
  Page.SetRGBStrokeColor(clBlack);
  Page.MoveTo(Plot.Left, Plot.Bottom);
  Page.LineTo(Plot.Left + Plot.Width, Plot.Bottom);
  Page.Stroke;
end;

顺序就是这里的整个分层模型。PDF 用画家的模型:内容流里靠后的操作符盖在靠前的上面,所以网格线先画,条形盖上去,基线最后。把网格线那段挪到循环下面,虚线就会横穿每根条

间隙取槽位的比例而不是固定的点数。470 点宽的绘图区放四个类别,每槽 117.5 点,条间约有 29 点的空气;放到四十个类别,同一段代码留出的间隙不足 3 点,看起来仍是分明的条形。换成固定 12 点间隙,四十个类别要吞掉 480 点,超出 470 点的可用宽度,条宽会算成负数

互不打架的轴标签

标签是手绘图表最先坏掉的地方,而且坏法几乎总一样。屏幕上放得下的文字到了页面上就溢出,因为开发测试用的是“Sep”,德语报表印出来却是“September”或“Dezember”,用的还是 9 磅字。值轴有同一问题的安静版本:固定 X 偏移的左对齐刻度标签,数字一变长就参差,“1,200”会撞上“800”让出来的轴线

量,别猜。TextWidth 返回字符串在当前字体下按页面单位的宽度,TextHeight 返回当前字号的上伸高度。把每个刻度标签右对齐到轴上、竖直居中到刻度上:

procedure DrawValueAxis(Page: THPDFPage; const Plot: TPlotArea;
  TickCount: Integer);
var
  I: Integer;
  TickV, TickY: Single;
  S: string;
begin
  Page.SetLineWidth(1.0);
  Page.MoveTo(Plot.Left, Plot.Bottom);
  Page.LineTo(Plot.Left, Plot.Bottom - Plot.Height);
  Page.Stroke;

  Page.SetFont('Arial', [], 8);
  for I := 0 to TickCount do
  begin
    TickV := (Plot.MaxValue / TickCount) * I;
    TickY := ValueToY(Plot, TickV);
    Page.MoveTo(Plot.Left - 4, TickY);        // 轴外侧的短刻度
    Page.LineTo(Plot.Left, TickY);
    Page.Stroke;

    S := FormatFloat('#,##0', TickV);
    Page.TextOut(Plot.Left - 7 - Page.TextWidth(AnsiString(S)),
      TickY - Page.TextHeight(AnsiString(S)) / 2, 0, S);
  end;
end;

类别标签方面,同样的测量告诉你什么时候该放弃水平排版。画任何东西之前,先把最宽的标签和槽宽比一比。放不下就把字号降一两磅;还放不下,就给 TextOut 的角度参数传 90 让标签立起来,然后在基线下给最长的那个留足边距。用报表真能产出的最宽标签做测试——本地化版本里月份名最宽的通常不是英文那个

折线图复用同一映射

折线图只改点的连接方式。把数据走一遍,每个值用 ValueToY 转换,再把点串成一条路径:第一个点 MoveTo,之后每个点 LineTo,最后 Stroke 一次。如果点已经在数组里,Polyline 接受 array of THPDFCurrPoint,开一条新路径,描边留给你;点数少于两个会抛异常,所以只有一个读数的系列该画标记而不是线

间距是折线图与同绘图区条形图分道扬镳之处。条形按类别数分宽度,因为每根条占一个槽;折线按区间数 Count - 1 分,因为首尾两个点落在绘图区边缘。两者叠加时,折线的点会落在槽位边界而不是条形中心。折线骑在条形上时,把点放在每个槽的中心 Plot.Left + I * SlotW + SlotW / 2,彻底放弃 Count - 1 间距。要每个点带标记,在线描完之后补一个小 Circle 加 Fill 即可

用 Pie 画扇形,从十二点顺时针

一块扇瓣是两条半径加一条弧。手搓的做法从圆心出发,沿边缘每隔两三度走一小段 LineTo,最后闭合回圆心,即下面插图里的构造。能用,但一个 270 度的扇瓣会变成一百多段路径,放大了边缘仍是多边形

HotPDF:扇形构造:从圆心的 MoveTo 开始,沿每个扇形扫过角的弧线以约两度间隔逐步画出小的 LineTo 段,再闭合回圆心,使 Fill 填充实心楔形
扇形从圆心 MoveTo 开始,沿弧段以约两度间隔走小步 LineTo,最后闭合,Fill 即可将其涂实

换成 Pie。THPDFPage.Pie 遵循 GDI 惯例:一个包围矩形、以度为单位的首尾角,0 指东、90 指北、正角逆时针。它用每段至多 90 度的贝塞尔构建弧,画到圆心的连线,再闭合路径,边缘因此保持真曲线,一个完整扇瓣只花几个操作符。业务饼图通常从十二点顺时针走,用 GDI 的话说就是从 90 起步让角度往下走:

procedure DrawPieChart(Page: THPDFPage; CX, CY, Radius: Single;
  const Values: array of Double; const Colors: array of TColor);
var
  I: Integer;
  Total, Sweep, Angle: Double;
begin
  Total := 0;
  for I := 0 to High(Values) do
    if Values[I] > 0 then
      Total := Total + Values[I];
  if Total <= 0 then
    Exit;

  Angle := 90;                            // 十二点方向
  Page.SetRGBStrokeColor(clWhite);
  Page.SetLineWidth(0.8);
  for I := 0 to High(Values) do
  begin
    if Values[I] <= 0 then
      Continue;                           // 见下文:绝不要传入零或负的扫角
    Sweep := Values[I] / Total * 360;
    Page.SetRGBFillColor(Colors[I mod Length(Colors)]);
    // 从 Angle - Sweep 到 Angle 的逆时针弧,正是当前位置
    // 顺时针一侧的那块扇瓣
    Page.Pie(CX - Radius, CY - Radius, CX + Radius, CY + Radius,
      Angle - Sweep, Angle);
    Page.FillAndStroke;                   // 白色描边用来分隔扇瓣
    Angle := Angle - Sweep;
  end;
end;

Continue 那道护栏是全文最要紧的一行。Pie 按 GDI 的读法把小于起始角的终止角当成绕过 360 的扫角,这正是扇瓣能跨越 0 度线的原因。源数据里一行退款或一条更正会给出负值,算出的终止角落到起始角之下,扇瓣绕成一整块几乎满圆的圆盘,盖住之前画的一切。零值温和些但仍然可见:闭合路径塌缩成一条半径,白色分隔描边把它画成一条从边缘到圆心的杂线。两者都要在循环前过滤,另外单独决定报表如何呈现负数——饼图根本表现不了它们

设计不坚持圆形时,一根水平堆叠条就能用首尾相接的 Rectangle 呈现同样的份额,而且读者比较长度比比较角度更准。超过五六个类别的部分-整体图,这是更好的选择,上面的条形图代码已经干了大半活

本文每张图都用 HotPDF Delphi Component 的页面画布调用画成,标准折线、条形、面积、饼图与散点布局另有 DrawChart 可用;无论 Delphi 还是 C++Builder 都能直接跑,构建机上无需安装任何图表库