HTML로 접근성 있는 태그된 PDF 작성

한눈에 보기

이 레시피는 시맨틱 HTML에서 태그된 PDF를 작성합니다. NextPDF는 논리적 구조 트리, 카탈로그 언어, PDF/UA-2 마커를 생성합니다. 적합성 판정은 검사기가 수행합니다. 이 레시피는 examples/31-pdfua2-tagged.php를 기준으로 합니다.

사전 요구 사항

Core 설치 완료: composer require nextpdf/core:^3.
검증 단계에 사용할 PDF/UA 검사기. 이 예제는 veraPDF를 사용합니다.

레시피

문서를 생성합니다.
먼저 BCP-47 언어 태그와 함께 enableTaggedPdf()를 반드시 writeHtml() 호출 전에 호출합니다. HTML 파이프라인은 파서를 빌드할 때 태그된 모드를 감지하고 태그된 콘텐츠 이미터를 연결합니다.
문서 메타데이터(제목, 언어)를 설정합니다. setLanguage()는 enableTaggedPdf()와 함께 사용해도 멱등적입니다.
시맨틱 HTML을 작성합니다. 파서는 각 블록 요소를 구조 요소에 매핑합니다. h1은 H1로, p는 P로, ul/li는 L/LI로, table은 Table/TR/TD로 매핑됩니다.
저장한 다음 PDF/UA 검사기로 검증합니다.

전체 예제

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// Step 2 — enable tagged mode BEFORE writeHtml(). The lang argument
// drives the catalog /Lang entry and the structure tree root language.
$doc->enableTaggedPdf(lang: 'en');

// Step 3 — metadata. setLanguage() restates intent; it is idempotent here.
$doc->setTitle('Accessible Report');
$doc->setLanguage('en');

$doc->addPage();

// Step 4 — semantic HTML. Each block element becomes a StructElem; text
// runs are wrapped in BDC/EMC operators with stable MCIDs.
$html = <<<'HTML'
<h1>Quarterly Accessibility Report</h1>
<p>This document opts into tagged PDF so assistive technology can expose
a meaningful reading order.</p>
<h2>Findings</h2>
<ul>
  <li>Headings carry semantic roles.</li>
  <li>Lists keep their item structure.</li>
</ul>
HTML;

$doc->writeHtml($html);

$doc->save(__DIR__ . '/accessible.pdf');

echo "Wrote accessible.pdf — validate with: verapdf --flavour ua2 accessible.pdf\n";

예상 출력

Wrote accessible.pdf — validate with: verapdf --flavour ua2 accessible.pdf

출력에는 구조 트리, /MarkInfo << /Marked true >>, 카탈로그 /Lang 항목, pdfuaid:part XMP 마커가 포함됩니다. 검사기를 실행해 이러한 항목이 존재하며 내부적으로 일관되는지 확인합니다.

엣지 케이스

호출 순서. enableTaggedPdf()를 writeHtml() 이후에 호출해도 이미 작성된 콘텐츠에 소급하여 태그가 지정되지 않습니다. 먼저 태그된 모드를 활성화해야 합니다.
언어 태그. 두 번째 인수로 ConformancePolicy::strictUa2()를 전달하면 잘못된 형식의 BCP-47 태그를 쓰기 시점에 자동으로 삭제하지 않고 API 경계에서 거부합니다.
멱등적 재활성화. enableTaggedPdf()를 두 번 호출하면 이미 채워 둔 구조 트리를 다시 빌드하지 않고 언어만 업데이트합니다.
수동 태그 지정. HTML이 아닌 콘텐츠의 경우, 항목을 beginTag() / endTag()로 감쌉니다. 컨테이너 유형(Table, TR, L, LI)은 표시된 콘텐츠가 없는 그룹화 요소가 되고, 리프 유형(P, H1–H6, TD)은 MCID를 받습니다.
지원은 적합성이 아닙니다. NextPDF는 PDF/UA-2에 필요한 구조적 메타데이터를 생성합니다. 또한 저하된 패리티 경고를 표시합니다. 프로덕션 승인을 위한 외부 오라클 검증은 호출자의 책임입니다. 파일이 적합하다고 명시하기 전에 검사기를 실행해야 합니다.

적합성

설명	사양	조항	reference_id (참조 ID)
실제 콘텐츠에는 논리적 구조가 필요합니다.	ISO 14289-2	§8.2.2
구조 요소는 정의된 중첩 및 읽기 순서를 따릅니다.	ISO 14289-2	§8.2.3

이 레시피는 접근성 있는 작성을 지원하는 태그된 구조를 생성하는 방법을 보여줍니다. PDF/UA-2 적합성을 보장하지 않으며, 적합 여부는 검사기가 판단합니다.