Đánh dấu artifact của trang qua Connect

Tổng quan nhanh

Công thức này bọc các thành phần khung trang, bao gồm đầu trang và chân trang lặp lại, số trang, hình mờ và nền, thành nội dung được đánh dấu artifact qua các transport của Connect. Các thành phần khung này vẫn hiển thị trên trang, nhưng nằm ngoài cây cấu trúc và trình tự đọc của công nghệ hỗ trợ. Công cụ artifact thuộc bậc Enterprise: NextPDF phát hiện nó bằng một lần thăm dò class_exists() và chỉ đăng ký khi nextpdf/premium được cài đặt cùng với server. Subtype dùng một enum đã định kiểu (Pagination, Layout, Page, Background).

Để kiểm tra đầu ra, hãy dùng công cụ kiểm tra chuẩn Enterprise; công cụ này báo cáo theo PDF/UA-2. Kết quả đạt chỉ là kết quả kiểm tra của chính công cụ, 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ụ artifact Enterprise có sẵn bằng một lệnh gọi tools/list. Xem /connect/tool-catalog/.

Tổng quan khái niệm

Nội dung không thuộc cấu trúc logic được đánh dấu là artifact và được loại khỏi trình tự đọc (PDF/UA-2 §8.3). Artifact bao gồm nội dung phân trang, bố cục, trang hoặc nền, và được phân biệt với nội dung thực (PDF/UA-2 §8.3). Nội dung thực được phản ánh trong cây cấu trúc; artifact thì không (PDF/UA-2 §8.2.4).

Công cụ mở một chuỗi nội dung được đánh dấu artifact với subtype được yêu cầu. Mọi thao tác vẽ bạn phát ra trước lệnh đóng tương ứng đều được bọc bên trong chuỗi này.

Bề mặt API

Kiểm tra tên công cụ trên 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 không lặp lại số lượng công cụ.

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

Mở một artifact Background, vẽ hình mờ, rồi đóng nó lại:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Background" }
  }
}

Mẫu mã — môi trường production

Ghép từng lệnh mở với một lệnh đóng và kiểm tra để trang không có nội dung mồ côi:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Page", "attached": "Bottom" }
  }
}

Sau khi vẽ văn bản chân trang, hãy đóng nó bằng công cụ kết thúc artifact và chạy bước kiểm tra chuẩn theo PDF/UA-2. Cây cấu trúc chỉ được chứa nội dung thân; hình mờ và chân trang phải được loại trừ khỏi đó.

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

Subtype không xác định (ví dụ "Header") sẽ bị từ chối. Hãy truyền một trong Pagination, Layout, Page, Background.
Đóng mà không có lệnh mở sẽ thất bại với thông báo cho biết độ sâu bằng không. Luôn ghép lệnh mở với lệnh đóng.
Vẽ trước khi có bất kỳ ngữ cảnh artifact hoặc ngữ cảnh cấu trúc nào sẽ tạo ra nội dung mồ côi và khiến quy tắc cấu trúc thất bại. Hãy mở một ngữ cảnh cấu trúc hoặc artifact trước.
Thiếu công cụ. Nếu không có nextpdf/premium, công cụ artifact Enterprise sẽ không được đăng ký và lệnh gọi sẽ 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à giới hạn dùng cho tài liệu. Việc bọc artifact không bổ sung giai đoạn riêng nào có thể đo lường được.

Ghi chú về bảo mật

Không có yêu cầu riêng ngoài hướng dẫn chung về transport của Connect.

Tuân thủ

Ánh xạ PDF/UA-2

Subtype	Trường hợp sử dụng
`Pagination`	Đầu trang/chân trang lặp lại (running headers/footers), số trang, khung điều hướng
`Layout`	Đường kẻ, dấu phân tách, viền trang trí
`Page`	Phần phụ trợ gắn với trang (dấu cắt, dấu căn chỉnh in)
`Background`	Hình mờ, lớp nền tô màu, nhận diện thương hiệu

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

Tuyên bố	Điều khoản	reference_id
Nội dung phi cấu trúc được đánh dấu là artifact và được loại khỏi trình tự đọc	PDF/UA-2 §8.3
Các subtype artifact: pagination/layout/page/background	PDF/UA-2 §8.3
Nội dung thực nằm trong cây cấu trúc; artifact thì không	PDF/UA-2 §8.2.4

Ánh xạ WCAG 2.2

Việc loại khung trang trí khỏi trình tự đọc hỗ trợ tiêu chí Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) ở cấp độ nội dung.

Kết quả đạt của bước kiểm tra chuẩn chỉ là một bước kiểm tra, không phải chứng nhận tuân thủ. Chỉ một công cụ kiểm tra độc lập mới có thể đưa ra kết luận đó.

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

Công cụ artifact thuộc bậc Enterprise và 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 transport (MCP / REST / gRPC)

Bạn gọi các công cụ này theo cùng một cách qua MCP tools/call, endpoint công cụ REST và dịch vụ gRPC. Cả ba đều dùng chung bộ thực thi công cụ.

Bậc rủi ro HITL

Việc phát ra artifact và vẽ nội dung được xếp ở mức cần thận trọng; bước kiểm tra chuẩn là chỉ đọc. Theo mặc định, không công cụ nào nằm ở mức approval_required. Xem /connect/hitl-risk-tiers/.

Gói JSON của cổng xác nhận

Các công cụ này không kích hoạt cổng kiểm soát trừ khi một thiết lập ghi đè của người vận hành nâng một công cụ lên mức approval_required. Gói này và hợp đồng token dùng một lần được mô tả trong /connect/hitl-risk-tiers/.

Xem thêm

/cookbook/connect/aria-tagged-pdf/ — ánh xạ vai trò landmark.
/cookbook/connect/figure-caption/ — nhóm hình ảnh có thể truy cập.
/connect/tool-catalog/ — cách tính bộ công cụ theo từng bậc.
/connect/hitl-risk-tiers/ — mô hình rủi ro và cổng kiểm soát.