Artisan 快速上手

概覽

將 ChromeRendererConfig 設定到 NextPDF 文件，呼叫 writeHtmlChrome()，再儲存即可。Chrome 會負責繪製 HTML，橋接層（bridge）則將結果匯入為 Form XObject，文字仍會保持可選取。

概念說明

writeHtmlChrome() 是 NextPDF 核心 Document 的方法，由 HasTextOutput 這個 concern 提供。這個方法會驗證輸入、解析出 Artisan renderer（渲染器）、將 HTML 送交 Chrome、剖析回傳的 PDF，並把第 0 頁以 Form XObject 形式嵌入目前的游標位置。公開簽章為 writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static，並已對照 nextpdf/coresrc/Core/Concerns/HasTextOutput.php 驗證。

程式碼範例 — 快速上手

<?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');

這就是套件 README.md 示範的標準流程。Chrome 負責處理 flex 版面配置。輸出中的數字仍是可選取文字，因為該頁是以 Form XObject 形式嵌入，而非點陣影像。

自訂頁面尺寸

以 PDF 點（point）為單位明確傳入寬度與高度，即可套用固定頁面尺寸（此處以 A4 為例）：

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

兩者都提供時，Chrome 會精確依該紙張尺寸列印。若省略高度（或傳入 null），橋接層會自動依量測到的內容高度調整，並加入少量重排（reflow）安全緩衝。若想了解這道緩衝為何存在，以及何時該覆寫它，請參閱 /integrations/artisan/production-usage/ 一節。

你會得到什麼

屬性	行為
文字	可選取且可搜尋（向量文字，不會點陣化）
CSS	由 Chrome 負責排版 — flexbox、grid、複雜選擇器，以及透過 data URI 載入的網頁字型
網路	不會抓取任何子資源；遠端 URL 不會載入（參見 /integrations/artisan/security-and-operations/ 頁面）
頁面	只會匯入 Chrome 輸出的第 0 頁

邊界情況與陷阱

空 HTML 不會執行任何動作。 writeHtmlChrome('') 會原封不動地回傳文件（已於 HasTextOutput::writeHtmlChrome 驗證）。
尚無頁面時。 若文件還沒有任何頁面，writeHtmlChrome() 會在繪製前先新增一頁。
遠端資產不會載入。 <img src="https://..."> 會呈現為空白。請把資產以 data: URI 形式內嵌。這是網路隔離的設計取向，並非錯誤。請參閱 /integrations/artisan/security-and-operations/.
缺少橋接層時。 若未安裝 nextpdf/artisan，核心會拋出版面配置例外，而不是致命錯誤。

效能

第一次呼叫會包含 Chrome 啟動與版面配置成本。後續呼叫則會透過 BrowserPool 重複使用仍在運作的 Chrome 行程。若用於批次處理或長時間執行的 worker，請閱讀 /integrations/artisan/production-usage/ 頁面上的生命週期與資源指引。

安全性須知

本快速上手使用的是可信、寫死的 HTML。在把任何受使用者影響的 HTML 傳給 writeHtmlChrome() 之前，請先閱讀 /integrations/artisan/security-and-operations/. 橋接層雖然隔離了網路存取，但 HTML 繪製本身仍有威脅面。

商業情境

本流程會使用開源橋接層，從 HTML 產生 PDF。若要在同一份文件中嵌入符合規範的電子發票 XML，Premium Pro 方案會提供對應的嵌入器（embedder）。即使未安裝 Premium，開源流程也不受影響。

另請參閱

安裝：/integrations/artisan/install/
組態：/integrations/artisan/configuration/
生產環境使用：/integrations/artisan/production-usage/
疑難排解：/integrations/artisan/troubleshooting/
安全性與維運：/integrations/artisan/security-and-operations/