运行时日志门面（HPDFLogger）

概述

HPDFLogger 单元提供统一的运行时日志门面，可在不重新编译、不开编译期开关的前提下，捕获 HotPDF 内部诊断（例如 LoadFromFile 的页面/加密/耗时，以及 CreatePreflightReport 的摘要与字节数）。门面由一个进程级全局实例 HPDFLog 暴露，HPDFDoc 在内部 uses HPDFLogger 并把上述钩子接入门面

生产构建默认 Enabled = False，此时 Log() 快速路径只做一次布尔检查即返回，对性能无可观测影响。仅在需要排查时把它打开，按严重级别过滤、并扇出到一个或多个目标（文件 / OutputDebugString / 控制台）

核心类型

• THPDFLogger：日志门面类，进程内由单元初始化段自动创建为全局变量 HPDFLog，应用代码只需配置属性并调用方法
• THPDFLogLevel：严重级别枚举，按序数排 llOff（全部抑制）→ llError → llWarning → llInfo → llDebug（最详细）。过滤规则：当记录的级别 ≤ 门面的 Level（且 Level <> llOff）时才输出
• THPDFLogTarget / THPDFLogTargets：输出目标枚举与集合，ltFile（写入 FileName 指定的文件）、ltOutputDebugString（送入 IDE 事件日志 / DebugView）、ltConsole（写入标准输出）

配置属性

• Enabled: Boolean：总开关，默认 False。置 True 才会真正输出
• Level: THPDFLogLevel：当前过滤级别，排错时通常设 llDebug 捕获最详细输出
• Targets: THPDFLogTargets：输出目标集合，可同时启用多个（例如 [ltFile, ltOutputDebugString, ltConsole]）
• FileName: string：当 Targets 含 ltFile 时写入的文件全路径

记录方法

每个严重级别都有一个无格式重载和一个 Format 风格的格式化重载（参数数组与 System.SysUtils.Format 一致）

• Info(const Msg: string) 与 Info(const Fmt: string; const Args: array of const)
• Warning(const Msg: string) 与 Warning(const Fmt: string; const Args: array of const)
• Error(const Msg: string) 与 Error(const Fmt: string; const Args: array of const)
• Debug(const Msg: string) 与 Debug(const Fmt: string; const Args: array of const)
• Log(Level: THPDFLogLevel; const Msg: string) 与对应的格式化重载，用于显式指定级别

使用示例

启用日志并扇出到多个目标

// Delphi example - 在进行任何 HotPDF 工作前配置门面
uses
  HPDFDoc, HPDFLogger;

procedure ConfigureLogger;
var
  LogPath: string;
begin
  LogPath := ExtractFilePath(ParamStr(0)) + 'HotPDF.log';
  if FileExists(LogPath) then
    DeleteFile(LogPath);          // 清掉上一次运行，保证可读的干净跟踪

  HPDFLog.FileName := LogPath;
  HPDFLog.Level := llDebug;       // 最详细
  HPDFLog.Targets := [ltFile, ltOutputDebugString, ltConsole];
  HPDFLog.Enabled := True;

  HPDFLog.Info('Logging configured, targets enabled');
end;
        

捕获 LoadFromFile 与 preflight 诊断

配置好门面后，THotPDF 的内部钩子会在以下操作时自动写出结构化行（页数、加密标志、耗时毫秒等）。应用代码无需任何额外调用，只需正常使用 API：

// Delphi example - LoadFromFile 与 CreatePreflightReport 的诊断会自动落入日志
var
  PDF: THotPDF;
  Pages: Integer;
  Report: AnsiString;
begin
  ConfigureLogger;

  PDF := THotPDF.Create(nil);
  try
    // LoadFromFile 钩子写出：页数、加密标志、耗时
    Pages := PDF.LoadFromFile('Input.pdf');
    HPDFLog.Info('Loaded %d page(s)', [Pages]);

    // CreatePreflightReport 钩子写出：摘要、格式、字节数、耗时
    Report := PDF.CreatePreflightReport('Input.pdf', '');
    HPDFLog.Info('Preflight report length: %d bytes', [Length(Report)]);
  finally
    PDF.Free;
  end;
end;
        

C++Builder 用法

C++Builder 通过同样的全局 HPDFLog 实例配置（需 #include "HPDFLogger.hpp"）。属性与方法签名与 Delphi 一一对应，集合用 THPDFLogTargets() << ltFile << ltOutputDebugString << ltConsole 构造：

// C++Builder example
#include "HPDFLogger.hpp"

void ConfigureLogger()
{
    String LogPath = ExtractFilePath(ParamStr(0)) + "HotPDF.log";
    if (FileExists(LogPath))
        DeleteFile(LogPath);

    HPDFLog->FileName = LogPath;
    HPDFLog->Level = llDebug;
    HPDFLog->Targets = THPDFLogTargets() << ltFile << ltOutputDebugString << ltConsole;
    HPDFLog->Enabled = true;

    HPDFLog->Info("Logging configured, targets enabled");
}
        

性能与部署说明

• 零成本关闭：Enabled = False 时 Log() 仅一次布尔检查即返回，生产构建可放心保留门面代码而无性能顾虑
• 无需重新编译：严重级别与目标在运行时配置，排错时可在不重建二进制的情况下动态打开（例如由配置文件或命令行驱动）
• IDE 事件日志：启用 ltOutputDebugString 时，在调试器下运行的输出会出现在 RAD Studio 事件日志或 DebugView 中
• 文件轮转：门面每次写入时追加到 FileName，示例中在配置前删除旧文件以保证干净跟踪；生产环境可自行按大小或日期轮转

另请参阅

• THotPDF.LoadFromFile Method
• THotPDF.CreatePreflightReport Method
• Preflight Reports Overview