MergeFiles - TPdf - PDFium Delphi Component

组件: TPdf · 单元: PDFium

通过原生页面导入 API 合并基于文件的 PDF 来源，同时限制来源句柄数量并公开显式的操作策略

语法

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;

来源选择

FileName 标识一个基于文件的 PDF 来源
Password 在来源打开之前应用
PageRange 是从 1 开始、以逗号分隔的列表，例如 1,3,5-7
空的 PageRange 导入全部页面
选择顺序和重复的页码都会保留

默认选项

ErrorPolicy	`bmepStop`
FormPolicy	`bmfpPreserveNative`
OutlinePolicy	`bmopDiscard`
ResourcePolicy	`bmrpSourceScoped`
PageChunkSize	`PdfBatchMergeDefaultPageChunkSize`，当前为 128 页
InsertAt	-1，表示追加到目标末尾
CreateDestination	`True`
CopyViewerPreferences	`True`
RollbackOnCancelOrFailure	`True`

资源与取消策略

bmrpSourceScoped 对每个来源执行一次原生导入，让 PDFium 在该来源的所有选定页面之间复用其克隆对象映射

bmrpChunked 把选择拆分为 PageChunkSize 大小的批次，以可能出现的跨批次资源重复为代价，提供更细的取消点和更小的原生调用

同一时刻至多打开一个来源 TPdf，每个来源都在其导入尝试结束后立即关闭

取消检查发生在来源操作与原生批次之间；单个 PDFium 导入调用无法被中断

OnProgress 接收开始、打开、导入、来源、回滚、取消、失败和完成等阶段，并可设置其 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 接受与异步及渐进式 API 所用相同的 IPdfCancellationToken 契约

表单、书签与查看器首选项

bmfpPreserveNative 保留 PDFium 尽力而为的页面与部件导入，但不解决 AcroForm 字段树、同名字段、资源、默认外观或计算顺序冲突
bmfpFlatten 在导入前只为选定的来源页面生成外观并扁平化
bmfpReject 拒绝 AcroForm 和 XFA 来源
bmopDiscard 导入页面而不重建来源书签，而 bmopReject 拒绝包含书签的来源
启用 CopyViewerPreferences 时，查看器首选项会在页面导入成功后从第一个成功的来源尽力复制；当该来源没有受支持的条目时，ViewerPreferencesSourceIndex 保持 -1

失败与回滚

在一个或多个批次插入页面后失败的来源，总是会在停止或跳过处理之前回滚到其来源边界

bmepSkip 记录问题并继续处理下一个来源，而 bmepStop 终止操作

在 RollbackOnCancelOrFailure=True 时，停止失败与取消会移除操作插入的所有页面；由操作创建的目标会被关闭

禁用回滚时，成功导入的来源保持已提交状态，并体现在 CommittedPageCount 中

回滚会移除插入的页面，但无法保证撤销每个原生目录副作用，例如 producer 元数据

报告

Status 为 bmrsCompleted、bmrsCompletedWithErrors、bmrsCancelled 或 bmrsFailed

报告把已尝试、已导入、已跳过和已失败的来源，与已导入、已提交和已回滚的页面分开统计

NativeImportCallCount、LargestNativeImportPageCount 和 PeakOpenSourceCount 使所选调度策略可被度量

Issues 保留失败以及非致命终端回调错误的来源索引、文件名和错误文本

示例

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;

参见

ImportPagesByIndex, ImportPages, 异步执行