Popper.js 构造函数

Popper 带有两个构造函数可供使用。

createPopper

createPopper 构造函数是 Popper 的核心。 它允许您使用状态和方法创建单独的 popper 实例（对象）。

Imports

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

// cjs
const { createPopper } = require('@popperjs/core');

// umd
const { createPopper } = Popper;

用法

const reference = document.querySelector('#reference');
const popper = document.querySelector('#popper');

createPopper(reference, popper, {
  // options
});

配置项Options

type Options = {|
  placement: Placement, // "bottom"
  modifiers: Array<$Shape<Modifier<any>>>, // []
  strategy: PositioningStrategy, // "absolute",
  onFirstUpdate?: ($Shape<State>) => void, // undefined
|};

type Placement =
  | 'auto'
  | 'auto-start'
  | 'auto-end'
  | 'top'
  | 'top-start'
  | 'top-end'
  | 'bottom'
  | 'bottom-start'
  | 'bottom-end'
  | 'right'
  | 'right-start'
  | 'right-end'
  | 'left'
  | 'left-start'
  | 'left-end';
type Strategy = 'absolute' | 'fixed';

placement

描述 popper 的首选位置。 像flip的修饰符可能会改变 popper 的位置以使其更适合。

createPopper(reference, popper, {
  placement: 'right-start',
});

“auto”展示位置将选择空间最大的一侧。

modifiers

描述要添加或配置的修饰符数组。 Popper 的默认（完整）版本包括菜单中列出的所有修饰符。

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

有关更多信息，请参阅修饰符。

strategy

描述要使用的定位策略。 默认情况下，它是绝对的，在最简单的情况下不需要重新定位 popper。

如果您的参考元素在固定容器中，请使用固定策略：

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

这将防止任何跳跃，因为不需要重新定位。

实例

createPopper 返回一个 popper 实例。 这是一个带有状态属性和一些方法的普通对象。

在 DevTools 中将其注销：

const instance = createPopper(reference, popper);
console.log(instance);

{
  // 这是主要的状态对象，包含所有关于popper.

  state,

// 同步更新 popper 实例。 用于低频更新。
 
  forceUpdate() {},

// 异步更新 popper 实例，并返回一个 promise， 用于高频更新。
  update() {},

  // 更新实例的选项。
  setOptions(options) {},

  // .销毁实例
  destroy() {},
};

Types

type CreatePopper = (
  reference: Element | VirtualElement,
  popper: HTMLElement,
  options?: Options
) => Instance;

type Options = {|
  placement: Placement,
  modifiers: Array<$Shape<Modifier<any>>>,
  strategy: PositioningStrategy,
  onFirstUpdate?: ($Shape<State>) => void,
|};

type Instance = {|
  state: State,
  destroy: () => void,
  forceUpdate: () => void,
  update: () => Promise<$Shape<State>>,
  setOptions: (
    options: $Shape<Options> | (($Shape<Options>) => $Shape<Options>)
  ) => Promise<$Shape<State>>,
|};

setOptions

您可以使用 setOptions 方法更新 popper 实例的选项。

该方法接受一个选项对象或一个将当前选项对象作为参数并返回新选项的函数。

下面我们设置一个新的配置对象来替换当前的配置对象。 请注意，以下示例将取消设置所有修饰符配置和任何其他自定义选项：

instance.setOptions({
  placement: 'bottom',
});

相反，如果我们想要更新现有配置，我们可以使用一个函数来读取当前选项并返回更新的选项（自 2.10.0 版起可用）：

// 禁用事件侦听器选项而不会丢失其余的设置选项
instance.setOptions(options => ({
  ...options,
  modifiers: [
     ...options.modifiers,
     { name: 'eventListeners', enabled: false }
  ]
});

// 重新启用它，你也可以使用 Ramda#assocPath 之类的东西来使这个更简洁
instance.setOptions((options) =>
  R.assocPath(['modifiers'], { name: 'eventListeners', enabled: true }, options)
);

popperGenerator

popperGenerator 构造函数生成一个 createPopper 函数。 这允许您使用所需的功能配置 createPopper，而无需每次都传递相同的默认值。

Imports

// esm
import { popperGenerator } from '@popperjs/core';

// cjs
const { popperGenerator } = require('@popperjs/core');

// umd
const { popperGenerator } = Popper;

用法

const createPopper = popperGenerator({
  defaultOptions: { placement: 'top' },
  defaultModifiers: [popperOffsets, computeStyles, applyStyles, eventListeners],
});

// 现在，您自定义的“createPopper”可以使用了。

Types

type PopperGenerator = (options?: PopperGeneratorOptions) => CreatePopper;

type PopperGeneratorOptions = {
  defaultModifiers?: Array<Modifier<any>>,
  defaultOptions?: $Shape<Options>,
};