# @codastic/react-positioning-portal 中文文档

规范地址：https://npmcn.com/package/%40codastic/react-positioning-portal/

版本：0\.8\.0
npm 元数据更新时间：2025-11-18T14:31:05.875Z
中文译文更新时间：2026-11-10T05:36:45.146Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40codastic/react-positioning-portal
原文对照：https://npmcn.com/package/%40codastic/react-positioning-portal/?lang=original
项目主页：https://github.com/codastic/react-positioning-portal#readme
源码仓库：https://github.com/codastic/react-positioning-portal

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

- 包体积（解压后）：86.8 kB，47 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.0\.0
- 运行依赖：0 个
- peer 依赖：react ^16\.12\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0，react-dom ^16\.12\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0
- 首次发布：2020-04-10T08:10:38.006Z
- 最新版本发布：2025-11-18T14:31:05.637Z
- 近 30 天下载量：25204（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 1 个）

## 中文简介

定位出入口是一个低级反应组件,用于构建各种绝对定位的飞出,它们被锚入了景点中的另一个元素. 这可用于创建下拉,工具提示,上下文菜单等.

## 安装

```sh
npm install @codastic/react-positioning-portal
```

也可以使用：`pnpm add @codastic/react-positioning-portal`、`yarn add @codastic/react-positioning-portal`、`bun add @codastic/react-positioning-portal`

## README

# 反应定位门户

[![Build Status](https://travis-ci.org/codastic/react-positioning-portal.svg?branch=master)](https://travis-ci.org/codastic/react-positioning-portal) ![NPM](https://img.shields.io/npm/l/@codastic/react-positioning-portal)

定位门户是一个低级反应组件,用于构建各种 完全定位的飞行器 被固定在景点的另一部分. 这可用于创建下拉,工具提示,上下文菜单等.

定位门户的构建尽可能不开放 这意味着它只创建微小的DOM 并且不依赖于特定样式的图书馆。 它只在出入口上使用一些内置样式来进行定位.

门户相对于其主机在DOM中的位置由下列定义: _定位战略_。 。 。 . 默认定位策略应足以用于大量使用案例. 要么就把门户放在上面 (左或右对齐)到锚或下方,取决于当前取景口中可用的空间. 此默认策略完全适合构建例如自定义下拉.

还有可能覆盖定位战略. 工具提示的示例如下: [故事书](https://codastic.github.io/react-positioning-portal/?path=/story/example-tooltip--base)。 。 。 .

见 [故事书](https://codastic.github.io/react-positioning-portal/) 需要更多的实例.

## 安装

```
$ npm install @codastic/react-positioning-portal react react-dom --save
```

## 使用量

基本用途 `<PositioningPortal />` 州治在外边.

```
import { useState } from 'react';
import { PositioningPortal } from '@codastic/react-positioning-portal';

// ...

const [isPortalOpen, setIsPortalOpen] = useState(false);

<PositioningPortal
  isOpen={isPortalOpen}
  onOpen={() => setIsPortalOpen(true)}
  onShouldClose={() => setIsPortalOpen(false)}
  portalContent={
    <div>
      Portal content goes here.
      <button type="button" onClick={() => setIsPortalOpen(false)}>
        Close
      </button>
    </div>
  }
>
  <button type="button" onClick={() => setIsPortalOpen(true)}>
    Open portal
  </button>
</PositioningPortal>
```

基本用途 `<PositioningPortalWithState />` 处理内部状态.

```
import { PositioningPortalWithState } from '@codastic/react-positioning-portal';

// ...

<PositioningPortalWithState
  portalContent={
    <div>
      Portal content goes here.
    </div>
  }
>
  {({ open}) => (
    <button type="button" onClick={open}>
      Open portal
    </button>
  )}
</PositioningPortalWithState>
```

## 特征

### `<PositioningPortal />`

-   支持自定义定位策略.
-   在定位门外处理国家事务.
-   手接外出点击关闭门户.
-   处理下键关闭门户.
-   开关时的门户过渡.
-   定义门户的自定义根节点.

### `<PositioningPortalWithState />`

这个组件几乎相当于 `<PositioningPortal />` 除外 页:1 `isOpen` 状态已经由组件本身处理。 所以,如果你不必控制这个州外 可以比较容易使用 `<PositioningPortalWithState />` 让它自己处理国家.

## API 参考

### `<PositioningPortal />`

-   `children: React.ReactNode`数字 :
    
    定位门户组件将门户的锚点要素作为儿童。 内容 `width` 传递到 `portalContent` 渲染道具参数 `relatedWidth`。 。 。 .
    
-   `portalElement?: React.ReactElement`: (默认值 : `<div />`(中文(简体) )
    
    这个 `portalElement` 覆盖 `portalContent`在渲染时 `portalContent` 定位门户附件 样式 `position`, (中文(简体) ), `width`, (中文(简体) ), `left`, (中文(简体) ), `top` 财务报告和审定财务报表 `visibility` 页:1 `portalElement`通过定义自己的风格 `portalElement` 你可以覆盖这些风格。 例如,如果您喜欢为门户设置固定位置,您可以 执行下列:
    
    ```
      <PositioningPortal
        portalElement={<div style={{ position: 'fixed' }} />}
      >
      // ...
    ```
    
-   `portalContent: React.ReactNode | ((params: PortalContentRenderProps<Strategy>) => React.ReactNode);`数字 :
    
    门户开放时提供实际内容. `portalContent` 可以是任何反应节点或函数 返回反应节点。 该功能获得以下道具:
    
    ```
    interface PortalContentRenderProps<Strategy> {
      close: () => void; // Basically calls the handler passed to onShouldClose
      isOpen: boolean;
      isPositioned: boolean; // Becomes true after the portalContent is positioned and visible
      strategy: Strategy; // Whatever the positionStrategy returns
      relatedWidth: number; // The width of the PositioningPortal children
      transitionStarted: () => void; // Signals that there is a transition
      transitionEnded: () => void; // Should be called when the portal can safely be removed from the DOM
    }
    ```
    
-   `onOpen: () => void`数字 :
    
    将在门户内容定位和可见后调用.
    
-   `onClose?: () => void`
    
    门户关上后召回.
    
-   `onShouldClose?: () => void`数字 :
    
    如果 `PortalContentRenderProps.close` 在门户内容之外点击( 如果有的话) `closeOnOutsideClick` 是真实的)或 `closeOnKeyDown` 返回真实.
    
-   `closeOnOutsideClick?: boolean`: (默认值 : `true`(中文(简体) )
    
    如果设置为 `true`, (中文(简体) ), `onShouldClose` 通过在门户内容外点击来拨打.
    
-   `closeOnKeyDown?: (event: KeyboardEvent) => boolean`: (默认值 : `event => event.keyCode === 27`,关闭 ESC)
    
    函数,将调用 `keydown`。如果返回的话 `true`,处理器传递给 `onShouldClose` 将召入.
    
-   `isOpen?: boolean`数字 :
    
    设置要打开或关闭的定位门户.
    
-   `positionStrategy?: PositioningStrategy<Strategy>`数字 :
    
    设置自定义定位战略。 详见"定位战略"部分.
    
-   `rootNode?: HTMLElement`数字 :
    
    为要添加的门户通过自定义根节点 .
    

### `<PositioningPortalWithState />`

扩展属性 `<PositioningPortal />` 并添加/更改起伏属性:

-   `children: React.ReactNode | ((params: RenderProps) => React.ReactNode)`数字 :
    
    由于状态是在组成部分内处理的,因此有可能通过渲染功能使儿童得到以下渲染道具:
    
    ```
    interface RenderProps {
      close: () => void;
      open: () => void;
      isOpen: boolean;
    }
    ```
    

### 定位 战略

定位策略是接收母锚元素矩形的函数 `parentRect` 相对于取景口(以 `getBoundingClientRect()`(中文(简体) ) 和传送门的矩形。 在第一个渲染阶段,在调用定位战略之前,门户是隐形的.

战略职能部门应返回门户的位置(`top` 财务报告和审定财务报表 `left`) (中文(简体) ). 我可以选择返回其他任意数据(`strategy`),可用于自定义传送门的渲染. 例如,定义工具提示箭头的取向.

```
const positionStrategy (
  parentRect,
  portalRect
  props
) => {
  // Compute where the portal should be positioned...

  return {
    top,
    left,
    strategy
  };
};
```

这就是定位策略的类型定义:

```
export type PositioningStrategy<Strategy> = (
  parentRect: ClientRect,
  portalRect: ClientRect,
  props: Props<Strategy>
) => {
  top: number;
  left: number;
  strategy: Strategy;
};
```

## 实例

-   [由按钮打开的基本门户.](https://codastic.github.io/react-positioning-portal/?path=/story/positioningportal--base)
    
-   [基本门户动画](https://codastic.github.io/react-positioning-portal/?path=/story/positioningportal--with-animation) [反应- 过渡组](https://github.com/reactjs/react-transition-group)。 。 。 .
    
-   [和锚地元素相同宽度的门户.](https://codastic.github.io/react-positioning-portal/?path=/story/positioningportal--same-width-as-parent)
    
-   [关闭外部点击时禁用](https://codastic.github.io/react-positioning-portal/?path=/story/positioningportal--no-click-outside-close)
    
-   [关闭密钥的传送门 .](https://codastic.github.io/react-positioning-portal/?path=/story/positioningportal--close-on-keydown-q)
    
-   [内部有状态处理的基本工具提示](https://codastic.github.io/react-positioning-portal/?path=/story/positioningportalwithstate--base)
    
-   [简单工具端](https://codastic.github.io/react-positioning-portal/?path=/story/example-tooltip--base)
    
-   [带有首选位置的工具提示](https://codastic.github.io/react-positioning-portal/?path=/story/example-tooltip--preferred-position-top)

## 常见问题

### @codastic/react-positioning-portal 是什么？

定位出入口是一个低级反应组件,用于构建各种绝对定位的飞出,它们被锚入了景点中的另一个元素\. 这可用于创建下拉,工具提示,上下文菜单等\.

### 如何安装 @codastic/react-positioning-portal？

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

### @codastic/react-positioning-portal 支持 TypeScript 吗？

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

### @codastic/react-positioning-portal 支持 ESM 还是 CommonJS？

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

### @codastic/react-positioning-portal 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @codastic/react-positioning-portal 可以商用吗？

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

### @codastic/react-positioning-portal 的下载量有多少？

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

### @codastic/react-positioning-portal 还在维护吗？

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