Accessibility API¶

namespace NextPDF\Core\Accessibility;

final class AccessibilityManager

/** 取得文件結構樹 */
public function structureTree(): StructureTree

/** 設定文件主要語言 */
public function setLanguage(Language $language): void

/** 設定文件標題（供螢幕閱讀器讀取）*/
public function setTitle(string $title): void

/** 是否已啟用 Tagged PDF */
public function isTagged(): bool

/** 設定 Tab 順序 */
public function setTabOrder(array $order): void

/** 取得 WCAG 檢查器 */
public function wcagChecker(): WcagChecker

/** 取得 PDF/UA 驗證器 */
public function pdfUaValidator(): PdfUaValidator

namespace NextPDF\Core\Accessibility;

final class StructureTree

/** 取得根結構元素（Document 角色）*/
public function root(): StructureElement

/** 取得所有標籤元素的扁平列表 */
public function allElements(): list<StructureElement>

/** 驗證結構樹的完整性 */
public function validate(): list<StructureValidationError>

namespace NextPDF\Core\Accessibility;

final class StructureElement

/**
 * 新增段落元素。
 *
 * @param non-empty-string $text 段落文字
 * @param string           $lang BCP 47 語言標記
 */
public function appendParagraph(string $text, string $lang = ''): self

/**
 * 新增標題元素（H1–H6）。
 *
 * @param positive-int     $level 1–6
 * @param non-empty-string $text  標題文字
 */
public function appendHeading(int $level, string $text, string $lang = ''): self

/** 新增章節（Section / Article / Part）*/
public function appendSection(
    'Section'|'Article'|'Part' $role = 'Section',
    string                      $lang = '',
): self

/** 新增圖像 / 圖形元素 */
public function appendFigure(
    string  $altText    = '',
    string  $actualText = '',
    string  $lang       = '',
): self

/** 新增表格元素（含完整結構：THead/TBody/TFoot）*/
public function appendTable(string $summary = ''): TableStructureElement

/** 新增清單元素（含 ListItem）*/
public function appendList(
    'L'|'Lbl'|'LI' $listType = 'L',
): ListStructureElement

/** 新增行內文字片段（Span，可設定不同語言）*/
public function appendSpan(string $text, string $lang = ''): self

/** 將此元素標記為 Artifact（螢幕閱讀器忽略）*/
public function markAsArtifact(): self

public readonly string $role;     // 標籤角色（P / H1 / Figure / Table 等）
public readonly string $altText;
public readonly string $lang;

public function id(): string
public function children(): list<StructureElement>
public function hasChildren(): bool

namespace NextPDF\Core\Accessibility;

final class WcagChecker

public static function create(): self

/**
 * 執行 WCAG 合規檢查。
 *
 * @param Document         $document 要檢查的文件
 * @param ComplianceLevel  $level    合規等級
 * @return WcagReport
 */
public function check(Document $document, ComplianceLevel $level = ComplianceLevel::AA): WcagReport

enum ComplianceLevel
{
    case A;    // WCAG 2.x Level A
    case AA;   // WCAG 2.x Level AA（一般要求）
    case AAA;  // WCAG 2.x Level AAA（最嚴格）
}

final readonly class WcagReport
{
    public bool   $passed;
    public string $wcagVersion;  // '2.1' | '2.2'
    public string $level;        // 'A' | 'AA' | 'AAA'

    /** @return list<WcagViolation> */
    public function violations(): array

    /** @return list<WcagViolation> */
    public function warnings(): array

    /** 通過的檢查項目數 */
    public function passedCount(): int

    /** 失敗的檢查項目數 */
    public function failedCount(): int
}

namespace NextPDF\Core\Accessibility;

final class PdfUaValidator

public static function create(): self

/**
 * @param '1'|'2' $version PDF/UA 版本
 */
public function validate(Document $document, string $version = '2'): PdfUaResult

final readonly class PdfUaResult
{
    public bool   $passed;
    public string $conformanceLevel;   // 'PDF/UA-1' | 'PDF/UA-2'

    /** @return list<ValidationFailure> */
    public function failures(): array

    /** Matterhorn Protocol 的通過/失敗項目 */
    public function matterhornResults(): MatterhornResult
}