MergeFiles - TPdf - PDFium Delphi Component

Komponente: TPdf · Unit: PDFium

Führt dateigestützte PDF-Quellen über native Seitenimport-APIs zusammen, begrenzt dabei Quell-Handles und legt explizite Operationsrichtlinien offen

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;

Quellauswahl

FileName bezeichnet eine dateigestützte PDF-Quelle
Password wird angewendet, bevor die Quelle geöffnet wird
PageRange ist eine kommagetrennte, einsbasierte Liste wie 1,3,5-7
Ein leerer PageRange importiert alle Seiten
Auswahlreihenfolge und wiederholte Seitennummern bleiben erhalten

Standardoptionen

ErrorPolicy	`bmepStop`
FormPolicy	`bmfpPreserveNative`
OutlinePolicy	`bmopDiscard`
ResourcePolicy	`bmrpSourceScoped`
PageChunkSize	`PdfBatchMergeDefaultPageChunkSize`, derzeit 128 Seiten
InsertAt	-1, was an das Ziel anhängt
CreateDestination	`True`
CopyViewerPreferences	`True`
RollbackOnCancelOrFailure	`True`

Ressourcen- und Abbruchrichtlinie

bmrpSourceScoped führt einen nativen Import pro Quelle durch und erlaubt PDFium, seine Klonobjekt-Map über alle ausgewählten Seiten dieser Quelle wiederzuverwenden

bmrpChunked teilt die Auswahl in Chargen der Größe PageChunkSize und bietet so feinere Abbruchpunkte und kleinere native Aufrufe auf Kosten möglicher ressourcenbezogener Doppellungen über Chargen hinweg

Es ist stets höchstens eine Quell-TPdf-Instanz geöffnet, und jede Quelle wird unmittelbar nach ihrem Importversuch geschlossen

Der Abbruch wird zwischen Quelloperationen und nativen Chargen geprüft; ein einzelner PDFium-Importaufruf kann nicht unterbrochen werden

OnProgress empfängt die Stufen gestartet, öffnen, importieren, Quelle, Rollback, Abbruch, Fehlschlag und Abschluss und kann seinen Parameter Cancel setzen; jeder TPdfBatchMergeProgress-Schnappschuss trägt Stage, SourceIndex, SourceCount, FileName, SourcePageCount, ImportedSourceCount, ImportedPageCount und NativeImportCallCount

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

CancellationToken akzeptiert denselben IPdfCancellationToken-Vertrag, den die asynchronen und progressiven APIs verwenden

Formulare, Gliederungen und Viewer-Einstellungen

bmfpPreserveNative behält PDFiums Best-Effort-Import von Seiten und Widgets bei, löst aber keine Konflikte in AcroForm-Feldbäumen, bei Feldern gleichen Namens, bei Ressourcen, Standarddarstellungen oder Berechnungsreihenfolgen
bmfpFlatten erzeugt Erscheinungsbilder und flacht nur die ausgewählten Quellseiten vor dem Import ab
bmfpReject weist AcroForm- und XFA-Quellen zurück
bmopDiscard importiert Seiten, ohne die Quellgliederung neu aufzubauen, während bmopReject Quellen zurückweist, die eine Gliederung enthalten
Viewer-Einstellungen werden nach erfolgreichem Seitenimport nach Best-Effort aus der ersten erfolgreichen Quelle kopiert, wenn CopyViewerPreferences aktiviert ist; ViewerPreferencesSourceIndex bleibt -1, wenn diese Quelle keine unterstützten Einträge besitzt

Fehlschlag und Rollback

Eine Quelle, die nach einer oder mehreren Chargen mit eingefügten Seiten fehlschlägt, wird stets auf ihre Quellgrenze zurückgerollt, bevor Stopp oder Überspringen behandelt werden

bmepSkip zeichnet die Feststellung auf und fährt mit der nächsten Quelle fort, während bmepStop die Operation beendet

Mit RollbackOnCancelOrFailure=True entfernen Stopp-Fehlschläge und Abbruch alle von der Operation eingefügten Seiten; ein von der Operation erzeugtes Ziel wird geschlossen

Bei deaktiviertem Rollback bleiben erfolgreich importierte Quellen festgeschrieben und schlagen sich in CommittedPageCount nieder

Rollback entfernt eingefügte Seiten, kann aber die Umkehrung jedes nativen Katalog-Nebeneffekts wie Hersteller-Metadaten nicht garantieren

Bericht

Status ist bmrsCompleted, bmrsCompletedWithErrors, bmrsCancelled oder bmrsFailed

Der Bericht trennt versuchte, importierte, übersprungene und fehlgeschlagene Quellen von importierten, festgeschriebenen und zurückgerollten Seiten

NativeImportCallCount, LargestNativeImportPageCount und PeakOpenSourceCount machen die gewählte Ablaufplanungs-Richtlinie messbar

Issues bewahrt Quellindex, Dateinamen und Fehlertext für Fehlschläge und nicht fatale Fehler in Abschluss-Callbacks

Beispiel

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;

Siehe auch

ImportPagesByIndex, ImportPages, Asynchrone Ausführung