Tạo Figure dễ tiếp cận có Caption qua Connect

Tổng quan nhanh

Gửi một <figure> HTML có một <img> và một <figcaption> qua các transport của Connect. Pipeline tạo một phần tử cấu trúc Figure tiêu chuẩn, lồng phần chú thích dưới dạng phần tử con Caption, và dùng thuộc tính alt để điền vào /Alt. Xác minh kết quả bằng công cụ trợ năng bậc Pro. NextPDF phát hiện công cụ này qua class_exists() và chỉ đăng ký nó khi nextpdf/premium được cài đặt cùng với máy chủ. Các công cụ Core đảm nhận việc tạo tài liệu và nạp HTML.

Việc công cụ trợ năng trả về kết quả đạt 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.

Cài đặt

composer require nextpdf/server

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

Tổng quan khái niệm

Mô tả thay thế cung cấp văn bản cho nội dung phi văn bản, chẳng hạn như hình minh họa (ISO 32000-2 §14.8). Phần tử cấu trúc lưu mô tả đó trong mục /Alt của nó (ISO 32000-2 §14.8). Thuộc tính alt trong HTML điền vào /Alt trên Figure được tạo ra. Pipeline tạo <figcaption> dưới dạng phần tử con Caption được lồng vào, thay vì một đoạn văn cùng cấp, để phần chú thích vẫn tiếp cận được như một phần của hình minh họa (PDF/UA-2 §8.2.4).

Bề mặt API

Đối chiếu 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ụ document và HTML của core, cùng với bước kiểm tra trợ năng Pro. Công thức không nhắc lại số lượng công cụ.

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

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

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

Thêm phần đánh dấu cho figure. Thuộc tính alt là bắt buộc để hình minh họa dễ tiếp cận:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<figure><img src=\"diagrams/architecture.png\" alt=\"Three-tier deployment: web frontend, REST API, datastore\" /><figcaption>Figure 1 — Deployment topology.</figcaption></figure>"
    }
  }
}

Chạy bước kiểm tra trợ năng, rồi rà soát cây cấu trúc được báo cáo. Kết quả cho thấy một Figure duy nhất có /Alt và đúng một phần tử con Caption.

Trường hợp biên & lưu ý

<img> không có alt. Bước kiểm tra báo lỗi thiếu văn bản thay thế cho hình minh họa. Hãy cung cấp một alt mang tính mô tả hoặc đánh dấu hình ảnh chỉ để trang trí là artifact (xem /cookbook/connect/page-artifacts/).
<figcaption> rỗng. Pipeline đưa ra cảnh báo. Hãy cung cấp nội dung chú thích hoặc loại bỏ phần tử này.
<figcaption> nằm ngoài mọi <figure>. Pipeline biến nó thành một caption mồ côi. Hãy bọc nó trong một <figure>.
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 front-matter là một giới hạn phục vụ tài liệu. Việc xử lý figure chạy như một phần của lượt bố cục thông thường.

Lưu ý bảo mật

Không có hướng dẫn bổ sung nào ngoài hướng dẫn chung về transport của Connect.

Tuân thủ

Ánh xạ PDF/UA-2

Tuyên bố	Điều khoản	reference_id
Mô tả thay thế cho nội dung phi văn bản	ISO 32000-2 §14.8
Mô tả thay thế được lưu trong `/Alt`	ISO 32000-2 §14.8
Caption có thể tiếp cận được qua cây cấu trúc	PDF/UA-2 §8.2.4

Thẻ → tham chiếu chéo ISO 32000-2 §14.9

Figure và Caption là các kiểu cấu trúc tiêu chuẩn. Việc lồng <figcaption> làm Caption xác lập hợp đồng cho figure dễ tiếp cận.

Ánh xạ WCAG 2.2

Một hình minh họa có văn bản alt và caption đi kèm sẽ hỗ trợ Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.1.1 (Non-text Content) và SC 1.3.1 (Info and Relationships) ở cấp độ nội dung.

Việc công cụ trợ năng trả về kết quả đạt là một bước kiểm tra trợ năng, không phải chứng nhận tuân thủ. Kết luận đó cần đến một bộ kiểm tra độc lập.

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ủ.

Đặc thù của Connect

Tính khả dụng của transport (MCP / REST / gRPC)

Gọi create_pdf, add_html, và bước kiểm tra trợ năng theo cùng một cách qua Model Context Protocol (MCP), REST, và gRPC thông qua trình 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 được xếp ở mức thận trọng. Bước kiểm tra trợ năng chỉ đọc. Theo mặc định, không công cụ nào trong số này là approval_required. Xem /connect/hitl-risk-tiers/.

Vỏ bọc 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 thao tác ghi đè từ người vận hành nâng một công cụ lên approval_required. Vỏ bọc và hợp đồng 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ò landmark.
/cookbook/connect/aria-noteref-pattern/ — vai trò tham chiếu chú thích cuối trang và phần thân.
/cookbook/connect/page-artifacts/ — đánh dấu hình ảnh trang trí là artifact.
/connect/tool-catalog/ — tính toán bộ công cụ theo từng bậc.