แมปบทบาทแลนด์มาร์ก ARIA ไปยัง tagged PDF ผ่าน Connect

ภาพรวมโดยย่อ

ส่ง HTML ที่ใช้องค์ประกอบแบ่งส่วน (sectioning element) ของ HTML5 และบทบาทแลนด์มาร์กของ Accessible Rich Internet Applications (ARIA) ผ่าน Connect ไปป์ไลน์เนื้อหาแบบ tagged จะแมปบทบาทเหล่านั้นไปยังชนิดโครงสร้างมาตรฐานของ PDF 2.0 เพื่อให้เทคโนโลยีช่วยเหลือนำทางตามแลนด์มาร์กได้ แทนการนำทางตามตำแหน่งที่มองเห็น การตรวจสอบการช่วยสำหรับการเข้าถึงที่ใช้ในที่นี้เป็น ระดับ Pro: ระบบค้นพบเครื่องมือนี้ผ่านการตรวจสอบด้วย class_exists() และจะลงทะเบียนเฉพาะเมื่อติดตั้ง nextpdf/premium ควบคู่กับเซิร์ฟเวอร์เท่านั้น การสร้างเอกสารและการนำเข้า HTML ใช้เครื่องมือระดับ core

เครื่องมือตรวจสอบการช่วยสำหรับการเข้าถึงจะรายงานข้อค้นพบโดยเทียบกับ PDF/UA-2 (ISO 14289-2) ผลลัพธ์ที่ผ่านเป็นการประเมินของเครื่องมือเอง นี่คือการตรวจสอบการช่วยสำหรับการเข้าถึง ไม่ใช่การรับรองความสอดคล้องโดยอิสระ veraPDF หรือเครื่องมือตรวจสอบอื่น ๆ เป็นตัวกำหนดความสอดคล้อง

การติดตั้ง

composer require nextpdf/server

ยืนยันว่าเครื่องมือตรวจสอบการช่วยสำหรับการเข้าถึงระดับ Pro มีอยู่ในสภาพแวดล้อมที่กำลังรันอยู่ โดยเรียก tools/list (ดู /connect/tool-catalog/) หากไม่มีเครื่องมือนี้ แสดงว่ายังไม่ได้ติดตั้ง nextpdf/premium ในสภาพแวดล้อมนี้ ดังนั้นขั้นตอนการตรวจสอบของสูตรนี้จึงทำงานไม่ได้

ภาพรวมเชิงแนวคิด

องค์ประกอบโครงสร้างแบบจัดกลุ่ม (grouping structure element) จัดระเบียบโครงสร้างเชิงตรรกะของเอกสารให้เป็นส่วน (section) และคอนเทนเนอร์ที่มีลักษณะคล้ายกัน (ISO 32000-2 §14.8) ไปป์ไลน์ HTML แมปองค์ประกอบเหล่านี้:

<aside> และ role="complementary" → ชนิดมาตรฐาน Aside ของ PDF 2.0
<article> / role="article" → Art
<nav> / role="navigation" → Sect

ชนิดโครงสร้างที่ไม่เป็นมาตรฐานยอมรับได้เฉพาะเมื่อมีการ role-map ไปยังชนิดมาตรฐานเท่านั้น (PDF/UA-2 §8.2.5) ไปป์ไลน์จะส่งออกชนิดมาตรฐานโดยตรง จึงไม่จำเป็นต้องมี role map แบบกำหนดเอง เนื้อหาต้องสะท้อนอยู่ใน structure tree เพื่อให้เทคโนโลยีช่วยเหลือเข้าถึงเนื้อหานั้นได้ (PDF/UA-2 §8.2.4)

พื้นผิว API

ตรวจสอบชื่อเครื่องมือเทียบกับรีจิสทรีที่กำลังทำงานด้วย tools/list แค็ตตาล็อกที่ถือเป็นหลักฐานอ้างอิงคือ /connect/tool-catalog/ สูตรนี้ใช้เครื่องมือสร้างเอกสารและนำเข้า HTML ระดับ core ร่วมกับการตรวจสอบการช่วยสำหรับการเข้าถึงระดับ Pro สูตรนี้จึงไม่ระบุจำนวนเครื่องมือแบบตายตัวซ้ำอีก

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

สร้างเอกสาร tagged PDF 2.0 เพิ่ม HTML ที่มีบทบาทแลนด์มาร์ก แล้วตรวจสอบเอกสารด้วยลำดับคำขอ 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" }
  }
}

เชื่อมต่อ tagged-content emitter ก่อนเพิ่ม HTML ใด ๆ สร้างเอกสารพร้อมกำหนดภาษาไว้ เพื่อให้ emitter ทำงานตั้งแต่การเรียกเนื้อหาครั้งแรก

ตัวอย่างโค้ด — สำหรับใช้งานจริง

เพิ่ม HTML ที่ใช้แลนด์มาร์กและเรียกใช้การตรวจสอบการช่วยสำหรับการเข้าถึง ให้ถือว่าสถานะที่ไม่สำเร็จเป็นผลลัพธ์ปกติที่ต้องตรวจสอบ ไม่ใช่ข้อผิดพลาดของการขนส่ง (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>"
    }
  }
}

ผลตอบกลับจากการตรวจสอบจะรายงาน structure tree ที่ตรวจพบและสรุปข้อค้นพบตาม PDF/UA-2 ทั้ง <aside> และ <div role="complementary"> จะถูกยุบรวมเป็นชนิดมาตรฐาน Aside เดียวกัน

กรณีขอบและข้อควรระวัง

การส่งออกแบบ tagged ไม่ได้เปิดใช้งานก่อนมีเนื้อหา หากไม่ได้สร้างเอกสารพร้อมภาษา / โหมด tagged การเพิ่ม HTML ครั้งแรกจะสร้างเนื้อหาแบบ untagged และการตรวจสอบจะรายงานว่าเนื้อหาแบบ tagged ล้มเหลว สร้างเอกสารใหม่โดยกำหนดภาษาไว้
บทบาทที่ขัดแย้งกันบนองค์ประกอบการแบ่งส่วน (<aside role="navigation">) จะทำให้เกิดคำเตือน ลบบทบาทที่ขัดแย้งกันออก หรือใช้ <div> แทน
ไม่มีเครื่องมือ หากไม่มี nextpdf/premium เครื่องมือตรวจสอบการช่วยสำหรับการเข้าถึงระดับ Pro จะไม่ถูกลงทะเบียน และขั้นตอนการตรวจสอบจะล้มเหลวด้วยข้อผิดพลาดว่าไม่รู้จักเครื่องมือ (unknown-tool)

ประสิทธิภาพ

งบประมาณใน frontmatter เป็นเพดานระดับเอกสาร การแมปแลนด์มาร์กเป็นส่วนหนึ่งของรอบการวางเค้าโครงตามปกติ การแมปแลนด์มาร์กไม่ได้เพิ่มเฟสที่วัดได้แยกต่างหากสำหรับเอกสารทั่วไป

หมายเหตุด้านความปลอดภัย

ไม่มีคำแนะนำเพิ่มเติมนอกเหนือจากกฎการขนส่งทั่วไปของ Connect: ห้ามบันทึกเนื้อหาเอกสารหรือเนื้อหา HTML ในระดับล็อกที่ส่งออกไปภายนอก

ความสอดคล้อง

การแมป PDF/UA-2

HTML	ชนิดมาตรฐานของ PDF 2.0
`<aside>`, `role="complementary"`	`Aside`
`<article>`, `role="article"`	`Art`
`<nav>`, `role="navigation"`	`Sect`

การอ้างอิงไขว้ Tag → ISO 32000-2 §14.9

ข้อกล่าวอ้าง	ข้อกำหนด	รหัสอ้างอิง (reference_id)
องค์ประกอบแบบจัดกลุ่มจัดระเบียบโครงสร้างเชิงตรรกะเป็นส่วน	ISO 32000-2 §14.8
ชนิดที่ไม่เป็นมาตรฐานต้องมีการ role-map ไปยังชนิดมาตรฐาน	PDF/UA-2 §8.2.5
เนื้อหาต้องเข้าถึงได้ผ่าน structure tree	PDF/UA-2 §8.2.4

การแมป WCAG 2.2

การนำทางตามแลนด์มาร์กรองรับ WCAG 2.2 SC 1.3.1 (Info and Relationships) และ SC 2.4.1 (Bypass Blocks) ที่ระดับเนื้อหา รูปแบบ PDF ทำหน้าที่บรรจุโครงสร้างไว้ ผู้เขียนเนื้อหายังคงรับผิดชอบการตัดสินใจด้านการสร้างเนื้อหาในระดับ WCAG

ผลลัพธ์ที่ผ่านจากเครื่องมือตรวจสอบการช่วยสำหรับการเข้าถึงเป็นการตรวจสอบการช่วยสำหรับการเข้าถึง ไม่ใช่การรับรองความสอดคล้อง เครื่องมือตรวจสอบที่เป็นอิสระ (เช่น veraPDF) เป็นตัวกำหนดความสอดคล้อง PDF/UA-2

บริบทเชิงพาณิชย์

เครื่องมือตรวจสอบการช่วยสำหรับการเข้าถึงอยู่ในระดับ Pro และจะลงทะเบียนเฉพาะเมื่อติดตั้ง nextpdf/premium ควบคู่กับเซิร์ฟเวอร์เท่านั้น

รายละเอียดเฉพาะของ Connect

ความพร้อมใช้งานของการขนส่ง (MCP / REST / gRPC)

เรียกใช้ create_pdf, add_html และการตรวจสอบการช่วยสำหรับการเข้าถึงด้วยวิธีเดียวกันผ่าน MCP tools/call, เอนด์พอยต์เครื่องมือ REST และบริการ gRPC โดยทั้งหมดผ่าน tool executor ที่ใช้ร่วมกัน

ระดับความเสี่ยง HITL

การสร้างเอกสารและการนำเข้า HTML อยู่ในระดับ caution (ทำงานอัตโนมัติ พร้อมบันทึกตรวจสอบ) การตรวจสอบการช่วยสำหรับการเข้าถึงเป็นแบบอ่านอย่างเดียว ไม่มีเครื่องมือใดในกลุ่มนี้เป็น approval_required โดยค่าเริ่มต้น ดู /connect/hitl-risk-tiers/

ซองหุ้ม JSON ของเกตการยืนยัน

เครื่องมือเหล่านี้จะไม่ทริกเกอร์เกต เว้นแต่ผู้ดำเนินการจะลบล้างการกำหนดค่าเพื่อยกระดับเครื่องมือใดเครื่องมือหนึ่งเป็น approval_required เมื่ออยู่ภายใต้เกต ซองหุ้มของ challenge และสัญญาโทเค็นแบบใช้ครั้งเดียวจะเป็นไปตาม /connect/hitl-risk-tiers/

ดูเพิ่มเติม

/cookbook/connect/figure-caption/ — โครงสร้าง Figure / Caption แบบซ้อนกัน
/cookbook/connect/aria-noteref-pattern/ — บทบาทของการอ้างอิงเชิงอรรถและเนื้อหา
/connect/tool-catalog/ — การคำนวณชุดเครื่องมือต่อระดับ
/connect/hitl-risk-tiers/ — โมเดลความเสี่ยงและเกต