84

0

Floating UI

用于创建浮动元素的工具包。工具提示、弹出框、下拉菜单等

浮动用户界面

Popper 现在是浮动 UI!对于 Popper v2,请访问 其专用分支。 有关迁移的帮助,请查看 迁移指南。

浮动 UI是一个小型库,用于创建“浮动”元素,如工具提示、弹出框、下拉菜单、菜单等。

该库提供了两个关键功能:

1.锚定定位原语

CSS 目前缺少一个称为“锚定定位”的功能——能够将一个元素(如工具提示)锚定到另一个元素(如按钮),同时通过避免剪辑和溢出来尽可能地保持它在视图中。

尝试使用当今的纯 CSS 进行完全动态的锚定定位是不可能的。浮动 UI 提供了此功能的 JavaScript 实现。

2. 用户交互原语

在创建遵循 WAI-ARIA 创作实践的弹出框、下拉菜单、选择或组合框组件时,复杂性会急剧增加。焦点陷阱、索引导航和预输入很难做到正确。

此功能目前可用于 React DOM,但将来会变得不可知。

安装

选择适合您的套餐。

Vanilla DOM 定位引擎

与 vanilla JavaScript 或非 React 框架一起使用(查看教程)。

npm install @floating-ui/dom

React DOM 定位引擎

与 React DOM 一起使用(查看文档)。

npm install @floating-ui/react-dom

React DOM 交互和定位引擎

除了定位引擎之外,与 React DOM 一起使用的原始钩子和组件(查看文档)。

npm install @floating-ui/react-dom-interactions

React Native 定位引擎

与 React Native 一起使用(查看文档)。

npm install @floating-ui/react-native

Canvas或其他平台

了解如何创建平台

npm install @floating-ui/core

快速开始

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

const referenceElement = document.querySelector('#button');
const floatingElement = document.querySelector('#tooltip');

function applyStyles({x = 0, y = 0, strategy = 'absolute'}) {
  Object.assign(floatingElement.style, {
    position: strategy,
    left: `${x}px`,
    top: `${y}px`,
  });
}

applyStyles();

computePosition(referenceElement, floatingElement, {
  placement: 'right',
}).then(applyStyles);

访问文档以获取详细信息

入口

使用 webpack、Vite 或 Parcel?跳过此部分,因为现代捆绑器会为您处理此问题。

浮动 UI 用于 process.env.NODE_ENV确定您的构建是处于开发模式还是生产模式。这允许我们在开发过程中添加控制台警告和错误以帮助您,但确保它们在生产中被剥离以保持包大小较小。

这会导致汇总错误和低/无构建设置。为了解决这个问题,浮动 UI 导出了浏览器就绪的 ES 模块。利用“浏览器”包导出条件来使用这些模块。

汇总示例

贡献

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

  • 分叉并克隆 repo
  • 在根目录中安装依赖项 npm install
  • 构建初始包 dist 文件 npm run build

测试

npm -w packages/dom run dev在根目录中将启动 @floating-ui/dom 开发可视化测试 http://localhost:1234。Playground 使用 React 编写每个测试路线,由 Parcel 捆绑。

每条路线都有 Playwright 为页面截取的屏幕截图,以确保所有功能按预期工作;这是测试代码的一种简单、可靠和高级的方法。

主容器下方是用于打开某些状态和选项的 UI 控件。每个状态组合都通过快照进行可视化测试,以尽可能多地覆盖。

执照

MIT