ARIA-landmarkrollen toewijzen aan een getagde PDF via Connect

In één oogopslag

Dien via Connect HTML in die HTML5-sectie-elementen en landmarkrollen van Accessible Rich Internet Applications (ARIA) gebruikt. De pijplijn voor getagde content wijst deze toe aan de standaardstructuurtypen van PDF 2.0, zodat hulptechnologie op basis van landmarks kan navigeren in plaats van op visuele positie. De toegankelijkheidscontrole die hier wordt gebruikt, is Pro-niveau: de tool wordt ontdekt via een probe met class_exists() en registreert zich alleen wanneer nextpdf/premium naast de server is geïnstalleerd. Voor het aanmaken van documenten en het inlezen van HTML worden core-tools gebruikt.

De toegankelijkheidstool rapporteert bevindingen op basis van PDF/UA-2 (ISO 14289-2). Een geslaagd resultaat is een beoordeling door de tool zelf. Het is een toegankelijkheidscontrole, geen onafhankelijke conformiteitscertificering. veraPDF of een andere checker stelt de conformiteit vast.

Installeren

composer require nextpdf/server

Controleer met een tools/list-aanroep of de Pro-toegankelijkheidstool aanwezig is op de actieve implementatie (zie /connect/tool-catalog/). Als deze ontbreekt, is nextpdf/premium niet op deze implementatie geïnstalleerd en kan de verificatiestap van dit recipe niet worden uitgevoerd.

Conceptueel overzicht

Groeperende structuurelementen organiseren de logische structuur van een document in secties en vergelijkbare containers (ISO 32000-2 §14.8). De HTML-pijplijn wijst deze elementen toe:

<aside> en role="complementary" → het standaardtype Aside van PDF 2.0
<article> / role="article" → Art
<nav> / role="navigation" → Sect

Een niet-standaardstructuurtype is alleen aanvaardbaar wanneer het via role-mapping aan een standaardtype is gekoppeld (PDF/UA-2 §8.2.5). De pijplijn geeft het standaardtype rechtstreeks uit, zodat je geen handmatige role-map nodig hebt. Content moet in de structuurboom zijn opgenomen, zodat hulptechnologie deze kan bereiken (PDF/UA-2 §8.2.4).

API-oppervlak

Controleer toolnamen aan de hand van het actieve register met tools/list. De gezaghebbende catalogus is /connect/tool-catalog/. Dit recipe gebruikt de core-tools voor het aanmaken van documenten en het inlezen van HTML, plus de Pro-toegankelijkheidscontrole. Het legt geen vast aantal tools opnieuw vast.

Codevoorbeeld — snelstart

Maak een getagd PDF 2.0-document aan, voeg HTML met landmarkrollen toe en controleer het resultaat door MCP-tools/call-aanvragen na elkaar uit te voeren:

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

Koppel de emitter voor getagde content voordat je HTML toevoegt. Maak het document aan met een ingestelde taal, zodat de emitter vanaf de eerste contentaanroep actief is.

Codevoorbeeld — productie

Voeg de landmark-HTML toe en voer de toegankelijkheidscontrole uit. Behandel een status die geen succes aangeeft als een resultaat dat normaal moet worden geïnspecteerd, niet als een transportfout:

{
  "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>"
    }
  }
}

De controleresponse rapporteert de door de controle waargenomen structuurboom en een samenvatting van de PDF/UA-2-bevindingen. Zowel <aside> als <div role="complementary"> worden samengevoegd tot hetzelfde standaardtype Aside.

Randgevallen en valkuilen

Getagde uitvoer niet actief vóór content. Als het document niet is aangemaakt met een taal- of getagde modus, levert de eerste HTML-toevoeging niet-getagde content op en rapporteert de controle een fout over getagde content. Maak het document opnieuw aan met de taal ingesteld.
Conflicterende rol op een sectie-element (<aside role="navigation">) leidt tot een waarschuwing. Verwijder de conflicterende rol of gebruik een <div>.
Tool ontbreekt. Zonder nextpdf/premium wordt de Pro-toegankelijkheidstool niet geregistreerd en mislukt de verificatiestap met een onbekende-toolfout.

Prestaties

Het budget in de frontmatter is een documentatielimiet. Landmark-toewijzing maakt deel uit van de normale lay-outfase. Het voegt voor typische documenten geen afzonderlijke meetbare fase toe.

Beveiligingsnotities

Behalve de algemene Connect-transportregel gelden er geen aanvullende richtlijnen: log documentcontent of de HTML-body niet op een extern verzonden logniveau.

Conformiteit

PDF/UA-2-toewijzing

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

Tag → ISO 32000-2 §14.9-kruisverwijzing

Bewering	Clausule	reference_id
Groeperende elementen organiseren de logische structuur in secties	ISO 32000-2 §14.8
Niet-standaardtypen vereisen role-mapping naar een standaardtype	PDF/UA-2 §8.2.5
Content moet bereikbaar zijn via de structuurboom	PDF/UA-2 §8.2.4

WCAG 2.2-toewijzing

Navigatie via landmarks ondersteunt WCAG 2.2 SC 1.3.1 (Info and Relationships) en SC 2.4.1 (Bypass Blocks) op contentniveau. Het PDF-formaat bevat de structuur. De contentauteur blijft verantwoordelijk voor authoring-beslissingen op WCAG-niveau.

Een geslaagd resultaat van de toegankelijkheidstool is een toegankelijkheidscontrole, geen conformiteitscertificering. Een onafhankelijke checker (bijvoorbeeld veraPDF) bepaalt de PDF/UA-2-conformiteit.

Commerciële context

De tool voor de toegankelijkheidscontrole is Pro-niveau en registreert alleen wanneer nextpdf/premium naast de server is geïnstalleerd.

Connect-specifieke details

Transportbeschikbaarheid (MCP / REST / gRPC)

Roep create_pdf, add_html en de toegankelijkheidscontrole op dezelfde manier aan via MCP tools/call, het REST-toolendpoint en de gRPC-service via de gedeelde tool-executor.

HITL-risiconiveau

Het aanmaken van documenten en het inlezen van HTML hebben caution-niveau (automatisch uitgevoerd, gelogd voor audit). De toegankelijkheidscontrole is alleen-lezen. Voor geen van deze tools is standaard approval_required ingesteld. Zie /connect/hitl-risk-niveaus/.

JSON-envelop van de bevestigingsgate

Deze tools activeren de gate niet, tenzij een operatorconfiguratie-override een ervan verhoogt naar approval_required. Wanneer er een gate van toepassing is, volgen de challenge-envelop en het contract voor eenmalig te gebruiken tokens de regels in /connect/hitl-risk-niveaus/.

Zie ook

/cookbook/connect/figure-caption/ — geneste Figure / Caption-structuur.
/cookbook/connect/aria-noteref-pattern/ — rollen voor voetnootverwijzing en -tekst.
/connect/tool-catalog/ — berekening van de toolset per niveau.
/connect/hitl-risk-niveaus/ — het risicomodel en de gate.