THotPDF.AddStructureElement and Tagged PDF Helpers
Esta página documenta os helpers atuais de tagged PDF e árvore de estrutura PDF/UA do THotPDF. Os identificadores de código correspondem às declarações públicas
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;Creating Structure Elements
AddStructureElement cria um dicionário /StructElem e o anexa como filho de Parent (passe nil para anexar sob a raiz da árvore de estrutura). PageIndex liga o elemento à página dele via /Pg; passe um valor negativo para omitir. MCID, quando zero ou maior, associa uma sequência de marked-content da página ao elemento e registra-a no /ParentTree do documento. A sobrecarga de seis argumentos adiciona /Alt (descrição alternativa lida em voz alta para conteúdo não textual como figuras e fórmulas) e /ActualText (texto de substituição retornado por copy/paste para glifos difíceis de extrair). A sobrecarga de sete argumentos adicionalmente grava um /ID único no documento, para que outros elementos de estrutura possam mirar no elemento por ID (ISO 32000-1 §14.7.2)
Tipos de estrutura padrão (Table 333)
A sobrecarga com enum THPDFStandardStructureType é o ponto de entrada type-safe: o nome de papel /S emitido é garantido como um dos tipos de estrutura padrão da ISO 32000-1 §14.8.4 Table 333, eliminando o risco de erro de digitação e de sensibilidade a maiúsculas da sobrecarga de string aberta. O enum agrupa os nomes pela família de especificação:
- Grouping:
sstDocument,sstPart,sstArt,sstSect,sstDiv,sstBlockQuote,sstCaption,sstTOC,sstTOCI,sstIndex,sstNonStruct,sstPrivate - Nível de bloco:
sstH,sstH1-sstH6,sstP,sstL,sstLI,sstLbl,sstLBody,sstTable,sstTR,sstTH,sstTD,sstTHead,sstTBody,sstTFoot - Nível inline:
sstSpan,sstQuote,sstNote,sstReference,sstBibEntry,sstCode,sstLink,sstAnnot - Ruby and Warichu:
sstRuby,sstRB,sstRT,sstRP,sstWarichu,sstWT,sstWP - Illustration:
sstFigure,sstFormula,sstForm
Repare nas letras minúsculas em sstLbl / sstLBody: os nomes literais de papel do PDF são Lbl e LBody. Nomes de papel customizados ainda podem ser passados pela sobrecarga AnsiString e mapeados de volta a um papel padrão com AddStructRoleMap
Exemplo
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', '');Atributos de estrutura e mapeamento de papéis
SetStructureElementLanguage grava uma sobrescrita /Lang BCP-47, SetStructureElementExpansionText grava o texto de expansão /E, SetStructureElementTitle grava o título /T legível por humanos, e AddStructRoleMap mapeia papéis de estrutura customizados de volta a papéis padrão do PDF. StandardStructureTypeToName retorna o nome de papel do PDF para um valor THPDFStandardStructureType, e IsStandardStructureType checa se um nome de papel é um dos papéis padrão
Helpers tagged de alto nível
EmitTaggedHeading, BeginTaggedList, EmitTaggedListItem, BeginTaggedTable, AddTaggedTableRow, EmitTaggedTableHeader, EmitTaggedTableCell, BeginTaggedFigure, EndTaggedFigure e RegisterAnnotForStructure cobrem a fiação comum de headings, listas, tabelas, figuras e anotações do PDF/UA sem forçar chamadores a gerenciar MCIDs manualmente
Fluxo de trabalho típico
Habilite a saída tagged ou PDFUACompliance, crie o elemento de estrutura raiz, use a família de helpers para emitir conteúdo semântico e feche toda sequência de tagged content ou figura iniciada antes de EndDoc
Criação segura para continuações
BeginTaggedContentForStructure e AppendStructureMarkedContent anexam referências de marked-content locais de página a um único elemento lógico de estrutura existente através de continuações de página
Automatic PDF/UA Structure from Layout Trees aplica o mesmo modelo a headings, listas, tabelas, figuras e artifacts declarativos