flip

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

用法

¥Usage

computePosition(referenceEl, floatingEl, {
  middleware: [flip()],
});

选项

¥Options

这些是你可以传递给 flip() 的选项。

¥These are the options you can pass to flip().

interface FlipOptions extends DetectOverflowOptions {
  mainAxis?: boolean;
  crossAxis?: boolean;
  fallbackAxisSideDirection?: 'none' | 'start' | 'end';
  flipAlignment?: boolean;
  fallbackPlacements?: Array<Placement>;
  fallbackStrategy?: 'bestFit' | 'initialPlacement';
}

mainAxis

默认：true

¥default: true

这是检查溢出以执行翻转的主轴。通过禁用此功能，它将忽略溢出。

¥This is the main axis in which overflow is checked to perform a flip. By disabling this, it will ignore overflow.

• y 轴用于 'top' 和 'bottom' 放置

  ¥y-axis for 'top' and 'bottom' placements

• x 轴用于 'left' 和 'right' 放置

  ¥x-axis for 'left' and 'right' placements

flip({
  mainAxis: false,
});

crossAxis

默认：true

¥default: true

这是检查溢出以执行翻转的交叉轴，该轴垂直于 mainAxis。通过禁用此功能，它将忽略溢出。

¥This is the cross axis in which overflow is checked to perform a flip, the axis perpendicular to mainAxis. By disabling this, it will ignore overflow.

flip({
  crossAxis: false,
});

fallbackAxisSideDirection

默认：'none'

¥default: 'none'

如果没有沿首选放置轴的放置，是否允许回退到相反的轴，如果是，则选择沿该轴的哪一侧方向。如果有必要，它会退回到另一个方向。

¥Whether to allow fallback to the opposite axis if no placements along the preferred placement axis fit, and if so, which side direction along that axis to choose. If necessary, it will fallback to the other direction.

• 'none' 表示不应回退到相反的轴。

  ¥'none' signals that no fallback to the opposite axis should take place.

• 'start' 代表 'top' 或 'left'。

  ¥'start' represents 'top' or 'left'.

• 'end' 代表 'bottom' 或 'right'。

  ¥'end' represents 'bottom' or 'right'.

例如，默认情况下，如果初始 placement 设置为 'right'，则要尝试的展示位置（按顺序）为：

¥For instance, by default, if the initial placement is set to 'right', then the placements to try (in order) are:

['right', 'left']

在狭窄的视口中，这些可能甚至很可能都不适合。

¥On a narrow viewport, it’s possible or even likely that neither of these will fit.

通过指定 'none' 以外的字符串，你可以尝试沿初始放置的垂直轴进行放置。方向决定首先尝试放置的哪一侧：

¥By specifying a string other than 'none', you allow placements along the perpendicular axis of the initial placement to be tried. The direction determines which side of placement is tried first:

flip({
  fallbackAxisSideDirection: 'start',
});

上面的结果是：['right', 'left', 'top', 'bottom']。

¥The above results in: ['right', 'left', 'top', 'bottom'].

flip({
  fallbackAxisSideDirection: 'end',
});

上面的结果是：['right', 'left', 'bottom', 'top']。

¥The above results in: ['right', 'left', 'bottom', 'top'].

例如，如果你希望将 'right' 位置的工具提示放置在移动设备顶部（假设它不适合），那么你可以使用 'start'。对于交互式弹出窗口，你可能希望使用 'end'，因此将其放置在底部，更靠近用户的手指。

¥As an example, if you’d like a tooltip that has a placement of 'right' to be placed on top on mobile (assuming it doesn’t fit), then you’d use 'start'. For an interactive popover, you likely want to use 'end' so it’s placed on the bottom, closer to the user’s fingers.

在以下每个演示中，placement 是 'right'。

¥In each of the following demos, the placement is 'right'.

flipAlignment

默认：true

¥default: true

当指定对齐方式时，例如 'top-start' 而不仅仅是 'top'，如果 start 不适合，这将翻转到 'top-end'。

¥When an alignment is specified, e.g. 'top-start' instead of just 'top', this will flip to 'top-end' if start doesn’t fit.

flip({
  flipAlignment: false,
});

将其与 shift() 中间件一起使用时，请确保 flip() 位于中间件数组中的 shift() 之前。这确保了 flipAlignment 逻辑可以在 shift() 之前采取行动。

¥When using this with the shift() middleware, ensure flip() is placed before shift() in your middleware array. This ensures the flipAlignment logic can act before shift()’s does.

fallbackPlacements

默认：[oppositePlacement]

¥default: [oppositePlacement]

这描述了如果初始 placement 不适合检查溢出的轴时要尝试的显式放置数组。

¥This describes an explicit array of placements to try if the initial placement doesn’t fit on the axes in which overflow is checked.

flip({
  fallbackPlacements: ['right', 'bottom'],
});

在上面的示例中，如果 placement 设置为 'top'，则要尝试的展示位置（按顺序）为：

¥In the above example, if placement is set to 'top', then the placements to try (in order) are:

['top', 'right', 'bottom']

fallbackStrategy

默认：'bestFit'

¥default: 'bestFit'

当没有合适的展示位置时，你需要决定会发生什么。'bestFit' 将使用最适合检查的轴的放置位置。'initialPlacement' 将使用指定的初始 placement。

¥When no placements fit, then you’ll want to decide what happens. 'bestFit' will use the placement which fits best on the checked axes. 'initialPlacement' will use the initial placement specified.

flip({
  fallbackStrategy: 'initialPlacement',
});

…detectOverflowOptions

detectOverflow 的所有选项都可以通过。例如：

¥All of detectOverflow’s options can be passed. For instance:

flip({
  padding: 5, // 0 by default
});

从状态导出选项

¥Deriving options from state

你可以从 中间件生命周期状态 导出选项：

¥You can derive the options from the middleware lifecycle state:

flip((state) => ({
  padding: state.rects.reference.width,
}));

最终位置

¥Final placement

从函数返回的位置始终是最后一个，不一定是你作为 “preferred” 传入的位置。

¥The placement returned from the function is always the final one, not necessarily the one you passed in as the “preferred” one.

computePosition(referenceEl, floatingEl, {
  placement: 'bottom',
  middleware: [flip()],
}).then(({placement}) => {
  console.log(placement); // 'top' or 'bottom'
});

与 shift() 结合

¥Combining with shift()

如果你允许通过 fallbackAxisSideDirection 或 fallbackPlacements 回退到首选位置的相反轴，那么你可能需要确定将 flip() 与 shift() 组合时想要的行为。

¥If you’re allowing fallback to the opposite axis of the preferred placement via fallbackAxisSideDirection or fallbackPlacements, then you may want to determine what behavior you want when combining flip() with shift().

如果你想确保尽可能保留放置面而不翻转，那么你有两个选择可以考虑：

¥If you want to ensure the placement side is preserved as best as possible without flipping, then you have two options to consider:

1. 禁用 flip() 中的交叉轴检查会将 shift() 的工作放在首位，而 flip() 仅在绝对必要时才采取行动。将尽可能保留浮动元素的首选放置位置。

   ¥Disabling the cross axis check in flip() places top priority on shift() to do its work, with flip() only taking action when absolutely necessary. The preferred placement of the floating element will be conserved as much as possible.

const middleware = [
  flip({
    fallbackAxisSideDirection: 'start',
    crossAxis: false,
  }),
  shift(),
];

2. 在数组中将 shift() 放置在 flip() 之前可确保它可以在 flip() 尝试更改放置位置之前完成其工作。这与上面的第一种技术类似，但允许 flip() 也对其 crossAxis 采取行动 - 如果 shift() 有限制器，则很有用。

   ¥Placing shift() before flip() in the array ensures it can do its work before flip() tries to change the placement. This is similar to the first technique above, but allows flip() to take action on its crossAxis too — useful if shift() has a limiter.

const middleware = [
  shift({
    limiter: limitShift(),
  }),
  flip({
    fallbackAxisSideDirection: 'start',
  }),
];

与 autoPlacement() 冲突

¥Conflict with autoPlacement()

flip() 和 autoPlacement() 不能在同一个中间件数组中一起使用；确保你只选择使用其中之一。

¥flip() and autoPlacement() cannot be used together inside the same middleware array; make sure you choose only one of them to use.

原因是他们都试图在安置上进行工作，但策略相反。因此，他们会不断尝试改变另一个的结果或工作，从而导致重置循环。

¥The reason is they both try to perform work on the placement but with opposing strategies. Therefore, they will continually try to change the result or work of the other one, leading to a reset loop.

• flip() 使用后备 “没有空间” 策略。确保保留首选位置，除非没有剩余空间。

  ¥flip() uses a fallback “no space” strategy. Ensures the preferred placement is kept unless there is no space left.

• autoPlacement() 使用主要 “大部分空间” 策略。始终选择可用空间最多的位置。

  ¥autoPlacement() uses a primary “most space” strategy. Always chooses the placement with the most space available.