预检指南

本 cookbook 将 preflight APIs 和 demos 按任务导向配方组织起来。需要精确签名时请使用 API reference；需要为应用程序、构建脚本或 CI job 找到可工作的路径时，请使用本页

Choose an output format

var
  PDF: THotPDF;
begin
  PDF := THotPDF.Create(nil);
  try
    PDF.SavePreflightReport('Input.pdf', 'Input.preflight.txt');
    PDF.SavePreflightReport('Input.pdf', 'Input.preflight.json', '', pfJSON);
    PDF.SavePreflightReport('Input.pdf', 'Input.preflight.html', '', pfHTML);
    PDF.SavePreflightReport('Input.pdf', 'Input.preflight.csv', '', pfCSV);
  finally
    PDF.Free;
  end;
end;

文本输出具有字节稳定性且便于 diff。JSON 适合管线摄取。HTML 是自包含的，可直接打开或保存为 CI artifact。CSV 使用稳定列，适合电子表格和批量报告工作流

Validate PDF/VT documents

var
  PDF: THotPDF;
  Report: AnsiString;
begin
  PDF := THotPDF.Create(nil);
  try
    if not PDF.ValidatePDFVT('Input.pdf', Report) then
      WriteLn(string(Report));
  finally
    PDF.Free;
  end;
end;

PDF/VT 报告聚焦 ISO 16612-2 标识和 document-part 结构：元素文本或 RDF attribute 形式的 XMP GTS_PDFVTVersion、修改日期匹配、PDF/X base marker、output intent、DPartRoot、DPartRootNode、NodeNameList，以及页面级 DPart 覆盖

Apply a profile

var
  PDF: THotPDF;
  Report: AnsiString;
begin
  PDF := THotPDF.Create(nil);
  try
    Report := PDF.CreatePreflightReportWithProfile(
      'Input.pdf', '', 'project-preflight.ini', pfJSON);
  finally
    PDF.Free;
  end;
end;

Profiles suppress named checks, warnings, or all hints. Use ValidatePreflightProfile before applying a user-authored profile when failing closed is more important than silently ignoring an obsolete name.

从 preset 创建可复用 profile

var
  PDF: THotPDF;
  Profile: THPDFPreflightProfile;
begin
  PDF := THotPDF.Create(nil);
  try
    Profile := PDF.GetBuiltInPreflightProfile('compact');
    Profile.DisableWarnings := 'OpenAction,JavaScript,URIAction';
    PDF.SavePreflightProfile(Profile, 'compact-no-actions.ini');
  finally
    PDF.Free;
  end;
end;

使用 MergePreflightProfiles 将 preset 与项目专用名称组合。使用 DiffPreflightProfiles 在更新共享配置文件前审查 profile drift

Archive the report with the PDF

PDF.EmbedPreflightReportInPDF('Input.pdf', 'Input-with-report.pdf');
PDF.EmbedPreflightReportAsXMP('Input.pdf', 'Input-with-xmp-report.pdf');

文本嵌入路径会在最终 EOF marker 之后追加可读注释块。XMP 路径会为扫描 metadata packets 的归档工作流追加 RDF 形态载荷

Validate an embedded report

var
  OriginalReport: AnsiString;
  CurrentReport: AnsiString;
begin
  if not PDF.LoadAndValidatePreflightReport(
    'Input-with-report.pdf', OriginalReport, CurrentReport) then
    WriteLn(string(PDF.ComparePreflightReports(OriginalReport, CurrentReport)));
end;

验证路径会将嵌入 fingerprint 与针对源字节重新运行的 preflight 结果比较。diff 辅助函数按行工作，并针对 HotPDF preflight reports 调优

运行保守 repair pass

var
  RepairsApplied: AnsiString;
begin
  if PDF.RepairPDFFromPreflightReport(
    'Broken.pdf', 'Broken-repaired.pdf', RepairsApplied) then
    WriteLn(string(RepairsApplied));
end;

repair 辅助函数刻意保持范围狭窄。它处理最终 EOF marker 之后的尾随字节和缺失 EOF marker，但不会重建 cross-reference tables 或重写 streams

Aggregate many reports

Reports[0] := PDF.CreatePreflightReport('A.pdf');
Reports[1] := PDF.CreatePreflightReport('B.pdf');
Summary := PDF.AggregatePreflightReports(Reports);

aggregate 输出为每个 PDF 列出一行状态，并汇总已处理报告、失败和警告数量。当管线需要一个总览，而详细报告仍按输入文件保留时，这很有用

使用 command-line tool

HotPDFPreflight Input.pdf -f json -o reports
HotPDFPreflight Input.pdf --pdfvt -o reports
HotPDFPreflight C:\Archive -r --preset compact -f text -o reports --aggregate reports\Aggregate.txt
HotPDFPreflight C:\Archive -r --profile project-preflight.ini -f html -o reports

CLI 映射库工作流：一个文件或递归目录输入、text / JSON / HTML 输出、可选 password、可选 profile、内置 preset、详细进度和 aggregate summary

Build a static dashboard

PreflightDashboard C:\Archive C:\Archive\preflight-dashboard

dashboard demo 会写入一个 index.html 以及每个文件对应的 HTML report。不需要 web server，因此输出可作为静态 artifact 发布

Adapt to veraPDF-style JSON consumers

Report := PDF.CreatePreflightReport('Input.pdf');
JSON := PDF.ConvertPreflightReportToVeraPDFStyle(Report);

该适配器保持 HotPDF 语义，同时将 failures 重塑为熟悉的 validation-result 结构，便于已经消费 veraPDF-like JSON 的工具使用

Related Topics