动态 PDF 条件渲染：基于读取者身份的客户端混合方案

在 B2B SaaS 和企业文档系统中，同一份 PDF 往往需要面向不同角色呈现差异化内容 —— 销售看到报价明细，法务看到合规条款，而高管仅览摘要。传统方案依赖服务端生成多版本 PDF，维护成本高且实时性差。本文探讨一种客户端混合方案：利用 PDF.js 的双层渲染架构，在浏览器端基于读取者身份动态控制内容可见性。

核心挑战与架构选择

PDF 作为静态文档格式，本身不具备 "条件内容" 语义。实现动态渲染的关键在于将 PDF 内容分层处理：底层为固定视觉层（Canvas 渲染的 PDF 页面），上层为可编程的文本与交互层（TextLayer + DOM 覆盖层）。这种分层架构允许我们在不修改 PDF 源文件的前提下，通过 JavaScript 控制上层内容的显隐与注入。

PDF.js 作为 Mozilla 开源的客户端渲染引擎，天然支持这种双层模型。其渲染流程分为两个阶段：首先将 PDF 页面绘制到 Canvas 元素（视觉保真），然后基于 getTextContent() 提取的文本信息，在 Canvas 上方生成可交互的 TextLayer（支持文本选择与搜索）。这一设计为条件渲染提供了理想的介入点。

身份识别与内容映射

客户端条件渲染的前提是建立 "身份 → 可见内容" 的映射规则。实践中通常采用以下数据流：

1. 身份令牌解析：从 JWT 或 Session 中提取用户角色（role）与权限位（permissions）
2. 内容标记匹配：PDF 源文件需预先嵌入结构化标记（如 PDF/UA 标准的 Section 标签，或通过书签 / 命名目的地标识内容区块）
3. 渲染策略执行：根据身份匹配结果，决定渲染哪些页面、显示哪些 TextLayer 区块、注入哪些动态覆盖层

以合同文档为例，可在 PDF 生成阶段为敏感条款添加命名目的地（Named Destination）如 pricing-details 或 legal-risks。客户端渲染时，若当前用户角色不包含 finance 权限，则在 TextLayer 渲染阶段跳过对应文本块的生成，同时在 Canvas 上方添加遮罩层覆盖视觉内容。

条件渲染实现模式

模式一：TextLayer 选择性渲染

这是最轻量的实现方式。PDF.js 的 renderTextLayer API 允许传入自定义容器元素，通过控制容器的显隐即可实现文本级条件渲染。

// 伪代码示意
const viewport = page.getViewport({ scale: 1.5 });
const textContent = await page.getTextContent();

// 根据身份过滤文本项
const filteredContent = filterByRole(textContent, currentUser.role);

await pdfjs.renderTextLayer({
  textContent: filteredContent,
  container: textLayerDiv,
  viewport
});

此模式的优势在于保持 PDF 视觉完整性，仅控制文本层的可访问性。但需注意：Canvas 上的视觉内容仍然存在，敏感信息可通过截图获取，因此仅适用于非高敏感场景。

模式二：DOM 覆盖层注入

对于需要动态插入内容的场景（如显示 "内部资料" 水印、添加角色特定的批注），可在 TextLayer 之上叠加自定义 DOM 元素。

// 基于页面坐标定位覆盖层
const overlay = document.createElement('div');
overlay.className = 'conditional-banner';
overlay.style.position = 'absolute';
overlay.style.left = `${viewport.width * 0.1}px`;
overlay.style.top = `${viewport.height * 0.05}px`;
overlay.textContent = `${currentUser.department} 内部版本`;
viewerContainer.appendChild(overlay);

覆盖层定位需与 PDF 页面坐标系对齐，建议使用 PDF.js 的 convertToViewportPoint 方法进行坐标转换。

模式三：页码级条件渲染

当内容差异以页面为单位时，可在文档加载阶段即过滤页码列表。

const rolePageMap = {
  'executive': [1, 2, 8],      // 仅摘要页
  'finance': [1, 3, 4, 5, 8],  // 含财务详情
  'legal': [1, 6, 7, 8]       // 含法务条款
};

const allowedPages = rolePageMap[currentUser.role] || [1, 8];

此模式实现简单，但粒度较粗，适合章节级权限控制。

安全边界与性能考量

客户端方案的核心风险在于 "隐藏不等于删除"。PDF 源文件仍包含全部内容，具备技术能力的用户可通过直接下载 PDF 或分析网络请求获取完整数据。因此，客户端条件渲染应被视为 "体验层优化" 而非 "安全层控制"。

对于真正敏感的内容，建议采用以下混合策略：

• 服务端预分段：将 PDF 按敏感级别拆分为多个文件，客户端根据身份请求对应片段
• 服务端动态合成：使用 PDF 库（如 pdf-lib.js）在服务端按需合并页面，再推送至客户端
• 客户端解密层：PDF 内容以加密形式传输，客户端根据身份令牌解密特定区块

性能方面，TextLayer 渲染是 CPU 密集型操作。当条件逻辑涉及大量 DOM 操作时，建议：

• 使用 requestAnimationFrame 批量处理覆盖层注入
• 对频繁切换的身份场景，预渲染多版本 TextLayer 并缓存
• 设置渲染超时阈值（如 500ms），超时后降级为完整渲染

可落地参数清单

总结

基于 PDF.js 的条件渲染方案为同一份文档的多角色适配提供了轻量路径。其核心价值在于将 "内容生成" 与 "内容呈现" 解耦：PDF 源文件保持单一来源，客户端根据运行时身份动态调整可见层。然而，开发者需清醒认识其安全边界 —— 客户端隐藏无法替代服务端权限控制。对于高敏感场景，建议将客户端渲染作为体验增强层，配合服务端的内容分段或动态合成，构建完整的身份感知文档系统。

资料来源

• Mozilla PDF.js 官方文档与 TextLayer API 实现
• PDF.js 社区关于条件渲染与文本层覆盖的实践讨论

web