Ảnh SVG trong fpdf2: Giữ đường dẫn trong PDF Python

Dùng pdf.image("logo.svg", x=20, y=20, w=60) để đặt SVG vào tài liệu fpdf2. Hình học SVG được hỗ trợ trở thành các đường dẫn vẽ trong PDF. Bạn không cần kết xuất logo thành PNG trước. Tài liệu SVG chính thức mô tả cách trực tiếp này cùng các giới hạn.

Nếu bạn chưa quen định dạng, hướng dẫn tệp SVG giải thích đường dẫn và vùng chứa ảnh. Nhập thành công vẫn cần kiểm tra. Tệp có thể chứa pixel nhúng, phụ thuộc vào các tính năng mà công cụ nhập không tái tạo, hoặc có khoảng trống quanh hình. Hướng dẫn này tạo một logo nhỏ tự thiết kế, đặt nó ở kích thước chỉ định rõ và kiểm tra PDF kết quả. Giữ bản gốc vector sẵn có; khôi phục hình từ PNG hoặc JPG là một bước riêng trước đó.

Bắt đầu với SVG đã biết và phiên bản fpdf2 cố định

Chúng tôi chạy ví dụ với Python 3.12 và fpdf2 2.8.8. Đây là phiên bản đã kiểm tra, không phải lời đảm bảo mọi bản phát hành sau đều hoạt động giống hệt. Trang PyPI chính thức của gói mô tả cách cài với tên phân phối fpdf2; tên import trong Python là fpdf.

Dùng môi trường mới để ví dụ không phụ thuộc vào các gói của dự án khác:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "fpdf2==2.8.8"

Trên Windows, thay vào đó hãy kích hoạt môi trường bằng .venv\Scripts\activate. Lưu biểu tượng hình chữ nhật tự tạo này thành logo.svg:

<svg xmlns="http://www.w3.org/2000/svg"
     width="120" height="80" viewBox="0 0 120 80">
  <path fill="#137d89" fill-rule="evenodd"
        d="M10 10H110V70H10Z M30 25H90V55H30Z"/>
</svg>

Có hai đường dẫn con đóng. Hình chữ nhật ngoài được tô màu, còn hình chữ nhật trong trở thành lỗ nhờ quy tắc tô evenodd. Không có phông chữ, ảnh hay hiệu ứng, nên phép thử đầu dễ chẩn đoán.

Lưu đoạn sau thành place_logo.py bên cạnh SVG:

from pathlib import Path
from fpdf import FPDF
 
folder = Path(__file__).resolve().parent
pdf = FPDF(unit="mm")
pdf.add_page()
pdf.image(str(folder / "logo.svg"), x=20, y=20, w=60)
pdf.output(str(folder / "logo.pdf"))

Chạy python place_logo.py. Mở logo.pdf và kiểm tra khung chữ nhật xanh cổ vịt gần góc trên bên trái, với phần trang nhìn xuyên qua tâm.

Phân biệt khung vẽ SVG với phần logo được tô

Khung vẽ nguồn có tỷ lệ 3:2: rộng 120 đơn vị và cao 80 đơn vị. Với w=60, ví dụ này chiếm khung vẽ 60 × 40 mm. Phần hình bắt đầu cách mép khung 10 đơn vị nguồn, nên hình chữ nhật ngoài được tô có kích thước 50 × 30 mm, bắt đầu tại 25, 25 mm trên trang. Đây là các phép tính từ tọa độ và tỷ lệ của mẫu thử này.

Lề đó giải thích vì sao đo phần hình có màu cho kết quả khác với đo khung đặt ảnh. Nếu logo của khách hàng trông quá nhỏ, hãy kiểm tra lề trong nguồn trước khi tăng chiều rộng trên PDF.

Hướng dẫn ảnh của fpdf2 giải thích cách xử lý kích thước và tùy chọn giữ tỷ lệ trong một hộp chỉ định. Với ví dụ đầu này, chỉ đặt chiều rộng. Nếu sau đó cung cấp cả hai kích thước, hãy chủ động kiểm tra cách vừa khung bạn muốn thay vì cho rằng mọi nguồn có cùng tỷ lệ.

Xác minh PDF đã lưu chứa đường dẫn

Bản xem trước PDF cho thấy diện mạo, nhưng ảnh cũng có thể trông sắc nét ở mức phóng to vừa phải. Hãy kiểm tra cả tệp. Chúng tôi kiểm tra ví dụ riêng biệt này bằng pypdf 6.1.1:

python -m pip install "pypdf==6.1.1"

from pathlib import Path
from pypdf import PdfReader
 
folder = Path(__file__).resolve().parent
page = PdfReader(folder / "logo.pdf").pages[0]
print("Page images:", len(page.images))
print(page.get_contents().get_data().decode("latin-1"))

Đầu ra của chúng tôi báo không có ảnh trên trang. Nội dung giải mã chứa các đường bao chữ nhật được thể hiện qua thao tác di chuyển, vẽ đoạn thẳng và đóng đường dẫn, theo sau bởi f*, thao tác tô chẵn-lẻ. Cùng với lỗ được hiển thị, điều đó hỗ trợ kết luận rằng mẫu thử không có ảnh này vẫn là hình học vẽ trong PDF đã lưu.

Đừng áp dụng kết luận đó cho đầu vào khác mà không kiểm tra. Báo cáo có thể chứa ảnh chụp ở nơi khác một cách hợp lý; bản thân SVG cũng có thể chứa ảnh. Cách chẩn đoán raster nhúng giúp phân biệt logo dựa trên đường dẫn với bitmap được bọc trong mã SVG. PDF phức tạp hơn cũng có thể đặt nội dung vẽ trong các đối tượng được tham chiếu, nên tập lệnh ngắn trên là điểm bắt đầu cho mẫu thử riêng biệt này, không phải phép kiểm định PDF toàn diện.

Chẩn đoán phần hình bị thiếu bằng bản phát hành đã cài

Bắt đầu bằng cách chạy biểu tượng nhỏ phía trên. Nếu nó hoạt động còn logo thực tế thất bại, bạn đã thu hẹp vấn đề về phần hình nguồn hoặc những tính năng nó dùng. Giữ bản gốc và đơn giản hóa một bản sao, mỗi lần một tính năng.

Cần thận trọng với các câu trả lời cũ ở đây. Phép thử riêng của chúng tôi trên 2.8.8 chứa phần tử <text> đơn giản tạo ra văn bản HELLO có thể trích xuất, và hình chữ nhật có gradient tuyến tính cơ bản cũng xuất thành công. Những phép kiểm tra hẹp này không xác nhận khả năng tương thích đầy đủ với văn bản SVG, phông chữ, CSS hay gradient. Tuy nhiên, chúng cho thấy vì sao nhận định cũ rằng mọi văn bản SVG hoặc mọi gradient đều không được hỗ trợ có thể khiến bạn raster hóa không cần thiết.

Danh sách tính năng SVG hiện tại vẫn nêu các giới hạn như marker, pattern, chữ trên đường dẫn và CSS phức tạp hoặc bên ngoài. Giữ cảnh báo của công cụ nhập hiển thị trong lúc chẩn đoán và đối chiếu trang đã lưu với nguồn. Chỉ nhật ký không có lỗi không chứng minh mọi tính năng thị giác còn nguyên.

Dùng raster dự phòng khi kết quả cần điều đó

Nếu hiệu ứng không thể tái tạo trong quy trình đã chọn, hãy quyết định việc giữ diện mạo có quan trọng hơn giữ hình học hay không. PNG đã kết xuất có thể phù hợp cho phần đó của tài liệu. Kiểm tra ở kích thước vật lý cuối cùng và mô tả đầu ra chính xác; nhúng bản kết xuất raster không giữ các đường dẫn gốc.

Với logo thương hiệu, chữ dạng đường bao đã duyệt hoặc bản xuất vector đơn giản hơn có thể là lựa chọn tốt hơn. Với văn bản tài liệu cần chỉnh sửa, hãy giữ việc xử lý phông chữ và văn bản trong quy trình tài liệu. Dò nét ảnh chụp màn hình của một câu không khôi phục kiểu chữ hay biến nó thành văn bản có thể chọn.

Nếu mã PDF hiện có dùng thư viện Python khác, quy trình SVG trong ReportLab có các bước kiểm tra nhập và kích thước riêng. Đổi thư viện là một quyết định triển khai riêng, nên hãy thử tính năng thực sự gây lỗi trước khi xây dựng lại tài liệu.

Chuẩn bị hình chỉ có raster trước bước PDF

Khi logo chỉ còn PNG hoặc JPG, công cụ vector hóa logo của PerfectVector có thể chuẩn bị bản SVG ứng viên trước khi bạn nhập bằng fpdf2. Đối chiếu đường bao, các lỗ nhỏ và vùng màu với nguồn, rồi đưa bản ứng viên qua cùng các phép kiểm tra vị trí và PDF.

Dùng vector gốc nếu còn. Chữ thương hiệu cần chính xác có thể phải gõ lại hoặc sửa thủ công; hướng dẫn vector hóa logo giải thích lựa chọn đó. Biểu tượng trong bài này là SVG tự tạo bằng tay, không phải kết quả chuyển đổi PerfectVector đã đo. PerfectVector chuẩn bị phần hình, còn fpdf2 kiểm soát vị trí của nó trong PDF.

Câu hỏi thường gặp

fpdf2 có thể chèn SVG trực tiếp không? Có. Truyền tệp SVG vào phương thức image và đặt vị trí cùng kích thước. Hình học được hỗ trợ có thể trở thành đường dẫn PDF, nhưng hãy kiểm tra tệp xuất và diện mạo với phần hình của chính bạn.

fpdf2 có hỗ trợ văn bản SVG không? Phép thử văn bản cơ bản của chúng tôi hoạt động với fpdf2 2.8.8. Điều đó không đảm bảo mọi phông chữ, tính năng bố cục hoặc cấu trúc chữ trên đường dẫn. Kiểm tra bản phát hành đã cài và thử phần chữ tài liệu thực sự dùng.

Vì sao ảnh 60 mm trông hẹp hơn 60 mm? Kích thước yêu cầu áp dụng cho khung đặt ảnh. Lề trống trong SVG vẫn là một phần của khung đó, nên hình được tô có thể hẹp hơn.

Tôi có nên chuyển logo PNG thành SVG trước khi thêm không? Chỉ khi bạn cần đường dẫn chỉnh sửa được và hình phù hợp với dò nét. Giữ ảnh chụp ở dạng raster, và dùng logo vector gốc khi có. Kiểm tra bản ứng viên đã dò nét trước khi chèn.

Nguồn tham khảo

1. fpdf2 — SVG — Mô tả chèn SVG trực tiếp, hỗ trợ tính năng và nhật ký cảnh báo.
2. fpdf2 — Ảnh — Giải thích vị trí ảnh, kích thước và cách vừa khung theo tỷ lệ.
3. fpdf2 — Gói PyPI — Xác định tên phân phối cài được và quy ước import trong Python.

Bạn chỉ có logo raster? Chuẩn bị bản SVG ứng viên bằng PerfectVector, kiểm tra đường bao và các lỗ, rồi đặt ở kích thước yêu cầu bằng fpdf2 và kiểm tra PDF đã lưu.