基本用法

本页将逐步介绍 TCPDF-Next 文档的基本构成要素：创建文档、新增页面、输出文字、嵌入图片，以及生成最终的 PDF。

创建文档

Document::create() 静态工厂方法是创建 PDF 的唯一入口点：

use Yeeefang\TcpdfNext\Core\Document;

$doc = Document::create();

所有参数均为可选——默认会创建一份以毫米为单位的 A4 纵向文档。完整参数列表请参阅配置页面。

新增页面

文档创建后不含任何页面。在输出内容之前，至少需调用一次 addPage()：

use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

// 使用文档默认值新增页面
$doc->addPage();

// 新增横向 Letter 页面，搭配自定义边距
$doc->addPage(
    pageSize: PageSize::Letter,
    orientation: Orientation::Landscape,
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

页面尺寸

PageSize 是一个枚举，涵盖所有标准 ISO 与北美尺寸：

枚举值	尺寸
PageSize::A3	297 x 420 mm
PageSize::A4	210 x 297 mm
PageSize::A5	148 x 210 mm
PageSize::Letter	215.9 x 279.4 mm
PageSize::Legal	215.9 x 355.6 mm

亦可通过 PageSize::custom(width, height) 指定自定义尺寸。

设置字体

TCPDF-Next 内建标准 PDF 基本字体，以及支持 Unicode 的 DejaVu Sans 字体家族。

// 内建基本字体
$doc->setFont('Helvetica', size: 12);

// 内建 Unicode 字体
$doc->setFont('DejaVuSans', size: 10);

// 粗体 / 斜体变体
$doc->setFont('Helvetica', style: FontStyle::Bold, size: 14);
$doc->setFont('Helvetica', style: FontStyle::BoldItalic, size: 14);

自定义字体

注册 TrueType 或 OpenType 字体后，即可通过别名使用：

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    $config->addFont('/fonts/Inter-Regular.ttf', alias: 'Inter');
});

$doc->setFont('Inter', size: 11);

文字输出

TCPDF-Next 提供四种方法将文字放置到页面上，各自适用于不同的排版需求。

cell()

输出单行单元格。适合标签、表格单元格与短文字：

$doc->cell(
    width: 80,
    height: 10,
    text: 'Invoice #1042',
    border: true,
    align: Align::Center,
);

multiCell()

输出会自动换行的文字区块，依指定宽度排列。每次调用后光标会自动往下移动：

$doc->multiCell(
    width: 0,        // 0 = 使用全部可用宽度
    height: 7,
    text: 'This is a longer paragraph that will wrap across multiple lines '
        . 'based on the available width and the current font size.',
);

text()

在绝对坐标 (x, y) 位置放置文字。不会移动光标：

$doc->text(x: 105, y: 20, text: 'Centered Title', align: Align::Center);

write()

在当前光标位置写入行内文字。支持超链接，适合在段落中自然串接：

$doc->write(height: 5, text: 'Visit the ');
$doc->write(height: 5, text: 'TCPDF-Next docs', link: 'https://tcpdf-next.dev');
$doc->write(height: 5, text: ' for more information.');

图片

从文件路径加载

$doc->imageFromFile(
    path: '/images/logo.png',
    x: 15,
    y: 15,
    width: 40,
);

从字符串或资源加载

$binary = file_get_contents('https://example.com/photo.jpg');

$doc->image(
    data: $binary,
    x: 15,
    y: 60,
    width: 50,
    type: 'JPEG',
);

支持格式：PNG、JPEG、GIF、SVG、WebP。

保存与输出

TCPDF-Next 提供多种方式获取最终的 PDF。

保存至磁盘

$doc->save('/reports/invoice-1042.pdf');

发送至浏览器

use Yeeefang\TcpdfNext\Core\Enums\OutputDestination;

// 在浏览器中直接显示（Content-Disposition: inline）
$doc->output('invoice.pdf', OutputDestination::Inline);

// 强制下载（Content-Disposition: attachment）
$doc->output('invoice.pdf', OutputDestination::Download);

获取原始 PDF 数据

$pdfBytes = $doc->getPdfData();

// 可搭配 PSR-7 响应、队列任务、S3 上传等使用

OutputDestination 枚举

值	行为
OutputDestination::Inline	发送至浏览器，以内嵌方式查看
OutputDestination::Download	发送至浏览器，以文件下载方式处理
OutputDestination::File	写入指定文件路径（save() 内部使用）
OutputDestination::String	返回原始二进制字符串（getPdfData() 内部使用）

链式 API

大多数 setter 方法均返回 $this，支持流畅的链式调用风格：

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\Enums\Align;
use Yeeefang\TcpdfNext\Core\Enums\FontStyle;

$pdf = Document::create()
    ->setTitle('Monthly Report')
    ->setAuthor('Acme Corp')
    ->addPage(pageSize: PageSize::A4, orientation: Orientation::Portrait)
    ->setFont('Helvetica', style: FontStyle::Bold, size: 18)
    ->cell(width: 0, height: 15, text: 'Monthly Report — February 2026', align: Align::Center)
    ->ln()
    ->setFont('Helvetica', size: 11)
    ->multiCell(width: 0, height: 6, text: 'This report summarises key metrics...')
    ->save('/reports/monthly.pdf');

完整示例

将以上所有概念整合在一起：

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\Align;
use Yeeefang\TcpdfNext\Core\Enums\FontStyle;
use Yeeefang\TcpdfNext\Core\Enums\OutputDestination;

$doc = Document::create();

$doc->setTitle('Hello World');
$doc->setAuthor('TCPDF-Next');

$doc->addPage();

// 标题
$doc->setFont('Helvetica', style: FontStyle::Bold, size: 20);
$doc->cell(width: 0, height: 15, text: 'Hello, TCPDF-Next!', align: Align::Center);
$doc->ln(20);

// 正文
$doc->setFont('DejaVuSans', size: 12);
$doc->multiCell(
    width: 0,
    height: 7,
    text: 'TCPDF-Next is a modern, type-safe PDF generation library for PHP 8.5+. '
        . 'It provides a clean API, strict static analysis, and comprehensive Unicode support.',
);

// 商标图片
$doc->imageFromFile(path: __DIR__ . '/logo.png', x: 15, y: 80, width: 30);

// 输出
$doc->output('hello.pdf', OutputDestination::Download);

下一步

• 配置 — 微调默认值、加密与无障碍配置。
• 配置 — 了解 Core、Pro 与 Artisan 的模块关系。
• 常见问题 — 常见疑问与解答。