README

一个用于在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 - 通用模块定义：AMD、RequireJS 和全局变量；
• ESM - ES 模块：适用于 webpack/Rollup 或支持该规范的浏览器；
• ESNext：在 dist/ 中可用，可以与 webpack 和 babel-preset-env 一起使用；

请确保使用适合您需求的目标。如果您想通过 <script> 标签导入它，请使用 UMD。

使用方法

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

var reference = document.querySelector('.my-button');
var popper = document.querySelector('.my-popper');
var anotherPopper = 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: 800,
        },
    },
});

从 Popper.js v0 迁移

由于 API 已更改，我们准备了迁移说明，以便轻松升级到 Popper.js v1。

https://github.com/FezVrasta/popper.js/issues/62

如果您有任何问题，请在问题内部进行评论。

性能

Popper.js 非常高效。它通常需要 0.5 毫秒来计算 popper 的位置（在配备 3.5 GHz Intel Core i5 的 iMac 上）。
这意味着它不会引起任何 jank，从而提供流畅的用户体验。

备注

使用 Popper.js 的库

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

访问 MENTIONS 页面，获取项目列表的最新更新。

致谢

我想感谢一些朋友和项目，他们为我所做的工作

• @AndreaScn 为其 GitHub 页面工作以及他在开发期间进行的手动测试；
• @vampolo 为其原始想法和库的名称；
• Sysdig 在这些年中教会了我许多奇妙的事物，使我能够写出这个库；
• Tether.js 启发我编写一个适用于现实世界的定位库；
• 贡献者 为他们受到高度评价的拉取请求和错误报告；
• 你 为你将给予这个项目的 star，以及你愿意尝试这个项目真是太棒了 :)

版权和许可

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