基于PDF原生坐标在pdf.js画布中高亮区域的位置校准问题

我之前在项目里也遇到过完全一样的问题！折腾了好一阵才搞明白，核心是PDF的坐标体系和浏览器DOM的坐标体系差异巨大，再加上pdf.js的视口缩放、旋转，必须做精准的坐标转换才能让高亮div对齐目标区域。下面是我总结的解决步骤和代码示例：

先搞懂两个坐标体系的差异 #

• PDF原生坐标：以页面左下角为原点，Y轴向上延伸，单位是“用户空间单位”（通常对应1/72英寸）。
• 浏览器DOM/视口坐标：以元素左上角为原点，Y轴向下延伸，单位是像素。

pdf.js的Viewport对象就是连接这两个体系的桥梁，它会帮我们处理缩放、旋转、坐标翻转这些复杂转换。

精准转换的步骤 #

1. 获取与渲染一致的Viewport #

当你用pdf.js渲染PDF页面时，一定要用**相同的缩放比例（scale）和旋转角度（rotation）**创建Viewport，否则转换出来的坐标肯定错位。

// 假设已经加载了PDF页面对象page
const currentScale = 1.5; // 你渲染PDF时用的缩放比例
const currentRotation = 0; // 页面旋转角度（0/90/180/270）
const viewport = page.getViewport({ scale: currentScale, rotation: currentRotation });

2. 格式化Nuance OCR返回的PDF坐标 #

Nuance返回的PDF区域坐标通常是类似left, bottom, right, top或者x, y, width, height的格式，你需要先把它转成pdf.js要求的**[minX, minY, maxX, maxY]**数组（对应PDF原生坐标的左下角到右上角）：

• 如果是left, bottom, right, top：直接用[left, bottom, right, top]
• 如果是x, y, width, height：转换为[x, y, x+width, y+height]

3. 转换为视口坐标 #

用Viewport的convertToViewportRectangle()方法一键完成转换，这个方法会自动处理坐标翻转、缩放和旋转：

// 假设Nuance返回的PDF原生区域是 [100, 200, 300, 400]
const pdfRect = [100, 200, 300, 400];
const viewportRect = viewport.convertToViewportRectangle(pdfRect);

viewportRect现在就是浏览器视口下的坐标数组，格式为[x1, y1, x2, y2]，对应DOM元素的左上角(x1,y1)到右下角(x2,y2)。

4. 渲染高亮Div #

把高亮Div绝对定位到转换后的坐标，注意父容器必须设置position: relative，这样Div才会相对于PDF渲染容器定位：

const highlightDiv = document.createElement('div');
highlightDiv.style.cssText = `
  position: absolute;
  left: ${viewportRect[0]}px;
  top: ${viewportRect[1]}px;
  width: ${viewportRect[2] - viewportRect[0]}px;
  height: ${viewportRect[3] - viewportRect[1]}px;
  border: 2px solid rgba(255, 0, 0, 0.6);
  background-color: rgba(255, 0, 0, 0.15);
  pointer-events: none; /* 避免干扰PDF的交互（比如滚动、选择） */
`;

// 假设你的PDF渲染容器id是pdf-container，且已设置position: relative
document.getElementById('pdf-container').appendChild(highlightDiv);

处理PDF缩放/旋转的动态更新 #

如果你的页面支持缩放或旋转PDF，需要在缩放/旋转后重新计算Viewport和高亮Div的位置：

function updateHighlight(page, newScale, newRotation, highlightDiv) {
  const updatedViewport = page.getViewport({ scale: newScale, rotation: newRotation });
  const pdfRect = [100, 200, 300, 400]; // 原始PDF坐标，不用变
  const updatedRect = updatedViewport.convertToViewportRectangle(pdfRect);
  
  highlightDiv.style.left = `${updatedRect[0]}px`;
  highlightDiv.style.top = `${updatedRect[1]}px`;
  highlightDiv.style.width = `${updatedRect[2] - updatedRect[0]}px`;
  highlightDiv.style.height = `${updatedRect[3] - updatedRect[1]}px`;
}

常见坑点提醒 #

• 确保父容器设置position: relative，否则Div会相对于整个页面定位，导致错位。
• 确认Nuance返回的是PDF的用户空间坐标，而不是裁剪框（Crop Box）或媒体框（Media Box）坐标，如果是后者需要先转换为用户空间坐标。
• 旋转PDF时，Viewport的rotation参数必须和渲染时完全一致，否则转换后的坐标会旋转错位。

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