MergeFiles

Component: TPdf · Unit: PDFium

Menggabungkan sumber PDF berbasis file melalui API impor halaman native sembari membatasi handle sumber dan mengekspos policy operasi yang eksplisit

Syntax

function MergeFiles(const Sources: TPdfBatchMergeSources; out Report: TPdfBatchMergeReport): Boolean; overload;

function MergeFiles(const Sources: TPdfBatchMergeSources; const Options: TPdfBatchMergeOptions; out Report: TPdfBatchMergeReport): Boolean; overload;

class function TPdfBatchMergeSource.FromFile(const AFileName: string; const APageRange: string = ''; const APassword: string = ''): TPdfBatchMergeSource; static;

class function TPdfBatchMergeOptions.Default: TPdfBatchMergeOptions; static;

Source selection

FileName mengidentifikasi satu sumber PDF berbasis file
Password diterapkan sebelum sumber dibuka
PageRange adalah daftar berbasis 1 yang dipisah koma, misalnya 1,3,5-7
PageRange yang kosong mengimpor semua halaman
Urutan seleksi dan nomor halaman yang berulang dipertahankan

Default options

ErrorPolicy	`bmepStop`
FormPolicy	`bmfpPreserveNative`
OutlinePolicy	`bmopDiscard`
ResourcePolicy	`bmrpSourceScoped`
PageChunkSize	`PdfBatchMergeDefaultPageChunkSize`, saat ini 128 halaman
InsertAt	-1, yang berarti menambahkan di akhir tujuan
CreateDestination	`True`
CopyViewerPreferences	`True`
RollbackOnCancelOrFailure	`True`

Resource and cancellation policy

bmrpSourceScoped melakukan satu impor native per sumber, memungkinkan PDFium memakai ulang peta cloned-object-nya untuk semua halaman terpilih dari sumber tersebut

bmrpChunked membagi seleksi menjadi batch berukuran PageChunkSize, memberi titik pembatalan yang lebih halus dan panggilan native yang lebih kecil dengan biaya kemungkinan duplikasi resource lintas-chunk

Maksimal satu TPdf sumber terbuka pada satu waktu dan setiap sumber ditutup segera setelah percobaan impornya

Pembatalan diperiksa di antara operasi sumber dan batch native; satu panggilan impor PDFium tidak dapat diinterupsi

OnProgress menerima tahap started, opening, importing, source, rollback, cancellation, failure, dan completion serta dapat men-set parameter Cancel-nya; setiap snapshot TPdfBatchMergeProgress membawa Stage, SourceIndex, SourceCount, FileName, SourcePageCount, ImportedSourceCount, ImportedPageCount, dan NativeImportCallCount

TPdfBatchMergeReport mengembalikan Status, SourceCount, AttemptedSourceCount, ImportedSourceCount, SkippedSourceCount, FailedSourceCount, ImportedPageCount, CommittedPageCount, RolledBackPageCount, PageCountBefore, PageCountAfter, NativeImportCallCount, LargestNativeImportPageCount, PeakOpenSourceCount, FormSourceCount, OutlineSourceCount, DestinationCreated, ViewerPreferencesSourceIndex, ErrorMessage, dan Issues

CancellationToken menerima kontrak IPdfCancellationToken yang sama dengan yang dipakai API asinkron dan progresif

Forms, outlines, and viewer preferences

bmfpPreserveNative mempertahankan impor halaman dan widget best-effort milik PDFium tetapi tidak menyelesaikan konflik field-tree AcroForm, field bernama sama, resource, default appearance, atau calculation-order
bmfpFlatten menghasilkan appearance dan hanya melakukan flatten pada halaman sumber terpilih sebelum impor
bmfpReject menolak sumber AcroForm dan XFA
bmopDiscard mengimpor halaman tanpa membangun ulang outline sumber, sedangkan bmopReject menolak sumber yang memuat outline
Viewer preferences disalin secara best-effort setelah impor halaman berhasil dari sumber pertama yang berhasil ketika CopyViewerPreferences aktif; ViewerPreferencesSourceIndex tetap -1 ketika sumber itu tidak punya entri yang didukung

Failure and rollback

Sumber yang gagal setelah satu atau lebih chunk menyisipkan halaman selalu di-rollback ke batas sumbernya sebelum penanganan stop atau skip

bmepSkip merekam issue dan melanjutkan ke sumber berikutnya, sedangkan bmepStop mengakhiri operasi

Dengan RollbackOnCancelOrFailure=True, kegagalan stop dan pembatalan menghapus semua halaman yang disisipkan operasi; tujuan yang dibuat oleh operasi ditutup

Dengan rollback nonaktif, sumber yang berhasil diimpor tetap ter-commit dan tercermin di CommittedPageCount

Rollback menghapus halaman yang disisipkan tetapi tidak dapat menjamin pembalikan setiap side effect katalog native seperti metadata producer

Report

Status bernilai bmrsCompleted, bmrsCompletedWithErrors, bmrsCancelled, atau bmrsFailed

Laporan memisahkan sumber yang dicoba, diimpor, dilewati, dan gagal dari halaman yang diimpor, ter-commit, dan di-rollback

NativeImportCallCount, LargestNativeImportPageCount, dan PeakOpenSourceCount membuat policy penjadwalan yang dipilih dapat diukur

Issues menyimpan indeks sumber, nama file, dan teks error untuk kegagalan serta error callback terminal yang non-fatal

Example

var
  Sources: TPdfBatchMergeSources;
  Options: TPdfBatchMergeOptions;
  Report: TPdfBatchMergeReport;
begin
  SetLength(Sources, 2);
  Sources[0] := TPdfBatchMergeSource.FromFile('part-a.pdf', '1-10');
  Sources[1] := TPdfBatchMergeSource.FromFile('part-b.pdf', '3,1', Password);
  Options := TPdfBatchMergeOptions.Default;
  Options.ErrorPolicy := bmepSkip;
  Options.FormPolicy := bmfpFlatten;
  if not Pdf.MergeFiles(Sources, Options, Report) then
    Log(Report.ErrorMessage);
end;