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 | 設定標頭並輸出至瀏覽器 |