檔案附件¶

NextPDF 支援在 PDF 文件中嵌入任意格式的附件檔案。附件可以是文件層級（透過附件面板存取）或頁面層級（附加至頁面的標注圖示）。這是 ZUGFeRD 等電子發票標準的基礎功能。

文件層級附件¶

use NextPDF\Navigation\FileAttachment;

$attachments = $document->attachments();

// 嵌入 XML 檔案（例如：ZUGFeRD 電子發票）
$attachments->attach(
    path: '/path/to/invoice.xml',
    filename: 'zugferd-invoice.xml',
    description: 'ZUGFeRD 2.3 Electronic Invoice',
    mimeType: 'application/xml',
    relationship: FileRelationship::Alternative, // Source | Data | Alternative | Supplement | Unspecified
);

// 嵌入 Excel 附件
$attachments->attach(
    path: '/path/to/data.xlsx',
    filename: 'raw-data.xlsx',
    description: 'Raw financial data',
    mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
);

頁面層級附件標注¶

use NextPDF\Navigation\AnnotationManager;
use NextPDF\Navigation\FileAnnotation;

$annotations = $document->annotations();

// 在頁面上建立附件標注圖示
$annotations->addFileAnnotation(
    pageNumber: 3,
    position: Position::at(x: 170.0, y: 250.0),
    attachment: FileAnnotation::create(
        path: '/path/to/reference.pdf',
        filename: 'reference-document.pdf',
        description: 'Technical Reference Manual',
        icon: FileAnnotationIcon::PaperClip, // PaperClip | PushPin | Graph | Tag
    ),
);

從記憶體附加¶

// 直接從位元組字串附加（不需要暫存檔案）
$attachments->attachBytes(
    bytes: $xmlBytes,
    filename: 'data.xml',
    description: 'Embedded XML Data',
    mimeType: 'application/xml',
    modificationDate: new DateTimeImmutable(),
);

附件中繼資料¶

use NextPDF\Navigation\FileAttachmentMetadata;

$attachments->attach(
    path: '/path/to/file.csv',
    filename: 'report-data.csv',
    metadata: FileAttachmentMetadata::create(
        creationDate: new DateTimeImmutable('2026-01-15'),
        modificationDate: new DateTimeImmutable('2026-03-01'),
        checksum: hash_file('md5', '/path/to/file.csv'),
    ),
);

PDF/A-3 附件合規¶

// PDF/A-3 要求附件具有明確的 AFRelationship 與 MIME 類型
$attachments->attach(
    path: '/path/to/source.xml',
    filename: 'source-data.xml',
    mimeType: 'application/xml',
    relationship: FileRelationship::Source,  // PDF/A-3 必要
    pdfa3Compliant: true,
);

文字標注¶

除了檔案附件，AnnotationManager 也支援文字標注：

// 便利貼標注
$annotations->addNote(
    pageNumber: 2,
    position: Position::at(x: 150.0, y: 100.0),
    content: 'Review this section before printing.',
    author: 'Editor',
    color: Color::rgb(255, 255, 0),  // 黃色
);

參見¶

連結 — 超連結標注
書籤 — 文件大綱
Enterprise ZUGFeRD — 電子發票附件整合