THotPDF.AddStructureElement và helper Tagged PDF

Trang này ghi lại các helper THotPDF hiện tại cho Tagged PDF và cây cấu trúc PDF/UA. Mã định danh giữ đúng theo khai báo công khai

Bề mặt Delphi hiện tại

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;

Tạo phần tử cấu trúc

AddStructureElement tạo dictionary /StructElem và thêm nó làm con của Parent; truyền nil để gắn dưới gốc cây cấu trúc. PageIndex liên kết phần tử với trang qua /Pg, còn giá trị âm sẽ bỏ liên kết này. MCID từ 0 trở lên liên kết một chuỗi marked-content trên trang với phần tử và đăng ký nó trong /ParentTree của tài liệu. Overload sáu tham số thêm /Alt và /ActualText, còn overload bảy tham số ghi thêm /ID duy nhất trong tài liệu

Kiểu cấu trúc chuẩn (Table 333)

Overload THPDFStandardStructureType là điểm vào type-safe: tên role /S phát ra luôn là một kiểu cấu trúc chuẩn của ISO 32000-1 §14.8.4 Table 333, tránh rủi ro gõ sai hoặc khác biệt chữ hoa chữ thường trong role dạng chuỗi mở

Nhóm: sstDocument, sstPart, sstArt, sstSect, sstDiv, sstBlockQuote, sstCaption, sstTOC, sstTOCI, sstIndex, sstNonStruct, sstPrivate
Mức khối: sstH, sstH1-sstH6, sstP, sstL, sstLI, sstLbl, sstLBody, sstTable, sstTR, sstTH, sstTD, sstTHead, sstTBody, sstTFoot
Mức nội dòng: sstSpan, sstQuote, sstNote, sstReference, sstBibEntry, sstCode, sstLink, sstAnnot
Ruby và Warichu: sstRuby, sstRB, sstRT, sstRP, sstWarichu, sstWT, sstWP
Minh họa: sstFigure, sstFormula, sstForm

Lưu ý chữ thường trong sstLbl / sstLBody: tên role PDF thực tế là Lbl và LBody. Tên role tùy chỉnh vẫn có thể đi qua overload AnsiString và được ánh xạ lại về role chuẩn bằng AddStructRoleMap

Ví dụ

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', '');

Thuộc tính cấu trúc và ánh xạ role

SetStructureElementLanguage ghi override /Lang theo BCP-47, SetStructureElementExpansionText ghi văn bản mở rộng /E, SetStructureElementTitle ghi tiêu đề đọc được /T, và AddStructRoleMap ánh xạ role cấu trúc tùy chỉnh về role PDF chuẩn. StandardStructureTypeToName trả về tên role PDF cho giá trị THPDFStandardStructureType, còn IsStandardStructureType kiểm tra tên role có phải chuẩn hay không

Helper cấp cao cho nội dung tagged

EmitTaggedHeading, BeginTaggedList, EmitTaggedListItem, BeginTaggedTable, AddTaggedTableRow, EmitTaggedTableHeader, EmitTaggedTableCell, BeginTaggedFigure, EndTaggedFigure và RegisterAnnotForStructure bao phủ cách nối heading, danh sách, bảng, hình và annotation PDF/UA thông dụng mà không bắt người gọi quản lý MCID thủ công

Quy trình thường dùng

Bật output tagged hoặc PDFUACompliance, tạo phần tử cấu trúc gốc, dùng nhóm helper để phát nội dung ngữ nghĩa, rồi đóng mọi chuỗi tagged-content hoặc hình đã bắt đầu trước EndDoc