detectOverflow

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

剪切容器（或边界）是一种如果其内部的子元素溢出则导致其被剪切的容器。可见性优化器中间件使用此函数进行冲突检测，这对于你自己执行相同操作的自定义中间件非常有用。

¥A clipping container (or boundary) is one that causes child elements inside it to be clipped if they overflow it. Visibility optimizer middleware use this function for collision detection, making it useful for your own custom middleware that do the same.

用法

¥Usage

在你的自定义中间件中，将其设置为 fn async 和 await，并传入中间件 state：

¥Inside your custom middleware, make your fn async and await it, passing in the middleware state:

const middleware = {
  name: 'middleware',
  async fn(state) {
    const overflow = await detectOverflow(state);
    return {};
  },
};

返回值 overflow 是一个 SideObject，其中包含带有表示偏移量的数字的侧面属性。

¥The returned value, overflow, is a SideObject containing side properties with numbers representing offsets.

• 正数表示元素超出了裁剪边界的像素数。

  ¥A positive number means the element is overflowing the clipping boundary by that number of pixels.

• 负数意味着元素在溢出剪切边界之前还剩下一定数量的像素。

  ¥A negative number means the element has that number of pixels left before it will overflow the clipping boundary.

• 0 表示该边与剪切边界齐平。

  ¥0 means the side lies flush with the clipping boundary.

选项

¥Options

detectOverflow() 将选项作为第二个参数。

¥detectOverflow() takes options as a second argument.

await detectOverflow(state, {
  // options
});

interface DetectOverflowOptions {
  boundary: Boundary;
  rootBoundary: RootBoundary;
  elementContext: ElementContext;
  altBoundary: boolean;
  padding: Padding;
}

boundary

type Boundary =
  | 'clippingAncestors'
  | Element
  | Array<Element>
  | Rect;

这描述了将相对于检查溢出的剪切元素或区域。默认为 'clippingAncestors'，这是溢出祖级，将导致元素被裁剪。

¥This describes the clipping element(s) or area that overflow will be checked relative to. The default is 'clippingAncestors', which are the overflow ancestors which will cause the element to be clipped.

await detectOverflow(state, {
  boundary: document.querySelector('#container'),
});

rootBoundary

type RootBoundary = 'viewport' | 'document' | Rect;

这描述了将检查元素是否相对于溢出的根边界。默认值为 'viewport'，即用户在屏幕上可以看到的页面区域。这是 视觉视口，当键盘打开时，它可以正确处理捏缩放和移动视口。

¥This describes the root boundary that the element will be checked for overflow relative to. The default is 'viewport', which is the area of the page the user can see on the screen. This is the Visual Viewport which correctly handles pinch-zooming and mobile viewports when the keyboard is open.

另一个字符串选项是 'document'，它是视口之外的整个页面。

¥The other string option is 'document', which is the entire page outside the viewport.

await detectOverflow(state, {
  rootBoundary: 'document', // 'viewport' by default
});

你还可以传递 Rect 对象来定义自定义边界区域（相对于视口）。

¥You may also pass a Rect object to define a custom boundary area (relative to the viewport).

await detectOverflow(state, {
  // Layout viewport, instead of the visual viewport
  rootBoundary: {
    x: 0,
    y: 0,
    width: document.documentElement.clientWidth,
    height: document.documentElement.clientHeight,
  },
});

padding

type Padding =
  | number
  | Partial<{
      top: number;
      right: number;
      bottom: number;
      left: number;
    }>;

这描述了边界周围的虚拟填充以检查溢出。

¥This describes the virtual padding around the boundary to check for overflow.

await detectOverflow(state, {
  // 5px on all sides
  padding: 5,
  // Unspecified sides are 0
  padding: {
    top: 5,
    left: 20,
  },
});

elementContext

type ElementContext = 'reference' | 'floating';

默认情况下，浮动元素是要检查溢出的元素。

¥By default, the floating element is the one being checked for overflow.

但你也可以将上下文更改为 'reference'，以检查其相对于其剪切边界的溢出。

¥But you can also change the context to 'reference' to instead check its overflow relative to its clipping boundary.

await detectOverflow(state, {
  elementContext: 'reference', // 'floating' by default
});

altBoundary

这是一个布尔值，决定是否检查备用 elementContext 的边界。

¥This is a boolean value which determines whether to check the alternate elementContext’s boundary.

例如，如果 elementContext 是 'floating'，并且启用此选项，则检查溢出的边界是 'reference' 的边界。这仅适用于你使用默认 'clippingAncestors' 字符串作为 boundary 的情况。

¥For instance, if the elementContext is 'floating', and you enable this option, then the boundary in which overflow is checked for is the 'reference'’s boundary. This only applies if you are using the default 'clippingAncestors' string as the boundary.

await detectOverflow(state, {
  altBoundary: true, // false by default
});