配置

TCPDF-Next 提供合理的默认值，开箱即可使用。每项配置都可以在创建文档时覆写，也可以之后通过链式 API 的 setter 方法修改。

文档默认值

调用 Document::create() 时，若未另行指定，将应用以下默认值：

配置	默认值	说明
页面尺寸	PageSize::A4	ISO A4（210 x 297 mm）
方向	Orientation::Portrait	纵向
单位	Unit::Millimeter	所有尺寸以毫米为单位
左边距	15 mm	页面左边距
上边距	27 mm	页面上边距
右边距	15 mm	页面右边距
下边距	25 mm	页面下边距
自动换页	true	接近下边距时自动新增页面
字体	Helvetica, 12 pt	默认字体与字号

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\Enums\Unit;

$doc = Document::create(
    pageSize: PageSize::Letter,
    orientation: Orientation::Landscape,
    unit: Unit::Inch,
);

边距（Margins）

边距可以设置为全局值，也可以对单独页面覆写：

use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

// 全局边距
$doc->setMargins(new Margin(
    left: 20,
    top: 30,
    right: 20,
    bottom: 25,
));

// 针对特定页面覆写
$doc->addPage(
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

字体路径与目录

TCPDF-Next 会从可配置的目录清单中搜索字体文件。内建字体（Helvetica、Courier、Times、Symbol、ZapfDingbats）始终可用。若需使用自定义或 Unicode 字体，请注册额外的路径：

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    // 新增包含 .ttf / .otf 文件的目录
    $config->addDirectory('/path/to/my/fonts');

    // 新增单一字体文件并指定别名
    $config->addFont('/path/to/MyFont-Regular.ttf', alias: 'MyFont');
});

TIP

字体文件默认以子集化方式嵌入，可有效缩小 PDF 文件大小。如有需要，也可以针对单独字体启用完整嵌入。

加密配置

PDF 加密通过 EncryptionConfig 值对象进行配置：

use Yeeefang\TcpdfNext\Core\Config\EncryptionConfig;
use Yeeefang\TcpdfNext\Core\Enums\EncryptionLevel;
use Yeeefang\TcpdfNext\Core\Enums\Permission;

$doc->setEncryption(new EncryptionConfig(
    level: EncryptionLevel::AES256,
    userPassword: 'reader-pass',
    ownerPassword: 'admin-pass',
    permissions: [
        Permission::Print,
        Permission::Copy,
    ],
));

等级	说明
EncryptionLevel::RC4_40	旧版 40 位 RC4（不建议使用）
EncryptionLevel::RC4_128	128 位 RC4
EncryptionLevel::AES128	128 位 AES
EncryptionLevel::AES256	256 位 AES（建议使用）

标记式 PDF 配置

标记式（无障碍）PDF 可提升屏幕阅读器的支持度，且为 PDF/UA 标准所要求。全局启用标记功能：

$doc->enableTaggedPdf();

// 选择性设置文档语言，以利无障碍支持
$doc->setLanguage('zh-CN');

启用标记式 PDF 模式后，文字与表格 API 会自动生成结构标签（<P>、<H1>–<H6>、<Table> 等）。

确定性模式（Deterministic Mode）

默认情况下，PDF 会包含时间戳与唯一标识符，使每次输出的内容都不同。确定性模式会移除这些信息，让相同输入产生完全一致的字节输出——适用于快照测试与可复现的构建流程：

$doc->enableDeterministicMode();

WARNING

确定性模式会移除创建日期、修改日期与唯一文件标识符。若文档需要这些元数据字段，请勿启用此模式。

完整配置示例

以下示例将所有主要配置选项集中展示：

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\Enums\Unit;
use Yeeefang\TcpdfNext\Core\Enums\EncryptionLevel;
use Yeeefang\TcpdfNext\Core\Enums\Permission;
use Yeeefang\TcpdfNext\Core\Config\EncryptionConfig;
use Yeeefang\TcpdfNext\Core\Config\FontConfig;
use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

$doc = Document::create(
    pageSize: PageSize::A4,
    orientation: Orientation::Portrait,
    unit: Unit::Millimeter,
);

// 边距
$doc->setMargins(new Margin(
    left: 15,
    top: 27,
    right: 15,
    bottom: 25,
));

// 字体
$doc->configureFonts(function (FontConfig $config): void {
    $config->addDirectory('/path/to/fonts');
});

// 加密
$doc->setEncryption(new EncryptionConfig(
    level: EncryptionLevel::AES256,
    userPassword: '',
    ownerPassword: 'secret',
    permissions: [Permission::Print],
));

// 无障碍
$doc->enableTaggedPdf();
$doc->setLanguage('zh-CN');

// 确定性输出（供测试使用）
// $doc->enableDeterministicMode();

// 元数据
$doc->setTitle('公司报告');
$doc->setAuthor('TCPDF-Next');
$doc->setSubject('每月摘要');
$doc->setKeywords('报告, 财务, 2026');

$doc->addPage();
$doc->cell(text: 'Hello, configured world!');
$doc->save('/tmp/configured.pdf');