README

Popper.js

一个用于在Web应用程序中定位弹出元素的库。

什么？弹出元素？

弹出元素是在屏幕上“弹出”的元素，它从应用程序的自然流程中分离出来。
常见的弹出元素示例包括工具提示、弹出窗口和下拉菜单。

所以，又一个工具提示库？

实际上，不是。
Popper.js是一个 定位引擎；其目的是计算元素的位置，使其能够将其定位在指定的参考元素附近。

该引擎完全模块化，其大多数功能都作为 修饰符（类似于中间件或插件）实现。
整个代码库是用ES2015编写的，其功能通过SauceLabs和TravisCI在真实浏览器上自动测试。

Popper.js没有依赖项。没有jQuery，没有LoDash，什么都没有。
它被像Twitter（Bootstrap v4）、Microsoft（WebClipper）和Atlassian（AtlasKit）这样的大公司所使用。

Popper.js

这是引擎，这个库计算并可选地应用弹出元素的风格。

一些关键点是

• 保持元素在原始DOM上下文中定位（不会弄乱您的DOM!）；
• 允许导出计算信息以与React和其他视图库集成；
• 支持Shadow DOM元素；
• 由于基于修饰符的结构，可完全自定义；

访问我们的 项目页面，了解您可以使用Popper.js做什么的许多示例！

在这里 找到文档。

Tooltip.js

由于许多用户只需要一种简单的方法将功能强大的工具提示集成到他们的项目中，我们创建了 Tooltip.js。
这是一个小型库，它使自动创建工具提示变得容易，其引擎为Popper.js。
其API几乎与著名的Bootstrap工具提示系统相同，这样就可以轻松将其集成到项目中。
由Tooltip.js生成的工具提示可以通过aria标签访问。

在这里 找到文档。

安装

Popper.js可在以下包管理器和CDN上使用

Tooltip.js也是如此

*: Bower不支持官方，只能通过unpkg.com CDN安装Tooltip.js。此方法有一个限制，即不能定义库的特定版本。Bower和Popper.js建议为项目使用npm或Yarn。
有关更多信息，请 阅读相关问题。

目标分发

Popper.js目前有3个目标：UMD、ESM和ESNext。
不知道我在说什么？你可能正在寻找UMD。

• UMD - 通用模块定义：AMD、RequireJS和全局；
• ESM - ES模块：适用于webpack/Rollup或支持该规范的浏览器；
• ESNext：在/dist中可用，可使用webpack和babel-preset-env。

请确保使用适合您需求的版本。 如果您想使用 <script> 标签导入，请使用 UMD。
如果您在 Git 仓库中找不到 /dist 文件夹，这是因为分发文件仅提供给 Bower、npm 或我们的 CDNs。您可以通过访问 https://unpkg.com/popper.js/dist/ (或 https://unpkg.com/tooltip.js/dist/) 找到它们

使用方法

给定一个现有的 popper DOM 节点，请让 Popper.js 将其定位在其按钮附近。

<div class="my-button">reference</div>
<div class="my-popper">popper</div>

var reference = document.querySelector('.my-button');
var popper = document.querySelector('.my-popper');
var popperInstance = new Popper(reference, popper, {
  // popper options here
});

回调函数

Popper.js 支持两种类型的回调；onCreate 回调在 popper 初始化后调用。而 onUpdate 回调在后续的任何更新中调用。

const reference = document.querySelector('.my-button');
const popper = document.querySelector('.my-popper');
new Popper(reference, popper, {
  onCreate: data => {
    // data is an object containing all the informations computed
    // by Popper.js and used to style the popper and its arrow
    // The complete description is available in Popper.js documentation
  },
  onUpdate: data => {
    // same as `onCreate` but called on subsequent updates
  },
});

自己编写修饰符

Popper.js 基于类似“插件”的架构，其大部分功能都是完全封装的“修饰符”。
修饰符是一个函数，每次 Popper.js 需要计算 popper 的位置时都会调用它。因此，修饰符应该非常高效，以避免瓶颈。

要了解如何创建修饰符，请阅读修饰符文档

React、Vue.js、Angular、AngularJS、Ember.js（等等...）集成

将第三方库集成到 React 或其他库中可能会很痛苦，因为它们通常会改变 DOM 并使库变得疯狂。
Popper.js 将其所有 DOM 修改限制在 applyStyle 修饰符内，您可以直接禁用它并使用您选择的库手动应用 popper 坐标。

要查看可以让你在现有框架中使用 Popper.js 的库的完整列表，请访问MENTIONS 页面。

或者，您甚至可以覆盖自己的 applyStyles 并自行集成 Popper.js！

function applyReactStyle(data) {
  // export data in your framework and use its content to apply the style to your popper
}

const reference = document.querySelector('.my-button');
const popper = document.querySelector('.my-popper');
new Popper(reference, popper, {
  modifiers: {
    applyStyle: { enabled: false },
    applyReactStyle: {
      enabled: true,
      fn: applyReactStyle,
      order: 900,
    },
  },
});

如何在 Jest 中使用 Popper.js

由于 JSDOM 的一些限制，建议用户在 Jest 测试中使用 Popper.js 的模拟。

模拟 Popper.js 的最简单方法是，将以下代码放置在 __mocks__/popper.js.js 中，与您的 node_modules 目录相邻。Jest 将自动拾取它。

import PopperJs from 'popper.js';

export default class Popper {
  static placements = PopperJs.placements;

  constructor() {
    return {
      destroy: () => {},
      scheduleUpdate: () => {},
    };
  }
}

或者，您可以手动为特定测试模拟 Popper.js。

jest.mock('popper.js', () => {
  const PopperJS = jest.requireActual('popper.js');

  return class Popper {
    static placements = PopperJS.placements;

    constructor() {
      return {
        destroy: () => {},
        scheduleUpdate: () => {},
      };
    }
  };
});

从 Popper.js v0 迁移

由于 API 发生变化，我们准备了一些迁移说明，以便轻松升级到 Popper.js v1。

floating-ui#62

如果您有任何问题，请随时在问题内评论。

性能

Popper.js 性能极好。通常，它需要 0.5 毫秒来计算 popper 的位置（在 3.5G GHz Intel Core i5 的 iMac 上）。
这意味着它不会引起任何 卡顿，从而带来流畅的用户体验。

注意事项

使用 Popper.js 的库

Popper.js 的目标是提供一个稳定且功能强大的定位引擎，可供第三方库使用。

请访问MENTIONS 页面，查看项目列表。

致谢

我想感谢一些朋友和项目，感谢他们所做的努力

• @AndreaScn 对 GitHub 页面的工作，以及在开发期间进行的手动测试；
• @vampolo 对原始想法和库名称的命名；
• Sysdig 在这些年中让我学到了许多奇妙的东西，使我能够编写这个库；
• Tether.js 启发我编写一个面向现实世界的定位库。
• 感谢各位贡献者提交的宝贵拉取请求和错误报告；
• 你为此项目投上的星标，以及愿意尝试这个项目，真是太棒了 😊

版权和许可

代码和文档版权所有 2016 Federico Zivolo。代码在MIT 许可下发布。文档在创意共享许可下发布。