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 及其高级功能的信息，请访问官方文档或探索组件中包含的全面演示应用程序。