# @custom-react-hooks/use-lock-body-scroll 中文文档

规范地址：https://npmcn.com/package/%40custom-react-hooks/use-lock-body-scroll/

版本：1\.5\.1
npm 元数据更新时间：2024-08-18T11:20:22.582Z
中文译文更新时间：2026-11-11T05:16:49.406Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40custom-react-hooks/use-lock-body-scroll
原文对照：https://npmcn.com/package/%40custom-react-hooks/use-lock-body-scroll/?lang=original
项目主页：https://custom-react-hooks-live.vercel.app/
源码仓库：https://github.com/djkepa/custom-react-hooks

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

- 包体积（解压后）：8.1 kB，8 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=16
- 首次发布：2023-12-01T23:49:14.504Z
- 最新版本发布：2024-08-18T11:20:22.357Z
- 近 30 天下载量：14770（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

`useLockBodyScroll` 用于控制网络应用程序中身体元素的滚动行为。 这对打开模式或上覆等需要禁用背景卷轴的情景特别有用.

## 安装

```sh
npm install @custom-react-hooks/use-lock-body-scroll
```

也可以使用：`pnpm add @custom-react-hooks/use-lock-body-scroll`、`yarn add @custom-react-hooks/use-lock-body-scroll`、`bun add @custom-react-hooks/use-lock-body-scroll`

## README

# 使用LockBody滚动钩

`useLockBodyScroll` 用于控制网络应用程序中身体元素的滚动行为。 这对打开模式或上覆等需要禁用背景卷轴的情景特别有用.

## 特征

-   **有条件的滚动锁 :** 允许您有条件启用或禁用身体滚动.
-   **样式保存 :** 保留了原车体外溢样式,并在卸载后恢复.
-   **服务器- Side 渲染( SSR) 兼容性 :** 在安全部门改革环境中使用的安全性,检查 `document` 对象.
-   **同步执行 :** 用途 `useLayoutEffect` 用于同步更新 DOM.

## 安装

### 只安装当前钩

```bash
npm install @custom-react-hooks/use-lock-body-scroll
```

或者说

```bash
yarn add @custom-react-hooks/use-lock-body-scroll
```

### 安装全部钩

```sh
npm install @custom-react-hooks/all
```

或者说

```sh
yarn add @custom-react-hooks/all
```

## 导入虎克

这个 `useLockBodyScroll` 钩必须使用下列命名的导入方式导入:

**已命名的导入 :**

```javascript
import { useLockBodyScroll } from '@custom-react-hooks/use-lock-body';
```

这种方法确保了钩子无缝地融入到您的项目中,在您如何使用我们的包时保持一致性和可预测性.

## 使用量

```typescript
import React, { useState } from 'react';
import { useLockBodyScroll } from '@custom-react-hooks/all';

const LockBodyScrollComponent= () => {
  const [isModalOpen, setIsModalOpen] = useState(false);
  useLockBodyScroll(isModalOpen);

  return (
    <div>
      <p>{isModalOpen ? 'Scroll hidden' : 'When you click on the button scroll will be hidden'}</p>
      <button onClick={() => setIsModalOpen(true)}>Open Modal</button>
      {isModalOpen && (
        <div className="modal">
          <div>
            <p>Modal Content</p>
            <button onClick={() => setIsModalOpen(false)}>Close Modal</button>
          </div>
        </div>
      )}
    </div>
  );
};

export default LockBodyScrollComponent;
```

在这个例子中,钩子用来锁住模式打开后的身体卷轴.

## API 参考

-   `lock`:一个布尔表示是否锁定(`true`)或解锁(`false`)身体卷轴.

## 使用大小写

1.  **模块和弹出**:这是最常用的用例. 当一个模式或弹出被打开时,往往需要锁定背景内容来阻止用户滚动. 这保持了对模式内容的关注.
    
2.  **满分菜单**:在移动响应设计或某些桌面布局中,当全屏菜单被打开时,您可能想要锁定滚动来保持用户对导航选项的关注.
    
3.  **入住流动或导游**:如果您的应用程序有分步登机的过程或导游,您可能想要锁定滚动,以确保用户在不分散注意力的情况下遵循流量.
    
4.  **图像或视频收藏**:当用户点击一幅图像或视频以更大的格式(如灯盒)查看时,将卷轴锁上可以去除背景分心来增强取景体验.
    
5.  **无限分卷预防**: 在某些情况下,您可能想要暂时禁用无限滚动特性. 例如,当一个用户执行需要注意或确认的动作时,可以锁定滚动来保持他们专注于任务.
    
6.  **交互式游戏或Quizzes**:如果在网络应用程序中嵌入游戏或试玩,在这些元素被聚焦时,可能想要锁定背景卷轴来增强用户参与,并预防出意外的卷轴脱落.
    
7.  **警报或重要通知**:当显示需要立即关注或采取行动的关键警报或通知时,使背景卷轴失效可以确保用户在不分散注意力的情况下处理这些警报.
    
8.  **复杂形式或调查**:在一个长而多步骤的形式或调查中,您可能想要在显示验证错误或重要信息时将卷轴锁定,以确保用户看到并承认这些消息.
    

## 捐款

你对改进的贡献 `useLockBodyScroll` 欢迎光临。 请随意向存储处提交问题或调取请求.

## 常见问题

### @custom-react-hooks/use-lock-body-scroll 是什么？

useLockBodyScroll 用于控制网络应用程序中身体元素的滚动行为。 这对打开模式或上覆等需要禁用背景卷轴的情景特别有用\.

### 如何安装 @custom-react-hooks/use-lock-body-scroll？

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

### @custom-react-hooks/use-lock-body-scroll 支持 TypeScript 吗？

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

### @custom-react-hooks/use-lock-body-scroll 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @custom-react-hooks/use-lock-body-scroll 可以商用吗？

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

### @custom-react-hooks/use-lock-body-scroll 的下载量有多少？

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

### @custom-react-hooks/use-lock-body-scroll 还在维护吗？

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