技術文章

Excel 填滿字元(*)在 PDF 匯出與列印中的角色

用自製格式器匯出一張套用 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 內建的會計格式,編號 41 到 44。這些編號是 Excel 自家的:§18.8.30 的內建表從 40 直接跳到 45,HotXLS 按 Excel 的編號登記底下這四個代碼

Excel 編號格式代碼符號小數位
41_(* #,##0_);_(* (#,##0);_(* "-"_);_(@_)無0
42_("$"* #,##0_);_("$"* (#,##0);_("$"* "-"_);_(@_)$0
43_(* #,##0.00_);_(* (#,##0.00);_(* "-"??_);_(@_)無2
44_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)$2

從左到右讀 44 的正數區段 _("$"* #,##0.00_):一個 ( 那麼寬的空白、一個錢號、重複到填滿欄位的空格、數字,再一個 ) 那麼寬的空白。負數區段把結尾那個空白換成真括號。零值區段印一條短線加上 ??——兩個數字寬的空白,把短線擺到小數點那一欄。值會挑哪個區段、空區段會怎樣,遵循Excel 數字格式區段的規則。拔掉填滿,錢號就黏上數字;把星號印出來,讀者看到的就是格式語法

HotXLS for Delphi 中 Excel 會計格式 44 正數區段的剖析:括號寬度的空白、錢號、重複空格填滿與數字
一個星號就讓下一個字元重複到欄寬為止,會計區段裡的每個空白都出自底線

格式器為什麼不能自己插入重複字元?

因為它不知道次數。重複次數等於欄寬減去其餘一切寬度,再除以一個填滿字元的寬度,每個項都隨字型、字號、縮放與輸出設備而變。回傳純字串的格式器必須挑一個數,而任何人為固定的數,欄位一被調整就錯。HotXLS 把工作拆開:TXLSXCell.FormattedText 回傳不含填滿字元的顯示文字;GetFormattedTextFill 回傳同一份文字加上填滿字元與一個索引——重複該出現的位置之前有幾個字元。格式沒有填滿時,以及 rich text 儲存格(其 run 原樣繪製),這個方法回傳 False

自動負號排在填滿之前。用格式 **0、值 -5 時,文字是 -5、填滿字元是 *、索引是 1,拉寬的儲存格因此顯示 -****5,與 Excel 的 Range.Text 給這個儲存格的字串相同。沒有欄位的呼叫者就拿不到填滿:TEXT 工作表函式就是這種呼叫者,所以在 HotXLS 計算引擎裡,A1 放 1234 時 TEXT(A1, "$* #,##0") 求值為 $1,234。下面的程式碼設三種格式,並印出渲染器各自收到的東西

HotXLS for Delphi 中 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 顯示的擺法如下,取決於水平對齊:

HotXLS for Delphi 中填滿字元零頭擺放位置的矩陣:從 general 與靠左對齊到置中、靠右與縮小以符合大小
general 與靠左對齊把剩餘零頭放在填滿與後綴之間,一整欄錢號才能紋絲不動
  • General 與靠左:前綴貼左內距、後綴貼右內距,零頭落在填滿與後綴之間(沒有後綴時在行尾)
  • 置中:前綴與填滿右移零頭的一半;靠右對齊則全移
  • 填滿、左右對齊、分散對齊與自動換列:三個部分從左依序排,零頭在行尾
  • 縮排照常壓縮可用寬度,「縮小以符合大小」的儲存格沒有填滿

General 對齊正是自製渲染器出錯的地方。General 底下的數字通常靠右,帶填滿的儲存格不是。守住「數字靠右」的規則,零頭就會落在填滿前面,把錢號頂離左內距最多一個空格寬。沿著一整欄格式 44 的金額看下去,錢號便逐列搖晃。較少見的版面走同一個模型:

  • 旋轉文字:填滿長度取自旋轉後仍放得進儲存格的最長行
  • Rich text:重複字元的樣式取自填滿位置前一字元
  • 跨選取範圍置中:填滿鋪滿整個跨度
  • 多行文字:只有包含填滿位置的那一行會重複

由右至左的工作表是 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 元件產出的 SaveAsPDF 頁面就是拿來對照的基準