Bắt đầu nhanh với Artisan

Tổng quan nhanh

Gắn một ChromeRendererConfig vào tài liệu NextPDF, gọi writeHtmlChrome(), rồi lưu tệp Portable Document Format (PDF). Chrome kết xuất phần Hypertext Markup Language (HTML). Cầu nối nhập kết quả dưới dạng Form XObject, nên văn bản vẫn có thể chọn được.

Tổng quan khái niệm

writeHtmlChrome() là một phương thức trên Document lõi của NextPDF. Concern HasTextOutput cung cấp phương thức này. Nó xác thực dữ liệu đầu vào và phân giải bộ kết xuất Artisan. Sau đó, phương thức gửi HTML đến Chrome, phân tích cú pháp PDF trả về, rồi nhúng trang 0 dưới dạng Form XObject tại vị trí con trỏ hiện tại. Chữ ký công khai là writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static — đã được xác minh dựa trên nextpdf/coresrc/Core/Concerns/HasTextOutput.php.

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

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

require __DIR__ . '/vendor/autoload.php';

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();

$doc->writeHtmlChrome('
    <div style="display: flex; gap: 20px; font-family: sans-serif;">
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Revenue</h2><p style="font-size: 2em; color: #2563eb;">$124,500</p>
        </div>
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Orders</h2><p style="font-size: 2em; color: #16a34a;">1,847</p>
        </div>
    </div>
');

$doc->save('/tmp/report.pdf');

Đây là luồng chuẩn lấy từ README.md của gói. Chrome xử lý bố cục flex của Cascading Style Sheets (CSS). Trong kết quả, các con số vẫn là văn bản có thể chọn được vì trang được nhúng dưới dạng Form XObject, không phải ảnh raster.

Kích thước trang tùy chỉnh

Truyền chiều rộng và chiều cao cụ thể theo điểm PDF để vừa với một trang cố định (ví dụ A4):

$doc->writeHtmlChrome($html, width: 595.28, height: 841.89);

Khi bạn cung cấp cả hai giá trị, Chrome sẽ in đúng theo khổ giấy đó. Khi bạn bỏ qua chiều cao (hoặc truyền null), cầu nối sẽ khớp với chiều cao nội dung đo được và thêm một vùng đệm an toàn nhỏ cho reflow. Xem /integrations/artisan/production-usage/ để biết vì sao vùng đệm này tồn tại và khi nào nên ghi đè.

Bạn nhận được gì

Thuộc tính	Hành vi
Văn bản	Có thể chọn và tìm kiếm (văn bản vector, không bị rasterize)
Cascading Style Sheets (CSS)	Bố cục của Chrome: flexbox, grid, các bộ chọn phức tạp, phông chữ web thông qua giá trị data Uniform Resource Identifier (URI)
Mạng	Không tải tài nguyên con; các Uniform Resource Locator (URL) từ xa không được tải (xem /integrations/artisan/security-and-operations/)
Trang	Trang 0 trong kết quả của Chrome được nhập vào

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

HTML rỗng không làm gì cả. writeHtmlChrome('') trả về tài liệu không đổi (đã được xác minh trong HasTextOutput::writeHtmlChrome).
Chưa có trang nào. Nếu tài liệu chưa có trang nào, writeHtmlChrome() sẽ thêm một trang trước khi kết xuất.
Tài nguyên từ xa không được tải. <img src="https://..."> kết xuất thành nội dung rỗng. Nhúng trực tiếp tài nguyên dưới dạng URI data:. Đây là cơ chế cô lập mạng, không phải lỗi. Xem /integrations/artisan/security-and-operations/.
Thiếu cầu nối. Nếu nextpdf/artisan chưa được cài đặt, core sẽ phát sinh một ngoại lệ bố cục thay vì lỗi nghiêm trọng.

Hiệu năng

Lần gọi đầu tiên bao gồm thời gian khởi động Chrome và dựng bố cục. Các lần gọi sau tái sử dụng tiến trình Chrome đang chạy thông qua BrowserPool. Với tác vụ hàng loạt hoặc worker chạy lâu, hãy đọc hướng dẫn về vòng đời và tài nguyên trên trang /integrations/artisan/production-usage/.

Lưu ý về bảo mật

Phần bắt đầu nhanh dùng HTML đáng tin cậy, được viết cố định trong mã. Trước khi truyền bất kỳ HTML nào chịu ảnh hưởng từ người dùng vào writeHtmlChrome(), hãy đọc /integrations/artisan/security-and-operations/. Cầu nối cô lập quyền truy cập mạng, nhưng việc kết xuất HTML vẫn có bề mặt rủi ro.

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

Cách này tạo một PDF từ HTML bằng cầu nối nguồn mở. Để nhúng một tệp Extensible Markup Language (XML) hóa đơn điện tử tuân thủ chuẩn vào cùng tài liệu đó, gói Premium Pro cung cấp một bộ nhúng. Luồng nguồn mở không bị ảnh hưởng khi không có Premium.

Xem thêm

/integrations/artisan/install/
/integrations/artisan/configuration/
/integrations/artisan/production-usage/
/integrations/artisan/troubleshooting/
/integrations/artisan/security-and-operations/