Artisan 包总览

Artisan · LGPL-3.0

yeeefang/tcpdf-nextartisan 通过 Chrome DevTools Protocol（CDP）实现高保真的 HTML 转 PDF 渲染。它能忠实地将任何浏览器可呈现的 HTML/CSS 转换为 PDF，包括 Flexbox、Grid、Web Fonts、CSS 变量等完整的 CSS3 功能。

何时使用 Artisan vs Core

面向	Core（内置 HTML 解析器）	Artisan（Chrome CDP）
CSS 支持	基本子集（表格、行内样式）	完整 CSS3（Flexbox、Grid、动画）
Web Fonts	需手动嵌入 TrueType	自动加载 Google Fonts 等
JavaScript	不支持	完整支持（图表、动态内容）
外部依赖	无	需要 Chrome / Chromium
渲染速度	极快（毫秒级）	较慢（需启动浏览器进程）
适用场景	报表、发票、简单版面	复杂版面、品牌设计、仪表板

经验法则： 如果你的 HTML 在浏览器中看起来完美、但用 Core 渲染不理想，就改用 Artisan。

安装

composer require yeeefang/tcpdf-nextartisan

Chrome / Chromium 安装

Artisan 需要可执行的 Chrome 或 Chromium。在服务器环境中，建议安装无头 Chromium：

# Ubuntu / Debian
sudo apt-get install -y chromium-browser

# Alpine（Docker 常用）
apk add --no-cache chromium

# macOS
brew install --cask chromium

快速开始

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

HtmlRenderer::create()
    ->loadHtml('<h1>Hello Artisan</h1><p>完整 CSS3 支持。</p>')
    ->save('/tmp/output.pdf');

包内容

Artisan 包包含以下 7 个核心类：

类	说明
HtmlRenderer	主要入口点 — 加载 HTML 并渲染为 PDF
RenderOptions	页面设置 — 尺寸、边界、页首页尾、缩放
PdfMerger	将多份 PDF 合并为单一文件
StyleInjector	在渲染前注入额外的 CSS 样式
ScreenshotCapture	将 HTML 渲染为 PNG / JPEG 截图
ChromeProcess	管理 Chrome 子进程的生命周期
CdpConnection	底层 CDP WebSocket 连接管理

下一步

1. HTML 渲染器 — 从字符串、文件或 URL 加载 HTML 并渲染为 PDF。
2. 渲染选项 — 设置页面尺寸、边界、页首页尾与打印参数。
3. 高级功能 — PDF 合并、CSS 注入、截图与错误处理。
4. Docker 设置 — 在容器中执行 Artisan 与 Chrome 的最佳实践。