# @chakra-ui/modal 中文文档

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

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

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

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

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

- 包体积（解压后）：578 kB，123 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：react \>=18，react-dom \>=18，framer-motion \>=4\.0\.0，@chakra-ui/system \>=2\.0\.0
- 首次发布：2020-06-20T20:43:23.824Z
- 最新版本发布：2023-09-08T23:04:22.634Z
- 近 30 天下载量：1286501（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：511（近 12 个月 0 个）

## 中文简介

React & Chakra UI 可访问对话框( 模式) 组件

## 安装

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

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

## README

# @ chakra-ui/ 模式

模式是主窗口或其他对话框上覆盖的窗口 窗口。 模式对话框后面的内容 **惰性** 表示用户不能 与对话框后面的内容交互.

## 安装

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

# or

npm i @chakra-ui/modal
```

## 导入组件

```jsx
import {
  Modal,
  ModalOverlay,
  ModalContent,
  ModalHeader,
  ModalFooter,
  ModalBody,
  ModalCloseButton,
} from "@chakra-ui/react"
```

## 使用量

当模式打开时, 焦点被传送到模式并设定为第一个可制表符 键。 如果没有标签元素,则将焦点设置在 `ModalContent`。 。 。 .

```jsx
function BasicUsage() {
  const { isOpen, onOpen, onClose } = useDisclosure()
  return (
    <>
      <Button onClick={onOpen}>Open Modal</Button>

      <Modal isOpen={isOpen} onClose={onClose}>
        <ModalOverlay>
          <ModalContent>
            <ModalHeader>Modal Title</ModalHeader>
            <ModalCloseButton />

            <ModalBody>
              <Lorem count={2} />
            </ModalBody>

            <ModalFooter>
              <Button colorScheme="blue" mr={3} onClick={onClose}>
                Close
              </Button>
              <Button variant="ghost">Secondary Action</Button>
            </ModalFooter>
          </ModalContent>
        </ModalOverlay>
      </Modal>
    </>
  )
}
```

### Modal 关闭时控制焦点

当对话框关闭时, 它返回焦点到触发的元素 。 设定 `finalFocusRef` ,用于在模式打开时应当聚焦的元素.

```jsx
function ReturnFocus() {
  const { isOpen, onOpen, onClose } = useDisclosure()
  const finalRef = React.useRef()

  return (
    <>
      <Box ref={finalRef} tabIndex={-1} aria-label="Focus moved to this box">
        Some other content that'll receive focus on close.
      </Box>

      <Button mt={4} onClick={onOpen}>
        Open Modal
      </Button>

      <Modal finalFocusRef={finalRef} isOpen={isOpen} onClose={onClose}>
        <ModalOverlay>
          <ModalContent>
            <ModalHeader>Modal Title</ModalHeader>
            <ModalCloseButton />
            <ModalBody>
              <Lorem count={2} />
            </ModalBody>

            <ModalFooter>
              <Button colorScheme="blue" mr={3} onClick={onClose}>
                Close
              </Button>
              <Button variant="ghost">Secondary Action</Button>
            </ModalFooter>
          </ModalContent>
        </ModalOverlay>
      </Modal>
    </>
  )
}
```

# 提醒对话框

提醒Dialog 组件使用强制确认中断用户 或行动.

## 安装

```sh
yarn add @chakra-ui/alert-dialog

# or

npm i @chakra-ui/alert-dialog
```

## 导入组件

```jsx
import {
  AlertDialog,
  AlertDialogBody,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogContent,
  AlertDialogOverlay,
} from "@chakra-ui/react"
```

## 基本用途

## 使用量

警报Dialog要求您提供 `leastDestructiveRef` 道具 (英语).

依据 [WAI-ARIA 规格](https://www.w3.org/TR/wai-aria-practices/#alertdialog), (中文(简体) ), 当对话框打开时,重点应放在破坏最小的元素上, 防止用户意外确认破坏行动.

```jsx
function AlertDialogExample() {
  const [isOpen, setIsOpen] = React.useState()
  const onClose = () => setIsOpen(false)
  const cancelRef = React.useRef()

  return (
    <>
      <Button colorScheme="red" onClick={() => setIsOpen(true)}>
        Delete Customer
      </Button>

      <AlertDialog
        isOpen={isOpen}
        leastDestructiveRef={cancelRef}
        onClose={onClose}
      >
        <AlertDialogOverlay>
          <AlertDialogContent>
            <AlertDialogHeader fontSize="lg" fontWeight="bold">
              Delete Customer
            </AlertDialogHeader>

            <AlertDialogBody>
              Are you sure? You can't undo this action afterwards.
            </AlertDialogBody>

            <AlertDialogFooter>
              <Button ref={cancelRef} onClick={onClose}>
                Cancel
              </Button>
              <Button colorScheme="red" onClick={onClose} ml={3}>
                Delete
              </Button>
            </AlertDialogFooter>
          </AlertDialogContent>
        </AlertDialogOverlay>
      </AlertDialog>
    </>
  )
}
```

## 使用打字符

使用以上示例会丢出一个打字错误 。 你会想修改 类型 `useRef` 钩入您所关注的和 HTML 元素 默认值为无效.

```tsx
const cancelRef = React.useRef<HTMLButtonElement>(null)
```

# 绘图器

抽取器组件是一个从屏幕边缘滑出面板. 这个 当用户需要完成某项任务或查看一些细节时,可以有用 不离开当前页面.

## 安装

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

# or

npm i @chakra-ui/modal
```

## 导入组件

```jsx
import {
  Drawer,
  DrawerOverlay,
  DrawerContent,
  DrawerHeader,
  DrawerFooter,
  DrawerBody,
  DrawerCloseButton,
} from "@chakra-ui/react"
```

## 基本用途

## 使用量

默认情况下,将焦点放在 `DrawerCloseButton` 当抽屉打开.

```jsx
function DrawerExample() {
  const { isOpen, onOpen, onClose } = useDisclosure()
  const btnRef = React.useRef()

  return (
    <>
      <Button ref={btnRef} colorScheme="teal" onClick={onOpen}>
        Open
      </Button>
      <Drawer
        isOpen={isOpen}
        placement="right"
        onClose={onClose}
        finalFocusRef={btnRef}
      >
        <DrawerOverlay />
        <DrawerContent>
          <DrawerCloseButton />
          <DrawerHeader>Create your account</DrawerHeader>

          <DrawerBody>
            <Input placeholder="Type here..." />
          </DrawerBody>

          <DrawerFooter>
            <Button variant="outline" mr={3} onClick={onClose}>
              Cancel
            </Button>
            <Button color="blue">Save</Button>
          </DrawerFooter>
        </DrawerContent>
      </Drawer>
    </>
  )
}
```

## 常见问题

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

React & Chakra UI 可访问对话框\( 模式\) 组件

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

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

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

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

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

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

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

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

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

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

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

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