floating-ui

<p align="center"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/7f068257-8e14-4966-a8dd-9e0c3280f4f5.png" alt="Floating UI" width="70%"> <p>

[!注意] Popper现已更名为Floating UI！如需查看Popper v2，请访问 其专用分支和其文档。 如需迁移帮助，请查看 迁移指南。

Floating UI是一个小型库，可帮助你创建"浮动"元素，如工具提示、弹出框、下拉菜单等。

它提供两个主要功能：

1. 锚点定位：将浮动元素（如工具提示）锚定到另一个元素（如按钮）上，同时通过避免碰撞尽可能确保它保持在视图中。此功能适用于所有平台。
2. React用户交互：用于组合交互以创建可访问的浮动UI组件的钩子和组件。

README赞助商

<table> <tr> <td> <a href="https://milfordasset.com/" target="_blank" rel="noopener noreferrer"><img width="176" height="150" src="https://yellow-cdn.veclightyear.com/835a84d5/d7aa5c83-2e5a-40da-ad9f-071061db36ad.svg" alt="Milford" /></a> </td> <td> <a href="https://dopt.com/?utm_source=floating_ui_readme" target="_blank" rel="noopener noreferrer"><img width="200" height="150" src="https://yellow-cdn.veclightyear.com/835a84d5/5e799815-07fa-42f4-869c-cdcbabee5811.png" alt="Dopt" /></a> </td> </tr> </table>

你可以通过Open Collective以多种方式赞助Floating UI。

为什么选择Floating UI

浮动元素通常采用绝对定位，并锚定到另一个UI元素。确保浮动元素始终锚定在另一个元素旁边可能具有挑战性，尤其是在滚动容器等特殊布局环境中。

当浮动元素过于接近视口边缘而被遮挡时，绝对定位也可能导致问题，这被称为碰撞。发生碰撞时，必须调整位置以确保浮动元素保持可见。

此外，浮动元素通常是可交互的，这在设计用户交互时可能会引发复杂的可访问性问题。

Floating UI提供了一套低级功能，帮助你应对这些挑战并构建可访问的浮动UI组件。

安装

要安装Floating UI，你可以使用npm等包管理器或CDN。不同平台有不同的版本可用。

原生版本

在网页上使用原生JavaScript。

npm install @floating-ui/dom

你可以从阅读教程开始，它会通过构建一个基本的工具提示来教你如何使用这个库，或者你可以直接跳转到API文档。

React

与React DOM或React Native一起使用。

React DOM

# 定位 + 交互
npm install @floating-ui/react

# 仅定位（体积更小）
npm install @floating-ui/react-dom

React Native

npm install @floating-ui/react-native

Vue

与Vue一起使用。

npm install @floating-ui/vue

Canvas或其他平台

如果你的目标平台不是原生DOM（网页）、React或React Native，你可以创建自己的平台。这允许你支持Canvas/WebGL或其他可以运行JavaScript的平台。

npm install @floating-ui/core

贡献

这个项目是一个使用pnpm工作区的TypeScript编写的monorepo。网站使用Next.js SSG和Tailwind CSS进行样式设计。

• 分叉并克隆仓库
• 在根目录下使用pnpm install安装依赖
• 使用pnpm run build构建初始包的dist文件

测试环境

DOM

在根目录运行pnpm run dev --filter @floating-ui/dom将在http://localhost:1234启动@floating-ui/dom的开发视觉测试。该测试环境使用React编写每个测试路由，由Vite打包。

每个路由都使用Playwright对页面进行截图，以确保所有功能按预期工作；这是一种简单、可靠且高级的测试定位逻辑的方法。

主容器下方是UI控件，用于开启某些状态和选项。通过快照测试每种状态组合，以尽可能覆盖所有情况。

React

在根目录运行pnpm run dev --filter @floating-ui/react将在http://localhost:1234启动@floating-ui/react的开发测试。

致谢

横幅图像中的浮动形状由Figma上杰出的艺术家@artstar3d、@killnicole和@liiiiiiii制作 —— 去看看他们的作品吧！

许可证

MIT