รูปแบบการอ้างอิงเชิงอรรถและเนื้อหาเชิงอรรถผ่าน Connect

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

เรนเดอร์การอ้างอิงเชิงอรรถและเนื้อหาเชิงอรรถผ่าน Connect เพื่อให้โครงสร้างต้นไม้รองรับบทบาทเชิงอรรถของ PDF 2.0 เครื่องหมายอินไลน์จะถูกแปลงเป็นการอ้างอิงแบบ footnote/endnote และข้อความเชิงอรรถจะถูกแปลงเป็นเนื้อหาหมายเหตุ โดยทั้งสองฝั่งมีการอ้างอิงย้อนกลับถึงกัน โครงสร้าง HTML สามรูปแบบให้ผลลัพธ์เดียวกัน ได้แก่ ลิงก์ภายในตัวยก (superscript) บทบาท Accessible Rich Internet Applications (ARIA) แบบชัดแจ้ง role="doc-noteref" และคอนเทนเนอร์เนื้อหา <aside class="footnote"> การตรวจสอบใช้เครื่องมือการช่วยการเข้าถึงระดับ Pro NextPDF ค้นพบเครื่องมือนี้ด้วย class_exists() และลงทะเบียนเฉพาะเมื่อมีการติดตั้ง nextpdf/premium ควบคู่กับเซิร์ฟเวอร์เท่านั้น

ผลลัพธ์ที่ผ่านเครื่องมือการช่วยการเข้าถึงเป็นการตรวจสอบการช่วยการเข้าถึง ไม่ใช่การรับรองความสอดคล้องโดยอิสระ

การติดตั้ง

composer require nextpdf/server

ยืนยันว่าเครื่องมือการช่วยการเข้าถึงระดับ Pro พร้อมใช้งานโดยเรียก tools/list ดูที่ /connect/tool-catalog/

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

PDF 2.0 กำหนดชนิดโครงสร้างเฉพาะสำหรับ footnote/endnote และกำหนดความสัมพันธ์ระหว่างการอ้างอิงกับเนื้อหาของการอ้างอิงนั้น (PDF/UA-2 §8.2.5) การอ้างอิงเชิงอรรถต้องเชื่อมโยงกับเนื้อหาของการอ้างอิงนั้น (PDF/UA-2 §8.2.5) เพื่อให้โปรแกรมอ่านหน้าจอประกาศการอ้างอิงและตามลิงก์ไปอ่านหมายเหตุได้ ทั้งการอ้างอิงและเนื้อหาต้องเข้าถึงได้ผ่านโครงสร้างต้นไม้ (PDF/UA-2 §8.2.4)

ไปป์ไลน์รองรับรูปแบบการอ้างอิงสามแบบ ดังนี้

<sup><a href="#fn-N">N</a></sup> — รูปแบบย่อที่เป็นลิงก์ภายในตัวยก
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — บทบาท Digital Publishing Accessible Rich Internet Applications (DPUB-ARIA) แบบชัดแจ้ง โดย aria-describedby จะถูกส่งต่อไปเป็นเป้าหมายของการอ้างอิงย้อนกลับ
<aside class="footnote" id="fn-N">…</aside> (หรือ role="doc-footnote") — คอนเทนเนอร์เนื้อหา ซึ่งจะถูกสร้างเป็นเนื้อหาหมายเหตุพร้อมการอ้างอิงภายในที่ย้อนกลับไปยังการอ้างอิงที่ตรงกัน

พื้นผิว API

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

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

สร้างเอกสารที่มีการแท็กพร้อมกำหนดภาษา จากนั้นเพิ่มการอ้างอิงแบบย่อที่เป็นลิงก์ ดังนี้

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

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

สร้างการอ้างอิงทั้งสองรายการและเนื้อหาทั้งสองส่วนในการเพิ่ม HTML ครั้งเดียว จากนั้นเรียกใช้การตรวจสอบ ดังนี้

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<p>Revenue grew 24%<sup><a href=\"#fn-1\">1</a></sup>.</p><p>Margin 33%<sup role=\"doc-noteref\" aria-describedby=\"fn-2\">2</sup>.</p><aside class=\"footnote\" id=\"fn-1\"><p>YoY vs prior year.</p></aside><aside class=\"footnote\" id=\"fn-2\" role=\"doc-footnote\"><p>(Revenue − OpEx) / Revenue.</p></aside>"
    }
  }
}

การตรวจสอบการช่วยการเข้าถึงจะรายงานบทบาท reference/body ที่จับคู่กัน รวมถึงการอ้างอิงย้อนกลับซึ่งกันและกัน

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

มีการอ้างอิงแต่ไม่มีเนื้อหา (หรือมีเนื้อหาแต่ไม่มีการอ้างอิง) การตรวจสอบจะรายงานกรณีนี้ ทุกการอ้างอิงต้องมีเนื้อหาที่ตรงกัน และเนื้อหาทุกส่วนต้องมีการอ้างอิงที่ตรงกันเช่นกัน
id ไม่ตรงกัน ระหว่าง aria-describedby กับ id ของเนื้อหา ทำให้คู่นั้นไม่สามารถจับคู่ได้ (คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่)
ตัวยกที่ลิงก์ไปยัง URL ภายนอก จะถูกสร้างเป็นลิงก์ธรรมดา ไม่ใช่การอ้างอิงเชิงอรรถ ให้ใช้บทบาทแบบชัดแจ้งสำหรับเป้าหมายภายนอก
<aside> เปล่าที่ไม่มี class/role จะถือเป็นแลนด์มาร์ก ไม่ใช่เนื้อหาหมายเหตุ ให้เพิ่ม class="footnote" หรือ role="doc-footnote" ลงไป
ไม่มีเครื่องมือ หากไม่มี nextpdf/premium เครื่องมือการช่วยการเข้าถึงระดับ Pro จะไม่ถูกลงทะเบียน การตรวจสอบจึงล้มเหลวพร้อมข้อผิดพลาดแบบไม่รู้จักเครื่องมือ (unknown-tool)

ประสิทธิภาพ

งบประมาณใน frontmatter เป็นเพดานสำหรับเอกสาร การจับคู่เชิงอรรถเป็นส่วนหนึ่งของรอบการประมวลผลโครงสร้างตามปกติ

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

ไม่มีข้อควรพิจารณาเพิ่มเติมนอกเหนือจากคำแนะนำเรื่องการขนส่ง (transport) ของ Connect โดยทั่วไป

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

การแมป PDF/UA-2

ข้อกล่าวอ้าง	ข้อกำหนด	รหัสอ้างอิง (reference_id)
ชนิดโครงสร้าง footnote/endnote และความสัมพันธ์ reference/body	PDF/UA-2 §8.2.5
การอ้างอิงเชิงอรรถเชื่อมโยงกับเนื้อหาของการอ้างอิงนั้น	PDF/UA-2 §8.2.5
การอ้างอิงและเนื้อหาเข้าถึงได้ผ่านโครงสร้างต้นไม้	PDF/UA-2 §8.2.4

การอ้างอิงข้ามจากแท็ก → ISO 32000-2 §14.9

การอ้างอิงและเนื้อหาใช้ชนิดโครงสร้างมาตรฐาน footnote/endnote ของ PDF 2.0 การอ้างอิงย้อนกลับซึ่งกันและกันถือเป็นสัญญาของเชิงอรรถที่เข้าถึงได้

การแมป WCAG 2.2

การอ้างอิงเชิงอรรถและเนื้อหาที่เชื่อมโยงกันรองรับ Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) และ SC 2.4.1 (Bypass Blocks) ในระดับเนื้อหา

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

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

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

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

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

create_pdf add_html และการตรวจสอบการช่วยการเข้าถึงสามารถเรียกใช้ได้ในลักษณะเดียวกันผ่าน Model Context Protocol (MCP) REST และ gRPC โดยใช้ตัวเรียกใช้เครื่องมือร่วม (shared tool executor)

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

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

เอนเวโลป JSON ของเกตยืนยัน

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

ดูเพิ่มเติม

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