THotPDF.AddStructureElement and Tagged PDF Helpers
이 페이지는 현재 THotPDF tagged-PDF/PDF/UA 구조 트리 헬퍼를 문서화합니다. 코드 식별자는 public 선언과 일치합니다
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는 /StructElem 딕셔너리를 만들어 Parent의 자식으로 추가합니다(구조 트리 루트 아래에 붙이려면 nil을 전달). PageIndex는 /Pg를 통해 요소를 해당 페이지에 연결하며, 음수 값을 전달하면 생략됩니다. MCID가 0 이상이면 페이지의 marked-content 시퀀스를 이 요소와 연결하고 문서의 /ParentTree에 등록합니다. 인자 6개짜리 오버로드는 /Alt(도형이나 수식 같은 비텍스트 콘텐츠를 위해 소리 내어 읽어 주는 대체 설명)와 /ActualText(추출하기 어려운 글리프를 복사/붙여넣기할 때 반환되는 대체 텍스트)를 추가합니다. 인자 7개짜리 오버로드는 여기에 더해 문서 내에서 고유한 /ID를 기록하므로, 다른 구조 요소가 ID로 이 요소를 가리킬 수 있습니다(ISO 32000-1 §14.7.2)
Standard Structure Types (Table 333)
THPDFStandardStructureType enum overload가 타입 안전 진입점입니다. 출력 /S role 이름은 ISO 32000-1 §14.8.4 Table 333의 표준 구조 타입 중 하나임이 보장되어, 열린 문자열 overload의 오탈자·대소문자 위험을 없앱니다. 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 role 이름 리터럴은 Lbl과 LBody입니다. 사용자 정의 role 이름은 AnsiString overload로 계속 전달할 수 있고 AddStructRoleMap으로 표준 role에 되돌려 매핑할 수 있습니다
예제
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', '');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 제목, 리스트, 테이블, figure, 주석 연결을 다루며 호출자가 MCID를 수동 관리하도록 강요하지 않습니다
Typical Workflow
tagged 출력이나 PDFUACompliance를 켜고, 루트 구조 요소를 만들고, 헬퍼 계열로 시맨틱 콘텐츠를 출력하며, EndDoc 전에 시작한 모든 tagged-content/figure 시퀀스를 닫습니다
continuation 안전 작성
BeginTaggedContentForStructure와 AppendStructureMarkedContent는 페이지 로컬 marked-content 참조를 하나의 기존 논리 구조 요소에 페이지 continuation에 걸쳐 붙입니다
Layout 트리에서 자동 PDF/UA 구조는 같은 모델을 선언적 제목, 리스트, 테이블, figure, artifact에 적용합니다