autoUpdate

import {autoUpdate} from '@floating-ui/dom';

为了确保浮动元素保持锚定到其参考元素，例如在滚动和调整屏幕大小时，需要在必要时不断更新其位置。

¥To ensure the floating element remains anchored to its reference element, such as when scrolling and resizing the screen, its position needs to be continually updated when necessary.

为了解决这个问题，autoUpdate() 添加了监听器，这些监听器将自动调用更新函数，该更新函数在必要时调用 computePosition()。更新通常只需要大约 1 毫秒。

¥To solve this, autoUpdate() adds listeners that will automatically call an update function which invokes computePosition() when necessary. Updates typically take only ~1ms.

用法

¥Usage

重要的是，仅当浮动元素在屏幕上打开时才调用/设置此函数，并在删除浮动元素时清除该函数。否则，可能会导致严重的性能下降，尤其是在创建许多浮动元素时。

¥It’s important that this function is only called/set-up when the floating element is open on the screen, and cleaned up when it’s removed. Otherwise, it can cause severe performance degradation, especially with many floating elements being created.

仅当浮动元素打开或安装时才调用 autoUpdate()：

¥Call autoUpdate() only when the floating element is open or mounted:

// This function will get called repeatedly.
function updatePosition() {
  computePosition(referenceEl, floatingEl).then(({x, y}) => {
    // ...
  });
}
 
// Mount the floating element to the DOM, such as on hover
// or click.
document.body.append(floatingEl);
// Start auto updates.
const cleanup = autoUpdate(
  referenceEl,
  floatingEl,
  updatePosition,
);

然后，当用户悬停或单击离开时，卸载浮动元素并确保调用清理函数来停止自动更新：

¥Then, when the user unhovers or clicks away, unmount the floating element and ensure you call the cleanup function to stop the auto updates:

// Remove the floating element from the DOM, such as on blur
// or outside click.
floatingEl.remove();
// Stop auto updates.
cleanup();

选项

¥Options

这些是你可以作为第四个参数传递给 autoUpdate() 的选项。

¥These are the options you can pass as a fourth argument to autoUpdate().

interface AutoUpdateOptions {
  ancestorScroll?: boolean;
  ancestorResize?: boolean;
  elementResize?: boolean;
  layoutShift?: boolean;
  animationFrame?: boolean;
}

ancestorScroll

默认：true

¥default: true

滚动溢出祖级时是否更新位置。

¥Whether to update the position when an overflow ancestor is scrolled.

const cleanup = autoUpdate(referenceEl, floatingEl, update, {
  ancestorScroll: false,
});

ancestorResize

默认：true

¥default: true

调整溢出祖级的大小时是否更新位置。这使用了 resize 事件。

¥Whether to update the position when an overflow ancestor is resized. This uses the resize event.

const cleanup = autoUpdate(referenceEl, floatingEl, update, {
  ancestorResize: false,
});

elementResize

默认：true

¥default: true

当参考元素或浮动元素调整大小时是否更新位置。这使用了 ResizeObserver。

¥Whether to update the position when either the reference or floating elements resized. This uses a ResizeObserver.

const cleanup = autoUpdate(referenceEl, floatingEl, update, {
  elementResize: false,
});

layoutShift

默认：true

¥default: true

如果参考元素因布局移动而在屏幕上移动，是否更新浮动元素的位置。

¥Whether to update the position of the floating element if the reference element moved on the screen as the result of layout shift.

const cleanup = autoUpdate(referenceEl, floatingEl, update, {
  layoutShift: false,
});

animationFrame

默认：false

¥default: false

如果需要，是否更新每个动画帧上浮动元素的位置。虽然针对性能进行了优化，但在以下情况下应谨慎使用：

¥Whether to update the position of the floating element on every animation frame if required. While optimized for performance, it should be used sparingly in the following cases:

• 参考元素在屏幕上以 transform 的形式渲染动画。

  ¥The reference element is animating on the screen with transforms.

• 确保嵌套浮动元素在祖级浮动元素的滚动上下文之外时被锚定。

  ¥Ensure a nested floating element is anchored when it’s outside of ancestor floating elements’ scrolling contexts.

const cleanup = autoUpdate(referenceEl, floatingEl, update, {
  animationFrame: true,
});