檔案附件

TCPDF-Next 可以在 PDF 文件中嵌入任意檔案。附件系統由 Navigation\FileAttachment 管理，並透過 Document 流暢 API 存取。附件會隨 PDF 一起傳遞 — 收件者可直接從閱讀器中擷取嵌入的檔案。

所有方法皆回傳 static，因此可以鏈式串接。

快速參考

方法	用途
`addFileAttachment()`	將檔案嵌入 PDF 文件中

基本範例

php

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Invoice #2026-001', newLine: true)
    ->cell(0, 10, 'The original spreadsheet is attached to this PDF.', newLine: true)

    // 附加支援檔案
    ->addFileAttachment('/path/to/invoice-data.xlsx', 'invoice-data.xlsx', 'Original invoice data')
    ->addFileAttachment('/path/to/zugferd.xml', 'factur-x.xml', 'Factur-X e-invoice XML')

    ->save('invoice-with-attachments.pdf');

addFileAttachment()

php

$pdf->addFileAttachment(
    string $file,
    string $name = '',
    string $desc = '',
    string $mimeType = '',
    string $relationship = 'Unspecified'
): static

參數	型別	說明
`$file`	`string`	要嵌入的檔案絕對路徑
`$name`	`string`	閱讀器附件面板中的顯示名稱（預設為原始檔名）
`$desc`	`string`	附件的人類可讀描述
`$mimeType`	`string`	MIME 類型（留空則自動偵測）
`$relationship`	`string`	PDF 2.0 關聯檔案關係（`Data`、`Source`、`Alternative`、`Supplement`、`Unspecified`）

常見使用情境

附加原始資料、補充文件或高解析度原檔：

php

$pdf->addFileAttachment('/path/to/report-data.csv', 'report-data.csv', 'Raw CSV export')
    ->addFileAttachment('/path/to/terms.pdf', 'terms-and-conditions.pdf', 'Terms & Conditions')
    ->addFileAttachment('/path/to/photo-full.tiff', 'photo-full.tiff', 'Full-resolution original');

PDF/A-3 與 PDF/A-4 合規

PDF/A-3 與 PDF/A-4 典藏標準允許嵌入檔案，使附件成為結構化資料交換的關鍵功能。最常見的應用場景是 ZUGFeRD / Factur-X 電子發票 — 將機器可讀的 XML 發票嵌入人類可讀的 PDF 中。

php

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setPDFVersion('2.0')
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Electronic Invoice', newLine: true)
    ->cell(0, 10, 'This PDF contains a Factur-X XML attachment.', newLine: true)

    // Factur-X / ZUGFeRD 電子發票附件
    ->addFileAttachment(
        '/path/to/factur-x.xml',
        'factur-x.xml',
        'Factur-X BASIC invoice data',
        'text/xml',
        'Data'
    )

    ->save('e-invoice.pdf');

TIP

以 PDF/A-3 或 PDF/A-4 為目標時，請設定 $relationship 參數來描述附件與文件的關係。常用值為 Data（結構化資料表示）、Source（原始來源檔案）與 Alternative（替代表示形式）。

附件中繼資料

嵌入的檔案帶有中繼資料，閱讀器會在附件面板中顯示這些資訊：

中繼資料	來源
檔名	`$name` 參數（或原始檔名）
描述	`$desc` 參數
MIME 類型	`$mimeType` 參數（留空則自動偵測）
大小	從檔案自動計算
修改日期	從檔案系統的時間戳記讀取

提示

附件會使 PDF 檔案大小增加約等於嵌入檔案的大小。建議在嵌入前先壓縮大型附件。
Adobe Acrobat、Foxit Reader 與大多數桌面 PDF 閱讀器支援附件。瀏覽器內建的檢視器通常不會顯示附件面板。
沒有格式限制 — 你可以附加任何檔案類型（CSV、XLSX、XML、PNG、ZIP 等）。
進行電子發票流程時，嵌入前請務必將 XML 與相關標準綱要（ZUGFeRD、Factur-X 或 XRechnung）進行驗證。

檔案附件 ​

快速參考 ​

基本範例 ​

addFileAttachment() ​

常見使用情境 ​

PDF/A-3 與 PDF/A-4 合規 ​

附件中繼資料 ​

提示 ​