Nhúng hình ảnh bằng NextPDF Connect

Tổng quan nhanh

Nhúng hình ảnh vào tệp Portable Document Format (PDF) bằng NextPDF Connect. Nguồn có thể là đường dẫn tệp mà máy chủ đọc được hoặc một data URI base64 nội tuyến. Bạn dùng create_pdf, add_image và output_pdf — tất cả đều là công cụ Core. NextPDF vẽ hình ảnh dưới dạng một image XObject, được tô bằng toán tử Do (ISO 32000-2 §8.9).

Cài đặt

composer require nextpdf/server

Hãy liên kết một transport. NextPDF hỗ trợ các định dạng raster PNG, JPEG và GIF.

Tổng quan khái niệm

add_image nhận một source và phân giải nó theo thứ tự cố định này:

Data URI — một chuỗi bắt đầu bằng data:. NextPDF giải mã loại Multipurpose Internet Mail Extensions (MIME) và payload base64 thành một tệp tạm, nhúng tệp đó, rồi xóa tệp tạm.
Base64 thô — NextPDF giải mã một chuỗi base64 dài và xử lý nó như PNG.
Đường dẫn tệp — NextPDF xử lý mọi giá trị khác như một đường dẫn hệ thống tệp mà tiến trình máy chủ phải có thể đọc được.

Hình ảnh được đặt tại tọa độ x/y, theo đơn vị người dùng (mặc định là milimét). Nếu chỉ truyền width, NextPDF sẽ tính chiều cao để giữ nguyên tỷ lệ khung hình. Nếu truyền cả width và height, NextPDF co giãn hình ảnh đến đúng các kích thước đó. Đối tượng được nhúng là một external object được tô vào nội dung trang (ISO 32000-2 §8.8).

Bề mặt API

Công cụ	Vai trò	Cấp độ rủi ro
`create_pdf`	Mở phiên làm việc	An toàn
`add_image`	Nhúng một hình ảnh từ đường dẫn hoặc data URI	Thận trọng
`output_pdf`	Kết xuất và trả về PDF	Cần phê duyệt / Xem xét (base64)

Trang danh mục công cụ là tham chiếu chuẩn. Các công cụ có sẵn phụ thuộc vào gói bạn đã cài đặt.

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

create_pdf (A4 dọc, tiêu đề) → document_id.
add_image với source là một đường dẫn tuyệt đối, x, y, width.
add_image với source là một URI data:image/png;base64,... cùng width và height tường minh.
output_pdf → base64.

Mẫu mã — Production

Dùng data URI cho hình ảnh mà host tạo ra trong bộ nhớ, chẳng hạn như biểu đồ được kết xuất hoặc ảnh chụp màn hình. Dùng đường dẫn tệp cho tài nguyên đã tồn tại trên máy chủ. Luôn dùng đường dẫn tuyệt đối. Đường dẫn tương đối được phân giải dựa trên thư mục làm việc của máy chủ, thường không phải thư mục của host. Trước khi tiếp tục, hãy xác nhận rằng phản hồi của add_image cho biết hình ảnh nằm trên trang mong đợi.

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

Không tìm thấy đường dẫn. Một đường dẫn tệp không tồn tại sẽ trả về lỗi không tìm thấy hình ảnh.
Định dạng không được hỗ trợ. NextPDF từ chối SVG, BMP và WebP. Hãy chuyển đổi hình ảnh trước.
Base64 / data URI sai định dạng. Payload không hợp lệ, hoặc data URI thiếu dấu phẩy phân tách, sẽ trả về lỗi giải mã.
Hình ảnh quá khổ. Một hình ảnh lớn hơn trang sẽ bị cắt ở mép, chứ không bị từ chối. Hãy tính width/height dựa trên trang sau khi trừ lề (A4 dọc là 210×297 mm).

Hiệu năng

Kích thước đầu ra tỷ lệ thuận với nội dung hình ảnh. Hai hình ảnh nhỏ thường nằm trong khoảng 10–50 KB. Ngân sách nhúng hình ảnh rộng hơn ngân sách chỉ có văn bản. Trang này dùng hồ sơ structural.

Lưu ý bảo mật

Chế độ đường dẫn tệp đọc từ hệ thống tệp của máy chủ bằng quyền của tiến trình máy chủ. Hãy giới hạn những đường dẫn mà host được phép truyền vào. Không cho phép bên gọi không đáng tin cậy trỏ source tới các tệp máy chủ tùy ý. Chế độ base64 mang byte theo dạng nội tuyến, nên tránh được việc lộ đường dẫn máy chủ.

Mức độ tuân thủ

Phát biểu	Đặc tả	Điều khoản	reference_id
Một hình ảnh là một image XObject được tô bằng `Do`.	ISO 32000-2	§8.9
Hình ảnh là các external object được tô vào nội dung trang.	ISO 32000-2	§8.8

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

Không áp dụng — tất cả công cụ đều thuộc Core.

Khả dụng theo transport

Transport	Khả dụng	Ghi chú
MCP (stdio)	Có	Các payload base64 lớn làm tăng kích thước khung stdio.
REST	Có	Hãy ưu tiên multipart hoặc một đường dẫn máy chủ cho các tài nguyên lớn.
gRPC	Có	Unary; giới hạn kích thước thông điệp áp dụng cho base64 nội tuyến.

Cấp độ rủi ro HITL

create_pdf là An toàn, add_image là Thận trọng, và output_pdf là Cần phê duyệt — được hạ xuống mức Xem xét ở chế độ base64. Thao tác đọc ở chế độ đường dẫn diễn ra phía máy chủ và không được kiểm soát riêng, vì vậy hãy giới hạn thao tác này ở lớp chính sách (cấp độ rủi ro HITL).

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

Đầu ra base64 ở đây:

{ "allowed": true }