# @elliemae/react-popper 中文文档

规范地址：https://npmcn.com/package/%40elliemae/react-popper/

版本：1\.0\.2
npm 元数据更新时间：2022-04-05T07:20:18.163Z
中文译文更新时间：2026-11-13T13:24:52.984Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40elliemae/react-popper
原文对照：https://npmcn.com/package/%40elliemae/react-popper/?lang=original
项目主页：https://git.elliemae.com/platform-ui/react-popper
源码仓库：https://git.elliemae.io/platform-ui/react-popper

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：124 kB，20 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：react ^16\.0\.0
- 首次发布：2022-01-18T19:09:10.969Z
- 最新版本发布：2022-01-18T20:02:58.803Z
- 近 30 天下载量：5085（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

Popper.js周围的反应包装器

## 安装

```sh
npm install @elliemae/react-popper
```

也可以使用：`pnpm add @elliemae/react-popper`、`yarn add @elliemae/react-popper`、`bun add @elliemae/react-popper`

## README

## 反弹出器

[![Build Status](https://jenkins.dco.elmae/job/Platform%20UI/job/react-popper/job/master/badge/icon)](https://jenkins.dco.elmae/job/Platform%20UI/job/react-popper/job/master/)

反射包装 [波普尔.js (英语)](https://popper.js.org/)。 。 。 .

**重要说明:** poper. js为 **没有** 一个工具提示库,这是一个 _定位引擎_ 用于构建诸如(但不限于)工具提示等特性.

## 安装

通过软件包管理器 :

```bash
npm install react-popper --save
# or
yarn add react-popper
```

通过 `script` 标记( UMD 库已曝光为 `ReactPopper`:

```html
<script src="https://unpkg.com/react-popper/dist/index.umd.js"></script>
```

## 使用量

> 使用 `react-popper@0.x`您可以找到它的文档 [点击这里](https://github.com/souporserious/react-popper/tree/v0.x)

示例

```jsx
import { Manager, Reference, Popper } from 'react-popper';

const Example = () => (
  <Manager>
    <Reference>
      {({ ref }) => (
        <button type="button" ref={ref}>
          Reference element
        </button>
      )}
    </Reference>
    <Popper placement="right">
      {({ ref, style, placement, arrowProps }) => (
        <div ref={ref} style={style} data-placement={placement}>
          Popper element
          <div ref={arrowProps.ref} style={arrowProps.style} />
        </div>
      )}
    </Popper>
  </Manager>
);
```

`react-popper` 使用名为“反应”的模式 **"放弃道具"**如果你没有 熟悉,请读更多 [官方反应文档](https://reactjs.org/docs/render-props.html)。 。 。 .

> 使用回放 QQ15 还是Preact? 由它们创建的组件不支持返回 [碎片](https://reactjs.org/docs/fragments.html)这意味着你需要 关闭 `<Reference />` 财务报告和审定财务报表 `<Popper />` 变成单一的、共同的、, `<div />` 将制作 `react-popper` 工作时.

### API 文档

这个 `Manager` 组件是一个简单的包装器,需要包围其它所有 `react-popper` 按顺序排列 让他们互相交流.

这个 `Popper` 组件接受属性 `children`, (中文(简体) ), `placement`, (中文(简体) ), `modifiers`, (中文(简体) ), `eventsEnabled` 财务报告和审定财务报表 `positionFixed`。 。 。 .

```jsx
<Popper
  innerRef={(node) => this.popperNode = node}
  placement="right"
  modifiers={{ preventOverflow: { enabled: false } }}
  eventsEnabled={true}
  positionFixed={false}
>
    { props => [...] }
</Popper>
```

##### `children`

```js
children: ({|
  ref: (?HTMLElement) => void,
  style: { [string]: string | number },
  placement: ?Placement,
  outOfBoundaries: ?boolean,
  scheduleUpdate: () => void,
  arrowProps: {
    ref: (?HTMLElement) => void,
    style: { [string]: string | number },
  },
|}) => Node
```

将包含下列属性的对象作为参数的函数( 递归道具):

-   **`ref`**: 用来取回 [反应参考器](https://reactjs.org/docs/refs-and-the-dom.html) 会 议 日 程 和 议 程 **流行乐** 键.
-   **`style`**: 包含必要的 CSS 样式( React CSS 属性),由 Popper.js 计算以正确定位 **流行乐** 键.
-   **`placement`**: 描述在 Popper.js 应用了所有的修饰符后, 您的 popper 的放置 可能翻转或更改原提供的 `placement` 属性。 你可以用这个来改变 弹出器的样式和箭头的样式。 比如,你可以用这个 属性将箭头指向正确的方向.
-   **`outOfBoundaries`**:一个布尔表示如果弹出元素超越其边界.
-   **`scheduleUpdate`**: 您可以调用一个函数来调度一个 Popper.js 位置更新 。 它会直接呼叫 [波普尔# 时间安排更新](https://popper.js.org/popper-documentation.html#Popper.scheduleUpdate) 方法.
-   **`arrowProps`**: 一个对象,包含 `style` 财务报告和审定财务报表 `ref` 属性与 第1和第2个论点: `children`,但相对 **箭头** 键。 这个 `style` 属性包含 `left` 财务报告和审定财务报表 `top` 偏移值,用于将箭头置于弹出器内。 这些值可以与进一步的自定义样式和定位相合并. 见 [演示](https://github.com/FezVrasta/react-popper/blob/8994933c430e48ab62e71495be71e4f440b48a5a/demo/styles.js#L100) 举个例子.

##### `innerRef`

```js
innerRef?: (?HTMLElement) => void
```

可用于获取 popper 引用的函数

##### `placement`

```js
placement?: PopperJS$Placement;
```

表格中所列公认放置值之一 [Popper.js 文档](https://popper.js.org/popper-documentation.html#Popper.placements)。 。 。 .  
您的流行乐会根据这个地产的价值来放置.  
默认为 `bottom`。 。 。 .

```js
outOfBoundaries: ?boolean;
```

可以用来隐藏弹出元素的布尔 以防其溢出 从它的边界. [更多信息](https://popper.js.org/popper-documentation.html#modifiers..hide)。 。 。 .

##### `eventsEnabled`

```js
eventsEnabled?: boolean;
```

告诉 `react-popper` 以启用或禁用 [Popper.js 事件听众](https://popper.js.org/popper-documentation.html#Popper.Defaults.eventsEnabled)。 。 。 . `true` 默认.

##### `positionFixed`

设定此属性为 `true` 告诉Popper.js使用 `position: fixed` 战略 以定位弹出元素。 默认是虚假的,意味着它会使用 `position: absolute` 战略.

##### `modifiers`

```js
modifiers?: PopperJS$Modifiers;
```

包含自定义设置的对象 [Popper.js 修饰器](https://popper.js.org/popper-documentation.html#modifiers)。 。 。 .  
您可以使用此属性来覆盖他们的设置或注入自定义的设置 .

## 用法为 `ReactDOM.createPortal`

Popper.js聪明到可以工作,即使 **流行乐** 财务报告和审定财务报表 **参考文献** 元素没有 在同一DOM语境中.  
这意味着你可以使用 [`ReactDOM.createPortal`](https://reactjs.org/docs/portals.html) (或任何预回16的可选方案)将弹出元件移到DOM的别处.

如果您想要将工具提示放置在 `overflow: hidden` 集装箱 以便你们欲溢出。 请注意,你也可以尝试 `positionFixed` 战略 用更少的麻烦获得类似的效果.

```jsx
import { Manager, Reference, Popper } from 'react-popper';

const Example = () => (
  <Manager>
    <Reference>
      {({ ref }) => (
        <button type="button" ref={ref}>
          Reference
        </button>
      )}
    </Reference>
    {ReactDOM.createPortal(
      <Popper>
        {({ placement, ref, style }) => (
          <div ref={ref} style={style} data-placement={placement}>
            Popper
          </div>
        )}
      </Popper>,
      document.querySelector('#destination')
    )}
  </Manager>
);
```

## 无参考文献的使用 `HTMLElement`

每当您需要根据任意坐标定位弹出器时,您可以提供 `Popper` 带有 `referenceElement` 用于替换 `referenceProps.getRef` 反应裁判.

这个 `referenceElement` 属性必须是具有兼容 `HTMLElement` 一、导 言 [Popper.js 参考对象文档](https://popper.js.org/popper-documentation.html#referenceObject),这意味着如果需要,您也可以提供真实的 HTML 元素.

若为 `referenceElement` 将优先于任何 `referenceProps.ref` 提供参考文献.

```jsx
import { Popper } from 'react-popper';

class VirtualReference {
  getBoundingClientRect() {
    return {
      top: 10,
      left: 10,
      bottom: 20,
      right: 100,
      width: 90,
      height: 10,
    };
  }

  get clientWidth() {
    return this.getBoundingClientRect().width;
  }

  get clientHeight() {
    return this.getBoundingClientRect().height;
  }
}

// This is going to create a virtual reference element
// positioned 10px from top and left of the document
// 90px wide and 10px high
const virtualReferenceElement = new VirtualReference();

// This popper will be positioned relatively to the
// virtual reference element defined above
const Example = () => (
  <Popper referenceElement={virtualReferenceElement}>
    {({ ref, style, placement, arrowProps }) => (
      <div ref={ref} style={style} data-placement={placement}>
        Popper element
        <div ref={arrowProps.ref} style={arrowProps.style} />
      </div>
    )}
  </Popper>
);
```

## 流程和类型脚本类型

这个库是用Flow构建的,但它也支持TypeScript.

您可以在 `src/index.js`,则 类型脚本定义 `typings/react-popper.d.ts`。 。 。 .

## 本地运行

#### 安装依赖关系

`yarn`

#### 运行 dev 模式

`yarn demo:dev`

#### 打开浏览器访问 :

`http://localhost:1234/`

## 常见问题

### @elliemae/react-popper 是什么？

Popper\.js周围的反应包装器

### 如何安装 @elliemae/react-popper？

在项目目录运行 npm install @elliemae/react-popper，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^16\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @elliemae/react-popper 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @elliemae/react-popper 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @elliemae/react-popper 可以商用吗？

@elliemae/react-popper 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @elliemae/react-popper 的下载量有多少？

根据 npm 官方下载统计，@elliemae/react-popper 在 2026/10/14 – 2026/11/12 这 30 天内被下载 5,085 次，日均约 170 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @elliemae/react-popper 还在维护吗？

最新版本 1\.0\.2 发布于 2022/01/19（4 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/01/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。