THotPDF.AddStructureElement 與標記 PDF 輔助方法
本頁說明目前的 THotPDF 標記 PDF 與 PDF/UA 結構樹輔助方法。程式識別碼與公開宣告一致
目前 Delphi 介面
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 為零或更大時，會將頁面上的一段標記內容序列與該元素關聯，並登錄到文件的 /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 - 旁註標記與雙行夾註：
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 ride on the AnsiString overload; reuse the
// spec-prescribed role name via StandardStructureTypeToName
Fig := PDF.AddStructureElement(StandardStructureTypeToName(sstFigure), Doc, 0, -1,
'Sales by quarter: Q1 4.2M, Q2 5.1M, Q3 5.8M, Q4 6.4M', '');結構屬性與角色對照
SetStructureElementLanguage 寫入 BCP-47 的 /Lang 覆寫值，SetStructureElementExpansionText 寫入 /E 展開文字，SetStructureElementTitle 寫入供人閱讀的 /T 標題，AddStructRoleMap 則將自訂結構角色對應回標準 PDF 角色。StandardStructureTypeToName 傳回 THPDFStandardStructureType 值對應的 PDF 角色名稱，IsStandardStructureType 則檢查某個角色名稱是否屬於標準角色
高階標記輔助方法
EmitTaggedHeading、BeginTaggedList、EmitTaggedListItem、BeginTaggedTable、AddTaggedTableRow、EmitTaggedTableHeader、EmitTaggedTableCell、BeginTaggedFigure、EndTaggedFigure 與 RegisterAnnotForStructure 涵蓋了常見的 PDF/UA 標題、清單、表格、插圖與註解的連接，無需呼叫端手動管理 MCID
一般工作流程
啟用標記輸出或 PDFUACompliance，建立根結構元素，使用輔助方法群組輸出語意內容，並在 EndDoc
續排安全的撰寫方式
BeginTaggedContentForStructure 與 AppendStructureMarkedContent 可跨頁面續排,把頁面本地的 marked-content 參照附加到同一個既有的邏輯結構元素
從版面樹自動產生 PDF/UA 結構 把同一套模型套用到宣告式的標題、清單、表格、圖形與 artifact 之前關閉所有已啟動的標記內容或插圖序列