Kiểm tra khả năng truy cập về cấu trúc trong NextPDF Connect (Pro)

Tổng quan nhanh

Chạy phân tích khả năng truy cập về cấu trúc trong NextPDF Connect. Dùng check_accessibility, công cụ đã được xác minh với nhà cung cấp công cụ Pro; nhà cung cấp này đăng ký new CheckAccessibilityTool() dưới tên giao thức check_accessibility. Mô tả của công cụ xác định phạm vi hoạt động: nó phân tích khả năng truy cập về cấu trúc của một tệp PDF — tiêu đề, bảng, hình ảnh và các chỉ báo thứ tự đọc. Công cụ trả về các chỉ báo và gợi ý khắc phục. Nó không chứng nhận sự tuân thủ Portable Document Format/Universal Accessibility (PDF/UA) hay Web Content Accessibility Guidelines (WCAG). Chỉ một trình kiểm tra sự tuân thủ, chẳng hạn như veraPDF hoặc một công cụ kiểm tra PDF/UA, mới có thể đưa ra kết luận đó. check_accessibility là một công cụ thuộc tầng Pro. NextPDF phát hiện công cụ này bằng class_exists() khi khởi động và chỉ đăng ký nó khi gói Pro đã được cài đặt.

Cài đặt

composer require nextpdf/server
composer require nextpdf/pro

Ràng buộc một transport, rồi xác nhận công cụ bằng diagnostic.capabilities.

Tổng quan khái niệm

Cấu trúc có khả năng truy cập phụ thuộc vào hai yếu tố: cây cấu trúc logic gồm các phần tử cấu trúc (ISO 32000-2 §14.7) và ngôn ngữ tài liệu được khai báo qua mục Lang của catalog (ISO 32000-2 §14.9; PDF/UA-2 §8.4.4). check_accessibility kiểm tra các chỉ báo cấu trúc này và trả về các phát hiện cùng mức độ nghiêm trọng và hướng dẫn khắc phục. Hãy coi mọi điểm số dạng số hay giá trị pass/fail trong báo cáo là bản tóm tắt chỉ báo, không phải chứng nhận. Hãy dùng báo cáo này để phân loại ưu tiên xử lý.

Bề mặt API

Công cụ	Tầng	Vai trò	Mức rủi ro
`create_pdf`, `add_text`	Core	Tạo nội dung để kiểm tra	An toàn / Thận trọng
`check_accessibility`	Pro	Phân tích khả năng truy cập về cấu trúc	An toàn
`output_pdf`	Core	Kết xuất và trả về tệp PDF	Cần phê duyệt / Xem xét (base64)

Tên công cụ chính là tên giao thức trong registry. Danh mục công cụ là danh mục chính thức. Tầng đã cài đặt quyết định công cụ nào sẵn dùng.

Mã ví dụ — bắt đầu nhanh

create_pdf → thêm nội dung bằng add_text.
check_accessibility với document_id.
Xem xét các phát hiện: mức độ nghiêm trọng, chỉ báo, các trang bị ảnh hưởng và gợi ý khắc phục.
Tùy chọn dùng output_pdf (base64) để xem xét thủ công cùng với báo cáo.

Mã ví dụ — môi trường production

Hãy coi báo cáo là dữ liệu đầu vào để phân loại ưu tiên xử lý, không phải kết luận cuối cùng. Ánh xạ từng phát hiện tới một cách sửa cụ thể: bật đầu ra được gắn thẻ, đặt ngôn ngữ tài liệu và thêm cấu trúc tiêu đề. Để có một cổng kiểm tra sự tuân thủ, hãy chạy một trình kiểm tra bên ngoài. Hãy coi kết luận đó mới là kết luận có thẩm quyền, không phải điểm số của công cụ này. Hãy chạy kiểm tra trước khi gọi output_pdf với destroy: true; nếu không, công cụ sẽ không thấy được tài liệu.

Trường hợp biên & lưu ý dễ vấp

Không có nội dung. Một tài liệu trống trả về phát hiện không-có-nội-dung, không phải chứng nhận.
Tài liệu lớn. Thời gian chờ giới hạn quá trình phân tích; hãy chia nhỏ hoặc giới hạn phạm vi đầu vào lớn.
Phiên đã bị hủy. Hãy chạy kiểm tra trước khi bước xuất đầu ra hủy phiên.
Nguồn được mã hóa. Hãy cung cấp mật khẩu.
Không có Pro. Khi chỉ có Core, check_accessibility không được đăng ký.

Hiệu năng

Thời gian chờ trong ngân sách giới hạn quá trình phân tích. Hồ sơ là semantic: báo cáo là đầu ra của phân tích cấu trúc, nên hãy so sánh các phát hiện, không so sánh đầu ra byte.

Lưu ý bảo mật

Báo cáo mô tả cấu trúc, không phải các bí mật trong nội dung. Tài liệu đang được phân tích vẫn có thể nhạy cảm, nên hãy giữ nó trong ranh giới tin cậy của bạn. Luồng phân tích không ghi vào hệ thống tệp.

Sự tuân thủ

Phát biểu	Đặc tả	Điều khoản
Cấu trúc logic là một cây gồm các phần tử cấu trúc.	ISO 32000-2	§14.7
Ngôn ngữ tài liệu được khai báo qua mục `Lang`.	ISO 32000-2	§14.9
Ngôn ngữ tự nhiên phải được chỉ định để soạn thảo có khả năng truy cập.	PDF/UA-2	§8.4.4

check_accessibility báo cáo các chỉ báo cấu trúc hỗ trợ việc soạn thảo có khả năng truy cập. Nó không khẳng định sự tuân thủ PDF/UA hay WCAG. Chỉ một trình kiểm tra độc lập mới xác định điều đó.

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

check_accessibility là một công cụ thuộc tầng Pro. NextPDF chỉ đăng ký nó khi gói Pro được phân giải lúc máy chủ khởi động.

Ánh xạ PDF/UA-2

Các chỉ báo cấu trúc mà công cụ này kiểm tra phù hợp với nhu cầu soạn thảo PDF/UA-2: một cây cấu trúc được gắn thẻ (ISO 32000-2 §14.7) và một ngôn ngữ tài liệu được khai báo (PDF/UA-2 §8.4.4). Công cụ báo cáo liệu các chỉ báo này có hiện diện hay không. Chỉ một trình kiểm tra PDF/UA mới xác định sự tuân thủ PDF/UA-2, không phải báo cáo của công cụ.

Đối chiếu thẻ → ISO 32000-2 §14

Các phát hiện về tiêu đề và bảng tương ứng với các phần tử cấu trúc logic trong cây cấu trúc ISO 32000-2 §14.7. Phát hiện về ngôn ngữ tương ứng với mục Lang §14.9. Công cụ báo cáo liệu các neo cấu trúc này có hiện diện hay không. Nó không xác thực mọi quy tắc thẻ §14; đó là việc của một trình kiểm tra.

Ánh xạ WCAG 2.2

Các phát hiện về độ tương phản và thứ tự đọc liên quan đến các tiêu chí thành công của WCAG, chẳng hạn như độ tương phản và trình tự có ý nghĩa. Công cụ báo cáo các giá trị chỉ báo, chẳng hạn như tỷ lệ tương phản đo được. Một tuyên bố tuân thủ WCAG cần một đánh giá WCAG đầy đủ; công cụ này không thực hiện cũng không khẳng định điều đó.

Tính khả dụng của transport

Transport	Khả dụng	Ghi chú
MCP (stdio)	Có (Pro)	Báo cáo là kết quả của công cụ.
REST	Có (Pro)	Báo cáo là phần thân phản hồi.
gRPC	Có (Pro)	Unary; báo cáo nằm trong thông điệp phản hồi.

Mức rủi ro HITL

check_accessibility ở mức An toàn (phân tích chỉ đọc) và không bao giờ chặn. Khi output_pdf xuất tệp thì Cần phê duyệt, còn chế độ base64 thì Xem xét (Mức rủi ro HITL).

Lớp bọc JSON của cổng xác nhận

Phân tích không bao giờ chặn:

{ "allowed": true }