MergeFiles

Component: TPdf · Unit: PDFium

รวมแหล่ง PDF จากไฟล์ผ่าน native page import API โดยจำกัดจำนวนแฮนเดิลต้นทางและเปิดเผยนโยบายการทำงานอย่างชัดเจน

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 ระบุแหล่ง PDF จากไฟล์หนึ่งแหล่ง
Password ถูกใช้ก่อนที่แหล่งจะถูกเปิด
PageRange เป็นรายการแบบ 1-based คั่นด้วยเครื่องหมายจุลภาค เช่น 1,3,5-7
PageRange ที่ว่างเปล่าหมายถึง import ทุกหน้า
ลำดับการเลือกและเลขหน้าที่ซ้ำกันถูกคงไว้

Default options

ErrorPolicy	`bmepStop`
FormPolicy	`bmfpPreserveNative`
OutlinePolicy	`bmopDiscard`
ResourcePolicy	`bmrpSourceScoped`
PageChunkSize	`PdfBatchMergeDefaultPageChunkSize` ปัจจุบันคือ 128 หน้า
InsertAt	-1 หมายถึงต่อท้ายเอกสารปลายทาง
CreateDestination	`True`
CopyViewerPreferences	`True`
RollbackOnCancelOrFailure	`True`

Resource and cancellation policy

bmrpSourceScoped ทำการ import แบบ native หนึ่งครั้งต่อแหล่ง ให้ PDFium ใช้ cloned-object map ของตัวเองซ้ำกับทุกหน้าที่เลือกจากแหล่งนั้น

bmrpChunked แบ่งการเลือกเป็นชุดละ PageChunkSize ให้จุดยกเลิกละเอียดขึ้นและการเรียก native เล็กลง โดยแลกกับความเป็นไปได้ที่ resource จะซ้ำซ้อนข้าม chunk

เปิดแหล่ง TPdf พร้อมกันได้มากที่สุดหนึ่งแหล่ง และปิดทุกแหล่งทันทีหลังความพยายาม import จบลง

การยกเลิกถูกตรวจระหว่างการทำงานของแหล่งและระหว่าง chunk แบบ native; การเรียก import ของ PDFium หนึ่งครั้งไม่สามารถถูกขัดจังหวะได้

OnProgress รับสถานะ started, opening, importing, source, rollback, cancellation, failure และ completion พร้อมตั้งพารามิเตอร์ Cancel ได้; สแนปชอต TPdfBatchMergeProgress แต่ละชุดเก็บ Stage, SourceIndex, SourceCount, FileName, SourcePageCount, ImportedSourceCount, ImportedPageCount และ NativeImportCallCount

TPdfBatchMergeReport คืน Status, SourceCount, AttemptedSourceCount, ImportedSourceCount, SkippedSourceCount, FailedSourceCount, ImportedPageCount, CommittedPageCount, RolledBackPageCount, PageCountBefore, PageCountAfter, NativeImportCallCount, LargestNativeImportPageCount, PeakOpenSourceCount, FormSourceCount, OutlineSourceCount, DestinationCreated, ViewerPreferencesSourceIndex, ErrorMessage และ Issues

CancellationToken รับสัญญาแบบ IPdfCancellationToken เดียวกับที่ API แบบ asynchronous และ progressive ใช้

Forms, outlines, and viewer preferences

bmfpPreserveNative คงการ import หน้าและ widget แบบ best-effort ของ PDFium ไว้ แต่ไม่แก้ความขัดแย้งของ field-tree ของ AcroForm, ฟิลด์ชื่อซ้ำ, resource, default appearance หรือลำดับการคำนวณ
bmfpFlatten สร้าง appearance และ flatten เฉพาะหน้าต้นทางที่ถูกเลือกก่อน import
bmfpReject ปฏิเสธแหล่งที่เป็น AcroForm และ XFA
bmopDiscard import หน้าโดยไม่สร้าง outline ของแหล่งใหม่ ส่วน bmopReject ปฏิเสธแหล่งที่มี outline
Viewer preferences ถูกคัดลอกแบบ best-effort หลัง import หน้าสำเร็จ จากแหล่งแรกที่สำเร็จเมื่อ CopyViewerPreferences ถูกเปิดไว้; ViewerPreferencesSourceIndex จะคงค่า -1 หากแหล่งนั้นไม่มีรายการที่รองรับ

Failure and rollback

แหล่งที่ล้มเหลวหลังจาก chunk หนึ่งชุดขึ้นไปแทรกหน้าไปแล้ว จะถูก rollback กลับถึงขอบเขตของแหล่งนั้นเสมอ ก่อนเข้าสู่การจัดการแบบ stop หรือ skip

bmepSkip บันทึกปัญหาแล้วทำงานกับแหล่งถัดไปต่อ ส่วน bmepStop จะจบการทำงานทันที

เมื่อเปิด RollbackOnCancelOrFailure=True ความล้มเหลวแบบ stop และการยกเลิกจะลบหน้าที่การทำงานแทรกเข้าไปทั้งหมด; เอกสารปลายทางที่การทำงานสร้างขึ้นจะถูกปิด

เมื่อปิด rollback ไว้ แหล่งที่ import สำเร็จจะถูก commit ค้างอยู่และสะท้อนอยู่ใน CommittedPageCount

Rollback ลบหน้าที่แทรกเข้าไปได้ แต่ไม่รับประกันว่าจะย้อนผลข้างเคียงระดับ native catalog ได้ทุกอย่าง เช่น producer metadata

Report

Status เป็น bmrsCompleted, bmrsCompletedWithErrors, bmrsCancelled หรือ bmrsFailed

report แยกจำนวนแหล่งที่พยายาม import สำเร็จ ถูกข้าม และล้มเหลว ออกจากจำนวนหน้าที่ import, commit และ rollback

NativeImportCallCount, LargestNativeImportPageCount และ PeakOpenSourceCount ทำให้นโยบายการจัดคิวที่เลือกใช้วัดผลได้

Issues เก็บดัชนีแหล่ง ชื่อไฟล์ และข้อความ error ของความล้มเหลวและ error แบบไม่ถึงตายจาก callback ขั้นสุดท้าย

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;