Puppeteer生成PDF中SVG path未标记致WCAG2 PAC2021检测失败

我之前处理过类似场景，Puppeteer转PDF时的SVG可访问性问题在PAC检测里很常见，尤其是自动生成的装饰性SVG和Highcharts图表，给你几个可行的解决方向：

1. 确保Puppeteer生成带标记的PDF #

Puppeteer默认可能没有启用完整的可访问性标记生成，调用page.pdf()时必须配置关键参数：

await page.pdf({
  path: 'output.pdf',
  tagged: true, // 生成符合PDF/UA标准的带标签PDF
  printBackground: true, // 确保SVG的填充、背景被正确渲染
  displayHeaderFooter: false, // 避免默认页眉页脚干扰标记结构
  format: 'A4'
});

另外，启动浏览器时建议启用可访问性选项：

const browser = await puppeteer.launch({
  args: ['--enable-accessibility']
});

2. 简化SVG的可访问性标记（不要给每个path单独加） #

PAC工具会把每个<path>视为独立的可访问元素，即使给path加了aria-hidden，Puppeteer转PDF时也可能无法正确映射到PDF标签结构。正确的做法是：

• 装饰性SVG（比如边框、分隔线）：直接给父级<svg>添加aria-hidden="true"和role="presentation"，无需给内部path加属性：

  <svg aria-hidden="true" role="presentation" width="335" height="335" viewBox="0 0 335 335" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path fill-rule="evenodd" clip-rule="evenodd" d="M131" fill="#2E404F"/>
  </svg>
  

• 有实际意义的SVG（比如Highcharts图表）：给SVG加role="img"，配合<title>和<desc>，内部所有path统一设为role="presentation"：

  <svg role="img" aria-labelledby="chart-title" aria-describedby="chart-desc" width="600" height="400">
    <title id="chart-title">月度销售趋势图</title>
    <desc id="chart-desc">2024年1-6月产品A销售额从10万增长到35万，整体呈上升趋势</desc>
    <path role="presentation" d="..."/>
    <path role="presentation" d="..."/>
  </svg>
  

3. Highcharts图表的针对性配置 #

Highcharts自带可访问性配置，开启后会自动处理SVG内部元素的标记，无需手动修改：

Highcharts.chart('container', {
  accessibility: {
    enabled: true,
    description: '月度销售趋势图：2024年1-6月产品A销售额逐月增长'
  },
  title: {
    text: '月度销售趋势图'
  },
  // 其他图表配置...
});

开启后，Highcharts会自动给SVG添加正确的ARIA属性，把内部线条、柱状等path标记为装饰性元素，PAC检测时不会再报未标记项。

4. 生成PDF前批量预处理SVG元素 #

如果页面中有大量自动生成的SVG（比如来自CSS框架的装饰元素），可以在Puppeteer生成PDF前，通过page.evaluate()批量修改：

await page.evaluate(() => {
  // 处理无意义的装饰性SVG
  document.querySelectorAll('svg:not([aria-labelledby])').forEach(svg => {
    svg.setAttribute('aria-hidden', 'true');
    svg.setAttribute('role', 'presentation');
    svg.querySelectorAll('path').forEach(path => path.setAttribute('role', 'presentation'));
  });
  // 处理有实际意义的SVG
  document.querySelectorAll('svg[aria-labelledby]').forEach(svg => {
    svg.setAttribute('role', 'img');
    svg.querySelectorAll('path').forEach(path => path.setAttribute('role', 'presentation'));
  });
});

5. 验证手动打印的PDF是否正常 #

先手动用Chrome打开页面，通过「打印」功能生成PDF（确保勾选「生成带标签的PDF」），再用PAC检测。如果手动生成的PDF没问题，说明问题出在Puppeteer的配置上，重点检查tagged: true等参数是否正确设置。

内容的提问来源于stack exchange，提问作者Foxlab