THotPDF.AddStructureElement and Tagged PDF Helpers
Эта страница описывает актуальный набор помощников THotPDF для tagged-PDF и дерева структуры PDF/UA. Идентификаторы кода совпадают с публичными объявлениями
Current Delphi Surface
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;Structure Attributes and Role Mapping
AddStructureElement создаёт /StructElem словарь и добавляет его потомком Parent (передайте nil чтобы прикрепить элемент к корню дерева структуры). PageIndex привязывает элемент к странице через /Pg; отрицательное значение — опустить привязку. MCIDпри значении ноль или больше ассоциирует с элементом последовательность marked-content на странице и регистрирует её в /ParentTreeШестиаргументная перегрузка добавляет /Alt (альтернативное описание, зачитываемое для нетекстового контента вроде рисунков и формул) и /ActualText (замещающий текст, отдаваемый при copy/paste для глифов, которые трудно извлечь). Семиаргументная перегрузка дополнительно пишет уникальный в документе /ID чтобы другие элементы структуры могли адресовать элемент по ID (ISO 32000-1 §14.7.2)
High-Level Tagged Helpers
THPDFStandardStructureType перегрузка с enum — типобезопасная точка входа: записанное /S имя роли гарантированно входит в стандартные типы структуры ISO 32000-1 §14.8.4 Table 333, устраняя опасность опечаток и ошибок регистра открытого строкового варианта. Enum группирует имена по семействам спецификации:
- Группировка:
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
Typical Workflow
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 текст расширения (expansion), SetStructureElementTitle пишет человекочитаемый /T заголовок, а AddStructRoleMap отображает пользовательские роли структуры обратно в стандартные роли PDF. StandardStructureTypeToName возвращает имя PDF-роли для THPDFStandardStructureType значения, а IsStandardStructureType проверяет, является ли имя роли одной из стандартных
Высокоуровневые помеченные помощники
EmitTaggedHeading, BeginTaggedList, EmitTaggedListItem, BeginTaggedTable, AddTaggedTableRow, EmitTaggedTableHeader, EmitTaggedTableCell, BeginTaggedFigure, EndTaggedFigure, и RegisterAnnotForStructure покрывают типовые сценарии PDF/UA — заголовки, списки, таблицы, рисунки и аннотации — не заставляя вызывающих вручную управлять MCID
Типовой сценарий
Включите помеченный вывод или PDFUACompliance, создайте корневой элемент структуры, используйте семейство помощников для вывода семантического контента и закройте все начатые последовательности tagged-content или figure перед EndDoc
Авторинг с продолжениями
BeginTaggedContentForStructure и AppendStructureMarkedContent привязывают постраничные ссылки marked-content к одному существующему логическому элементу структуры при продолжениях страниц
Включите tagged output или PDFUACompliance, создайте корневой элемент структуры, используйте семейство helper-методов для вывода семантического содержимого и закрывайте каждую начатую последовательность tagged-content или figure перед EndDoc