ARIA-Landmark-Rollen mit Connect auf getaggtes PDF abbilden

Auf einen Blick

Übermitteln Sie HTML mit HTML5-Gliederungselementen und ARIA-Landmark-Rollen über die Connect-Transporte. Die Pipeline für getaggte Inhalte bildet diese Elemente auf die Standard-Strukturtypen von PDF 2.0 ab, sodass assistive Technologien anhand von Landmarks und nicht anhand der visuellen Position navigieren können. Die hier verwendete Barrierefreiheitsprüfung gehört zur Pro-Stufe: Das Tool wird über eine class_exists()-Prüfung erkannt und nur dann registriert, wenn nextpdf/premium zusammen mit dem Server installiert ist. Dokumenterstellung und HTML-Aufnahme verwenden Core-Tools.

Das Barrierefreiheits-Tool meldet Befunde gegen PDF/UA-2 (ISO 14289-2). Ein bestandenes Tool-Ergebnis ist eine Bewertung durch dieses Tool. Es handelt sich um eine Barrierefreiheitsprüfung, nicht um eine unabhängige Konformitätszertifizierung. Die Konformitätsbestimmung nimmt veraPDF oder ein anderer Prüfer vor.

Installation

composer require nextpdf/server

Bestätigen Sie mit einem tools/list-Aufruf, dass das Pro-Barrierefreiheits-Tool im laufenden Deployment vorhanden ist (siehe /connect/tool-catalog/). Ist es nicht vorhanden, ist nextpdf/premium in diesem Deployment nicht installiert; der Verifizierungsschritt des Rezepts kann dann nicht ausgeführt werden.

Konzeptioneller Überblick

Gruppierende Strukturelemente gliedern die logische Struktur eines Dokuments in Abschnitte und ähnliche Container (ISO 32000-2 §14.8). Die HTML-Pipeline ordnet diese Elemente wie folgt zu:

<aside> und role="complementary" → der PDF-2.0-Standardtyp Aside
<article> / role="article" → Art
<nav> / role="navigation" → Sect

Ein nicht standardisierter Strukturtyp ist nur dann zulässig, wenn er per Rollenzuordnung auf einen Standardtyp abgebildet wird (PDF/UA-2 §8.2.5). Die Pipeline gibt den Standardtyp direkt aus; eine manuelle Rollenzuordnung ist daher nicht erforderlich. Inhalte müssen im Strukturbaum abgebildet sein, damit assistive Technologien sie erreichen können (PDF/UA-2 §8.2.4).

API-Oberfläche

Tool-Namen werden über tools/list anhand der laufenden Registry verifiziert. Der maßgebliche Katalog ist /connect/tool-catalog/. Dieses Rezept verwendet die Core-Tools für Dokumenterstellung und HTML-Aufnahme sowie die Pro-Barrierefreiheitsprüfung. Es nennt keine feste Tool-Anzahl.

Codebeispiel — Schnellstart

Erstellen Sie ein getaggtes PDF-2.0-Dokument, fügen Sie HTML mit Landmark-Rollen hinzu und prüfen Sie das Ergebnis (MCP tools/call, sequenziell):

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "ARIA Landmark Demo", "language": "en" }
  }
}

Binden Sie den Emitter für getaggte Inhalte ein, bevor Sie HTML hinzufügen. Erstellen Sie das Dokument mit gesetzter Sprache, damit der Emitter ab dem ersten Inhaltsaufruf aktiv ist.

Codebeispiel — Produktion

Fügen Sie das Landmark-HTML hinzu und führen Sie die Barrierefreiheitsprüfung aus; behandeln Sie einen Nicht-Erfolgsstatus dabei als normales, zu prüfendes Ergebnis und nicht als Transportfehler:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<main><h1>Annual Report</h1><aside><h2>Aside</h2><p>Note.</p></aside><div role=\"complementary\"><h2>Related</h2><p>Links.</p></div><nav role=\"navigation\"><p>Skip nav</p></nav></main>"
    }
  }
}

Die Antwort der Prüfung meldet den beobachteten Strukturbaum sowie eine Zusammenfassung der PDF/UA-2-Befunde. Sowohl <aside> als auch <div role="complementary"> werden auf denselben Standardtyp Aside reduziert.

Randfälle & Stolperfallen

Getaggte Ausgabe vor dem Inhalt nicht aktiv. Wurde das Dokument nicht mit einer Sprache / im getaggten Modus erstellt, erzeugt das erste Hinzufügen von HTML ungetaggte Inhalte, und die Prüfung meldet einen Fehler bei getaggten Inhalten. Erstellen Sie das Dokument mit gesetzter Sprache neu.
Widersprüchliche Rolle an einem Gliederungselement (<aside role="navigation">) erzeugt eine Warnung. Entfernen Sie die widersprüchliche Rolle oder verwenden Sie ein <div>.
Tool nicht vorhanden. Ohne nextpdf/premium wird das Pro-Barrierefreiheits-Tool nicht registriert, und der Verifizierungsschritt schlägt mit einem Unknown-Tool-Fehler fehl.

Performance

Das Budget im Frontmatter ist eine Dokumentationsobergrenze. Die Landmark-Zuordnung ist Teil des normalen Layout-Durchlaufs. Bei typischen Dokumenten fügt sie keine separate messbare Phase hinzu.

Sicherheitshinweise

Über die allgemeinen Hinweise zum Connect-Transport hinaus gibt es nichts Spezifisches; protokollieren Sie Dokumentinhalte oder den HTML-Body nicht auf einer extern ausgelieferten Log-Stufe.

Konformität

PDF/UA-2-Zuordnung

HTML	PDF-2.0-Standardtyp
`<aside>`, `role="complementary"`	`Aside`
`<article>`, `role="article"`	`Art`
`<nav>`, `role="navigation"`	`Sect`

Tag → ISO 32000-2 §14.9 Querverweis

Aussage	Klausel	reference_id
Gruppierende Elemente gliedern die logische Struktur in Abschnitte	ISO 32000-2 §14.8
Nicht standardisierte Typen erfordern eine Rollenzuordnung auf einen Standardtyp	PDF/UA-2 §8.2.5
Inhalte müssen über den Strukturbaum erreichbar sein	PDF/UA-2 §8.2.4

WCAG-2.2-Zuordnung

Die Landmark-Navigation unterstützt WCAG 2.2 SC 1.3.1 (Info and Relationships) und SC 2.4.1 (Bypass Blocks) auf Inhaltsebene. Das PDF-Format trägt die Struktur. Die Verantwortung für Erstellungsentscheidungen auf WCAG-Ebene bleibt beim Inhaltsautor.

Ein bestandenes Ergebnis des Barrierefreiheits-Tools ist eine Barrierefreiheitsprüfung, keine Konformitätszertifizierung. Die PDF/UA-2-Konformitätsbestimmung nimmt ein unabhängiger Prüfer vor (zum Beispiel veraPDF).

Kommerzieller Kontext

Das Tool für die Barrierefreiheitsprüfung gehört zur Pro-Stufe und wird nur dann registriert, wenn nextpdf/premium zusammen mit dem Server installiert ist.

Connect-Besonderheiten

Transportverfügbarkeit (MCP / REST / gRPC)

create_pdf, add_html und die Barrierefreiheitsprüfung werden über MCP tools/call, den REST-Tool-Endpunkt und den gRPC-Dienst identisch über denselben Tool-Executor aufgerufen.

HITL-Risikostufe

Dokumenterstellung und HTML-Aufnahme liegen auf der Vorsichtsstufe (automatische Ausführung, im Audit-Log protokolliert). Die Barrierefreiheitsprüfung erfolgt schreibgeschützt. Keines dieser Tools ist standardmäßig approval_required. Siehe /connect/hitl-risk-tiers/.

JSON-Umschlag des Bestätigungs-Gates

Diese Tools lösen das Gate nicht aus, sofern keine Betreiber-Konfigurationsüberschreibung eines davon auf approval_required anhebt. Wenn das Gate greift, gelten der Challenge-Umschlag und der Vertrag für Einmal-Tokens, wie unter /connect/hitl-risk-tiers/ dokumentiert.

Siehe auch

/cookbook/connect/figure-caption/ — verschachtelte Figure / Caption-Struktur.
/cookbook/connect/aria-noteref-pattern/ — Fußnotenverweis- und Body-Rollen.
/connect/tool-catalog/ — Berechnung des Tool-Sets je Stufe.
/connect/hitl-risk-tiers/ — Risikomodell und Gate.