useHover

import {useHover} from '@floating-ui/react';

用法

¥Usage

该 Hook 返回事件处理程序 props。

¥This Hook returns event handler props.

要使用它，请将 useFloating() 返回的 context 对象传递给它，然后将其结果输入 useInteractions() 数组。然后将返回的 prop getter 传播到元素上进行渲染。

¥To use it, pass it the context object returned from useFloating(), and then feed its result into the useInteractions() array. The returned prop getters are then spread onto the elements for rendering.

function App() {
  const [isOpen, setIsOpen] = useState(false);
 
  const {refs, floatingStyles, context} = useFloating({
    open: isOpen,
    onOpenChange: setIsOpen,
  });
 
  const hover = useHover(context);
 
  const {getReferenceProps, getFloatingProps} = useInteractions([
    hover,
  ]);
 
  return (
    <>
      <div ref={refs.setReference} {...getReferenceProps()}>
        Reference element
      </div>
      {isOpen && (
        <div
          ref={refs.setFloating}
          style={floatingStyles}
          {...getFloatingProps()}
        >
          Floating element
        </div>
      )}
    </>
  );
}

示例

¥Examples

• 默认悬停

  ¥Default hover

属性

¥Props

interface UseHoverProps {
  enabled?: boolean;
  mouseOnly?: boolean;
  delay?: number | Partial<{open: number; close: number}>;
  restMs?: number;
  move?: boolean;
  handleClose?: null | HandleCloseFn;
}

enabled

默认：true

¥default: true

有条件地启用/禁用 Hook。

¥Conditionally enable/disable the Hook.

useHover(context, {
  enabled: false,
});

当你想要根据某些条件禁用进一步的事件触发时，这也很有用。例如，你可以在将鼠标悬停在浮动元素上后禁用钩子，以防止其关闭。

¥This is also useful when you want to disable further events from firing based on some condition. For example, you may disable the hook after hovering over the floating element to then prevent it from closing.

mouseOnly

默认：false

¥default: false

逻辑是否仅针对鼠标输入运行，忽略触摸和笔指针输入。

¥Whether the logic only runs for mouse input, ignoring both touch and pen pointer inputs.

useHover(context, {
  mouseOnly: true,
});

delay

默认：0

¥default: 0

等待事件监听器运行指定的时间，然后再更改 open 状态。

¥Waits for the specified time when the event listener runs before changing the open state.

useHover(context, {
  // Delay opening or closing the floating element by 500ms.
  delay: 500,
 
  // Configure the delay for opening and closing separately.
  delay: {
    open: 500,
    close: 0,
  },
});

restMs

默认：0（离开）

¥default: 0 (off)

等待用户的光标位于参考元素上方的 “rest” 处，然后再更改打开状态。

¥Waits until the user’s cursor is at “rest” over the reference element before changing the open state.

useHover(context, {
  // The user's cursor must be at rest for 150ms before opening.
  restMs: 150,
});

如果用户的光标从不静止，你还可以使用回退延迟，以确保浮动元素最终打开：

¥You can also use a fallback delay if the user’s cursor never rests, to ensure the floating element will eventually open:

useHover(context, {
  restMs: 150,
  // If their cursor never rests, open it after 1000ms as a
  // fallback.
  delay: {open: 1000},
});

move

默认：true

¥default: true

将光标移动到浮动元素上是否会打开它，而不需要常规的悬停事件。

¥Whether moving the cursor over the floating element will open it, without a regular hover event required.

例如，如果它在关闭时停留在参考元素上。使用 'mousemove' 事件。

¥For example, if it was resting over the reference element when it closed. Uses the 'mousemove' event.

useHover(context, {
  move: false,
});

handleClose

默认：null

¥default: null

当光标离开其引用时，我们可以将其保持打开状态，直到满足特定条件，而不是关闭浮动元素。

¥Instead of closing the floating element when the cursor leaves its reference, we can leave it open until a certain condition is satisfied.

该包导出一个 safePolygon() 处理程序，如果指针位于动态计算的多边形区域之外，该处理程序将仅关闭浮动元素。

¥The package exports a safePolygon() handler which will only close the floating element if the pointer is outside a dynamically computed polygon area.

这允许用户将光标从参考元素移向浮动元素而不关闭它（例如，它内部有交互式内容）。

¥This allows the user to move the cursor off the reference element and towards the floating element without it closing (e.g. it has interactive content inside).

import {useHover, safePolygon} from '@floating-ui/react';
 
useHover(context, {
  handleClose: safePolygon(),
});

该处理程序在 mousemove 上运行。

¥This handler runs on mousemove.

对于更简单的替代方案，根据浮动元素的类型，你可以使用较短的关闭延迟。

¥For a simpler alternative, depending on the type of floating element, you can use a short close delay instead.

safePolygon

”safe” 多边形是指针在悬停后离开参考元素并移向浮动元素时可以安全遍历的多边形。如果指针移出此安全区域，浮动元素将关闭。

¥A “safe” polygon is one that a pointer is safe to traverse as it moves off the reference element and toward the floating element after hovering it. If the pointer moves outside of this safe area, the floating element closes.

它是一个动态多边形（矩形或三角形），一旦光标离开参考元素，就会产生该多边形。三角形看起来像这样：

¥It is a dynamic polygon (either a rect or a triangle) originating from the cursor once it leaves a reference element. The triangle looks like this:

该函数需要选项。

¥This function takes options.

requireIntent

默认：true

¥default: true

确定生成三角形多边形是否需要意图（即，光标足够快地移向浮动元素）。无论意图如何，false 都会使三角形保持活动状态。

¥Determines whether intent is required for the triangle polygon to be generated (that is, the cursor is moving quickly enough toward the floating element). false will keep the triangle active no matter the intent.

useHover(context, {
  handleClose: safePolygon({
    requireIntent: false,
  }),
});

当参考元素彼此靠近放置并且每个参考元素都附加了一个可悬停浮动元素时，true 确保其他附近参考的悬停事件不会被过度阻止。

¥When reference elements are placed near each other and they each have a hoverable floating element attached, true ensures that hover events for the other nearby references aren’t too aggressively blocked.

buffer

默认：0.5

¥default: 0.5

确定多边形周围的缓冲区量（以像素为单位）。

¥Determines the amount of buffer (in pixels) there is around the polygon.

虽然默认值应该可以正确处理绝大多数情况，但如果你发现当指针尝试移向浮动元素时浮动元素意外关闭，请尝试增加此值。

¥While the default value should handle the vast majority of cases correctly, if you find your floating element is closing unexpectedly as the pointer tries to move toward the floating element, try increasing this value.

useHover(context, {
  handleClose: safePolygon({
    buffer: 1,
  }),
});

忽略三角形

¥Ignoring the triangle

如果只想考虑参考元素和浮动元素之间的偏移部分（矩形桥），可以将该值设置为 -Infinity。

¥If you only want the offset portion (rectangle bridge) between the reference and floating elements to be considered, you can set the value to -Infinity.

useHover(context, {
  handleClose: safePolygon({
    // Don't generate a triangle polygon, only consider the
    // rectangular bridge between the elements.
    buffer: -Infinity,
  }),
});

blockPointerEvents

默认：false

¥default: false

多边形、参考和浮动元素后面的 CSS pointer-events 是否被遮挡。这可确保用户在遍历多边形时不会无意中触发其他元素上的悬停事件。

¥Whether CSS pointer-events behind the polygon, reference, and floating elements are blocked. This ensures the user does not fire hover events over other elements unintentionally while they traverse the polygon.

useHover(context, {
  handleClose: safePolygon({
    blockPointerEvents: true,
  }),
});

这可能会导致监听 mouseleave 事件的容器元素触发。在旧版本的 Chrome (<114) 中，当指针位于浮动元素上方时，滚动容器无法滚动（主窗口不受影响）。

¥This can cause container elements that listen for mouseleave events to fire. In older versions of Chrome (<114), scrolling containers can’t be scrolled while the pointer is over the floating element (the main window remains unaffected).

[data-floating-ui-safe-polygon] 选择器可用作父选择器，因此滚动容器可以否定 pointer-events 样式：

¥A [data-floating-ui-safe-polygon] selector is available as a parent, so scrolling containers can negate the pointer-events style:

[data-floating-ui-safe-polygon] .scroll {
  pointer-events: auto;
}
 
[data-floating-ui-safe-polygon] .scroll > div {
  pointer-events: none;
}

<div className="scroll">
  <div>
    Content inside here will remain blocked without affecting the
    scrolling parent.
  </div>
</div>