MergeFiles

Component: TPdf · Unit: PDFium

Voegt bestandsgebaseerde PDF-bronnen samen via native pagina-import-API's, met begrensde bronhandles en expliciete beleidsregels voor de bewerking

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 identificeert één bestandsgebaseerde PDF-bron
Password wordt toegepast voordat de bron wordt geopend
PageRange is een door komma's gescheiden lijst met 1-gebaseerde nummers, zoals 1,3,5-7
Een lege PageRange importeert alle pagina's
De volgorde van de selectie en herhaalde paginanummers blijven behouden

Default options

ErrorPolicy	`bmepStop`
FormPolicy	`bmfpPreserveNative`
OutlinePolicy	`bmopDiscard`
ResourcePolicy	`bmrpSourceScoped`
PageChunkSize	`PdfBatchMergeDefaultPageChunkSize`, momenteel 128 pagina's
InsertAt	-1, wat achteraan aan de bestemming toevoegt
CreateDestination	`True`
CopyViewerPreferences	`True`
RollbackOnCancelOrFailure	`True`

Resource and cancellation policy

bmrpSourceScoped voert per bron één native import uit, zodat PDFium zijn cloned-object map kan hergebruiken voor alle geselecteerde pagina's uit die bron

bmrpChunked splitst de selectie in batches van PageChunkSize, wat fijnmaziger annuleerpunten en kleinere native aanroepen oplevert, ten koste van mogelijk dubbel aangelegde resources over chunkgrenzen heen

Er is tegelijk hooguit één bron-TPdf geopend en elke bron wordt direct na zijn importpoging gesloten

Annulering wordt gecontroleerd tussen bronbewerkingen en native batches door; een afzonderlijke PDFium-importaanroep kan niet worden onderbroken

OnProgress doorloopt de fasen started, opening, importing, source, rollback, cancellation, failure en completion en kan daarbij zijn parameter Cancel instellen; elke momentopname van TPdfBatchMergeProgress bevat Stage, SourceIndex, SourceCount, FileName, SourcePageCount, ImportedSourceCount, ImportedPageCount en NativeImportCallCount

Het TPdfBatchMergeReport geeft Status, SourceCount, AttemptedSourceCount, ImportedSourceCount, SkippedSourceCount, FailedSourceCount, ImportedPageCount, CommittedPageCount, RolledBackPageCount, PageCountBefore, PageCountAfter, NativeImportCallCount, LargestNativeImportPageCount, PeakOpenSourceCount, FormSourceCount, OutlineSourceCount, DestinationCreated, ViewerPreferencesSourceIndex, ErrorMessage en Issues terug

CancellationToken accepteert hetzelfde IPdfCancellationToken-contract dat de asynchrone en progressieve API's gebruiken

Forms, outlines, and viewer preferences

bmfpPreserveNative houdt de best-effort pagina- en widgetimport van PDFium aan, maar lost geen conflicten op rond de AcroForm-veldboom, velden met dezelfde naam, resources, default appearances of de berekeningsvolgorde
bmfpFlatten genereert appearances en flattent alleen de geselecteerde bronpagina's vóór de import
bmfpReject wijst AcroForm- en XFA-bronnen af
bmopDiscard importeert pagina's zonder de bronoutline opnieuw op te bouwen, terwijl bmopReject bronnen met een outline afwijst
Viewer preferences worden na geslaagde pagina-imports op best-effort-basis gekopieerd vanuit de eerste succesvolle bron wanneer CopyViewerPreferences is ingeschakeld; ViewerPreferencesSourceIndex blijft -1 wanneer die bron geen ondersteunde items bevat

Failure and rollback

Een bron die pas faalt nadat één of meer chunks pagina's hebben ingevoegd, wordt altijd teruggedraaid tot zijn bronbegrenzing vóór de stop- of skip-afhandeling

bmepSkip registreert het probleem en gaat verder met de volgende bron, terwijl bmepStop de bewerking beëindigt

Met RollbackOnCancelOrFailure=True verwijderen stopfouten en annulering alle pagina's die de bewerking heeft ingevoegd; een door de bewerking aangemaakte bestemming wordt gesloten

Met rollback uitgeschakeld blijven succesvol geïmporteerde bronnen vastgelegd en zichtbaar in CommittedPageCount

Rollback verwijdert ingevoegde pagina's, maar kan niet garanderen dat elke native neveneffect op de catalog wordt teruggedraaid, zoals producer-metadata

Report

Status is bmrsCompleted, bmrsCompletedWithErrors, bmrsCancelled of bmrsFailed

Het rapport scheidt geprobeerde, geïmporteerde, overgeslagen en mislukte bronnen van geïmporteerde, vastgelegde en teruggedraaide pagina's

NativeImportCallCount, LargestNativeImportPageCount en PeakOpenSourceCount maken het gekozen planningsbeleid meetbaar

Issues bewaart bronindex, bestandsnaam en fouttekst voor mislukkingen en niet-fatale terminale callbackfouten

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;