useMouse

跟踪鼠标位置。

useMouse 通过监听 mousemove 事件，在多个坐标系中跟踪鼠标光标位置。它返回一个包含 screenX/screenY（相对于屏幕）、clientX/clientY（相对于视口）、pageX/pageY（相对于文档）和 elementX/elementY/elementW/elementH/elementPosX/elementPosY（如果提供了目标元素，则相对于该元素）的对象。所有值在光标移动时实时更新。

使用场景

• 构建跟随鼠标位置的自定义光标、工具提示或上下文菜单
• 实现拖拽交互、绘图画布或视差效果
• 跟踪相对于特定元素的鼠标位置，用于基于悬停的可视化

注意事项

• SSR 安全：在服务端渲染期间所有坐标返回 0。服务端不会附加 mousemove 监听器。
• 元素相对坐标：传递一个 DOM 元素的 ref 还可以获取相对于该元素的坐标，包括其尺寸和位置。
• 相关 hooks：参见 useMousePressed 了解按压状态跟踪，以及 useElementByPoint 了解检测光标下方的元素。

Usage

function Demo() {
  const mouse = useMouse();

  return (
    <div>
      <p>
        客户端 - x: {mouse.clientX}, y: {mouse.clientY}
      </p>
      <p>
        页面 - x: {mouse.pageX}, y: {mouse.pageY}
      </p>
      <p>
        屏幕 - x: {mouse.screenX}, y: {mouse.screenY}
      </p>
    </div>
  );
};

API

useMouse

Returns

UseMouseCursorState: 鼠标位置

Arguments

UseMouseCursorState

Type

export interface UseMouseCursorState { screenX: number screenY: number clientX: number clientY: number pageX: number pageY: number elementX: number elementY: number elementH: number elementW: number elementPosX: number elementPosY: number }

BasicTarget

export type BasicTarget<T extends TargetType = Element> = (() => TargetValue<T>) | TargetValue<T> | MutableRefObject<TargetValue<T>>;

TargetValue

type TargetValue<T> = T | undefined | null;

TargetType

type TargetType = HTMLElement | Element | Window | Document | EventTarget;