Floating-UI 详解：构建弹出元素的利器

2025-02-20 08:30:16

在现代 Web 应用中，弹出元素（如菜单、提示框、下拉列表等）是不可或缺的一部分。它们不仅能够提升用户体验，还能有效节省页面空间。然而，实现这些弹出元素并非易事，尤其是当涉及到复杂布局和响应式设计时。Floating-UI 正是为了解决这一问题而诞生的。作为一个专注于创建和管理浮动元素的 JavaScript 库，Floating-UI 提供了丰富的功能和灵活的 API 接口，使得开发者可以轻松实现各种复杂的交互效果。

Logo

Floating-UI 核心功能

灵活的定位算法（Flexible Positioning Algorithm）

Floating-UI 的核心优势之一在于其强大的定位算法。该算法可以根据目标元素和参考元素之间的相对位置自动计算最佳的浮动位置，并支持多种定位策略，如顶部、底部、左侧、右侧等。此外，它还考虑到了边界检测、滚动条等因素，确保浮动元素始终位于可见区域内。

示例：基本定位

假设我们有一个按钮和一个弹出菜单，想要在点击按钮时显示菜单。可以使用以下代码：

<!-- HTML -->
<button id="trigger">Open Menu</button>
<div id="content" style="display:none;">
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
    <li>Item 3</li>
  </ul>
</div>

<script type="module">
import { computePosition, autoPlacement } from '@floating-ui/dom';

const trigger = document.getElementById('trigger');
const content = document.getElementById('content');

function showMenu() {
  // 隐藏其他内容
  content.style.display = 'block';
  
  // 计算并应用位置
  computePosition(trigger, content, {
    placement: 'bottom',
    middleware: [autoPlacement()]
  }).then(({ x, y }) => {
    Object.assign(content.style, {
      left: `${x}px`,
      top: `${y}px`
    });
  });
}

trigger.addEventListener('click', () => {
  showMenu();
});
</script>

上述代码展示了如何使用 computePosition 函数来计算弹出菜单相对于按钮的最佳位置，并将其应用到样式属性中。

丰富的中间件（Middleware）

为了进一步增强定位算法的功能，Floating-UI 提供了一系列内置的中间件。每个中间件都可以对最终的位置进行调整或添加额外的行为。常用的中间件包括但不限于：

  • offset：设置浮动元素与参考元素之间的偏移量。
  • flip：当首选位置不可用时自动切换到备用位置。
  • shift：防止浮动元素超出视口范围。
  • arrow：为带有箭头的浮动元素提供正确的定位。

示例：使用多个中间件

假设我们要创建一个带有箭头的提示框，并且希望它能够在必要时翻转方向。可以结合使用 flip 和 arrow 中间件：

<!-- HTML -->
<button id="tooltip-trigger">Hover me</button>
<div id="tooltip-content" style="display:none; position:absolute;">
  <div class="tooltip-arrow"></div>
  This is a tooltip!
</div>

<style>
.tooltip-arrow {
  width: 0;
  height: 0;
  border-left: 5px solid transparent;
  border-right: 5px solid transparent;
  border-bottom: 5px solid black;
  margin-left: -5px;
}
</style>

<script type="module">
import { computePosition, flip, arrow } from '@floating-ui/dom';

const trigger = document.getElementById('tooltip-trigger');
const content = document.getElementById('tooltip-content');
const arrowElement = content.querySelector('.tooltip-arrow');

function showTooltip() {
  content.style.display = 'block';
  
  computePosition(trigger, content, {
    placement: 'top',
    middleware: [
      flip(),
      arrow({ element: arrowElement })
    ]
  }).then(({ x, y, middlewareData }) => {
    Object.assign(content.style, {
      left: `${x}px`,
      top: `${y}px`
    });

    const { arrow: { x: arrowX, y: arrowY } = {} } = middlewareData;
    if (arrowX !== null && arrowY !== null) {
      Object.assign(arrowElement.style, {
        left: arrowX != null ? `${arrowX}px` : '',
        top: arrowY != null ? `${arrowY}px` : ''
      });
    }
  });
}

trigger.addEventListener('mouseenter', () => {
  showTooltip();
});

trigger.addEventListener('mouseleave', () => {
  content.style.display = 'none';
});
</script>

上述代码展示了如何使用 flip 和 arrow 中间件来创建一个带有箭头的提示框，并根据鼠标悬停事件动态显示和隐藏它。

支持多种框架（Framework Support）

除了原生 JavaScript 版本外，Floating-UI 还提供了针对不同框架的集成方案，如 React、Vue、Svelte 等。这使得开发者可以在各自熟悉的技术栈中快速上手并应用 Floating-UI 的功能。

示例：React 集成

对于 React 用户来说，可以使用 @floating-ui/react 包来简化开发过程。以下是创建一个简单的下拉菜单组件的示例：

// Dropdown.jsx
import React, { useState, useRef } from 'react';
import { useFloating, offset, flip } from '@floating-ui/react-dom';

function Dropdown() {
  const [isOpen, setIsOpen] = useState(false);
  const triggerRef = useRef(null);
  const menuRef = useRef(null);

  const { x, y, strategy, refs, floatingStyles } = useFloating({
    open: isOpen,
    onOpenChange: setIsOpen,
    middleware: [offset(5), flip()],
  });

  return (
    <>
      <button ref={triggerRef} onClick={() => setIsOpen(!isOpen)}>
        Open Menu
      </button>
      {isOpen && (
        <ul
          ref={menuRef}
          style={{
            ...floatingStyles,
            position: strategy,
            top: y ?? '',
            left: x ?? '',
          }}
        >
          <li>Item 1</li>
          <li>Item 2</li>
          <li>Item 3</li>
        </ul>
      )}
    </>
  );
}

export default Dropdown;

上述代码展示了如何使用 useFloating 钩子函数来创建一个响应式的下拉菜单组件，并通过 refs 属性获取触发器和菜单元素的引用。

轻量级设计（Lightweight Design）

作为一款专注于解决特定问题的库，Floating-UI 保持了轻量级的设计理念。它的核心包体积非常小，不会给项目带来过多的负担。同时，由于采用了模块化架构，用户可以根据实际需求选择性引入所需的模块，从而进一步减少打包后的文件大小。

示例：按需加载中间件

假设我们只需要使用 offset 和 flip 中间件，可以通过以下方式按需加载：

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

// 使用 computePosition 和中间件...

上述代码展示了如何仅导入必要的中间件模块，以减小最终项目的体积。

总结

通过本文的介绍，我们深入了解了 Floating-UI 的核心功能及其在 Web 开发中的广泛应用。从灵活的定位算法到丰富的中间件，再到多种框架的支持以及轻量级设计，每一个模块都得到了充分的解释，并通过具体的操作步骤展示了如何将其应用于实际项目中。

floating-ui
floating-ui/floating-ui
一个 JavaScript 库，用于定位浮动元素并为它们创建交互。
TypeScript
MIT
30.8 k