บทช่วยสอนการสร้าง Tagged PDF ด้วย Connect

บทช่วยสอนการสร้าง Tagged PDF ด้วย Connect

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

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

ในบทช่วยสอนนี้ คุณจะสร้างไฟล์ Portable Document Format (PDF) แบบติดแท็กผ่านทรานสปอร์ตของ Connect คุณจะเปิดใช้งานโหมดติดแท็ก กำหนดชื่อเรื่อง เพิ่ม HTML เชิงความหมาย และตรวจสอบผลลัพธ์ด้วยเครื่องมือ standards-check และ veraPDF เครื่องมือโหมดติดแท็กและเครื่องมือจัดการเนื้อหาที่ใช้ในที่นี้เป็นส่วนหนึ่งของรุ่น core ส่วนเครื่องมือยืนยัน standards-check อยู่ในระดับ Pro/Enterprise และจะลงทะเบียนผ่าน class_exists() เฉพาะเมื่อมีการติดตั้ง nextpdf/premium ควบคู่ไปกับเซิร์ฟเวอร์เท่านั้น

การติดตั้ง

composer require nextpdf/server

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

โครงสร้างเชิงตรรกะร่วมกับการระบุภาษาธรรมชาติทำให้เนื้อหานำทางได้ตามลำดับการอ่าน (ISO 32000-2 §14.7) รายการ /Alt เก็บคำอธิบายทางเลือกสำหรับเนื้อหาที่ไม่ใช่ข้อความ (ISO 32000-2 §14.8) เนื้อหาต้องสะท้อนอยู่ในแผนผังโครงสร้าง และเครื่องมือตรวจสอบเป็นผู้กำหนดความสอดคล้องตามมาตรฐาน (PDF/UA-2 §8.2.4) เมื่อคุณเขียน HTML เชิงความหมายที่มีโครงสร้างเหมาะสม ไปป์ไลน์จะสร้างโครงสร้างที่ถูกต้องให้โดยอัตโนมัติ บทช่วยสอนนี้จึงอาศัยกระบวนการดังกล่าว แทนที่จะให้คุณสร้างโครงสร้างด้วยตนเอง

ขอบเขตของ API

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

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

นี่คือวิธีที่สั้นที่สุด ให้เปิดใช้งานโหมดติดแท็กพร้อมกำหนดภาษา กำหนดชื่อเรื่อง แล้วจึงเพิ่มเนื้อหา

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "enable_tagged_pdf",
    "arguments": { "document_id": "<id>", "language": "en" }
  }
}

เปิดใช้งานโหมดติดแท็กก่อนการเรียกใช้เนื้อหาครั้งแรก ตัวเขียนจะตรึงโหมดไว้เมื่อสร้างหน้าแรก หากคุณเปิดใช้งานในภายหลัง NextPDF จะไม่ย้อนกลับไปติดแท็กเนื้อหาที่สร้างไปแล้ว ชื่อเอกสารเป็นสิ่งจำเป็นสำหรับ PDF/UA-2 และโหมดติดแท็กจะตั้งค่า viewer-title preference ให้

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

เพิ่ม HTML เชิงความหมาย แล้วไปป์ไลน์จะแมปหัวเรื่อง รายการ ตารางที่มี <th scope> ลิงก์ และรูปภาพที่มี alt ไปยังชนิดของโครงสร้างที่ถูกต้อง:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id>",
      "html": "<h1>Annual Report</h1><h2>Summary</h2><p>Revenue grew.</p><table><caption>Revenue</caption><thead><tr><th scope=\"col\">Region</th><th scope=\"col\">Q1</th></tr></thead><tbody><tr><th scope=\"row\">EMEA</th><td>120</td></tr></tbody></table><figure><img src=\"chart.png\" alt=\"Revenue by region bar chart\" /><figcaption>Figure 1.</figcaption></figure>"
    }
  }
}

RevenueRegionQ1EMEA120

Figure 1.

" } }}">

จากนั้นรัน standards check เทียบกับ PDF/UA-2 และรัน veraPDF --flavour ua2 กับผลลัพธ์ที่ได้ ผลการตรวจสอบและคำตัดสินของ veraPDF เป็นการประเมิน ซึ่งบอกคุณว่าเอกสารมุ่งให้สอดคล้องหรือไม่ veraPDF ไม่ใช่ NextPDF เป็นผู้ตัดสินความสอดคล้องตามมาตรฐาน

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

• เปิดใช้งานโหมดติดแท็กหลังจากเพิ่มเนื้อหาแล้ว เนื้อหาใดก็ตามที่คุณเพิ่มก่อนเปิดใช้งานโหมดจะไม่ถูกติดแท็ก การตรวจสอบจะรายงานความล้มเหลวด้านเนื้อหาที่ติดแท็ก ให้เปิดใช้งานโหมดทันทีหลังจากสร้างเอกสาร
• รูปภาพให้ข้อมูลที่ไม่มี alt การตรวจสอบจะรายงานความล้มเหลวด้านข้อความทางเลือกของรูปภาพ ให้ใส่ข้อความ alt หรือทำเครื่องหมายรูปภาพประดับว่าเป็น artifact (/cookbook/connect/page-artifacts/)
• ข้ามระดับหัวเรื่อง การข้ามระดับ เช่น H1 แล้วต่อด้วย H3 เป็นความล้มเหลวด้านลำดับหัวเรื่อง ลดระดับลงครั้งละไม่เกินหนึ่งระดับ
• <th> โดยไม่มี scope เซลล์ส่วนหัวที่ไม่มีเซลล์ข้อมูลที่เกี่ยวข้องเป็นความล้มเหลวด้านโครงสร้างตาราง กำหนดให้ทุก <th> มีอย่างใดอย่างหนึ่งระหว่าง scope="col" หรือ scope="row"
• ไม่มีชื่อเรื่อง เอกสารที่ไม่มีชื่อเรื่องเป็นความล้มเหลวด้านเมทาดาทา กำหนดชื่อเรื่องหลังจากที่คุณเปิดใช้งานโหมดติดแท็ก

ประสิทธิภาพ

งบประมาณใน front-matter เป็นเพดานระดับเอกสาร การติดแท็กเป็นส่วนหนึ่งของรอบการจัดเค้าโครงตามปกติ

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

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

ความสอดคล้องตามมาตรฐาน

การแมป PDF/UA-2

HTML เชิงความหมายจะแมปไปยังชนิดโครงสร้างมาตรฐานของ PDF/UA-2 (H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside) การแมปเป็นไปโดยอัตโนมัติ หน้าที่ของคุณตามข้อตกลงคือการเขียน HTML เชิงความหมาย

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

ข้อกล่าวอ้าง	ข้อกำหนด	รหัสอ้างอิง (reference_id)
โครงสร้างเชิงตรรกะ + ภาษา → นำทางได้ตามลำดับการอ่าน	ISO 32000-2 §14.7
คำอธิบายทางเลือกที่จัดเก็บอยู่ใน /Alt	ISO 32000-2 §14.8
เนื้อหาอยู่ในแผนผังโครงสร้าง เครื่องมือตรวจสอบเป็นผู้กำหนดความสอดคล้องตามมาตรฐาน	PDF/UA-2 §8.2.4

การแมป WCAG 2.2

โครงสร้างนี้รองรับ WCAG 2.2 SC 1.1.1, 1.3.1, 2.4.1 และ 2.4.6 ในระดับเนื้อหา ในฐานะผู้เขียนเนื้อหา คุณยังคงรับผิดชอบต่อการตัดสินใจด้านการเขียนในระดับ WCAG

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

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

เครื่องมือโหมดติดแท็กและเครื่องมือจัดการเนื้อหาเป็นส่วนหนึ่งของรุ่น core เครื่องมือยืนยัน standards-check อยู่ในระดับ Pro/Enterprise และจะลงทะเบียนเฉพาะเมื่อมีการติดตั้ง nextpdf/premium ควบคู่ไปกับเซิร์ฟเวอร์เท่านั้น

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

ความพร้อมใช้งานของทรานสปอร์ต (MCP / REST / gRPC)

คุณเรียกใช้เครื่องมือทุกตัวในบทช่วยสอนนี้ได้ด้วยวิธีเดียวกันผ่าน MCP tools/call เอนด์พอยต์เครื่องมือ REST และบริการ gRPC ทั้งหมดทำงานผ่านตัวรันเครื่องมือที่ใช้ร่วมกัน

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

การเปิดใช้งานโหมดติดแท็กและการใช้เครื่องมือจัดการเนื้อหาอยู่ในระดับ caution ส่วน standards check เป็นแบบอ่านอย่างเดียว เส้นทางผลลัพธ์แบบเขียนไฟล์ต้องได้รับการอนุมัติ แม้ว่าโหมด base64 จะไม่ต้องก็ตาม ดู /connect/hitl-risk-tiers/

JSON envelope ของเกตยืนยัน

เมื่อเส้นทางผลลัพธ์แบบเขียนไฟล์ถูกควบคุมด้วยเกต เกตจะส่งคืน challenge envelope และโทเค็นที่ใช้ได้ครั้งเดียว โทเค็นนี้ผูกกับชื่อเครื่องมือ nonce และ time-to-live (TTL) ขนาด 300 วินาที หากต้องการดำเนินการต่อ ให้เรียกใช้เครื่องมืออีกครั้งพร้อม arguments._confirmation_token ดู /connect/hitl-risk-tiers/

ดูเพิ่มเติม

• /cookbook/connect/conformance-mode/ — ตัวจำแนกโหมดที่อยู่เบื้องหลังโหมดติดแท็ก
• /cookbook/connect/aria-tagged-pdf/ — การแมป landmark role
• /cookbook/connect/page-artifacts/ — ไม่นำเนื้อหาประดับเข้าในแผนผังโครงสร้าง
• /connect/tool-catalog/ — การคำนวณชุดเครื่องมือตามแต่ละระดับ