预检指南

本 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 适合管线接入，为每个检查、提示和警告给出稳定的带命名空间 ruleId，以及结构化 location（含逻辑范围、路径、PDF 键，可用时还有精确的对象、页面或字节坐标）。HTML 展示同样的标识符和位置；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 属性形式的 XMP GTS_PDFVTVersion、修改日期匹配、PDF/X 基标记、输出意图、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;

Profile 可以屏蔽指定的检查、警告或全部提示。当"失败即拒绝"（fail closed）比静默忽略过时的名称更重要时，请在应用用户自定义的 profile 之前先调用 ValidatePreflightProfile。

从预设创建可复用的 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 把预设与项目专用名称组合；更新共享配置文件前，用 DiffPreflightProfiles 审查 profile 漂移。

将报告与 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 调优

执行一次保守的修复趟

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 列出一行状态，并汇总已处理报告、失败和警告数量。当管线需要一个总览，而详细报告仍按输入文件保留时，这很有用

使用命令行工具

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 示例会写出 index.html 和每个文件的 HTML 报告；不需要 web 服务器，输出可作为静态制品发布。

Adapt to veraPDF-style JSON consumers

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

该适配器保留 HotPDF 的语义，同时把失败信息重塑为熟悉的校验结果结构，便于已经在使用类 veraPDF JSON 的工具消费。其中的违规项保留与原生 JSON 报告相同的稳定 ruleId 和结构化 location 值

Related Topics