設定

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-TW');

啟用標記式 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-TW');

// 確定性輸出（供測試使用）
// $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');