Artisan 快速上手

概览

将 ChromeRendererConfig 挂载到一份 NextPDF 文档上，调用 writeHtmlChrome()，再保存即可。Chrome 负责渲染 HTML，桥接层（bridge）将结果导入为 Form XObject，文字仍可选取。

概念说明

writeHtmlChrome() 是 NextPDF 核心 Document 上的方法，由 HasTextOutput 这个 concern 提供。该方法会校验输入、resolve（解析）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/