Hướng dẫn tạo PDF được gắn thẻ qua Connect

Hướng dẫn tạo PDF được gắn thẻ qua Connect

Ranh giới tuân thủ (hãy đọc phần này trước). NextPDF xuất ra cấu trúc được gắn thẻ, văn bản thay thế và siêu dữ liệu mà PDF/UA-2 yêu cầu. Điều đó làm cho kết quả đầu ra được dự định tuân thủ PDF/UA-2 (ISO 14289-2). Nó không tự làm cho tài liệu trở nên “tuân thủ”. Chỉ trình kiểm tra độc lập, là veraPDF ở chế độ PDF/UA-2 nghiêm ngặt, mới quyết định sự tuân thủ. Hãy hiểu mọi chỗ ghi “PASS”, “conformant” hay “compliant” bên dưới theo nghĩa “tài liệu được dự định tuân thủ; veraPDF quyết định kết quả”.

Tổng quan nhanh

Trong hướng dẫn này, bạn tạo một tệp Portable Document Format (PDF) được gắn thẻ qua các kênh truyền tải Connect. Bạn bật chế độ gắn thẻ, đặt tiêu đề, thêm HTML ngữ nghĩa và xác minh kết quả bằng công cụ standards-check cùng veraPDF. Các công cụ chế độ gắn thẻ và nội dung dùng ở đây thuộc bản core. Công cụ xác minh standards-check thuộc cấp Pro/Enterprise. Công cụ này chỉ được đăng ký thông qua class_exists() khi nextpdf/premium được cài đặt cùng với server.

Cài đặt

composer require nextpdf/server

Tổng quan khái niệm

Cấu trúc logic cùng với đặc tả ngôn ngữ tự nhiên giúp nội dung có thể điều hướng theo thứ tự đọc (ISO 32000-2 §14.7). Mục /Alt chứa mô tả thay thế cho nội dung không phải văn bản (ISO 32000-2 §14.8). Nội dung phải được phản ánh trong cây cấu trúc, và trình kiểm tra sẽ xác định sự tuân thủ (PDF/UA-2 §8.2.4). Khi bạn viết HTML ngữ nghĩa có cấu trúc tốt, pipeline sẽ tạo cấu trúc chính xác cho bạn. Hướng dẫn này dựa vào luồng đó thay vì yêu cầu bạn dựng cấu trúc theo cách thủ công.

Bề mặt API

Tên công cụ được xác minh từ registry đang chạy thông qua tools/list. Danh mục chính thức là /connect/tool-catalog/. Hướng dẫn này không nhắc lại số lượng công cụ.

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

Đây là cách ngắn gọn nhất. Bật chế độ gắn thẻ với một ngôn ngữ, đặt tiêu đề, rồi thêm nội dung.

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

Hãy bật chế độ gắn thẻ trước lệnh gọi nội dung đầu tiên của bạn. Trình ghi sẽ cố định chế độ khi phát ra trang đầu tiên. Nếu bạn bật chế độ này muộn hơn, NextPDF sẽ không quay lại để gắn thẻ cho nội dung đã được phát ra. Tiêu đề tài liệu là bắt buộc đối với PDF/UA-2, và chế độ gắn thẻ sẽ thiết lập tùy chọn hiển thị tiêu đề trong trình xem.

Mẫu mã — bản chính thức

Thêm HTML ngữ nghĩa. Pipeline ánh xạ tiêu đề, danh sách, bảng có <th scope>, liên kết và hình ảnh có alt sang đúng các loại cấu trúc:

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

" } }}">

Sau đó chạy standards check đối chiếu với PDF/UA-2, rồi chạy veraPDF --flavour ua2 trên kết quả đầu ra. Kết quả kiểm tra và phán quyết của veraPDF chỉ là các đánh giá. Chúng cho bạn biết liệu tài liệu có được dự định tuân thủ hay không. veraPDF, chứ không phải NextPDF, mới quyết định sự tuân thủ.

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

• Bật chế độ gắn thẻ sau khi đã có nội dung. Bất kỳ nội dung nào bạn thêm vào trước khi bật chế độ đó đều không được gắn thẻ. Lượt kiểm tra sẽ báo lỗi tagged-content. Hãy bật chế độ này ngay sau khi tạo tài liệu.
• Hình ảnh mang thông tin nhưng không có alt. Lượt kiểm tra sẽ báo lỗi figure-alternate-text. Hãy cung cấp văn bản thay thế, hoặc đánh dấu hình ảnh trang trí là artifact (/cookbook/connect/page-artifacts/).
• Bỏ qua một cấp tiêu đề. Bỏ qua một cấp, ví dụ H1 rồi đến H3, là một lỗi heading-order. Mỗi lần chỉ đi xuống tối đa một cấp.
• <th> không có scope. Một ô tiêu đề không liên kết với ô dữ liệu nào là một lỗi table-structure. Hãy gán cho mỗi <th> scope="col" hoặc scope="row".
• Thiếu tiêu đề. Một tài liệu không có tiêu đề là một lỗi metadata. Hãy đặt tiêu đề sau khi bạn bật chế độ gắn thẻ.

Hiệu năng

Ngân sách trong front-matter là giới hạn được ghi trong tài liệu. Việc gắn thẻ là một phần của lượt bố cục thông thường.

Lưu ý về bảo mật

Không có yêu cầu riêng nào ở đây ngoài hướng dẫn chung về kênh truyền tải Connect: đừng ghi nhật ký nội dung tài liệu hoặc phần thân HTML ở mức nhật ký được phát ra bên ngoài.

Sự tuân thủ

Ánh xạ PDF/UA-2

HTML ngữ nghĩa ánh xạ sang các loại cấu trúc tiêu chuẩn của PDF/UA-2 (H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside). Việc ánh xạ diễn ra tự động. Bạn chịu trách nhiệm viết HTML ngữ nghĩa.

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

Khẳng định	Điều khoản	reference_id
Cấu trúc logic + ngôn ngữ → có thể điều hướng theo thứ tự đọc	ISO 32000-2 §14.7
Mô tả thay thế được lưu trong /Alt	ISO 32000-2 §14.8
Nội dung nằm trong cây cấu trúc; một trình kiểm tra xác định sự tuân thủ	PDF/UA-2 §8.2.4

Ánh xạ WCAG 2.2

Cấu trúc này hỗ trợ các SC 1.1.1, 1.3.1, 2.4.1 và 2.4.6 của WCAG 2.2 ở cấp nội dung. Là tác giả nội dung, bạn vẫn chịu trách nhiệm về các quyết định biên soạn ở cấp WCAG.

NextPDF tạo ra kết quả đầu ra được dự định tuân thủ PDF/UA-2. Nó không khẳng định sự tuân thủ. veraPDF, hoặc một trình kiểm tra khác, mới đưa ra phán quyết về sự tuân thủ. Một lượt kiểm tra đạt hoặc một lần chạy veraPDF là bằng chứng cho thấy kết quả đầu ra được dự định tuân thủ, chứ không phải chứng nhận từ NextPDF.

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

Các công cụ chế độ gắn thẻ và nội dung thuộc bản core. Công cụ xác minh standards-check thuộc cấp Pro/Enterprise, và công cụ này chỉ được đăng ký khi nextpdf/premium được cài đặt cùng với server.

Chi tiết riêng của Connect

Khả dụng theo kênh truyền tải (MCP / REST / gRPC)

Bạn gọi mọi công cụ trong hướng dẫn này theo cùng một cách qua MCP tools/call, endpoint công cụ REST và dịch vụ gRPC. Tất cả đều chạy qua trình thực thi công cụ dùng chung.

Cấp rủi ro HITL

Việc bật chế độ gắn thẻ và dùng các công cụ nội dung thuộc mức caution. Standards check là chỉ-đọc. Đường xuất ghi tệp yêu cầu phê duyệt, còn chế độ base64 thì không. Xem /connect/hitl-risk-tiers/.

Vỏ bọc JSON của cổng xác nhận

Khi đường xuất ghi tệp bị chặn bởi cổng, cổng trả về một vỏ bọc challenge cùng một token dùng-một-lần. Token được gắn với tên công cụ, một nonce và thời gian sống (TTL) 300 giây. Để tiếp tục, hãy gọi lại công cụ kèm arguments._confirmation_token. Xem /connect/hitl-risk-tiers/.

Xem thêm

• /cookbook/connect/conformance-mode/ — bộ phân biệt chế độ phía sau chế độ gắn thẻ.
• /cookbook/connect/aria-tagged-pdf/ — ánh xạ vai trò landmark.
• /cookbook/connect/page-artifacts/ — loại trừ nội dung trang trí khỏi cây cấu trúc.
• /connect/tool-catalog/ — tính toán tập công cụ theo cấp.