解决JS获取鼠标位置时页面滚动导致的坐标偏差

一、坐标偏差产生的根本原因与坐标系辨析

当我们在浏览器中移动鼠标时，底层硬件捕获的光标位置本身是基于操作系统的物理屏幕像素。浏览器接收到系统事件后，会向 DOM 事件监听器派发一个 MouseEvent 实例。该实例暴露了多组不同语义的坐标属性，初学者常因命名直觉而用错属性：

• clientX / clientY（视口坐标）：以浏览器当前可视窗口（Viewport）左上角为原点 (0, 0)。无论整篇文档有多长、当前滚动了多少像素，屏幕可视区最顶端始终是 clientY = 0。一旦页面向下滚动，文档中原本的内容向上移出了可视区，同一个 DOM 节点在视口里的 clientY 就会持续递减。
• pageX / pageY（文档坐标）：以整篇 HTML 文档（Document）的根部左上角为原点 (0, 0)。即使页面滚动了几千像素，文档原点始终固定在最顶部。因此，同一个静态内容在文档中的 pageY 是恒定不变的。
• offsetX / offsetY（事件目标局部坐标）：表示鼠标指针相对于触发事件的目标节点（e.target）内边距边缘的坐标。虽然它看似直接给出了局部坐标，但在复杂的 DOM 嵌套、包含子元素冒泡或伪元素场景下，e.target 会频繁在子孙节点之间切换，导致数值剧烈跳变，因而在严谨工程中极不可靠。
• screenX / screenY（屏幕坐标）：以用户物理显示器屏幕左上角为原点，通常仅用于多窗口通信或独立弹窗定位，无法直接用于网页内部排版。

如上图所示，当页面向下滚动了 window.scrollY 距离后，视口原点相对于文档原点下移。此时鼠标在文档中的绝对垂直高度与在视口中的垂直高度满足如下严格几何等式：

// 视口与文档绝对坐标换算公式
pageY = clientY + window.scrollY;
pageX = clientX + window.scrollX;

二、获取页面全局坐标的标准解法与兼容处理

当你的业务目标是将一个绝对定位（position: absolute）且直接挂载在 <body> 根节点下的元素精准移动到鼠标位置时，你需要的是文档坐标。

1. 现代浏览器标准用法：直接读取 pageX / pageY

在所有现代浏览器中，MouseEvent.prototype.pageX 和 MouseEvent.prototype.pageY 均已获得原生支持，其返回值已自动包含了当前页面的垂直与水平滚动位移：

// 随文档滚动的绝对定位元素（如气泡提示、跟随光标）
document.addEventListener('click', (event) => {
  const tooltip = document.getElementById('my-tooltip');
  
  // 直接使用 pageX / pageY，无需手动累加 scroll 距离
  tooltip.style.left = `${event.pageX}px`;
  tooltip.style.top = `${event.pageY}px`;
});

2. 降级兼容方案与兼容性封装

如果需要兼容非常老旧的运行环境（如旧版 IE 或某些特殊嵌入式 WebKit 内核），pageX/pageY 可能会返回 undefined。此时需要从 clientX/clientY 出发，手动补偿根节点的滚动偏移。需要注意的是，不同历史浏览器对滚动容器的挂载节点存在 window.scrollY、document.documentElement.scrollTop 以及 document.body.scrollTop 的差异：

/**
 * 安全获取相对于文档根部的鼠标绝对坐标（兼容全浏览器环境）
 * @param {MouseEvent} event 原生鼠标事件对象
 * @returns {{x: number, y: number}}
 */
function getDocumentMousePosition(event) {
  // 1. 优先使用标准 pageX / pageY
  if (typeof event.pageX === 'number') {
    return {
      x: event.pageX,
      y: event.pageY
    };
  }

  // 2. 降级：通过视口坐标 + 根节点滚动偏移计算
  const scrollLeft = window.pageXOffset 
    || document.documentElement.scrollLeft 
    || document.body.scrollLeft 
    || 0;

  const scrollTop = window.pageYOffset 
    || document.documentElement.scrollTop 
    || document.body.scrollTop 
    || 0;

  return {
    x: event.clientX + scrollLeft,
    y: event.clientY + scrollTop
  };
}

三、特定元素（Canvas / 拖拽区域）相对坐标的计算法宝

实际开发中更为高频且复杂的场景，是获取鼠标在某个特定容器元素（如 HTML5 <canvas> 画板、图表热区、列表拖拽目标）内部的相对点击位置。许多人会尝试将 e.pageX 减去目标元素的 offsetTop，但当页面中存在复杂的 offsetParent 层级、内联滚动或 margin 塌陷时，递归累加 offsetTop 不仅性能低下且极其容易漏算。

1. 最佳实践：基于 getBoundingClientRect() 的天然自抵消机制

现代 Web 开发解决元素内定位的标准方案，是调用目标元素的 getBoundingClientRect() 方法。该方法返回目标元素在当前视口中的几何包围盒（包含 left, top, right, bottom, width, height）。

令人拍案叫绝的数学特性在于：event.clientX/clientY 和 rect.left/top 的参考系完全一致，都是当前的浏览器视口！当页面发生滚动时，鼠标的视口坐标与元素的包围盒坐标会同时发生等量的位移偏差。将二者做差，外层的滚动位移量在代数上被完全减去，从而彻底免疫页面滚动：

/**
 * 获取鼠标相对于指定 DOM 元素内部左上角的内容坐标
 * @param {MouseEvent} event 鼠标事件对象
 * @param {HTMLElement} targetElement 目标参考元素
 * @returns {{x: number, y: number}}
 */
function getElementRelativeCoords(event, targetElement) {
  // 获取元素在视口中的几何边界信息
  const rect = targetElement.getBoundingClientRect();

  // 视口坐标相减：天然消解外部页面 window.scrollY / scrollX 的影响
  const x = event.clientX - rect.left;
  const y = event.clientY - rect.top;

  return { x, y };
}

2. 精度细节补偿：边框（Border）与盒模型内衬

rect.left 和 rect.top 计算的是元素外边框的外沿起点。如果你的业务（例如在带有边框的 Canvas 上进行像素级点阵绘制）要求坐标严格对齐内容区（Content Box），还需要将元素的左边框和上边框厚度扣除。在 DOM API 中，边框厚度可以通过 clientLeft 和 clientTop 极其便捷地获取：

// 扣除边框后的纯内容区坐标计算
function getCanvasPreciseCoords(event, canvas) {
  const rect = canvas.getBoundingClientRect();
  
  // 扣除 CSS 边框宽度
  const borderLeft = canvas.clientLeft || 0;
  const borderTop = canvas.clientTop || 0;

  return {
    x: event.clientX - rect.left - borderLeft,
    y: event.clientY - rect.top - borderTop
  };
}

四、复杂嵌套滚动与 CSS 缩放的边界处理

在实际企业级应用（如低代码设计器、数据可视化大屏、在线富文本编辑器）中，往往还会叠加两个特殊变量：局部容器自身的可滚动性与 CSS Transform 缩放。

1. 局部滚动容器（overflow: auto / scroll）的内坐标计算

如果目标元素内部有自己的滚动条（例如一个固定高度 height: 400px; overflow-y: scroll; 的长内容容器），当我们点击容器内部时，如果希望知道光标落在整个超长内容的第多少像素，就必须把容器自身的 scrollTop 补回来：

// 嵌套滚动容器：获取相对于容器内部长内容的绝对坐标
const rect = scrollContainer.getBoundingClientRect();
const contentX = (event.clientX - rect.left) + scrollContainer.scrollLeft;
const contentY = (event.clientY - rect.top) + scrollContainer.scrollTop;

2. CSS transform: scale() 缩放比例还原

许多数据看板或画布支持通过 transform: scale(0.8) 进行缩放展示。此时 rect.width 会变成元素的实际渲染像素（原始宽度 * 0.8）。如果不做比例矫正，鼠标移动 100px 对应到内部逻辑系统只有 80px，造成严重的比例漂移。修正公式如下：

// 消除 CSS scale 缩放引起的坐标畸变
function getScaledCoords(event, element) {
  const rect = element.getBoundingClientRect();
  
  // 计算 CSS 渲染尺寸与元素实际内部像素尺寸的比例
  const scaleX = element.offsetWidth > 0 ? (rect.width / element.offsetWidth) : 1;
  const scaleY = element.offsetHeight > 0 ? (rect.height / element.offsetHeight) : 1;

  // 将视口相对距离换算回未缩放状态下的逻辑像素
  return {
    x: (event.clientX - rect.left) / scaleX,
    y: (event.clientY - rect.top) / scaleY
  };
}

五、场景决策速查与工程化整合

为了在团队项目中形成规范，建议将鼠标坐标计算封装为通用的工具类或 Hook。在决定使用哪套计算公式前，可以对照下表快速匹配业务意图：