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

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

ส่ง 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

ข้อกล่าวอ้าง	ข้อกำหนด
องค์ประกอบแบบจัดกลุ่มจัดระเบียบโครงสร้างเชิงตรรกะเป็นส่วน	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/ — โมเดลความเสี่ยงและเกต