Ánh xạ các vai trò mốc ARIA sang PDF được gắn thẻ qua Connect

Tổng quan nhanh

Gửi HTML sử dụng các phần tử phân đoạn HTML5 và vai trò mốc Accessible Rich Internet Applications (ARIA) qua Connect. Pipeline nội dung gắn thẻ ánh xạ chúng sang các kiểu cấu trúc chuẩn của PDF 2.0, nhờ đó công nghệ hỗ trợ có thể điều hướng theo mốc thay vì theo vị trí trực quan. Bước kiểm tra trợ năng dùng ở đây thuộc bậc Pro: công cụ được phát hiện bằng một phép thăm dò class_exists() và chỉ được đăng ký khi nextpdf/premium được cài đặt cùng với máy chủ. Các bước tạo tài liệu và nạp HTML dùng công cụ core.

Công cụ trợ năng báo cáo các phát hiện theo PDF/UA-2 (ISO 14289-2). Kết quả đạt chỉ là đánh giá của riêng công cụ. Đây là một bước kiểm tra trợ năng, không phải chứng nhận tuân thủ độc lập. Chỉ veraPDF hoặc một trình kiểm tra khác mới xác định mức tuân thủ.

Cài đặt

composer require nextpdf/server

Xác nhận công cụ trợ năng Pro hiện diện trên bản triển khai đang chạy bằng một lệnh gọi tools/list (xem /connect/tool-catalog/). Nếu không thấy công cụ này, nextpdf/premium chưa được cài đặt trên bản triển khai này, nên bước xác minh trong công thức này không thể chạy.

Tổng quan khái niệm

Các phần tử cấu trúc nhóm tổ chức cấu trúc logic của tài liệu thành các phần và các vùng chứa tương tự (ISO 32000-2 §14.8). Pipeline HTML ánh xạ những phần tử này:

<aside> và role="complementary" → kiểu chuẩn Aside của PDF 2.0
<article> / role="article" → Art
<nav> / role="navigation" → Sect

Một kiểu cấu trúc phi chuẩn chỉ được chấp nhận khi nó có ánh xạ vai trò sang một kiểu chuẩn (PDF/UA-2 §8.2.5). Pipeline xuất trực tiếp kiểu chuẩn, nên bạn không cần một bảng ánh xạ vai trò thủ công. Nội dung phải được phản ánh trong cây cấu trúc để công nghệ hỗ trợ có thể tiếp cận (PDF/UA-2 §8.2.4).

Bề mặt API

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

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

Tạo tài liệu PDF 2.0 được gắn thẻ, thêm HTML có vai trò mốc rồi kiểm tra tài liệu bằng cách tuần tự hóa các yêu cầu tools/call của MCP:

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

Kết nối bộ phát nội dung được gắn thẻ trước khi thêm bất kỳ HTML nào. Tạo tài liệu kèm thiết lập ngôn ngữ để bộ phát hoạt động ngay từ lệnh gọi nội dung đầu tiên.

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

Thêm HTML có mốc và chạy bước kiểm tra trợ năng. Hãy coi trạng thái không thành công là một kết quả bình thường cần kiểm tra, không phải lỗi truyền tải:

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

Phản hồi kiểm tra báo cáo cây cấu trúc quan sát được và một bản tóm tắt các phát hiện PDF/UA-2. Cả <aside> lẫn <div role="complementary"> đều được rút gọn về cùng kiểu chuẩn Aside.

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

Chưa bật gắn thẻ trước nội dung. Nếu tài liệu không được tạo với chế độ ngôn ngữ / gắn thẻ, lần thêm HTML đầu tiên sẽ tạo ra nội dung không được gắn thẻ, và phần kiểm tra báo cáo lỗi về nội dung gắn thẻ. Tạo lại tài liệu có thiết lập ngôn ngữ.
Vai trò xung đột trên phần tử phân đoạn (<aside role="navigation">) tạo ra một cảnh báo. Hãy bỏ vai trò xung đột hoặc dùng một <div>.
Thiếu công cụ. Nếu không có nextpdf/premium, công cụ trợ năng Pro không được đăng ký, và bước xác minh thất bại với lỗi công cụ không xác định.

Hiệu năng

Ngân sách trong frontmatter là một giới hạn của tài liệu. Việc ánh xạ mốc là một phần của lượt bố cục thông thường. Với tài liệu thông thường, thao tác này không thêm riêng một giai đoạn có thể đo lường.

Lưu ý bảo mật

Không có hướng dẫn bổ sung nào ngoài quy tắc truyền tải Connect chung: không ghi nhật ký nội dung tài liệu hoặc phần thân HTML ở cấp nhật ký được xuất ra bên ngoài.

Mức tuân thủ

Ánh xạ PDF/UA-2

HTML	Kiểu chuẩn PDF 2.0
`<aside>`, `role="complementary"`	`Aside`
`<article>`, `role="article"`	`Art`
`<nav>`, `role="navigation"`	`Sect`

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

Tuyên bố	Điều khoản	reference_id
Các phần tử nhóm tổ chức cấu trúc logic thành các phần	ISO 32000-2 §14.8
Các kiểu phi chuẩn cần được ánh xạ vai trò sang một kiểu chuẩn	PDF/UA-2 §8.2.5
Nội dung phải tiếp cận được qua cây cấu trúc	PDF/UA-2 §8.2.4

Ánh xạ WCAG 2.2

Điều hướng theo mốc hỗ trợ WCAG 2.2 SC 1.3.1 (Info and Relationships) và SC 2.4.1 (Bypass Blocks) ở cấp độ nội dung. Định dạng PDF mang theo cấu trúc này. Người tạo nội dung vẫn chịu trách nhiệm về các quyết định biên soạn ở cấp WCAG.

Một kết quả đạt từ công cụ trợ năng là một bước kiểm tra trợ năng, không phải chứng nhận tuân thủ. Một trình kiểm tra độc lập (ví dụ, veraPDF) mới xác định mức tuân thủ PDF/UA-2.

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

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

Chi tiết về Connect

Khả dụng theo lớp truyền tải (MCP / REST / gRPC)

Gọi create_pdf, add_html, và phần kiểm tra trợ năng theo cùng một cách qua tools/call của MCP, endpoint công cụ REST, và dịch 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à nạp HTML thuộc mức thận trọng (tự động thực thi, có ghi nhật ký kiểm toán). Phần kiểm tra trợ năng chỉ đọc. Không công cụ nào trong nhóm này là approval_required theo mặc định. Xem /connect/hitl-risk-tiers/.

Lớp bao 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 một thiết lập ghi đè của người vận hành nâng một trong số chúng lên approval_required. Khi bị cổng chặn, lớp bao thử thách và hợp đồng token dùng một lần tuân theo /connect/hitl-risk-tiers/.

Xem thêm

/cookbook/connect/figure-caption/ — cấu trúc Figure / Caption lồng nhau.
/cookbook/connect/aria-noteref-pattern/ — vai trò tham chiếu chú thích cuối trang và phần thân.
/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.