Eine barrierefreie Figure mit Caption ausgeben

Auf einen Blick

Senden Sie eine HTML-<figure>, die ein <img> und eine <figcaption> enthält, über die Connect-Transporte. Die Pipeline gibt ein Figure-Standardstrukturelement aus, verschachtelt die Caption als Caption-Kind und nutzt das alt-Attribut, um /Alt zu füllen. Im Verifizierungsschritt kommt das Pro-Tier-Barrierefreiheitswerkzeug zum Einsatz. NextPDF erkennt dieses Werkzeug über class_exists() und registriert es nur, wenn nextpdf/premium zusammen mit dem Server installiert ist. Dokumenterstellung und HTML-Aufnahme nutzen Core-Werkzeuge.

Ein bestandenes Ergebnis des Barrierefreiheitswerkzeugs ist eine Barrierefreiheitsprüfung, jedoch keine unabhängige Konformitätszertifizierung.

Installation

composer require nextpdf/server

Bestätigen Sie mit einem tools/list-Aufruf, dass das Pro-Barrierefreiheitswerkzeug vorhanden ist. Siehe /connect/tool-catalog/.

Konzeptioneller Überblick

Eine alternative Beschreibung stellt Text für nicht-textuelle Inhalte wie eine Figure bereit (ISO 32000-2 §14.8). Das Strukturelement speichert diese Beschreibung in seinem /Alt-Eintrag (ISO 32000-2 §14.8). Das HTML-alt-Attribut füllt /Alt an der ausgegebenen Figure. Die Pipeline gibt die <figcaption> als verschachteltes Caption-Kind und nicht als benachbarten Absatz aus, sodass die Caption als Teil der Figure erreichbar bleibt (PDF/UA-2 §8.2.4).

API-Oberfläche

Prüfen Sie Werkzeugnamen mit tools/list gegen die laufende Registry. Der maßgebliche Katalog ist /connect/tool-catalog/. Dieses Recipe nutzt die Core-Werkzeuge für Dokumente und HTML sowie die Pro-Barrierefreiheitsprüfung. Eine Werkzeuganzahl wird hier nicht erneut genannt.

Codebeispiel – Schnellstart

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

Codebeispiel – Produktion

Fügen Sie das Figure-Markup hinzu. Das alt ist verpflichtend, damit die Figure barrierefrei ist:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<figure><img src=\"diagrams/architecture.png\" alt=\"Three-tier deployment: web frontend, REST API, datastore\" /><figcaption>Figure 1 — Deployment topology.</figcaption></figure>"
    }
  }
}

Führen Sie die Barrierefreiheitsprüfung aus und inspizieren Sie den gemeldeten Strukturbaum. Er zeigt eine einzelne Figure, die /Alt trägt, mit genau einem Caption-Kind.

Sonderfälle & Stolperfallen

• <img> ohne alt. Die Prüfung meldet einen Fehler beim Alternativtext der Figure. Geben Sie ein aussagekräftiges alt an oder markieren Sie ein rein dekoratives Bild als Artefakt (siehe /cookbook/connect/page-artifacts/).
• Leere <figcaption>. Die Pipeline warnt. Geben Sie Caption-Text an oder entfernen Sie das Element.
• <figcaption> außerhalb jeder <figure>. Die Pipeline gibt sie als verwaiste Caption aus. Umschließen Sie sie mit einer <figure>.
• Werkzeug fehlt. Ohne nextpdf/premium ist das Pro-Barrierefreiheitswerkzeug nicht registriert, und die Verifizierung schlägt mit einem Unknown-Tool-Fehler fehl.

Performance

Das Budget im Frontmatter ist eine Obergrenze für die Dokumentation. Die Figure-Verarbeitung läuft als Teil des normalen Layout-Durchlaufs.

Sicherheitshinweise

Über die allgemeine Connect-Transport-Anleitung hinaus: nicht zutreffend.

Konformität

PDF/UA-2-Zuordnung

Behauptung	Klausel
Alternative Beschreibung für nicht-textuelle Inhalte	ISO 32000-2 §14.8
Alternative Beschreibung gehalten in /Alt	ISO 32000-2 §14.8
Caption über den Strukturbaum erreichbar	PDF/UA-2 §8.2.4

Tag → ISO 32000-2 §14.9 Querverweis

Figure und Caption sind Standardstrukturtypen. Der Vertrag der barrierefreien Figure besteht darin, die <figcaption> als Caption zu verschachteln.

WCAG-2.2-Zuordnung

Eine Figure mit Alternativtext und einer zugehörigen Caption unterstützt WCAG 2.2 SC 1.1.1 (Nicht-Text-Inhalte) und SC 1.3.1 (Info und Beziehungen) auf Inhaltsebene.

Ein bestandenes Ergebnis des Barrierefreiheitswerkzeugs ist eine Barrierefreiheitsprüfung, jedoch keine Konformitätszertifizierung. Diese Feststellung trifft ein unabhängiger Prüfer.

Kommerzieller Kontext

Das Barrierefreiheitsprüfwerkzeug gehört zum Pro-Tier und registriert sich nur, wenn nextpdf/premium zusammen mit dem Server installiert ist.

Connect-Besonderheiten

Transportverfügbarkeit (MCP / REST / gRPC)

Sie rufen create_pdf, add_html und die Barrierefreiheitsprüfung identisch über MCP, REST und gRPC über den gemeinsamen Tool-Executor auf.

HITL-Risikostufe

Dokumenterstellung und HTML-Aufnahme liegen auf der Vorsichtsstufe. Die Barrierefreiheitsprüfung ist schreibgeschützt. Keine davon ist standardmäßig approval_required. Siehe /connect/hitl-risk-tiers/.

JSON-Envelope des Bestätigungs-Gates

Diese Werkzeuge lösen das Gate nicht aus, es sei denn, ein Operator-Override setzt eines auf approval_required. Der Envelope und der Vertrag des Einmal-Tokens stehen in /connect/hitl-risk-tiers/.

Siehe auch

• /cookbook/connect/aria-tagged-pdf/ – Zuordnung von Landmark-Rollen.
• /cookbook/connect/aria-noteref-pattern/ – Fußnotenreferenz- und Body-Rollen.
• /cookbook/connect/page-artifacts/ – dekorative Bilder als Artefakte markieren.
• /connect/tool-catalog/ – Berechnung der Werkzeugmenge pro Tier.