Menandai artefak halaman melalui Connect

Sekilas pandang

Resep ini membungkus elemen kerangka paginasi, termasuk running header dan footer, nomor halaman, tanda air, serta latar belakang, sebagai konten bertanda artefak melalui transport Connect. Elemen kerangka tersebut tetap tampil di halaman, tetapi berada di luar pohon struktur dan urutan baca teknologi bantu. Alat artefak ini bersifat tingkat Enterprise: NextPDF menemukannya melalui pemeriksaan class_exists() dan hanya mendaftarkannya ketika nextpdf/premium terpasang bersama server. Subtipenya menggunakan enum bertipe (Pagination, Layout, Page, Background).

Untuk memverifikasi keluaran, gunakan alat pemeriksaan standar Enterprise, yang melaporkan hasil terhadap PDF/UA-2. Hasil lulus merupakan pemeriksaan oleh alat itu sendiri, bukan sertifikasi kesesuaian independen.

Pemasangan

composer require nextpdf/server

Pastikan alat artefak Enterprise tersedia melalui panggilan tools/list. Lihat /connect/tool-catalog/.

Tinjauan konseptual

Konten yang bukan merupakan bagian dari struktur logis ditandai sebagai artefak dan dikecualikan dari urutan baca (PDF/UA-2 §8.3). Artefak mencakup konten paginasi, tata letak, halaman, atau latar belakang, dan berbeda dari konten nyata (PDF/UA-2 §8.3). Konten nyata tercermin dalam pohon struktur; artefak tidak (PDF/UA-2 §8.2.4).

Alat ini membuka rangkaian konten bertanda artefak dengan subtipe yang diminta. Setiap operasi menggambar yang Anda jalankan sebelum penutup yang sesuai akan dibungkus di dalamnya.

Permukaan API

Cocokkan nama alat dengan registri yang sedang berjalan melalui tools/list. Katalog acuan resmi adalah /connect/tool-catalog/. Resep ini tidak mencantumkan ulang jumlah alat.

Contoh kode — Mulai cepat

Buka artefak Background, gambar tanda air, lalu tutup:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Background" }
  }
}

Contoh kode — Produksi

Pasangkan setiap pembukaan dengan penutup, dan verifikasi bahwa halaman tidak memuat konten yatim:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Page", "attached": "Bottom" }
  }
}

Setelah Anda menggambar teks footer, tutup dengan alat penutup artefak dan jalankan pemeriksaan standar terhadap PDF/UA-2. Pohon struktur hanya boleh memuat konten badan; tanda air dan footer harus dikecualikan.

Kasus tepi & jebakan

Subtipe tidak dikenal (misalnya "Header") ditolak. Kirim salah satu dari Pagination, Layout, Page, Background.
Penutupan tanpa pembukaan gagal dengan pesan kedalaman nol. Selalu pasangkan pembukaan dan penutupan.
Menggambar sebelum ada konteks artefak atau struktur apa pun menghasilkan konten yatim dan kegagalan aturan struktur. Buka konteks struktur atau artefak terlebih dahulu.
Alat tidak tersedia. Tanpa nextpdf/premium, alat artefak Enterprise tidak terdaftar, dan panggilan gagal dengan kesalahan alat-tidak-dikenal.

Performa

Anggaran dalam frontmatter merupakan batas dokumentasi. Pembungkusan artefak tidak menambahkan fase terpisah yang dapat diukur.

Catatan keamanan

Tidak ada catatan khusus selain panduan transport Connect umum.

Kesesuaian

Pemetaan PDF/UA-2

Subtipe	Kasus penggunaan
`Pagination`	Running headers/footers, nomor halaman, elemen kerangka navigasi
`Layout`	Garis pemisah, separator, batas dekoratif
`Page`	Alat bantu yang terikat halaman (tanda potong, registrasi)
`Background`	Tanda air, isian latar belakang, branding

Referensi silang Tag → ISO 32000-2 §14.9

Klaim	Klausa	reference_id
Konten nonstruktural ditandai sebagai artefak, dikecualikan dari urutan baca	PDF/UA-2 §8.3
Subtipe artefak: pagination/layout/page/background	PDF/UA-2 §8.3
Konten nyata ada dalam pohon struktur; artefak tidak	PDF/UA-2 §8.2.4

Pemetaan WCAG 2.2

Mengecualikan elemen kerangka dekoratif dari urutan baca mendukung Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) pada tingkat konten.

Hasil lulus dari pemeriksaan standar adalah hasil pemeriksaan, bukan sertifikasi kesesuaian. Penetapan tersebut dibuat oleh pemeriksa independen.

Konteks komersial

Alat artefak berada pada tingkat Enterprise dan hanya terdaftar ketika nextpdf/premium terpasang bersama server.

Hal khusus Connect

Ketersediaan transport (MCP / REST / gRPC)

Anda memanggil alat-alat ini dengan cara yang sama melalui MCP tools/call, endpoint REST untuk alat, dan layanan gRPC. Ketiganya menggunakan eksekutor alat bersama.

Tingkat risiko HITL

Emisi artefak dan penggambaran konten berada di tingkat peringatan; pemeriksaan standar bersifat hanya-baca. Secara default, tidak ada yang approval_required. Lihat /connect/hitl-risk-tiers/.

Amplop JSON untuk gerbang konfirmasi

Alat-alat ini tidak memicu gerbang kecuali jika penggantian oleh operator menaikkan 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/figure-caption/ — pengelompokan gambar yang dapat diakses.
/connect/tool-catalog/ — perhitungan set alat per tingkat.
/connect/hitl-risk-tiers/ — model risiko dan gerbangnya.