Membuat Figure yang Aksesibel dengan Caption melalui Connect

Sekilas pandang

Kirimkan HTML <figure> yang berisi <img> dan <figcaption> melalui transport Connect. Pipeline membuat elemen struktur standar Figure, menyarangkan caption sebagai anak Caption, serta menggunakan atribut alt untuk mengisi /Alt. Verifikasi hasilnya dengan alat aksesibilitas tingkat Pro. NextPDF menemukan alat tersebut melalui class_exists() dan hanya mendaftarkannya jika nextpdf/premium terpasang bersama server. Alat inti menangani pembuatan dokumen dan ingesti HTML.

Hasil lulus dari alat aksesibilitas merupakan pemeriksaan aksesibilitas, bukan sertifikasi kesesuaian independen.

Pemasangan

composer require nextpdf/server

Pastikan alat aksesibilitas Pro tersedia melalui panggilan tools/list. Lihat /connect/tool-catalog/.

Tinjauan konseptual

Deskripsi alternatif menyediakan teks bagi konten non-teks, seperti figure (ISO 32000-2 §14.8). Elemen struktur menyimpan deskripsi tersebut dalam entri /Alt miliknya (ISO 32000-2 §14.8). Atribut HTML alt mengisi /Alt pada Figure yang dihasilkan. Pipeline menghasilkan <figcaption> sebagai anak Caption yang tersarang, bukan sebagai paragraf sejajar, sehingga caption tetap dapat dijangkau sebagai bagian dari figure (PDF/UA-2 §8.2.4).

Permukaan API

Verifikasi nama alat pada registri yang sedang berjalan dengan tools/list. Katalog rujukan resminya adalah /connect/tool-catalog/. Resep ini menggunakan alat dokumen dan HTML inti, ditambah pemeriksaan aksesibilitas Pro. Resep ini tidak mencantumkan ulang jumlah alat.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Tambahkan markup figure. Atribut alt wajib ada agar figure aksesibel:

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

Jalankan pemeriksaan aksesibilitas, lalu tinjau pohon struktur yang dilaporkan. Pohon struktur menampilkan satu Figure dengan /Alt dan tepat satu anak Caption.

Kasus tepi & jebakan

<img> tanpa alt. Pemeriksaan melaporkan kegagalan pada teks alternatif figure. Sediakan alt yang deskriptif, atau tandai gambar yang sepenuhnya dekoratif sebagai artifact (lihat /cookbook/connect/page-artifacts/).
<figcaption> kosong. Pipeline mengeluarkan peringatan. Sediakan teks caption atau hapus elemen tersebut.
<figcaption> di luar <figure> mana pun. Pipeline menghasilkannya sebagai caption tanpa induk. Bungkus dengan <figure>.
Alat tidak tersedia. Tanpa nextpdf/premium, alat aksesibilitas Pro tidak terdaftar, dan verifikasi gagal dengan galat bahwa alat tidak dikenal.

Performa

Budget dalam front matter merupakan batas dokumentasi. Penanganan figure berjalan sebagai bagian dari alur tata letak normal.

Catatan keamanan

Tidak ada panduan tambahan selain panduan umum transport Connect.

Kesesuaian

Pemetaan PDF/UA-2

Klaim	Klausa	reference_id
Deskripsi alternatif untuk konten non-teks	ISO 32000-2 §14.8
Deskripsi alternatif yang disimpan dalam `/Alt`	ISO 32000-2 §14.8
Caption dapat dijangkau melalui pohon struktur	PDF/UA-2 §8.2.4

Referensi silang tag → ISO 32000-2 §14.9

Figure dan Caption merupakan tipe struktur standar. Menyarangkan <figcaption> sebagai Caption menetapkan kontrak figure yang aksesibel.

Pemetaan WCAG 2.2

Figure dengan teks alt dan caption yang terkait mendukung Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.1.1 (Non-text Content) dan SC 1.3.1 (Info and Relationships) pada tingkat konten.

Hasil lulus dari alat aksesibilitas merupakan pemeriksaan aksesibilitas, bukan sertifikasi kesesuaian. Pemeriksa independenlah yang menentukan hal tersebut.

Konteks komersial

Alat pemeriksaan aksesibilitas berada pada tingkat Pro dan hanya terdaftar jika 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 Model Context Protocol (MCP), REST, dan gRPC menggunakan eksekutor alat bersama.

Tingkat risiko HITL

Pembuatan dokumen dan ingesti HTML berada pada tingkat kehati-hatian. Pemeriksaan aksesibilitas bersifat hanya-baca. Tidak satu pun dari keduanya bersifat approval_required secara baku. Lihat /connect/hitl-risk-tiers/.

Amplop JSON gerbang konfirmasi

Alat-alat ini tidak memicu gerbang kecuali operator mengganti pengaturan sehingga salah satunya menjadi approval_required. Amplop dan kontrak token sekali pakai dijelaskan di /connect/hitl-risk-tiers/.

Lihat juga

/cookbook/connect/aria-tagged-pdf/ — pemetaan peran landmark.
/cookbook/connect/aria-noteref-pattern/ — peran referensi catatan kaki dan badan.
/cookbook/connect/page-artifacts/ — menandai gambar dekoratif sebagai artifact.
/connect/tool-catalog/ — perhitungan kumpulan alat per tingkat.