THotPDF.AddStructureElement and Tagged PDF Helpers

本页记录当前 THotPDF 的 Tagged PDF 与 PDF/UA 结构树辅助方法。代码标识符与公开声明一致

Current Delphi Surface

function AddStructureElement(const Role: AnsiString; Parent: THPDFDictionaryObject;
  PageIndex: Integer = -1; MCID: Integer = -1): THPDFDictionaryObject; overload;
function AddStructureElement(const Role: AnsiString; Parent: THPDFDictionaryObject;
  PageIndex: Integer; MCID: Integer;
  const AltText: AnsiString; const ActualText: AnsiString): THPDFDictionaryObject; overload;
function AddStructureElement(const Role: AnsiString; Parent: THPDFDictionaryObject;
  PageIndex: Integer; MCID: Integer;
  const AltText: AnsiString; const ActualText: AnsiString;
  const IDStr: AnsiString): THPDFDictionaryObject; overload;
function AddStructureElement(T: THPDFStandardStructureType; Parent: THPDFDictionaryObject;
  PageIndex: Integer = -1; MCID: Integer = -1): THPDFDictionaryObject; overload;

procedure SetStructureElementLanguage(Elem: THPDFDictionaryObject; const Lang: AnsiString);
procedure SetStructureElementExpansionText(Elem: THPDFDictionaryObject; const ExpansionText: AnsiString);
procedure SetStructureElementTitle(Elem: THPDFDictionaryObject; const Title: AnsiString);
procedure AddStructRoleMap(const SourceRole: AnsiString; const TargetRole: AnsiString);

function BeginTaggedContent(const Role: AnsiString; Parent: THPDFDictionaryObject;
  const Lang: AnsiString = ''; const Alt: AnsiString = '';
  const ActualText: AnsiString = ''; const ExpansionText: AnsiString = ''): THPDFDictionaryObject;
procedure EndTaggedContent;

function EmitTaggedHeading(Level: Integer; Parent: THPDFDictionaryObject; X, Y: Single; const Text: WideString): THPDFDictionaryObject;
function BeginTaggedList(Parent: THPDFDictionaryObject; const NumberingStyle: AnsiString = 'None'): THPDFDictionaryObject;
function EmitTaggedListItem(ListElem: THPDFDictionaryObject; LblX, LblY: Single; const LabelText: WideString; BodyX, BodyY: Single; const BodyText: WideString): THPDFDictionaryObject;
function BeginTaggedTable(Parent: THPDFDictionaryObject): THPDFDictionaryObject;
function AddTaggedTableRow(TableElem: THPDFDictionaryObject): THPDFDictionaryObject;
function EmitTaggedTableHeader(TRElem: THPDFDictionaryObject; X, Y: Single; const Text: WideString; const Scope: AnsiString): THPDFDictionaryObject;
function EmitTaggedTableCell(TRElem: THPDFDictionaryObject; X, Y: Single; const Text: WideString): THPDFDictionaryObject;
function BeginTaggedFigure(Parent: THPDFDictionaryObject; const AltText: AnsiString; const BBox: array of Single): THPDFDictionaryObject;
procedure EndTaggedFigure;
procedure RegisterAnnotForStructure(AnnotDict: THPDFDictionaryObject; StructElem: THPDFDictionaryObject);

function StandardStructureTypeToName(T: THPDFStandardStructureType): AnsiString;
function IsStandardStructureType(const Name: AnsiString): Boolean;

创建结构元素

AddStructureElement 创建 /StructElem 字典并把它追加为 Parent 的子元素（传 nil 挂到结构树根下）。PageIndex 经 /Pg 把元素链接到其页面；传负值省略。MCID 不小于 0 时，把页面上的一个标记内容序列关联到该元素并注册进文档 /ParentTree。六参数重载增加 /Alt（为图、公式等非文本内容朗读的替代描述）与 /ActualText（复制 / 粘贴时对难以提取的字形返回的替换文本）。七参数重载额外写出文档唯一的 /ID，让其他结构元素可按 ID 定位该元素（ISO 32000-1 §14.7.2）

标准结构类型（Table 333）

THPDFStandardStructureType 枚举重载是类型安全入口：输出的 /S 角色名保证属于 ISO 32000-1 §14.8.4 Table 333 的标准结构类型，消除开放字符串重载的拼写与大小写风险。枚举按规范家族分组：

• 分组类：sstDocument、sstPart、sstArt、sstSect、sstDiv、sstBlockQuote、sstCaption、sstTOC、sstTOCI、sstIndex、sstNonStruct、sstPrivate
• 块级：sstH、sstH1-sstH6、sstP、sstL、sstLI、sstLbl、sstLBody、sstTable、sstTR、sstTH、sstTD、sstTHead、sstTBody、sstTFoot
• 行内级：sstSpan、sstQuote、sstNote、sstReference、sstBibEntry、sstCode、sstLink、sstAnnot
• Ruby 与 Warichu：sstRuby、sstRB、sstRT、sstRP、sstWarichu、sstWT、sstWP
• 插图类：sstFigure、sstFormula、sstForm

注意 sstLbl / sstLBody 中的小写字母：PDF 字面角色名是 Lbl 与 LBody。自定义角色名仍可经 AnsiString 重载传入，并用 AddStructRoleMap

示例

PDF.PDFUACompliance := pdfuaPDFUA1;
PDF.BeginDoc;
Doc := PDF.AddStructureElement(sstDocument, nil);
H1 := PDF.AddStructureElement(sstH1, Doc);
PDF.SetStructureElementLanguage(Doc, 'en-US');
PDF.SetStructureElementTitle(H1, 'Annual Report');
// Alt / ActualText 走 AnsiString 重载；经 StandardStructureTypeToName
// 复用规范规定的角色名
Fig := PDF.AddStructureElement(StandardStructureTypeToName(sstFigure), Doc, 0, -1,
  'Sales by quarter: Q1 4.2M, Q2 5.1M, Q3 5.8M, Q4 6.4M', '');

Structure Attributes and Role Mapping

SetStructureElementLanguage 写出 BCP-47 /Lang 覆盖，SetStructureElementExpansionText 写出 /E 展开文本，SetStructureElementTitle 写出人类可读的 /T 标题，AddStructRoleMap 把自定义结构角色映射回标准 PDF 角色。StandardStructureTypeToName 返回 THPDFStandardStructureType 值对应的 PDF 角色名，IsStandardStructureType 检查角色名是否属于标准角色

High-Level Tagged Helpers

EmitTaggedHeading、BeginTaggedList、EmitTaggedListItem、BeginTaggedTable、AddTaggedTableRow、EmitTaggedTableHeader、EmitTaggedTableCell、BeginTaggedFigure、EndTaggedFigure 与 RegisterAnnotForStructure 覆盖常见的 PDF/UA 标题、列表、表格、图和注释接线，无需调用方手动管理 MCID

Typical Workflow

启用 tagged 输出或 PDFUACompliance，创建根结构元素，用这组辅助方法输出语义内容，并在 EndDoc

跨延续的安全创作

BeginTaggedContentForStructure 与 AppendStructureMarkedContent 在页面延续间把页面局部的标记内容引用附加到同一个既有逻辑结构元素

从布局树自动生成 PDF/UA 结构 把同一模型应用于声明式标题、列表、表格、图和 artifact