Skip to content

HTML 渲染器

HtmlRenderer 是 Artisan 套件的主要進入點。它負責啟動 Chrome、載入 HTML 內容,並透過 CDP 的 Page.printToPDF 指令將頁面渲染為 PDF。

建立實例

使用靜態工廠方法建立渲染器:

php
use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create();

你也可以指定 Chrome 執行檔的路徑:

php
$renderer = HtmlRenderer::create(
    chromePath: '/usr/bin/chromium-browser',
);

載入 HTML

loadHtml() — 從字串載入

直接傳入 HTML 字串,適合動態產生的內容:

php
$renderer->loadHtml('<h1>標題</h1><p>這是一段文字。</p>');

loadFile() — 從本地檔案載入

讀取磁碟上的 HTML 檔案:

php
$renderer->loadFile('/path/to/template.html');

loadUrl() — 從 URL 載入

直接渲染網頁,Chrome 會自動載入所有外部資源(CSS、JS、圖片、字型):

php
$renderer->loadUrl('https://example.com/invoice/123');

TIP

loadUrl() 支援 file://http://https:// 協定。如果需要攜帶認證,可在 RenderOptions 中設定自訂的 HTTP 標頭。

輸出方式

save() — 儲存到檔案

php
$renderer->loadHtml($html)->save('/tmp/output.pdf');

toString() — 取得 PDF 二進位字串

php
$pdfBinary = $renderer->loadHtml($html)->toString();

output() — 直接輸出到瀏覽器

設定適當的 HTTP 標頭並輸出 PDF 內容,適用於非框架的 PHP 應用程式:

php
$renderer->loadHtml($html)->output('invoice.pdf');

搭配 RenderOptions

透過 withOptions() 自訂渲染行為:

php
use Yeeefang\TcpdfNext\Artisan\RenderOptions;

$options = RenderOptions::create()
    ->landscape()
    ->margin(top: 20, right: 15, bottom: 20, left: 15)
    ->printBackground();

$renderer->withOptions($options)
    ->loadHtml($html)
    ->save('/tmp/report.pdf');

完整範例:發票渲染

php
use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;
use Yeeefang\TcpdfNext\Artisan\RenderOptions;

$html = <<<'HTML'
<!DOCTYPE html>
<html lang="zh-TW">
<head>
    <meta charset="UTF-8">
    <style>
        body { font-family: "Noto Sans TC", sans-serif; margin: 0; padding: 40px; }
        .header { display: flex; justify-content: space-between; align-items: center; }
        .logo { font-size: 24px; font-weight: bold; color: #ff6600; }
        table { width: 100%; border-collapse: collapse; margin-top: 30px; }
        th { background: #333; color: #fff; padding: 10px; text-align: left; }
        td { border-bottom: 1px solid #eee; padding: 10px; }
        .total { font-size: 18px; text-align: right; margin-top: 20px; }
    </style>
</head>
<body>
    <div class="header">
        <div class="logo">ACME Corp.</div>
        <div>發票編號:INV-2026-0042</div>
    </div>
    <table>
        <tr><th>品名</th><th>數量</th><th>單價</th><th>小計</th></tr>
        <tr><td>雲端主機 (月費)</td><td>12</td><td>NT$ 3,000</td><td>NT$ 36,000</td></tr>
        <tr><td>SSL 憑證</td><td>1</td><td>NT$ 2,500</td><td>NT$ 2,500</td></tr>
        <tr><td>技術支援方案</td><td>1</td><td>NT$ 15,000</td><td>NT$ 15,000</td></tr>
    </table>
    <div class="total"><strong>合計:NT$ 53,500</strong></div>
</body>
</html>
HTML;

$options = RenderOptions::create()
    ->pageSize('A4')
    ->margin(top: 10, right: 10, bottom: 10, left: 10)
    ->printBackground();

HtmlRenderer::create()
    ->withOptions($options)
    ->loadHtml($html)
    ->save('/tmp/invoice.pdf');

方法一覽

方法回傳值說明
create(?string $chromePath)static建立渲染器實例
loadHtml(string $html)static從 HTML 字串載入內容
loadFile(string $path)static從本地檔案載入 HTML
loadUrl(string $url)static從 URL 載入頁面
withOptions(RenderOptions $options)static設定渲染選項
save(string $path)void將 PDF 儲存至指定路徑
toString()string取得 PDF 的二進位字串
output(string $filename)void設定標頭並輸出至瀏覽器

以 LGPL-3.0-or-later 授權釋出。