Memetakan peran landmark ARIA ke PDF bertag melalui Connect

Sekilas

Kirim HTML yang menggunakan elemen sectioning HTML5 dan peran landmark Accessible Rich Internet Applications (ARIA) melalui Connect. Pipeline konten bertag memetakannya ke tipe struktur standar PDF 2.0, sehingga teknologi bantu dapat bernavigasi berdasarkan landmark, bukan berdasarkan posisi visual. Pemeriksaan aksesibilitas yang digunakan di sini adalah tingkat Pro: alat ini ditemukan melalui pemeriksaan class_exists() dan hanya terdaftar ketika nextpdf/premium terpasang bersama server. Pembuatan dokumen dan penambahan HTML menggunakan alat inti.

Alat aksesibilitas melaporkan temuan berdasarkan PDF/UA-2 (ISO 14289-2). Hasil yang lolos adalah penilaian dari alat itu sendiri. Ini adalah pemeriksaan aksesibilitas, bukan sertifikasi konformansi independen. veraPDF atau pemeriksa lainlah yang menentukan konformansi.

Pemasangan

composer require nextpdf/server

Pastikan alat aksesibilitas Pro tersedia pada deployment yang berjalan dengan memanggil tools/list (lihat /connect/tool-catalog/). Jika tidak ada, nextpdf/premium belum terpasang pada deployment ini, sehingga langkah verifikasi dalam resep ini tidak dapat dijalankan.

Tinjauan konseptual

Elemen struktur pengelompokan menata struktur logis dokumen menjadi bagian-bagian dan kontainer serupa (ISO 32000-2 §14.8). Pipeline HTML memetakan elemen berikut:

<aside> dan role="complementary" → tipe standar Aside PDF 2.0
<article> / role="article" → Art
<nav> / role="navigation" → Sect

Tipe struktur non-standar hanya dapat diterima jika perannya dipetakan ke tipe standar (PDF/UA-2 §8.2.5). Pipeline menghasilkan tipe standar secara langsung, sehingga Anda tidak memerlukan pemetaan peran manual. Konten harus tercermin dalam pohon struktur agar teknologi bantu dapat menjangkaunya (PDF/UA-2 §8.2.4).

Permukaan API

Verifikasi nama alat terhadap registry yang berjalan dengan tools/list. Katalog resmi ada di /connect/tool-catalog/. Resep ini menggunakan alat pembuatan dokumen dan penambahan HTML inti, ditambah pemeriksaan aksesibilitas Pro. Resep ini tidak menyebutkan ulang jumlah alat sebagai angka tetap.

Contoh kode — Mulai cepat

Buat dokumen PDF 2.0 bertag, tambahkan HTML dengan peran landmark, lalu periksa hasilnya dengan merangkai permintaan MCP tools/call:

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

Hubungkan emitter konten bertag sebelum Anda menambahkan HTML apa pun. Buat dokumen dengan bahasa yang ditetapkan agar emitter aktif sejak panggilan konten pertama.

Contoh kode — Produksi

Tambahkan HTML landmark dan jalankan pemeriksaan aksesibilitas. Perlakukan status non-sukses sebagai hasil normal yang perlu diperiksa, bukan sebagai galat transport:

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

Respons pemeriksaan melaporkan pohon struktur yang diamatinya dan ringkasan temuan PDF/UA-2. Baik <aside> maupun <div role="complementary"> dipetakan ke tipe standar Aside yang sama.

Kasus tepi & jebakan

Emisi bertag tidak aktif sebelum konten. Jika dokumen tidak dibuat dengan bahasa / mode bertag, penambahan HTML pertama menghasilkan konten tidak bertag, dan pemeriksaan melaporkan kegagalan konten bertag. Buat ulang dokumen dengan bahasa yang ditetapkan.
Peran yang berkonflik pada elemen sectioning (<aside role="navigation">) menghasilkan peringatan. Hapus peran yang berkonflik atau gunakan <div>.
Alat tidak tersedia. Tanpa nextpdf/premium, alat aksesibilitas Pro tidak terdaftar, dan langkah verifikasi gagal dengan galat alat tidak dikenal.

Performa

Anggaran dalam frontmatter adalah batas dokumentasi. Pemetaan landmark merupakan bagian dari proses tata letak normal. Hal ini tidak menambah fase tersendiri yang terukur untuk dokumen pada umumnya.

Catatan keamanan

Tidak ada panduan tambahan yang berlaku selain aturan transport Connect umum: jangan mencatat konten dokumen atau body HTML pada level log yang dikirim ke luar.

Konformansi

Pemetaan PDF/UA-2

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

Tag → rujukan silang ISO 32000-2 §14.9

Klaim	Klausul	reference_id
Elemen pengelompokan menata struktur logis menjadi bagian-bagian	ISO 32000-2 §14.8
Tipe non-standar memerlukan pemetaan peran ke tipe standar	PDF/UA-2 §8.2.5
Konten harus dapat dijangkau melalui pohon struktur	PDF/UA-2 §8.2.4

Pemetaan WCAG 2.2

Navigasi landmark mendukung WCAG 2.2 SC 1.3.1 (Info and Relationships) dan SC 2.4.1 (Bypass Blocks) pada tingkat konten. Format PDF membawa struktur tersebut. Penulis konten tetap bertanggung jawab atas keputusan penulisan pada tingkat WCAG.

Hasil alat aksesibilitas yang lolos adalah pemeriksaan aksesibilitas, bukan sertifikasi konformansi. Pemeriksa independen (misalnya, veraPDF) yang menentukan konformansi PDF/UA-2.

Konteks komersial

Alat pemeriksaan aksesibilitas berada di tingkat Pro dan hanya terdaftar ketika nextpdf/premium terpasang bersama server.

Spesifik Connect

Ketersediaan transport (MCP / REST / gRPC)

Panggil create_pdf, add_html, dan pemeriksaan aksesibilitas dengan cara yang sama melalui MCP tools/call, endpoint alat REST, dan layanan gRPC melalui eksekutor alat bersama.

Tingkat risiko HITL

Pembuatan dokumen dan penambahan HTML berada di tingkat waspada (eksekusi otomatis, tercatat dalam audit). Pemeriksaan aksesibilitas bersifat hanya-baca. Tidak satu pun dari alat ini yang approval_required secara baku. Lihat /connect/hitl-risk-tiers/.

Amplop JSON gerbang konfirmasi

Alat-alat ini tidak memicu gerbang kecuali penggantian konfigurasi operator menaikkan salah satunya menjadi approval_required. Ketika dipasangi gerbang, amplop tantangan dan kontrak token sekali-pakai mengikuti /connect/hitl-risk-tiers/.

Lihat juga

/cookbook/connect/figure-caption/ — struktur Figure / Caption bersarang.
/cookbook/connect/aria-noteref-pattern/ — peran rujukan catatan kaki dan body.
/connect/tool-catalog/ — penghitungan kumpulan alat per tingkat.
/connect/hitl-risk-tiers/ — model risiko dan gerbangnya.