LlosLab Software Development BlogEngineering notes for PDF, Delphi, and document software developers.

技術文章

HotPDF元件中的RtLTextOut函式

· PDF 程式設計

PDF 生成中的從右到左文本：介紹 HotPDF 的 RtLTextOut 函式。

從右到左語言簡介。

從右到左 (RTL) 語言代表了全球書面交流系統的重要組成部分，服務於超過 4 億人。這些語言包括阿拉伯語、希伯來語、波斯語 (Farsi)、烏爾都語、普什圖語以及其他多種語言，每種語言都有其獨特的特徵和文化意義。

歷史和文化背景。

從右到左的書寫系統具有悠久的歷史，可以追溯到數千年前。例如，阿拉伯語是從納巴泰文字演變而來，並在伊斯蘭早期標準化。希伯來語的歷史更悠久，古代希伯來語銘文可以追溯到西元前 10 世紀。這些書寫系統獨立於拉丁字母書寫系統發展，反映了組織書面資訊的不同方法。

RTL 語言的語言學特徵。

RTL 語言具有一些獨特的特徵，這些特徵會影響數字文本處理：

  • 指令碼方向。文本從右向左流動，與歐洲語言相反。
  • 上下文相關的字元形式。許多從右向左（RTL）的文字系統使用不同的字母形狀，具體取決於位置（開頭、中間、結尾、獨立）。
  • 連字和連線。字母經常連線形成連續的單詞，需要複雜的渲染。
  • 重音符號。母音符號和其他附加符號出現在基本字元的上方或下方。
  • 雙向文本。RTL文件通常包含嵌入的從左到右（LTR）元素（例如：數字、拉丁文本、URL）。

數字挑戰與Unicode標準。

RTL語言的數字表示形式帶來了獨特的技術挑戰：

  1. 字元編碼。Unicode為RTL字元提供了標準化的程式碼點：
    • 阿拉伯語：U+0600-U+06FF（阿拉伯語塊）。
    • 希伯來語：U+0590-U+05FF（希伯來語塊）。
    • 阿拉伯語補充：U+0750-U+077F。
    • 阿拉伯語擴充套件 A：U+08A0-U+08FF
  2. 雙向演算法: Unicode 雙向演算法 (UBA) 定義瞭如何處理混合 RTL/LTR 文本。
  3. 字型要求: RTL 文本需要具有適當字形覆蓋範圍和形狀處理功能的字型。
  4. 佈局注意事項: 使用者介面和文件必須適應從右向左的閱讀模式。

全球市場重要性

支援從右向左（RTL）語言對於在多元市場運營的企業和組織至關重要：

  • 阿拉伯語地區：22個國家，擁有超過3億的母語使用者。
  • 希伯來語市場：以色列以及全球猶太社群。
  • 波斯語/波斯語：伊朗、阿富汗和塔吉克。
  • 烏爾都語。巴基斯坦和印度部分地區。
  • 經濟影響。RTL語言區域的合併GDP超過4萬億美元。

在當今全球化的世界中，建立能夠正確支援多種語言和書寫系統的PDF文件變得越來越重要。雖然大多數PDF生成庫可以輕鬆處理從左到右（LTR）的語言，如英語、法語和德語，但支援從右到左（RTL）的語言，如阿拉伯語和希伯來語，則面臨獨特的挑戰。本文將探討創新的... RtLTextOut 該函式位於 HotPDF Delphi 元件中，並通過一個全面的演示應用程式展示了其實際應用。

理解 PDF 文件中從右到左 (RTL) 文本的挑戰。

從右向左書寫的語言在數字文件中需要特殊處理，原因如下：

  1. 字元順序從右向左的文本是從右向左流動的，與從左向右的語言相反。
  2. 雙向文本。文件通常包含混合的從右向左和從左向右的內容。
  3. PDF 觀看器的行為。PDF 閱讀器需要正確的方向提示才能正確顯示文本。
  4. Unicode 的複雜性。從右向左的字元具有特定的 Unicode 範圍，必須檢測並處理。

傳統的 PDF 生成方法在處理從右向左的文本時通常會失敗，導致字元順序反轉、閱讀順序錯誤或完全無法識別的輸出。

RTL Text Processing Workflow Diagram showing the complete process from input text analysis through character segmentation, segment-based processing algorithm, to final bidirectional output in PDF format
圖 1：HotPDF 中的 RTL 文本處理流程 - 說明了基於分段的演算法，該演算法通過保持 RTL 分段的原始順序，同時內部反轉 LTR 分段，以實現 PDF 文件中正確的雙向顯示。

介紹 HotPDF 的 RtLTextOut 函式。

HotPDF 元件通過其複雜的函式來應對這些挑戰。 RtLTextOut 與簡單的字元反轉方法不同， RtLTextOut 使用基於分段的處理方法，可以智慧地處理混合 RTL/LTR 內容。

函式簽名。

好的。 RtLTextOut 該函式提供了兩個過載版本，以實現最大的靈活性。

1
2
3
4
5
// PWORD version for direct Unicode character array access
procedure RtLTextOut(X, Y: Single; angle: Extended; Text: PWORD; TextLength: Integer);
 
// WideString version for convenient string handling
procedure RtLTextOut(X, Y: Single; angle: Extended; Text: WideString);

核心演算法：基於分段的處理。

的核心在於其基於分段的雙向演算法。 RtLTextOut 不採用簡單的字元反轉，而該函式：

  1. 分析字元型別：識別從右到左的字元（阿拉伯語：U+0600-U+06FF，希伯來語：U+0590-U+05FF）
  2. 分割文本：將連續相同型別的字元（從右到左或從左到右）分組
  3. 應用選擇性處理：:
    • 從右到左的分段保持其原始順序。
    • LTR 段落內部會被反轉。
  4. 產生正確的輸出。導致出現以下模式。 Reversed(C)+B+Reversed(A) 用於段落。 A+B+C

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// Core segment processing logic
I := 0;
while I < TextLength do begin // Determine if current character starts an RTL or LTR segment IsRTLChar := ((ReversedText[I] >= $0600) and (ReversedText[I] <= $06FF)) or // Arabic ((ReversedText[I] >= $0590) and (ReversedText[I] <= $05FF));      // Hebrew
  
  CurrentSegmentIsRTL := IsRTLChar;
  SegmentStart := I;
  
  // Find the end of current segment (same character type)
  while (I < TextLength) do begin IsRTLChar := ((ReversedText[I] >= $0600) and (ReversedText[I] <= $06FF)) or ((ReversedText[I] >= $0590) and (ReversedText[I] <= $05FF));
    
    if IsRTLChar <> CurrentSegmentIsRTL then
      Break;
    Inc(I);
  end;
  
  SegmentEnd := I - 1;
  
  // Process the segment
  if CurrentSegmentIsRTL then
  begin
    // RTL segment: keep original order
    for J := SegmentStart to SegmentEnd do
      OutputText[J] := ReversedText[J];
  end
  else
  begin
    // LTR segment: reverse the segment internally
    for J := SegmentStart to SegmentEnd do
      OutputText[J] := ReversedText[SegmentEnd - (J - SegmentStart)];
  end;
end;

自動配置 PDF 方向。

除了文本處理之外， RtLTextOut 自動配置 PDF 文件以獲得最佳的 RTL 顯示效果：

1
2
3
4
5
// Store original direction and set to RightToLeft
OriginalDirection := FParent.FDirection;
FParent.FDirection := RightToLeft;
FParent.FViewerPreference := FParent.FViewerPreference + [vpDirection];
FParent.FVPChanged := true;

這確保 PDF 閱覽器以正確的閱讀方向開啟文件，為使用者提供直觀的閱讀體驗。

探索 RtLTextOut 演示應用程式。

HotPDF 庫包含一個全面的演示應用程式 (Demo\Delphi\RtLTextOut\RtLTextOut.dpr)，該應用程式展示了 RtLTextOut 函式在各種場景下的功能。

演示結構和功能。

演示應用程式展示了：

  • 基本的阿拉伯文本輸出。簡單的從右到左文本渲染。
  • 支援希伯來語文本。: 完整的希伯來語字元處理。
  • : 混合語言內容: RTL/LTR 文本組合。
  • 技術文件。: 實施說明和最佳實踐。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
program RtLTextOut;
{$I ..\..\..\Lib\HotPDF.inc}
 
{$APPTYPE CONSOLE}
 
uses
  {$IFDEF XE2+}
  System.SysUtils,
  Vcl.Graphics,
  {$ELSE}
  SysUtils,
  Graphics,
  {$ENDIF}
  HPDFDoc;
 
var
  HotPDF: THotPDF;
begin
  try
    HotPDF := THotPDF.Create(nil);
    try
      HotPDF.FileName := 'RtLTextOut.pdf';
      HotPDF.Title := 'RtLTextOut Function Test - Right-to-Left Text Output';
 
      HotPDF.BeginDoc;
 
      // Title
      HotPDF.CurrentPage.SetFont('Arial', [fsBold], 18, 0, False);
      HotPDF.CurrentPage.TextOut(40, 50, 0, 'RtLTextOut Function Demonstration');
 
      // Arabic text demonstration
      HotPDF.CurrentPage.SetFont('Arial Unicode MS', [], 12, 178, False);
      HotPDF.CurrentPage.TextOut(40, 160, 0, 'RtLTextOut:');
      HotPDF.CurrentPage.RtLTextOut(40, 180, 0, 'يوضح ملف PDF هذا كيفية التعامل بشكل صحيح مع النص العربي من اليمين إلى اليسار.');
 
      // Hebrew text demonstration
      HotPDF.CurrentPage.SetFont('Arial Unicode MS', [], 12, 177, False);
      HotPDF.CurrentPage.RtLTextOut(40, 370, 0, 'קובץ PDF זה מדגים כיצד לטפל כראוי בטקסט עברי הזורם מימין לשמאל.');
 
      // Mixed text demonstration
      HotPDF.CurrentPage.RtLTextOut(40, 550, 0, 'مرحبا بالعالم! اكتب في مستندات PDF التي تم إنشاؤها بواسطة مكون HotPDF');
 
      HotPDF.EndDoc;
      Writeln('RtLTextOut.pdf created successfully!');
 
    finally
      HotPDF.Free;
    end;
  except
    on E: Exception do
      Writeln('Error: ', E.Message);
  end;
end.

關鍵演示亮點。

阿拉伯語文本處理。: 演示瞭如何 RtLTextOut 處理複雜的阿拉伯語句，並確保正確的字元排列和間距。

: 希伯來語支援: 演示了希伯來文本的正確渲染，包括正確的從右向左方向。

: 混合語言內容: 展示了該功能如何智慧地處理包含從右向左 (RTL) 和從左向右 (LTR) 元素的文本。

: 字型配置: 說明了正確的 Unicode 字型選擇方法。Arial Unicode MS用於支援從右向左 (RTL) 字元。

技術實現細節。

Unicode 字元檢測。

該函式採用強大的 Unicode 範圍檢測：

  • 阿拉伯語。: U+0600 到 U+06FF (1536-1791 十進位制)。
  • 希伯來語。: U+0590 到 U+05FF (1424-1535 十進位制)。

記憶體管理

高效的陣列處理可確保最佳效能：

1
2
3
4
5
6
7
8
9
10
// Initialize arrays
SetLength(ReversedText, TextLength);
SetLength(OutputText, TextLength);
 
// Copy original text first
for I := 0 to TextLength - 1 do
begin
  ReversedText[I] := TempText^;
  Inc(TempText);
end;

垂直文本支援

該功能包含針對垂直字型的特殊處理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
if CurrentFontObj.IsVertical then
begin
  DeltaH := TextHeight('Zj');
  DeltaW := TextWidth('W');
  HorizontalLine := Y;
  ChBuff := @ChCode;
  for I := 0 to TextLength - 1 do
  begin
    ChCode := OutputText[I];
    if (ChCode = $30FC) then
      ChCode := $7C;
    InternUnicodeTextOut(X + (DeltaW / 2), HorizontalLine - DeltaH, 0, ChBuff, 1);
    HorizontalLine := HorizontalLine + DeltaH;
  end;
end
else
  InternUnicodeTextOut(X, Y, angle, @OutputText[0], TextLength);

PDF 中 RTL 文本的最佳實踐

字型選擇

選擇支援您的目標 RTL 語言的 Unicode 字型：

  • Arial Unicode MS全面的 Unicode 支援
  • Times New Roman適合混合內容
  • Tahoma優秀的阿拉伯語支援

文本編碼

確保在您的原始碼文本中使用正確的 Unicode 編碼：

1
2
3
4
5
6
7
// Use WideString for Unicode text
var
  ArabicText: WideString;
begin
  ArabicText := 'النص العربي';
  HotPDF.CurrentPage.RtLTextOut(X, Y, 0, ArabicText);
end;

PDF 閱覽器相容性

自動方向設定確保在各種PDF檢視器上的相容性。

  • Adobe Acrobat Reader
  • Foxit Reader
  • Chrome PDF Viewer
  • Firefox PDF Viewer

效能考量

基於分段的演算法具有出色的效能特性。

  1. 線性時間複雜度O(n) 的處理時間
  2. 最小的記憶體開銷高效的陣列管理
  3. 單次處理不需要多次迭代
  4. 最佳化的字元檢測快速的 Unicode 範圍檢查

實際應用場景

文件本地化

好的。 RtLTextOut 該功能可實現對從右到左（RTL）語言市場的無縫文件本地化：

  • 阿拉伯語法律檔案
  • 希伯來語技術手冊
  • 多語言表格和合同
  • 教育材料

國際商務

在使用從右到左（RTL）語言市場的企業可以利用此功能來實現：

  • 發票生成
  • 報告建立
  • 證書列印
  • 營銷材料

常見問題排查

字元編碼問題

問題: 亂碼或缺失字元
解決方案: 確保正確的 Unicode 編碼和字型選擇

1
2
3
4
5
// Correct approach
HotPDF.CurrentPage.SetFont('Arial Unicode MS', [], 12, 178, False);
var
  Text: WideString := 'النص العربي';
HotPDF.CurrentPage.RtLTextOut(X, Y, 0, Text);

方向問題

問題: 文本顯示方向錯誤
解決方案: 確認是否 RtLTextOut 被用於代替常規設定。 TextOut

混合內容問題

問題: 混合 RTL/LTR 文本中的順序不正確
解決方案: 基於分段的演算法可以自動處理此問題

未來增強功能和路線圖

HotPDF 開發團隊將繼續增強對 RTL 的支援：

  1. 擴充套件語言支援額外的從右到左（RTL）語言支援。
  2. 複雜指令碼處理。高階排版特性。
  3. 效能最佳化。進一步的速度提升。
  4. 增強的除錯功能。更好的診斷工具。

總結。

好的。 RtLTextOut HotPDF 中的 function 代表了 PDF 生成技術在從右到左（RTL）語言方面的重大進步。其先進的基於分段的處理演算法，結合自動的 PDF 配置，為開發人員提供了一個強大的工具，用於建立真正國際化的 PDF 文件。

這個全面的演示應用程式既是學習資源，也是實踐指南，展示了在真實場景中處理從右到左（RTL）文本的最佳實踐。無論您是為阿拉伯語市場開發應用程式、建立希伯來語文件，還是構建多語言系統，該應用程式都… RtLTextOut 此函式提供了構建高質量 PDF 生成所需的基礎。

通過理解和實施這些技術，開發人員可以建立能夠很好地服務於全球受眾的PDF文件，從而打破語言障礙，並確保內容的可訪問性和可讀性，無論使用的書寫系統是什麼。

欲瞭解更多關於 HotPDF 及其高階功能的資訊，請訪問官方文件或探索元件中包含的全面演示應用程式。