태그된 PDF (접근성)

접근성 모듈(StructureTreeManager, RoleMap, TaggedContentManager)은 스크린 리더 및 보조 기술을 위한 태그된 PDF 출력을 활성화합니다. 활성화되면 모든 콘텐츠가 의미적 역할을 설명하는 구조 요소로 래핑됩니다. 모든 태깅 메서드는 체이닝을 위해 static을 반환합니다.

빠른 참조

메서드	설명
setTaggedPdf()	태그된 PDF 모드 활성화 또는 비활성화
setLanguage()	문서의 기본 언어 설정 (BCP 47)
openTag()	태그된 구조 요소 시작
closeTag()	태그된 구조 요소 종료
image(..., alt:)	접근성을 위한 대체 텍스트가 포함된 이미지 추가

태그된 PDF 활성화

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setTaggedPdf(true)
    ->setLanguage('en-US')
    ->addPage()
    ->setFont('Helvetica', '', 12);

setTaggedPdf(true)가 호출되면 StructureTreeManager가 지연 초기화되고 Marked = true인 MarkInfo 딕셔너리가 PDF 카탈로그에 작성됩니다.

구조 요소

TCPDF-Next는 전체 PDF 2.0 표준 태그 세트를 지원합니다:

카테고리	태그
그룹화	Document, Part, Sect, Div, BlockQuote, Caption, NonStruct
제목	H1, H2, H3, H4, H5, H6
단락	P, Span
목록	L, LI, Lbl, LBody
테이블	Table, TR, TH, TD, THead, TBody, TFoot
인라인	Link, Em, Strong, Code
일러스트레이션	Figure, Formula, Form

기본 태깅

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setTaggedPdf(true)
    ->setLanguage('en-US')
    ->addPage()
    ->setFont('Helvetica', '', 12)

    ->openTag('H1')
    ->cell(0, 10, 'Annual Report 2026', newLine: true)
    ->closeTag('H1')

    ->openTag('P')
    ->multiCell(0, 6, 'This document demonstrates tagged PDF output for accessibility compliance.')
    ->closeTag('P')

    ->save('tagged-basic.pdf');

태그는 올바르게 중첩되어야 합니다. StructureTreeManager는 중첩을 검증하고 불일치 시 예외를 던집니다.

태그된 테이블

$pdf->openTag('Table')
    ->openTag('TR')
    ->openTag('TH')->cell(50, 8, 'Quarter')->closeTag('TH')
    ->openTag('TH')->cell(50, 8, 'Revenue')->closeTag('TH')
    ->closeTag('TR')
    ->openTag('TR')
    ->openTag('TD')->cell(50, 8, 'Q1')->closeTag('TD')
    ->openTag('TD')->cell(50, 8, '$1,200,000')->closeTag('TD')
    ->closeTag('TR')
    ->closeTag('Table');

태그 속성

태그를 열 때 추가 속성을 전달합니다:

$pdf->openTag('Figure', ['Alt' => 'Company logo', 'ActualText' => 'Acme Corp Logo'])
    ->image('/path/to/logo.png', 10, 50, 40, 40)
    ->closeTag('Figure');

일반적인 속성:

속성	설명
Alt	비텍스트 요소에 대한 대체 텍스트
ActualText	요소에 대한 정확한 텍스트 대체
Lang	이 요소에 대한 언어 재정의 (BCP 47)
Title	사람이 읽을 수 있는 제목

image() 메서드도 단축 표현으로 alt 매개변수를 받습니다 -- $pdf->image('chart.png', 10, 80, 120, 60, alt: 'Revenue chart')는 자동으로 이미지를 Figure 태그로 래핑합니다.

역할 매핑

RoleMap은 사용자 정의 태그 이름을 표준 PDF 구조 유형에 매핑합니다. 이를 통해 PDF/UA 호환성을 유지하면서 도메인별 이름을 사용할 수 있습니다:

$pdf->openTag('Invoice', ['roleMap' => 'Sect'])
    ->openTag('LineItem', ['roleMap' => 'P'])
    ->cell(0, 8, 'Widget x 10 — $500.00', newLine: true)
    ->closeTag('LineItem')
    ->closeTag('Invoice');

역할 맵은 구조 트리 루트에 작성되어 검증기가 사용자 정의 태그를 표준 동등물로 해석합니다. 다국어 콘텐츠의 경우, 요소별로 언어를 재정의합니다: ->openTag('P', ['Lang' => 'de-DE']).

PDF/UA 준수

완전한 PDF/UA 준수 문서를 생성하려면 다음을 확인하십시오:

1. 태그된 PDF가 활성화됨 -- setTaggedPdf(true)
2. 문서 언어가 설정됨 -- setLanguage('en-US')
3. 모든 콘텐츠가 태그됨 -- 구조 요소 외부에 태그되지 않은 콘텐츠 없음
4. 모든 이미지에 대체 텍스트가 있음 -- alt: 매개변수 또는 Alt 속성이 있는 Figure 태그를 통해
5. 테이블이 헤더에 TH를 사용함 -- 헤더 셀은 데이터 셀과 구분되어야 함
6. 글꼴이 임베드됨 -- TCPDF-Next는 기본적으로 모든 글꼴을 임베드함

PDF/A-4와의 통합

태그된 PDF는 PDF/A-4와 완전히 호환됩니다. 보관 + 접근 가능한 문서를 위해 둘 다 활성화하십시오:

$pdf = Document::create()
    ->setTaggedPdf(true)
    ->setPdfA(true)
    ->setLanguage('en-US')
    ->setTitle('Accessible Archival Document')
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->openTag('H1')
    ->cell(0, 10, 'PDF/A-4 + PDF/UA Document', newLine: true)
    ->closeTag('H1')
    ->save('accessible-archival.pdf');