技术文章

PDF/UA-1 与 PDF/UA-2:变了的无障碍规则

内部 PDF/UA-1 检查清单拒收一份 veraPDF 放行的 PDF/UA-2 导出,点名一个标了 /ActualText () 的 Figure、没有 /Contents 的链接注释,以及一棵混用命名空间的结构树。三者都符合 ISO 14289-2:2024,所以规则集必须跟随每个文件声明的部分——这正是 PDFium Component 的 TPdf.ValidatePdfUa 读的第一样东西

声明的 pdfuaid:part 切换 Delphi 版 PDFium Component 的 PDF/UA 规则集,同一个 issue 值在 PDF/UA-1 与 PDF/UA-2 下指不同规则
XMP 里声明的部分挑选规则集,同一个 issue 值在 PDF/UA-1 与 PDF/UA-2 之间可以指两条不同规则

声明的部分决定适用哪些规则

每份 PDF/UA 文件都在 XMP 元数据里用 pdfuaid:part 报出部分,PDF/UA-2 又自加两个条件:一个 revision 条目和一份声明 PDF 2.0 的文件。这个声明就是开关。TPdf.ValidatePdfUa 返回 TPdfUaValidationResult,其 Conformance 字段报 puc1 或 puc2、确认不声称 PDF/UA 的文件报 pucNone、无法确定时报 pucUnknown,其 Issues 集只装适用于该部分的发现项。有些 issue 值在第 1 部分指一条规则,在第 2 部分指更宽的一条:第 1 部分文件上的 pvuaiActionTargetMissing 意思是 GoToR、URI 或 SubmitForm 动作缺目标键(§7.18.5);第 2 部分文件上它还可以指一个不通向结构元素的目标(§8.8)。第 2 部分文件上的 pvuaiAnnotationMissingContents 还包括没有标签的 widget。所以每份报告都把部分印在旁边:

uses
  SysUtils, TypInfo, PDFium, FPdfPdfua;

procedure ReportPdfUa(const FileName: string);
const
  PartNames: array[TPdfUaConformance] of string =
    ('unknown', 'not PDF/UA', 'PDF/UA-1', 'PDF/UA-2');
var
  Pdf: TPdf;
  Report: TPdfUaValidationResult;
  Issue: TPdfUaValidationIssue;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := FileName;
    Pdf.Active := True;
    if not Pdf.Active then
      raise Exception.CreateFmt('Cannot open %s', [FileName]);

    Report := Pdf.ValidatePdfUa;
    Writeln(Format('%s: %s, compliant=%s', [ExtractFileName(FileName),
      PartNames[Report.Conformance], BoolToStr(Report.IsCompliant, True)]));
    for Issue := Low(TPdfUaValidationIssue) to High(TPdfUaValidationIssue) do
      if Issue in Report.Issues then
        Writeln('  ', GetEnumName(TypeInfo(TPdfUaValidationIssue), Ord(Issue)));
  finally
    Pdf.Free;
  end;
end;

IsCompliant 只在部分为 1 或 2 且 issue 集为空时为真,没有 PDF/UA 声明的文件绝不会意外报成合规。跟 veraPDF 对比另有一个坑:命令行工具对不合规文件以退出码 1 结束,但完整的 XML 报告仍写到标准输出,看到退出码就停的脚本把规则编号全扔了。要读报告

哪些 UA-1 指控在 PDF/UA-2 下是误报?

开头示例里的每条指控适用的都是 PDF/UA-2 没有以该形式收录的规则。先说 Figure,错误多半出在解析代码里。ISO 14289-2 §8.2.5.28.2 要求 Figure 带 /Alt 或 /ActualText 键,测试的是键是否存在:/ActualText () 合规,两个键都没有的 Figure 才失败。把两种值都存进普通字符串的读取器,会把“存在但为空”与“不存在”塌缩成同一个 '',校验器于是给一个有替代文本的 Figure 报缺失。解析结构元素时,在每个字符串旁边存一个存在旗标。空的 /ActualText 是个孱弱的描述,人工审阅者可能仍想看到它,但第 2 部分校验器没有判它失败的依据

链接规则没了。PDF/UA-1 §7.18.5 要求每个链接注释带 /Contents;PDF/UA-2 没有在原地放注释键规则,而是在 §8.2.5.20 约束结构。通向不同目标的注释必须分居不同的 Link 或 Reference 结构元素,所以一个既包住跳到第 2 章、又包住外站 URI 的单一 Link 元素,两个注释都带 /Contents 也过不了第 2 部分。两个部分测的是不同的东西——一个测注释上的文本,一个测树里的分组。PDFium Component 只对声明第 1 部分的文件应用链接 /Contents 要求

命名空间指控来自读错了文档。ISO 14289-2 §8.2.4 有四条规则:非标准结构类型必须映射到标准类型;映射不得成环;类型不得在同一显式命名空间内映射;标准类型不得重映射成非标准类型。ISO/TS 32005 §5.3 给混用命名空间的文档加了一条建议——共享类型用 PDF 2.0 命名空间——这条建议不在 PDF/UA-2 合规条件之列。在 §5.3 上硬失败的清单会拒掉合法的混合树,比如一棵携带 MathML 公式的 PDF 2.0 树。经 /RoleMapNS 把自定义类型解析到标准类型是另一门功课,带角色映射与命名空间的 PDF/UA-2 校验有讲

三条在 ISO 14289-2 下能过的 PDF/UA-1 清单指控:Figure 上的空 ActualText、链接注释与命名空间混用,Delphi 版 PDFium Component 如此把它们挡在门外
每条指控适用的都是 PDF/UA-2 没有以该形式收录的规则,检查该放在声明的部分后面,而不是塞进一份共享清单

PDF/UA-2 新增或收紧的规则

反方向才是代价高的那边。UA-1 清单放行下面这些文件,失败要等有人跑第 2 部分校验器才现身:

  • Widget 需要标签或描述。PDF/UA-1 §7.18.1 豁免 widget 注释的 /Contents,因为 §7.18.4 的 Form 标签覆盖了它们。PDF/UA-2 §8.10.2.3 要求结构元素没有 Lbl 子元素的 widget 带 /Contents。字段的 /TU 工具提示不算标签
  • 文件附件要声明关系。§8.9.2.4.10 要求 FileAttachment 注释的文件规格带 /AFRelationship——Source、Data、Alternative、Supplement,以及 PDF/A-3 在关联文件与 AFRelationship 里已在用的其他值
  • 标题必须带编号。PDF/UA-1 接受泛用 H 标签或带编号的 H1…Hn 标题,只要一份文档不混用(§7.4.4)。PDF/UA-2 §8.2.5.12 直接禁掉泛用 H,靠普通 H 元素搭起来的标签方案得先重映射,导出才能声称第 2 部分
  • 目标要通向结构。§8.8 要求导航目标是 ISO 32000-2 §12.3.2.3 意义上的结构目标:首元素为结构元素的目标数组,或带 /SD 的 GoTo 动作

老规则别动。清单要长出第 2 部分覆盖时,顺手的改法是删掉 §7.18.1 的 widget 豁免,让没有 /Contents 的 widget 被点名——这一改会让合规的第 1 部分表单栽在它们的规范从来没有过的规则上。正确做法是把第 2 部分 widget 检查加在豁免旁边,并用声明的部分作闸。PDFium Component 报告 widget 规则正是这样:第 1 部分豁免继续生效,第 2 部分下没有标签或 /Contents 的 widget 以 pvuaiAnnotationMissingContents 现身

对比 PDF/UA-1 与 PDF/UA-2 的矩阵:widget 标签、AFRelationship、泛用标题与结构目标,Delphi 版 PDFium Component 按部分设闸的四项检查
第 2 部分的新增规则与第 1 部分规则并行而非取而代之,合规的 PDF/UA-1 表单因此在 Delphi 版 PDFium Component 里继续通过

怎样测结构目标而不误报?

读规范说算数的那把钥匙。ISO 32000-2 表 202 要求每个 GoTo 动作必须有 /D,/SD 可选,两者同在时结构目标优先。合规的第 2 部分链接因此常带着给老阅读器的页面目标(如 /D [6 0 R /Fit])和它旁边的 /SD [19 0 R /Fit]。读 /D 的自制检查会找到一个页面,报一个非结构目标,把文件判失败。动作看 /SD;裸目标数组就跟着它的首元素走,问被引用的字典是不是结构元素——按字节论,就是带顶层 /S 键的字典

顶层是难啃的部分。页字典照例带着透明组的 /Group << /S /Transparency >>,不跳过嵌套字典的键搜索会找到那个内层 /S,断定页面是结构元素,普通页面目标就此蒙混过关。只扫外层字典的键,把每个值当完整对象跳过,嵌套字典和数组都在内。把注释的 /StructParent 映回其结构元素的 ParentTree 也得同样当心:它的 /Nums 数组可能把键与单个引用配对(0 26 0 R),也可能与数组配对(0 [null 20 0 R]),数组形式下数组内的位置要加到键上才得到 /StructParent 值。只认识第一种形式的解析器,会让第二种形式的注释没有结构父节点,§8.2.5.20 分组规则随之失去比较对象。这些检查也要在按原样加载的字节上跑:重新保存或归一化的副本会重编注释对象号、重建数字树——你编辑页面后保持 /ParentTree 与 /StructParents 同步时重写的正是这棵树

哪些语言标签能过 /Lang 检查?

语法在两个部分之间没变(ISO 14289-1 §7.2、ISO 14289-2 §8.4.4),松垮的清单照样漏。veraPDF 把它写成 ^[a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*$:一至八个字母的首子标签,后跟任意多个一至八个字母或数字的子标签,每个前面带连字符。界限很锋利:portugue-pt 通过,portugues-pt 因九个字母的首子标签失败;nl-1234abcd 通过,nl-1234abcde 失败;1-pt 和 -pt 败在第一个字符上。只测字母、数字和连字符的检查会把这四个失败全放行。catalog 的 /Lang 和每个结构元素的 /Lang 要共用一个测试,否则同一个标签在一份文件里能挣到两个判决。存成 UTF-16BE 字符串的标签(如 <FEFF0045004E002D00550053>)先解码,那一个读出来是 EN-US,通过。坏标签常来自不起眼的地方:Java、ICU 或数据库设置的区域字符串用下划线,pt_BR 不是合法标签。IsPdfUaLanguageTagValid 施行同样的形状测试,标签落盘之前就能修:

uses
  SysUtils, PDFium;

// 把 pt_BR 这类平台区域串转成 PDF/UA 接受的标签,
// 简单替换救不回来时返回 ''
function LocaleToPdfLang(const Locale: string): string;
begin
  Result := StringReplace(Trim(Locale), '_', '-', [rfReplaceAll]);
  if not IsPdfUaLanguageTagValid(Result) then
    Result := '';
end;

procedure CheckTags;
const
  Samples: array[0..6] of string = ('en-US', 'pt_BR', 'zh_CN',
    'portugue-pt', 'portugues-pt', 'nl-1234abcd', 'nl-1234abcde');
var
  S: string;
begin
  // 预期:
  //   en-US、portugue-pt、nl-1234abcd   原样有效
  //   pt_BR、zh_CN                      无效,修成 pt-BR / zh-CN
  //   portugues-pt、nl-1234abcde        无效,修成 ''
  for S in Samples do
    Writeln(Format('%-14s valid=%-5s repaired=%s', [S,
      BoolToStr(IsPdfUaLanguageTagValid(S), True), LocaleToPdfLang(S)]));
end;

在标签进入管线的地方就调转换,趁它还没到 catalog 或任何结构元素。结果为空就是信号,退回文档确定在用的语言。硬把原始区域串写上去只是把失败推到下游,最后以 catalog 的 pvuaiLangInvalidFormat 或元素的 pvuaiStructElementLangInvalid 冒出来,离产生它的代码十万八千里

迁移从开头那段说的导出开始。用 PDFium Component for Delphi 把它过一遍第一个清单里的 ReportPdfUa:表头行应写着 PDF/UA-2,pvuaiFigureMissingAlt、pvuaiLinkMissingContents、pvuaiNamespaceReuseInvalid 都不该在下面出现。旧清单对那份文件仍然提出的任何指控,就是一条该挪到声明部分后面的第 1 部分规则