Mẫu tham chiếu và nội dung chú thích cuối trang qua Connect

Tổng quan nhanh

Kết xuất tham chiếu và nội dung chú thích cuối trang qua Connect để cây cấu trúc mang các vai trò chú thích cuối trang của PDF 2.0. Dấu hiệu nội dòng trở thành một tham chiếu footnote/endnote, còn phần văn bản chú thích cuối trang trở thành nội dung chú thích, với tham chiếu ngược qua lại giữa hai phần. Ba dạng HTML tạo ra cùng một kết quả: liên kết bên trong chỉ số trên, role="doc-noteref" Accessible Rich Internet Applications (ARIA) tường minh, và vùng chứa nội dung <aside class="footnote">. Việc xác minh dùng công cụ trợ năng bậc Pro. NextPDF phát hiện công cụ này bằng class_exists() và chỉ đăng ký khi nextpdf/premium được cài đặt cùng máy chủ.

Kết quả đạt yêu cầu từ công cụ trợ năng là một lần kiểm tra trợ năng, không phải chứng nhận tuân thủ độc lập.

Cài đặt

composer require nextpdf/server

Xác nhận công cụ trợ năng Pro có sẵn bằng lệnh gọi tools/list; xem /connect/tool-catalog/.

Tổng quan khái niệm

PDF 2.0 định nghĩa các kiểu cấu trúc footnote/endnote chuyên dụng và mối quan hệ giữa tham chiếu với nội dung của nó (PDF/UA-2 §8.2.5). Tham chiếu chú thích cuối trang phải được liên kết với phần nội dung của nó (PDF/UA-2 §8.2.5), để trình đọc màn hình có thể đọc tham chiếu và đi theo liên kết tới chú thích. Cả tham chiếu lẫn nội dung đều phải tiếp cận được thông qua cây cấu trúc (PDF/UA-2 §8.2.4).

Quy trình nhận diện ba dạng tham chiếu:

<sup><a href="#fn-N">N</a></sup> — dạng viết tắt: liên kết nằm trong chỉ số trên.
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — vai trò Digital Publishing Accessible Rich Internet Applications (DPUB-ARIA) tường minh; aria-describedby được chuyển tiếp làm đích tham chiếu ngược.
<aside class="footnote" id="fn-N">…</aside> (hoặc role="doc-footnote") — vùng chứa nội dung, được xuất ra dưới dạng phần nội dung chú thích với tham chiếu nội bộ trỏ ngược về tham chiếu tương ứng.

Bề mặt API

Xác minh tên công cụ với registry đang chạy bằng tools/list. Danh mục chính thức là /connect/tool-catalog/. Công thức này sử dụng các công cụ tài liệu lõi và HTML cùng với lần kiểm tra trợ năng Pro, và không lặp lại số lượng công cụ.

Mẫu mã — bắt đầu nhanh

Tạo tài liệu được gắn thẻ kèm thiết lập ngôn ngữ, rồi thêm tham chiếu dạng viết tắt có liên kết:

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

Mẫu mã — sản xuất

Xuất cả hai tham chiếu và cả hai phần nội dung trong một lần thêm HTML, rồi chạy kiểm tra:

{
  "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>"
    }
  }
}

Lần kiểm tra trợ năng báo cáo các vai trò reference/body đã được ghép cặp và các tham chiếu ngược qua lại.

Trường hợp biên & điểm cần lưu ý

Có tham chiếu nhưng không có phần nội dung (hoặc có phần nội dung nhưng không có tham chiếu) sẽ bị lần kiểm tra báo cáo; mỗi tham chiếu cần một phần nội dung tương ứng và ngược lại.
Không khớp id giữa aria-describedby và id của phần nội dung khiến cặp này không được phân giải (phân biệt chữ hoa chữ thường).
Liên kết neo trong chỉ số trên trỏ tới một URL bên ngoài sẽ xuất ra một liên kết thông thường, không phải tham chiếu chú thích cuối trang; hãy dùng vai trò tường minh cho đích bên ngoài.
<aside> trống không có class/role được xử lý như mốc định hướng, không phải phần nội dung chú thích. Hãy thêm class="footnote" hoặc role="doc-footnote".
Thiếu công cụ. Nếu không có nextpdf/premium, công cụ trợ năng Pro sẽ không được đăng ký, nên việc xác minh sẽ thất bại với lỗi công cụ không xác định.

Hiệu năng

Giới hạn trong frontmatter là giới hạn mang tính tài liệu; việc ghép cặp chú thích cuối trang là một phần của lượt xử lý cấu trúc thông thường.

Ghi chú bảo mật

Không có yêu cầu bổ sung ngoài hướng dẫn truyền tải Connect chung.

Tuân thủ

Ánh xạ PDF/UA-2

Tuyên bố	Điều khoản	reference_id
Các kiểu cấu trúc footnote/endnote và mối quan hệ reference/body	PDF/UA-2 §8.2.5
Một tham chiếu chú thích cuối trang được liên kết với phần nội dung của nó	PDF/UA-2 §8.2.5
Tham chiếu và phần nội dung có thể tiếp cận được thông qua cây cấu trúc	PDF/UA-2 §8.2.4

Tham chiếu chéo thẻ → ISO 32000-2 §14.9

Tham chiếu và phần nội dung sử dụng các kiểu cấu trúc tiêu chuẩn footnote/endnote của PDF 2.0. Các tham chiếu ngược qua lại là quy ước cho chú thích cuối trang có trợ năng.

Ánh xạ WCAG 2.2

Tham chiếu chú thích cuối trang và phần nội dung được liên kết hỗ trợ Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) và SC 2.4.1 (Bypass Blocks) ở cấp nội dung.

Kết quả đạt yêu cầu từ công cụ trợ năng là một lần kiểm tra trợ năng, không phải chứng nhận tuân thủ; chỉ bộ kiểm tra độc lập mới đưa ra phán định đó.

Bối cảnh thương mại

Công cụ kiểm tra trợ năng thuộc bậc Pro và chỉ đăng ký khi nextpdf/premium được cài đặt cùng máy chủ.

Chi tiết riêng của Connect

Khả dụng theo giao thức truyền tải (MCP / REST / gRPC)

create_pdf, add_html, và lần kiểm tra trợ năng được gọi giống nhau qua Model Context Protocol (MCP), REST, và gRPC thông qua bộ thực thi công cụ dùng chung.

Bậc rủi ro HITL

Việc tạo tài liệu và tiếp nhận HTML nằm ở mức thận trọng; lần kiểm tra trợ năng chỉ đọc. Theo mặc định, không có công cụ nào là approval_required. Xem /connect/hitl-risk-tiers/.

Phong bì JSON của cổng xác nhận

Các công cụ này không kích hoạt cổng trừ khi lệnh ghi đè của người vận hành nâng một công cụ lên approval_required. Quy ước về phong bì và token dùng một lần nằm trong /connect/hitl-risk-tiers/.

Xem thêm

/cookbook/connect/aria-tagged-pdf/ — ánh xạ vai trò mốc định hướng.
/cookbook/connect/figure-caption/ — cấu trúc Figure / Caption lồng nhau.
/connect/tool-catalog/ — cách tính tập công cụ theo từng bậc.
/connect/hitl-risk-tiers/ — mô hình rủi ro và cổng.