迁移到 Popper 2

Popper 2引入了很多更好的变化！ 这是帮助您迁移到新版本的指南。

1.安装新包

从 package.json 或 CDN 脚本标签中删除 popper.js 包，并安装 @popperjs/core。

Popper 已将其包名称更改为位于范围内的 @popperjs 组织下。 这也是 react-popper 等其他软件包现在也可以使用的地方。

2.更改导入

Modules

在 Popper 1 中，它是一个类：

import Popper from 'popper.js';

new Popper(reference, popper, options);

在 Popper 2 中，它现在是一个函数：

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

createPopper(reference, popper, options);

CDN/umd 版本

命名导入位于 Popper 命名空间对象下：

Popper.createPopper;

3.更改 CSS 属性选择器

在 v1 中，属性以 x- 为前缀，例如 x-placement。 在 v2 中，这些现在以 data-popper- 为前缀，它与 HTML5 规范匹配，并拥有自己的数据命名空间以防止冲突。

此外，x-out-of-boundaries 现在是*** data-popper-reference-hidden***。

4. 移除所有 CSS 边距

在 Popper 2 中，我们不再考虑 CSS 边距，因为它存在固有问题。 相反，要在 popper 及其引用元素之间应用一些填充，请使用偏移修饰符(offset )。 您还需要从箭头中删除 margin ； 而是使用箭头( arrow )修饰符中的 padding 选项。

5.确保所有展示位置的弹出框和箭头框大小保持不变

不同位置的 popper 和箭头不能有不同的宽度或高度； 它的大小必须是恒定的。 这是由于 Popper 生命周期的工作方式——它无法提前（在写入 DOM 之前）知道计算出的 CSS 将是什么，这会改变元素的大小。 在 Popper 1 中，这会导致各种闪烁和抖动问题。

我们正在寻找一种方法在未来允许这样做，但目前这是一个难以有效解决的问题。

6.如有必要，添加后边界填充

在 Popper 2 中，所有 padding 现在都是 0。在 v1 中，这些是 5，用于 preventOverflow和flip。 如有必要，您可以使用 padding 选项将这些添加回来，其工作方式与 v1 相同。

7.改变位置Fixed

在 Popper 2 中，这是现在的strategy选项：

createPopper(reference, popper, {
  strategy: 'fixed',
});

8. 更新方法名称

• update() 现在是 forceUpdate() （并且是同步的）
• scheduleUpdate() 现在是 update() （并返回promise）
• 没有enableEventListeners / disableEventListeners ； 请参阅 eventListeners 修饰符。 您可以使用 setOptions 方法随意更改 scroll 和调整*** resize*** 选项以复制原始方法的功能。

9.更新回调

• onCreate 现在是 onFirstUpdate
• onUpdate 不见了； 使用具有 afterWrite 阶段的自定义修饰符

10.更新修饰符

在 Popper 2 中，这现在是一个对象（修饰符）数组，而不是每个属性都是修饰符名称的对象。

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'flip',
      enabled: false,
    },
  ],
});

此外，它们的选项在 options 对象中组合在一起：

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'flip',
      options: {
        padding: 5,
      },
    },
  ],
});

我们无法在此处列出对它们的所有更改（有很多！）； 您需要访问菜单中的每个修饰符以了解有关其新行为的更多信息。

有关编写自定义修饰符的更多信息，请参阅修饰符。

11.inner、keepTogether、shift修饰符不见了

• 可以使用负值的 offset 修饰符复制 inner
• keepTogether 功能存在于 tether 选项中的 preventOverflow

12.移除虚拟元素属性

您的虚拟元素（或 Popper 1 中的参考对象）需要的唯一属性是 getBoundingClientRect。 现在不需要其他属性。

13. 过渡

在 Popper 2 中，computeStyles 修饰符有一个默认启用的名为 adaptive 的新选项，它会中断 CSS 转换。 如果启用了 CSS 转换，您应该将此选项设置为 false。

请记住，adaptive 的好处是允许您在大多数情况下更改 popper 的高度或宽度，而无需更新其位置，因此禁用它时您将失去此好处。