# @depasquale/three-immersive-controls 中文文档

规范地址：https://npmcn.com/package/%40depasquale/three-immersive-controls/

版本：0\.0\.17
npm 元数据更新时间：2024-09-27T16:35:47.868Z
中文译文更新时间：2026-11-11T23:09:02.723Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：416 kB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2022-03-05T19:42:20.997Z
- 最新版本发布：2024-09-27T16:35:47.678Z
- 近 30 天下载量：38940（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 0 个）

## 中文简介

Three.js 的相接( VR) 控制

## 安装

```sh
npm install @depasquale/three-immersive-controls
```

也可以使用：`pnpm add @depasquale/three-immersive-controls`、`yarn add @depasquale/three-immersive-controls`、`bun add @depasquale/three-immersive-controls`

## README

# 三.j. 隐形控制

-   Immersive (VR) 函数
    -   以 VR 控制器进行移动和旋转(用左拇指杆移动,用右拇指杆旋转)
    -   使用 VR 控制器选择对象( R)`A` 按钮或触发)
-   浏览器窗口功能
    -   键盘的移动和旋转( WASD 和箭头键)
    -   使用鼠标选择对象

### 安装

```
npm install @depasquale/three-immersive-controls
```

### 使用量

```javascript
import ImmersiveControls from '@depasquale/three-immersive-controls';

// Create the `camera`, `renderer`, and `scene` instances with Three.js
// ...

const controls = new ImmersiveControls(camera, renderer, scene, { /* options */ });
```

将此包含在渲染循环中 :

```javascript
controls.update();
```

### 选项

-   `initialPosition: THREE.Vector3`
    -   玩家在现场的初始位置. 默认是 `new THREE.Vector3(0, 1.6, 4)`。 。 。 .
-   `lookAt: THREE.Vector3`
    -   玩家最初方向的点。 (尚未执行。 )
-   `floor: number | false`
    -   `number` (默认为 `0`: 设置玩家无法通过下层的y位置(简单解决碰撞探测而不是导航).
    -   `false`:没有设定玩家沿y轴移动的限制.
-   `gravity: true | false`
    -   `true` (默认) : 玩家的移动被限制在x和z轴上,而y的位置仍然位于 `floor` 设置.
    -   `false`:玩家也可以沿着y轴(飞行模式)垂直移动.
-   `moveSpeed: { keyboard: number, vr: number }`
    -   玩家收到键盘或VR控制器输入时通过场景移动的速度. 默认是 `{ vr: 2.5, keyboard: 5 }`。 。 。 .
-   `rotateSpeed: number`
    -   收到键盘或VR控制器输入时玩家旋转的速度. 默认是 `1`。 。 。 .
-   `tumble: true | false`
    -   允许玩家在y轴之外再在x轴上旋转. 默认是 `false`。 。 。 .
-   `showControllerModel: true | false`
    -   以浸入模式显示 VR 控制器 。 默认是 `true`。 。 。 .
-   `showEnterVRButton: true | false`
    -   在 DOM 中添加一个按钮,允许用户在此功能被支持时进入浸入模式. 默认是 `true`。 。 。 .
-   `showExitVRButton: true | false`
    -   在现场玩家面前显示一个按钮,允许用户退出浸润模式. 默认是 `true`。 。 。 .
-   `vrControls: true | false`
    -   激活活化(VR)控制. 默认是 `true`。 。 。 .
-   `keyboardControls: true | false`
    -   激活键盘控制器 。 默认是 `true`。 。 。 .
-   `mouseControls: true | false`
    -   激活鼠标控制器 。 默认是 `true`. (使用鼠标输入的运动尚未执行,但使用鼠标进行对象选择。)
-   `showFps: true | false`
    -   显示 `Stats` 指示器在 DOM 中,并在现场的玩家面前监视性能. 默认是 `false`。 。 。 .

### 实例

报告提供了实例 `examples` 目录。 要在浏览器中本地尝试, 请运行 :

```
npm run examples
```

或者试试看 [这里](https://unpkg.com/@depasquale/three-immersive-controls/examples/index.html)。 。 。 .

### 来做

-   添加与导航相撞的探测
-   使用多种 VR 设备的测试( 目前仅使用 Oculus Quest 2 测试)
-   处理只有一个 VR 控制器的情况
-   为触摸屏设备添加控制
-   在现场更好地重新定位"Exit VR"按钮
-   可能的其他特征
    -   远程传送
    -   旋转和移动时的盲人
    -   用鼠标输入移动
    -   手迹追踪

## 常见问题

### @depasquale/three-immersive-controls 是什么？

Three\.js 的相接\( VR\) 控制

### 如何安装 @depasquale/three-immersive-controls？

在项目目录运行 npm install @depasquale/three-immersive-controls，或使用 pnpm add / yarn add / bun add。

### @depasquale/three-immersive-controls 支持 TypeScript 吗？

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

### @depasquale/three-immersive-controls 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @depasquale/three-immersive-controls 可以商用吗？

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

### @depasquale/three-immersive-controls 的下载量有多少？

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

### @depasquale/three-immersive-controls 还在维护吗？

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