# @charlietango/use-focus-trap 中文文档

规范地址：https://npmcn.com/package/%40charlietango/use-focus-trap/

版本：1\.4\.0
npm 元数据更新时间：2024-07-29T12:18:19.747Z
中文译文更新时间：2026-11-09T10:55:21.114Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40charlietango/use-focus-trap
原文对照：https://npmcn.com/package/%40charlietango/use-focus-trap/?lang=original
项目主页：https://github.com/charlie-tango/hooks#readme
源码仓库：https://github.com/charlie-tango/hooks

弃用说明：No longer supported\. Migrate to a new solution for support, or copy the code into the project

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

- 包体积（解压后）：22.8 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^15\.0\.0 \|\| ^16\.0\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0，react-dom ^15\.0\.0 \|\| ^16\.0\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0
- 首次发布：2019-02-28T19:46:17.449Z
- 最新版本发布：2022-04-14T21:10:51.370Z
- 近 30 天下载量：11921（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 0 个）

## 中文简介

陷阱键盘聚焦于 DOM 元素内, 以防止用户在模式外导航

## 安装

```sh
npm install @charlietango/use-focus-trap
```

也可以使用：`pnpm add @charlietango/use-focus-trap`、`yarn add @charlietango/use-focus-trap`、`bun add @charlietango/use-focus-trap`

## README

# 焦点文字

陷阱键盘聚焦在 DOM 元素内,以防止用户在模式外导航. 在使用此选项时, 请确保将其与固定位置结合 `<Backdrop>` 以阻止鼠标单击输入元素.

> 检查 [故事书](https://ct-hooks.now.sh/?path=/story/usefocustrap--readme) 演示.

## 安装

```sh
yarn add @charlietango/use-focus-trap
```

## API 密码

```js
const ref = useFocusTrap(active, options)
```

这个 `useFocusTrap` 钩子返回 a `ref` 您应该指定 DOM 元素,该元素需要锁定焦点. 除了这个元素之外,任何因素都不再能够集中.

您可以通过设置 `active` 布尔。 默认一旦 `ref` 指定.

### 选项

焦点陷阱接受一个带有这些可选选项的对象,这可以让你得到更多的控制.

| 名称 | 类型 | 默认 | 需求 | 说明 |
| --- | --- | --- | --- | --- |
| **焦点选择器** | `string` 编号 : `HTMLElement` | `undefined` | 虚假 | 启动时将焦点指定为匹配此选择器的元素 - 或您提供的特定元素 。 默认焦点将设定为第一个有效的标签目标 . |
| **已禁用 AriaHider** | `boolean` | `false` | 虚假 | 禁用设置 `aria-hidden` 内的其他要素 `document.body` 当陷阱正在激活时. |

## 示例

```jsx
import React from 'react'
import useFocusTrap from '@charlietango/use-focus-trap'

const Component = () => {
  const ref = useFocusTrap()
  return (
    <div ref={ref}>
      <button>Trapped to the button</button>
    </div>
  )
}

export default Component
```

### 创建模式

当使用这个钩子创建出一个Modal时,你还需要处理一些事情,这超出了这个钩子的范围:

-   陷阱焦点
-   越狱时关闭
-   点击背景关闭

#### 基数Modal.tsx

这是创建 `<Modal />`它收到一个 `onRequestClose` 方法, ,可以被触发来告诉包含的组件更新它状态关闭模式. 它没有包含 `<Backdrop />`,但这将是一个绝对位置部分 当点击触发时 `onRequestClose` 方法.

```typescript
import React, { useEffect } from 'react'
import ReactDOM from 'react-dom'
import useFocusTrap from '@charlietango/use-focus-trap'
import styled from 'styled-components'

type Props = {
  onRequestClose?: () => void
  children?: React.ReactNode
  isOpen: boolean
  className?: string
}

const Wrapper = styled.div`
  position: fixed;
  left: 0;
  right: 0;
  top: 0;
  bottom: 0;
  z-index: 5;
`

function BaseModal({ children, isOpen, onRequestClose, className }: Props) {
  const ref = useFocusTrap()

  function handleKeyDown(event: KeyboardEvent) {
    if (event.key === 'Escape') {
      if (onRequestClose) onRequestClose()
    }
  }

  useEffect(() => {
    if (isOpen) {
      document.addEventListener('keydown', handleKeyDown)
      return () => {
        document.removeEventListener('keydown', handleKeyDown)
      }
    }

    return
  }, [isOpen])

  const modal = (
    <Wrapper
      ref={ref}
      style={{ pointerEvents: !isOpen ? 'none' : undefined }}
      role="dialog"
      className={className}
    >
      {children}
    </Wrapper>
  )

  return ReactDOM.createPortal(modal, window.document.body)
}

BaseModal.displayName = 'BaseModal'
BaseModal.defaultProps = {}

export default BaseModal
```

## 常见问题

### @charlietango/use-focus-trap 是什么？

陷阱键盘聚焦于 DOM 元素内, 以防止用户在模式外导航注意：该包已被作者标记为弃用——No longer supported\. Migrate to a new solution for support, or copy the code into the project

### 如何安装 @charlietango/use-focus-trap？

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

### @charlietango/use-focus-trap 支持 TypeScript 吗？

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

### @charlietango/use-focus-trap 支持 ESM 还是 CommonJS？

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

### @charlietango/use-focus-trap 可以商用吗？

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

### @charlietango/use-focus-trap 的下载量有多少？

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

### @charlietango/use-focus-trap 还在维护吗？

最新版本 1\.4\.0 发布于 2022/04/15（4 年前）；至今共发布 16 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/03/01。作者已将其标记为弃用，新项目建议寻找替代方案。