# @chakra-ui/popper 中文文档

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

版本：3\.1\.0
npm 元数据更新时间：2025-08-25T12:24:47.753Z
中文译文更新时间：2026-11-09T09:50:31.520Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：144 kB，36 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react \>=18
- 首次发布：2020-06-20T20:42:48.399Z
- 最新版本发布：2023-07-18T23:00:57.032Z
- 近 30 天下载量：1441515（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：160（近 12 个月 0 个）

## 中文简介

用于 poper.js 的回放组件和钩子包装器

## 安装

```sh
npm install @chakra-ui/popper
```

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

## README

# 弹出器

用于 poper.js 容器周围动态定位的反钩包装器 参考文献.

> 这是Chakra-UI的内部钩子,它没有被铸币局覆盖,可能 导致应用程序出现出乎意料或中断的行为。 冒着风险使用它们.

## 安装

```sh
yarn add @chakra-ui/popper
```

## 基本用途

默认情况下 `usePopper` 弹出器、 参考和 箭头.

```jsx
import { Box } from "@chakra-ui/layout"
import { Button } from "@chakra-ui/button"
import { useDisclosure } from "@chakra-ui/hooks"
import { usePopper } from "@chakra-ui/popper"

function Example() {
  const { isOpen, onToggle } = useDisclosure()
  const { popperRef, referenceRef, getArrowProps } = usePopper()
  return (
    <>
      <Button ref={referenceRef} onClick={onToggle} mb={2}>
        {isOpen ? "Click me to see less" : "Click me to see more"}
      </Button>
      {isOpen && (
        <Box ref={popperRef} bg="red">
          <div
            {...getArrowProps({
              style: {
                background: "red",
              },
            })}
          />
          This is a popover for the button!
        </Box>
      )}
    </>
  )
}
```

## 参数

### 改变位置

你可以改变流行乐的位置,通过 `placement` 选项到 `usePopper` 并设置到 `popper.js` 放置.

```jsx
const { popperRef, referenceRef } = usePopper({
  placement: "right-start",
})
```

### 匹配引用宽度

在某些情况下,你可能想要允许 Popper 取去宽度 参考文献。 例如,自动完成,选择等.

为了实现这一点,通过 `matchWidth` 选项并设定为 `true`

```jsx
const { popperRef, referenceRef } = usePopper({
  matchWidth: true,
})
```

### 将弹出器放入引用

您可以将弹出器放在参考文献旁边, 不带边距或距离 他们之间 用于创建自动完整或打字头特性 .

```jsx
const { popperRef, referenceRef } = usePopper({
  gutter: 0,
})
```

### 在固定容器内使用

如果参考元素在固定容器内,应当使用 `fixed` 战略.

```jsx
const { popperRef, referenceRef } = usePopper({
  strategy: "fixed",
})
```

## 添加过渡

当向 popper 组件添加过渡时,通常建议应用 popper)和向不同元素过渡.

```tsx
// 1. Import components
import { useDisclosure } from "@chakra-ui/hooks"
import { usePopper } from "@chakra-ui/popper"
import { motion, AnimatePresence, Variants } from "framer-motion"

export function Example() {
  // 2. Create toggle state
  const { isOpen, onToggle } = useDisclosure()

  // 3. Create motion variants
  const slide: Variants = {
    exit: {
      y: -2,
      opacity: 0,
    },
    enter: {
      y: 0,
      opacity: 1,
    },
  }

  // 4. Consume the `usePopper` hook
  const { getPopperProps, getReferenceProps, getArrowProps, transformOrigin } =
    usePopper({
      placement: "bottom-start",
    })

  return (
    <>
      <button {...getReferenceProps({ onClick: onToggle })}>Toggle</button>
      <div {...getPopperProps()}>
        <AnimatePresence>
          {isOpen && (
            <motion.div
              transition={{
                type: "spring",
                duration: 0.2,
              }}
              variants={slide}
              initial="exit"
              animate="enter"
              exit="exit"
              style={{
                background: "red",
                width: 200,
                transformOrigin,
                borderRadius: 4,
              }}
            >
              Testing
              <div
                {...getArrowProps({
                  style: {
                    background: "red",
                  },
                })}
              />
            </motion.div>
          )}
        </AnimatePresence>
      </div>
    </>
  )
}
```

> 当不有条件地使弹出器,我们建议使用 `visibility: hidden` 改为 `hidden` 或者说 `display: none`

## 常见问题

### @chakra-ui/popper 是什么？

用于 poper\.js 的回放组件和钩子包装器

### 如何安装 @chakra-ui/popper？

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

### @chakra-ui/popper 支持 TypeScript 吗？

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

### @chakra-ui/popper 支持 ESM 还是 CommonJS？

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

### @chakra-ui/popper 可以商用吗？

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

### @chakra-ui/popper 的下载量有多少？

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

### @chakra-ui/popper 还在维护吗？

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