技术文章

PDF 导出与打印中的 Excel 填充符(*)

用自制格式化器导出一张 Excel 会计格式 44 的工作表,PDF 里的 $1,234.50 会挤成一团,或者带一个多余的星号变成 $* 1,234.50。那道空隙是 * 填充符,宽度由列宽和字体决定;它在文本中的位置由 HotXLS 经 TXLSXCell.GetFormattedTextFill 返回,渲染器数重复次数靠它就够了

* 和 _ 在 Excel 数字格式里怎么工作?

ECMA-376 Part 1 §18.8.30 在格式代码符号表里定义了这两个字符。* 把后一个字符重复“足够多次以填满列的当前宽度”;一节只容一个星号,出现多个时除最后一个外全部忽略。_“跳过后一个字符的宽度”,_) 于是留出与右括号等宽的空白,正数金额与显示成 (1,234.50) 的负数对齐。标准的例子很短:0*- 把短横线从数字一直排到单元格边缘,格式开头的 *0 给出前导零,0*x 在特定宽度的列里把 3 显示成 3xxxxxx。把两个字符合起来用的是 Excel 内置会计格式,ID 41 到 44。这些编号是 Excel 自家的:§18.8.30 的内置表从 40 直接跳到 45,HotXLS 按下面的 Excel 编号注册这四个代码

Excel ID格式代码符号小数位
41_(* #,##0_);_(* (#,##0);_(* "-"_);_(@_)无0
42_("$"* #,##0_);_("$"* (#,##0);_("$"* "-"_);_(@_)$0
43_(* #,##0.00_);_(* (#,##0.00);_(* "-"??_);_(@_)无2
44_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)$2

把 44 的正数节 _("$"* #,##0.00_) 从左往右读:一个与 ( 等宽的空白、一个美元符号、重复到填满列的空格、数字,以及一个与 ) 等宽的空白。负数节把末尾那个空白换成真括号。零节打印一条短横线跟 ??——两个数字宽的空白,把短横线安放在小数点那一列。数值选中四节中的哪一节、空节做什么,遵循 Excel 数字格式节的规则。去掉填充符,美元符号就贴上数字;把星号印出来,读者看到的就是格式语法

Delphi 中 HotXLS 解析 Excel 会计格式 44 正数节的结构:括号等宽空白、美元符号、重复空格填充与数字
一个星号让后一个字符重复到列宽,会计节里每个空白都来自下划线

格式化器为什么不能自己插入重复?

因为它不知道次数。重复次数等于列宽减去其余所有内容的宽度,再除以一个填充符的宽度,每一项都取决于字体、字号、缩放和输出设备。返回纯字符串的格式化器必须自己挑个数,而一旦有人调整列宽,任何固定数字都是错的。HotXLS 把活拆开:TXLSXCell.FormattedText 返回不含填充符副本的显示文本,GetFormattedTextFill 返回同一段文本外加填充符和一个索引——重复应归属的位置之前的字符数。格式没有填充符时该方法返回 False,富文本单元格也一样,它的 run 按原样绘制

自动负号排在填充符之前。格式 **0 配值 -5 时,文本是 -5,填充符是 *,索引是 1,宽单元格因此显示 -****5,与 Excel 的 Range.Text 对该单元格给出的字符串相同。没有列的调用者拿不到任何填充。TEXT 工作表函数就是这样的调用者,所以在 HotXLS 计算引擎里,A1 为 1234 时 TEXT(A1, "$* #,##0") 求值为 $1,234。下面的代码设置三种格式并打印渲染器各自收到的东西

Delphi 中 HotXLS GetFormattedTextFill 的契约:前缀文本、填充符与切分索引,渲染器借此为任意列宽数出重复次数
单元格报告切分点而非重复次数,因为只有画布知道真实的列宽
uses
  SysUtils, lxHandleX;

procedure InspectFills;
const
  Formats: array[0..2] of WideString = (
    // 与 Excel 内置格式 44 相同的代码
    '_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)',
    '0*-',     // 数字后面的短横线
    '**0');    // 数字前面的星号
  Values: array[0..2] of Double = (1234.5, 42, -5);
  // 每行应打印:
  //   [ $] fill " " [1,234.50 ]
  //   [42] fill "-" []
  //   [-] fill "*" [5]
var
  Book: TXLSXWorkbook;
  Sheet: TXLSXWorksheet;
  Text: WideString;
  Fill: WideChar;
  FillIndex, I: Integer;
begin
  Book := TXLSXWorkbook.Create;
  try
    Sheet := Book.Sheets.Add('Fills');
    for I := 0 to High(Formats) do
    begin
      Sheet.Cells[I + 1, 1].NumberFormat := Formats[I];
      Sheet.Cells[I + 1, 1].Value := Values[I];
      if Sheet.Cells[I + 1, 1].GetFormattedTextFill(Text, Fill, FillIndex) then
        Writeln(Format('[%s] fill "%s" [%s]', [
          Copy(Text, 1, FillIndex), string(Fill),
          Copy(Text, FillIndex + 1, MaxInt)]))
      else
        Writeln('no fill: ', string(Sheet.Cells[I + 1, 1].FormattedText));
    end;
    Sheet.SaveAsPDF('fills.pdf');   // PDF 导出按各列排布填充
  finally
    Book.Free;
  end;
end;

每行用方括号显示前缀、填充符和后缀。注意空白:第一行的前缀是一个空格加美元符号,后缀以空格结尾,都由 _ 对产生。SaveAsPDF 从同样三部分出发,按真实列宽算重复次数。fills.pdf 里美元符号应落在第一个单元格的左侧内边距上,42 后面的短横线应延伸到第二个单元格的右缘。那个文件的页面设置、边距和字体由常规的 工作表 PDF 导出设置负责

字符的剩余小数部分归哪一边?

General 和左对齐单元格:填充与后缀之间的空隙。重复次数是整数,几乎总会剩下一个字符的小数部分,§18.8.30 只字未提它去哪。Excel 自己的 PDF 输出和 Range.Text 展示如下摆放,取决于水平对齐方式:

Delphi 中 HotXLS 填充符剩余小数部分摆放矩阵:从 general 与左对齐到居中、右对齐和缩小字体填充
general 与左对齐把富余的小数放在填充与后缀之间,整列美元符号因此纹丝不动
  • General 与左对齐:前缀贴左侧内边距,后缀贴右侧内边距,剩余部分落在填充与后缀之间(没有后缀时在行尾)
  • 居中:前缀和填充向右移剩余的一半;右对齐全部移过去
  • 填充、两端对齐、分散对齐和自动换行文本:三部分从左连续排布,剩余在行尾
  • 缩进照常收窄可用宽度,“缩小字体填充”的单元格没有填充符

General 对齐是自制渲染器栽跟头的地方。General 下的数字通常右对齐,带填充的单元格不是。守住“数字靠右”的规则,剩余就会落在填充前面,把美元符号从左侧内边距顶开最多一个空格宽。一列格式 44 金额下来,美元符号逐行摇摆。少见的布局遵循同一模型:

  • 旋转文本:填充长度来自旋转后仍装得进单元格的最长行
  • 富文本:重复字符的样式取自填充位置之前的那个字符
  • 跨列居中:填充覆盖整个跨距
  • 多行文本:只有包含填充位置的那一行获得重复

从右到左的工作表是 HotXLS 唯一没有照抄 Excel PDF 导出的情形。那个导出会丢弃填充符和前缀字形,尽管同一些单元格的 Range.Text 仍包含它们。HotXLS 按网格展示的样子排布这类单元格,填充符在原位

在 VCL 画布上绘制填充

用什么画布画,就用什么画布量。自制网格、报表带和缩略图都一样。VCL 画布缩放时选择整数字号,按小数字号的字体度量算出的宽度比 GDI 实际画的略窄。单个字符的误差微不足道,一串重复下来就累积了。从较窄的宽度数起,左侧部分会溢出自己的矩形;绘制旗标里带 DT_END_ELLIPSIS 时,GDI 还会在后缀上叠一个省略号。下面的例程处理最常见的单行 General 或左对齐情形,其余一律走朴素的 TextRect 路径:

uses
  Windows, Types, Graphics, lxHandleX;

procedure DrawFilledCell(Canvas: TCanvas; const R: TRect; Cell: TXLSXCell);
const
  Pad = 2;                                   // 单元格内边距,像素
var
  Text: WideString;
  Fill: WideChar;
  FillIndex, Avail, Used, FillWidth, Count: Integer;
  Prefix, Suffix: string;
begin
  if not Cell.GetFormattedTextFill(Text, Fill, FillIndex) then
  begin
    Canvas.TextRect(R, R.Left + Pad, R.Top + Pad, Cell.FormattedText);
    Exit;
  end;
  Prefix := Copy(Text, 1, FillIndex);
  Suffix := Copy(Text, FillIndex + 1, MaxInt);

  // 用将实际绘制文本的同一画布、字体和字号来测量
  Avail := (R.Right - R.Left) - 2 * Pad;
  Used := Canvas.TextWidth(Prefix) + Canvas.TextWidth(Suffix);
  FillWidth := Canvas.TextWidth(string(Fill));
  Count := 0;
  if (FillWidth > 0) and (Used < Avail) then
    Count := (Avail - Used) div FillWidth;   // 只取整数字符

  // General / 左对齐:前缀 + 填充在左,后缀在右,
  // 剩余小数留在填充与后缀之间
  Canvas.TextOut(R.Left + Pad, R.Top + Pad, Prefix + StringOfChar(Fill, Count));
  Canvas.TextOut(R.Right - Pad - Canvas.TextWidth(Suffix), R.Top + Pad, Suffix);
end;

用两次独立调用画两半,金额就能钉在右缘,无论整数除法怎么舍入。居中或右对齐单元格,把第一个 TextOut 平移 Avail - Used - Count * FillWidth 的一半或全部。旋转和多行单元格换个办法更简单:把数好的重复插进文本的 FillIndex 处,用一个字符串走你惯用的旋转或换行代码。在手搓网格里——比如这篇 Delphi 自定义电子表格网格——行高和合并区域也应由同一画布驱动

定宽文本与 CSV 里的填充符和下划线

纯文本输出没有像素,但可以有宽度。TXLSXCell.FormattedText 把每个 _x 写成一个普通空格,格式 44 的正数节回来就是 $1,234.50 ,两端各一个空白。比例字体里空格通常比括号略窄,做预览够用了。等宽字体的文本报告里每个字符步进相同,空格是精确替身,填充次数就是纯算术:列宽字符数减文本长度。CSV 另说。读文件的是电子表格或数据库,要的是数字,所以写单元格的 Value,填充文本留给给人看的报表:

uses
  lxHandleX;

// 定宽报表列:格式 44、值 1234.5、Width 14
// 得到 ' $   1,234.50 '(美元符号后三个重复空格)
function PadToWidth(Cell: TXLSXCell; Width: Integer): WideString;
var
  Text: WideString;
  Fill: WideChar;
  FillIndex, Count: Integer;
begin
  if not Cell.GetFormattedTextFill(Text, Fill, FillIndex) then
    Exit(Cell.FormattedText);
  Count := Width - Length(Text);
  if Count < 0 then
    Count := 0;                    // 文本比列宽:不重复
  Result := Copy(Text, 1, FillIndex) + StringOfChar(Fill, Count) +
    Copy(Text, FillIndex + 1, MaxInt);
end;

从一个单元格开始:格式 44、值 1234.5,GetFormattedTextFill 应报告索引 2 处的空格。把列宽调整两次,确认美元符号仍停在左侧内边距,1,234.50 仍停在右缘。渲染器过了这一关,其余对齐只是第一个 TextOut 的偏移,对照的参照物就是 HotXLS Delphi Excel component 的 SaveAsPDF 页面