教程 > Popper.js 中文教程 阅读:2614

Popper.js 中文教程

给定一个元素,例如:按钮,以及描述它的工具提示元素,Popper 会自动将工具提示放在按钮附近的正确位置。

它将定位从文档流中“弹出”并漂浮在目标元素附近的任何 UI 元素。 最常见的示例是工具提示,但它也包括弹出窗口、下拉菜单等。 所有这些都可以概括地描述为“popper”元素。


为什么不使用纯 CSS?

  • 裁剪和溢出问题:纯CSS弹出程序不会被阻止溢出剪辑边界,例如视口。如果靠近边缘,由于没有动态定位逻辑,它会被部分切断或溢出。使用 Popper 时,您的 popper 将始终位于正确的位置,无需手动调整。
  • 无翻转:如有必要,CSS 弹出程序不会翻转到不同的位置以更好地适应视图。虽然您可以手动调整主轴溢出,但仅通过 CSS 无法实现此功能。 Popper 会自动翻转工具提示,使其尽可能适合用户。
  • 无虚拟定位:CSS弹出程序不能跟随鼠标光标或用作上下文菜单。 Popper 允许您相对于您想要的任何坐标定位您的工具提示。
  • 较慢的开发周期:当使用纯 CSS 来定位 popper 元素时,缺乏动态定位意味着必须仔细放置它们以考虑所有屏幕尺寸的溢出。在可重用组件库中,这意味着开发人员不能只是在页面的任何位置添加组件,因为每次都需要考虑和调整这些问题。使用 Popper,您可以将元素放置在任何地方并且它们将被正确定位,而无需考虑不同的屏幕尺寸、布局等。这大大加快了开发时间,因为这项工作会自动卸载到 Popper。
  • 缺乏可扩展性:CSS 弹出层无法轻松扩展来适应您可能需要调整的任意用例。 Popper 在构建时考虑了可扩展性。

为什么使用Popper

了解了 CSS 的缺点后,我们现在转向 JavaScript 领域中的 Popper。

简单的 JavaScript 工具提示实现通常存在以下问题:

  • 滚动容器:当在任意数量的滚动容器内滚动时,它们不能确保工具提示与参考元素保持一致。
  • DOM 上下文:它们通常需要工具提示移出其原始 DOM 上下文,因为它们不处理 offsetParent 上下文。
  • 兼容性:Popper 处理了大量关于不同浏览器和环境(移动视口、RTL、启用或禁用滚动条等)的边缘情况。 Popper 是一个流行且维护良好的库,因此您可以确信在任何设备上,都能为您的用户工作。
  • 可配置性:它们通常缺乏适合任何可能用例的高级可配置性。
  • 大小:它们通常相对较大,或者需要一个古老的 jQuery 依赖项。
  • 性能:他们经常有运行时性能问题,并且更新工具提示位置太慢。

Popper 以一种优雅、高效的方式解决了所有这些关键问题。它是一个约 3 kB 的轻量级库,旨在提供一个可靠且可扩展的定位引擎,您可以使用它来确保所有 popper 元素都定位在正确的位置。

当您开始编写自己的 popper 实现时,您将很快遇到上述所有问题。这些小部件在我们的 UI 中非常常见;Popper.js已经做了很多的工作来解决这个问题,因此您无需花费数小时来修复和处理我们在构建库时已经遇到的众多边缘情况!

Popper 用于流行的库,如 Bootstrap、Foundation、Material UI 等。在过去几年的中,您可能已经在网络上使用过由 Popper 定位的 popper 元素。

由于我们现在使用强大的抽象库(例如 React 或 Angular)编写 UI, Popper 可以与它们完全集成并与您的其他组件一起构建很好的应用。查看react-popper 以获取 React 的官方 Popper 包装器。


安装

1.Package Manager

# 使用 npm
$ npm i @popperjs/core

# 使用 Yarn
$ yarn add @popperjs/core

2.CDN

<!-- 开发版本 -->
<script src="https://unpkg.com/@popperjs/core@2/dist/umd/popper.js"></script>

<!-- 生产版本 -->
<script src="https://unpkg.com/@popperjs/core@2"></script>

3.直接下载

出于多种原因,不建议通过“直接下载”它们并将它们放入源代码来管理依赖项,包括容易错过修复更新。 请使用版本管理系统,如 CDN 或 npm/Yarn。

用法

最直接的入门方法是从 unpkg CDN 导入 Popper,其中包括其所有功能。 您可以调用 Popper.createPopper 构造函数来创建新的 popper 实例。 下面一个完整的例子:

<!DOCTYPE html>
<title>Popper example</title>
<style>
  #tooltip {
    background-color: #333;
    color: white;
    padding: 5px 10px;
    border-radius: 4px;
    font-size: 13px;
  }
</style>

<button id="button" aria-describedby="tooltip">I'm a button</button>
<div id="tooltip" role="tooltip">I'm a tooltip</div>

<script src="https://unpkg.com/@popperjs/core@2"></script>
<script>
  const button = document.querySelector('#button');
  const tooltip = document.querySelector('#tooltip');

  // 传递按钮、工具提示和一些选项,Popper 将执行
  // 神奇的定位
  Popper.createPopper(button, tooltip, {
    placement: 'right',
  });
</script>

尝试一下

访问Popper.js 使用方法来了解如何使用 Popper 从头开始构建自己的工具提示的示例。


Module 绑定

您可以从功能齐全的文件中导入 createPopper 构造函数:

import { createPopper } from '@popperjs/core';

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

  // 传递按钮、工具提示和一些选项,Popper 将执行
  // 神奇的定位
createPopper(button, tooltip, {
  placement: 'right',
});

文档菜单中列出的所有修饰符都将启用并“正常工作”,因此您无需考虑设置 Popper。 Popper 的大小(包括其所有功能)压缩后大约为 5 kB,但将来可能会增加一点。

Popper Lite (tree-shaking)

如果包大小是web应用考虑的一个重要的因素,您将需要用 Popper Lite。 该库以模块化方式构建,允许仅导入您真正需要的部分。

import { createPopper } from '@popperjs/core/lib/popper-lite.js';

Lite 版本包括最必要的修饰符,用于计算 popper 的偏移量、计算和添加定位样式以及添加事件侦听器。 这与纯 CSS 工具提示库的包大小接近,并且行为有些相似。但是,这不包括使 Popper 真正有用的功能。Lite 中未包含的两个最有用的修饰符是 preventOverflow 和 flip:

import { createPopper } from '@popperjs/core/lib/popper-lite.js';
import preventOverflow from '@popperjs/core/lib/modifiers/preventOverflow.js';
import flip from '@popperjs/core/lib/modifiers/flip.js';

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

createPopper(button, tooltip, {
  modifiers: [preventOverflow, flip],
});

版本

Popper 以 3 种不同的文件格式分发 3 个不同的版本。

3种文件格式是:

  • esm(使用导入语法 - 推荐)
  • umd(适用于 <script></script> 标签或 RequireJS
  • cjs(使用 require() 语法)

有两种不同的 esm 构建,一种用于捆绑消费者(例如 webpack、Rollup 等),位于 /lib 下,另一种用于本地支持 ES 模块的浏览器,位于 /dist/esm 下。 两者之间的唯一区别是浏览器兼容版本不使用 process.env.NODE_ENV 来运行开发检查。

3个版本是:

  • popper:在一个文件中包含所有修饰符(功能)(默认);
  • popper-lite:仅包含最少量的修饰符以提供基本功能;
  • popper-base:不包含任何修饰符,必须单独导入;

查看笔记

扫码一下
查看教程更方便