<!-- 代码功能和技术点详解
🎯 项目概述
这是一个基于Three.js和WebXR的VR手部追踪交互演示程序，展示了在虚拟现实环境中如何使用手部追踪技术实现自然的手势交互。

✨ 核心功能
1. 多模式手部可视化
提供三种不同风格的手部模型：

盒子模型：关节用立方体表示，简约风格

球体模型：关节用球体表示，抽象风格

网格模型：连续网格表面，逼真风格

左右手独立控制，可分别切换模型

2. 手势交互系统
捏合手势识别：通过pinchend事件检测用户捏合动作

模型切换机制：每次捏合手势切换一种手部模型

循环切换逻辑：三种模型按顺序循环显示

3. 双模式操作支持
VR沉浸模式：

使用VR设备（如Oculus Quest、HTC Vive等）

支持手部追踪无需控制器

真实的空间定位和手势交互

桌面预览模式：

使用鼠标和键盘控制视角

通过轨道控制器（OrbitControls）模拟VR视角

方便开发和调试

4. 完整的3D环境
场景搭建：包含地面、光照、阴影的完整3D场景

空间参考系：1.6米高的虚拟相机（模拟人眼高度）

视觉反馈：控制器射线指示器显示指向方向

🔧 主要技术点
1. WebXR API 集成
javascript
// 启用WebXR支持
renderer.xr.enabled = true;

// 要求手部追踪功能
const sessionInit = {
    requiredFeatures: ['hand-tracking']
};
WebXR Device API：连接VR/AR设备的标准化接口

手部追踪扩展：访问设备的骨骼手部追踪数据

会话管理：处理VR会话的进入、退出和状态管理

2. Three.js 核心架构
场景图系统：层次化的3D对象管理

相机系统：透视相机模拟人眼视角

渲染管线：WebGL渲染器负责图形绘制

几何体系统：BufferGeometry高效存储顶点数据

3. 控制器与手部模型管理
javascript
// 获取XR控制器和手部对象
controller1 = renderer.xr.getController(0);  // 左手控制器
hand1 = renderer.xr.getHand(0);              // 左手追踪数据

// 工厂模式创建模型
const handModelFactory = new XRHandModelFactory();
handModels.left = [
    handModelFactory.createHandModel(hand1, 'boxes'),
    handModelFactory.createHandModel(hand1, 'spheres'),
    handModelFactory.createHandModel(hand1, 'mesh')
];
控制器抽象层：统一处理不同XR设备的输入

工厂模式：标准化创建手部模型的过程

模型切换机制：通过可见性控制实现快速切换

4. 事件驱动交互
javascript
// 手势事件监听
hand1.addEventListener('pinchend', function() {
    // 隐藏当前模型
    handModels.left[this.userData.currentHandModel].visible = false;
    // 计算下一个模型索引
    this.userData.currentHandModel = (this.userData.currentHandModel + 1) % 3;
    // 显示新模型
    handModels.left[this.userData.currentHandModel].visible = true;
});
WebXR手势事件：pinchend、pinchstart等标准手势

自定义用户数据：在userData中存储模型状态

事件委托模式：手部对象直接处理自身事件

5. 光照与阴影系统
javascript
// 半球环境光
new THREE.HemisphereLight(0xbcbcbc, 0xa5a5a5, 3);

// 定向光（主光源）
const light = new THREE.DirectionalLight(0xffffff, 3);
light.castShadow = true;
light.shadow.mapSize.set(4096, 4096);
多光源组合：环境光+定向光实现真实光照

实时阴影：Shadow Mapping技术生成动态阴影

性能优化：合理设置阴影贴图分辨率

6. 响应式与性能优化
javascript
// 响应窗口大小变化
window.addEventListener('resize', onWindowResize);

// 动画循环
renderer.setAnimationLoop(animate);

// 设备像素比适配
renderer.setPixelRatio(window.devicePixelRatio);
响应式设计：自动适应不同屏幕尺寸

高效动画循环：setAnimationLoop替代传统RAF

高DPI适配：支持Retina等高分辨率显示

7. 模块化与可维护性
javascript
// ES6模块导入
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

// Import Maps配置
<script type="importmap">
{
    "imports": {
        "three": "../build/three.module.js",
        "three/addons/": "./jsm/"
    }
}
</script>
ES6模块系统：清晰的依赖关系管理

Import Maps：浏览器原生模块路径映射

代码分离：功能模块化，便于维护和扩展

🚀 技术亮点
1. 零控制器手部交互
摆脱传统控制器的限制

更自然的虚拟手部交互体验

降低VR使用门槛

2. 实时骨骼追踪
25个手部关节的实时追踪

亚毫米级精度（取决于设备）

低延迟数据传输

3. 跨平台兼容性
支持所有主流WebXR设备

优雅降级到桌面模式

无需安装原生应用

4. 开发者友好
详细的调试信息（场景挂载到window）

清晰的代码结构

完善的错误处理

🔍 应用场景
VR教育应用：手部交互的虚拟实验

虚拟培训：精细操作的手势模拟

沉浸式游戏：自然的手势控制

虚拟社交：手部表情和手势交流

原型设计：快速验证VR交互方案

📊 技术栈总结
技术层次	具体技术	作用
底层API	WebXR Device API	设备连接与数据获取
图形引擎	Three.js	3D图形渲染与场景管理
交互框架	WebXR Input Module	输入设备抽象与事件
模块系统	ES6 Modules	代码组织与依赖管理
样式层	CSS	基础页面样式
构建工具	Import Maps	模块路径解析 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：Three.js VR 手部输入 - 手部模型演示 -->
		<title>Three.js VR 手部输入 - 手部模型演示</title>
		<!-- 字符编码设置：UTF-8确保中文字符正确显示 -->
		<meta charset="utf-8">
		<!-- 视口设置：控制移动端显示，禁止用户缩放 -->
		<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
		<!-- 引入外部CSS样式表 -->
		<link type="text/css" rel="stylesheet" href="main.css">
	</head>
	<body>
		<!-- 页面顶部信息显示区域，用于展示项目信息和操作指引 -->
		<div id="info">
			<!-- Three.js官网链接 -->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> 
			VR - 手部输入 - 手部模型演示<br/>
			<!-- 操作说明：在VR中使用捏合手势切换手部模型 -->
			操作说明：在VR模式下，使用捏合手势可以切换手部模型（盒子/球体/网格三种样式）<br/>
			<!-- 技术特性说明 -->
			支持WebXR手部追踪 | 支持控制器交互 | 支持桌面模式预览
		</div>

		<!-- 导入映射（Import Map）：用于在支持原生ES模块的浏览器中配置模块导入路径 -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 主JavaScript模块：type="module"表示这是ES6模块，支持import/export语法 -->
		<script type="module">
			// ============ 模块导入部分 ============
			// 导入Three.js核心库的所有功能
			import * as THREE from 'three';
			// 导入轨道控制器：用于在桌面模式下用鼠标控制相机视角
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			// 导入VR按钮组件：自动创建进入/退出VR的UI按钮
			import { VRButton } from 'three/addons/webxr/VRButton.js';
			// 导入XR控制器模型工厂：用于创建3D控制器模型
			import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';
			// 导入XR手部模型工厂：用于创建手部追踪的3D手部模型
			import { XRHandModelFactory } from 'three/addons/webxr/XRHandModelFactory.js';

			// ============ 全局变量声明部分 ============
			// 容器变量：用于承载Three.js渲染的Canvas元素
			let container;
			// Three.js核心对象：相机、场景、渲染器
			let camera, scene, renderer;
			// XR手部对象：分别对应左手和右手的XR手部追踪数据
			let hand1, hand2;
			// XR控制器对象：分别对应左手和右手的XR控制器
			let controller1, controller2;
			// XR控制器握把对象：用于附着控制器3D模型
			let controllerGrip1, controllerGrip2;

			// 手部模型存储对象：使用对象字面量存储左右手的不同模型
			const handModels = {
				left: null,   // 左手模型数组，包含三种不同样式的手部模型
				right: null   // 右手模型数组，包含三种不同样式的手部模型
			};

			// 轨道控制器变量：用于非VR模式下的视角控制
			let controls;

			// ============ 初始化调用 ============
			// 页面加载完成后立即调用初始化函数
			init();

			/**
			 * 主初始化函数：设置Three.js场景、相机、渲染器、光照、控制器等所有必要组件
			 * 此函数按照特定顺序执行，确保依赖关系正确
			 */
			function init() {
				// ------------ 1. 创建和配置DOM容器 ------------
				// 创建一个新的div元素作为Three.js渲染的容器
				container = document.createElement('div');
				// 将容器添加到body中，使其成为页面的子元素
				document.body.appendChild(container);

				// ------------ 2. 创建Three.js场景 ------------
				// 创建场景对象：所有3D对象的容器
				scene = new THREE.Scene();
				// 将场景挂载到window对象上，方便在浏览器控制台中调试和访问
				window.scene = scene;
				// 设置场景背景颜色：深灰色（十六进制颜色码0x444444）
				scene.background = new THREE.Color(0x444444);

				// ------------ 3. 创建和配置相机 ------------
				// 创建透视相机：模拟人眼视角，参数依次为：视野角度、宽高比、近裁剪面、远裁剪面
				camera = new THREE.PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.1, 10);
				// 设置相机初始位置：x=0（中心），y=1.6（近似人眼高度），z=3（距离原点3个单位）
				camera.position.set(0, 1.6, 3);

				// ------------ 4. 创建轨道控制器（用于桌面模式） ------------
				// 创建轨道控制器：允许用户用鼠标拖拽、缩放、旋转视角
				controls = new OrbitControls(camera, container);
				// 设置控制器目标点：相机看向的位置（1.6米高度，与人眼高度一致）
				controls.target.set(0, 1.6, 0);
				// 更新控制器状态，确保初始设置生效
				controls.update();

				// ------------ 5. 创建场景几何体 ------------
				// 创建地板：为用户提供空间参考平面
				// 地板几何体：4x4单位的平面
				const floorGeometry = new THREE.PlaneGeometry(4, 4);
				// 地板材质：使用标准材质，中等灰色
				const floorMaterial = new THREE.MeshStandardMaterial({ color: 0x666666 });
				// 创建地板网格对象：结合几何体和材质
				const floor = new THREE.Mesh(floorGeometry, floorMaterial);
				// 旋转地板：使其从垂直变为水平（-π/2弧度 = -90度）
				floor.rotation.x = -Math.PI / 2;
				// 启用地板接收阴影：使其他物体的阴影能投射到地板上
				floor.receiveShadow = true;
				// 将地板添加到场景中
				scene.add(floor);

				// ------------ 6. 创建和配置光照 ------------
				// 创建半球光：模拟天空和地面的环境反射光
				// 参数：天空颜色，地面颜色，光照强度
				scene.add(new THREE.HemisphereLight(0xbcbcbc, 0xa5a5a5, 3));

				// 创建定向光：模拟太阳光，方向性光源
				const light = new THREE.DirectionalLight(0xffffff, 3);
				// 设置光源位置：从上方6个单位处照射
				light.position.set(0, 6, 0);
				// 启用阴影投射：使此光源能产生阴影
				light.castShadow = true;
				// 配置阴影相机范围：定义阴影计算区域
				light.shadow.camera.top = 2;      // 阴影相机顶部边界
				light.shadow.camera.bottom = -2;  // 阴影相机底部边界
				light.shadow.camera.right = 2;    // 阴影相机右边界
				light.shadow.camera.left = -2;   // 阴影相机左边界
				// 设置阴影贴图分辨率：更高的分辨率产生更清晰的阴影边缘
				light.shadow.mapSize.set(4096, 4096);
				// 将光源添加到场景
				scene.add(light);

				// ------------ 7. 创建和配置渲染器 ------------
				// 创建WebGL渲染器：{antialias: true}启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGLRenderer({ antialias: true });
				// 设置设备像素比：适配高DPI显示器（如Retina屏幕）
				renderer.setPixelRatio(window.devicePixelRatio);
				// 设置渲染器尺寸为整个窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				// 设置动画循环：指定animate函数为每一帧调用的回调函数
				renderer.setAnimationLoop(animate);
				// 启用阴影映射：允许场景中的物体投射和接收阴影
				renderer.shadowMap.enabled = true;
				// 启用XR（扩展现实）支持：这是VR功能的基础
				renderer.xr.enabled = true;
				// 将渲染器的canvas元素添加到之前创建的容器中
				container.appendChild(renderer.domElement);

				// ------------ 8. 配置XR会话和VR按钮 ------------
				// 定义XR会话初始化配置对象
				const sessionInit = {
					// requiredFeatures指定会话必须支持的功能
					// 'hand-tracking'表示要求设备支持手部追踪
					requiredFeatures: ['hand-tracking']
				};
				// 创建VR按钮：根据浏览器和设备能力自动生成进入VR的按钮
				// 参数：渲染器实例和会话初始化配置
				document.body.appendChild(VRButton.createButton(renderer, sessionInit));

				// ------------ 9. 设置XR控制器 ------------
				// 获取第一个XR控制器（通常是左手控制器）
				controller1 = renderer.xr.getController(0);
				// 将控制器添加到场景中
				scene.add(controller1);
				// 获取第二个XR控制器（通常是右手控制器）
				controller2 = renderer.xr.getController(1);
				scene.add(controller2);

				// 创建控制器模型工厂：用于生成3D控制器模型
				const controllerModelFactory = new XRControllerModelFactory();
				// 创建手部模型工厂：用于生成手部追踪的3D手部模型
				const handModelFactory = new XRHandModelFactory();

				// ------------ 10. 配置左手（索引0） ------------
				// 获取左手控制器的握把对象：用于附着3D模型
				controllerGrip1 = renderer.xr.getControllerGrip(0);
				// 为握把添加控制器3D模型
				controllerGrip1.add(controllerModelFactory.createControllerModel(controllerGrip1));
				// 将握把添加到场景
				scene.add(controllerGrip1);

				// 获取左手的手部追踪对象
				hand1 = renderer.xr.getHand(0);
				// 在用户数据中存储当前显示的手部模型索引（0=盒子，1=球体，2=网格）
				hand1.userData.currentHandModel = 0;
				// 将手部对象添加到场景
				scene.add(hand1);

				// 创建三种不同样式的左手模型
				handModels.left = [
					// 盒子模型：用立方体表示每个手部关节
					handModelFactory.createHandModel(hand1, 'boxes'),
					// 球体模型：用球体表示每个手部关节
					handModelFactory.createHandModel(hand1, 'spheres'),
					// 网格模型：用连续的网格表示手部
					handModelFactory.createHandModel(hand1, 'mesh')
				];

				// 将三种手部模型添加到左手对象，但只显示第一个
				for (let i = 0; i < 3; i++) {
					// 获取当前索引对应的手部模型
					const model = handModels.left[i];
					// 设置可见性：只有第一个模型（索引0）初始可见
					model.visible = i == 0;
					// 将模型添加到手部对象中
					hand1.add(model);
				}

				// 为左手添加捏合结束事件监听器
				// 'pinchend'是WebXR手部追踪的标准事件，当用户停止捏合手势时触发
				hand1.addEventListener('pinchend', function () {
					// 隐藏当前显示的手部模型
					handModels.left[this.userData.currentHandModel].visible = false;
					// 计算下一个模型索引：使用模运算实现循环切换（0→1→2→0...）
					this.userData.currentHandModel = (this.userData.currentHandModel + 1) % 3;
					// 显示新的手部模型
					handModels.left[this.userData.currentHandModel].visible = true;
				});

				// ------------ 11. 配置右手（索引1） ------------
				// 右手配置逻辑与左手完全相同，只是使用索引1
				controllerGrip2 = renderer.xr.getControllerGrip(1);
				controllerGrip2.add(controllerModelFactory.createControllerModel(controllerGrip2));
				scene.add(controllerGrip2);

				hand2 = renderer.xr.getHand(1);
				hand2.userData.currentHandModel = 0;
				scene.add(hand2);

				handModels.right = [
					handModelFactory.createHandModel(hand2, 'boxes'),
					handModelFactory.createHandModel(hand2, 'spheres'),
					handModelFactory.createHandModel(hand2, 'mesh')
				];

				for (let i = 0; i < 3; i++) {
					const model = handModels.right[i];
					model.visible = i == 0;
					hand2.add(model);
				}

				hand2.addEventListener('pinchend', function () {
					handModels.right[this.userData.currentHandModel].visible = false;
					this.userData.currentHandModel = (this.userData.currentHandModel + 1) % 3;
					handModels.right[this.userData.currentHandModel].visible = true;
				});

				// ------------ 12. 创建控制器射线指示器 ------------
				// 创建射线几何体：用于可视化控制器的指向方向
				// 定义两个点：起点(0,0,0)和终点(0,0,-1)，表示向前的方向
				const geometry = new THREE.BufferGeometry().setFromPoints([
					new THREE.Vector3(0, 0, 0),    // 起点：控制器位置
					new THREE.Vector3(0, 0, -1)    // 终点：向前一个单位
				]);

				// 创建线对象：使用上面定义的几何体
				const line = new THREE.Line(geometry);
				// 为线对象设置名称，便于调试和识别
				line.name = 'line';
				// 将线在Z轴方向缩放5倍，使射线更长更明显
				line.scale.z = 5;

				// 为两个控制器分别添加射线指示器的克隆
				// 使用clone()创建独立的副本，避免共享几何体引用
				controller1.add(line.clone());
				controller2.add(line.clone());

				// ------------ 13. 添加窗口大小变化监听器 ------------
				// 当浏览器窗口大小变化时，调用onWindowResize函数
				window.addEventListener('resize', onWindowResize);
			}

			/**
			 * 窗口大小变化处理函数
			 * 当用户调整浏览器窗口大小时，此函数被调用以重新调整渲染
			 */
			function onWindowResize() {
				// 更新相机的宽高比，使其与新的窗口尺寸匹配
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机的投影矩阵：这是必要的，因为改变宽高比后需要重新计算投影
				camera.updateProjectionMatrix();
				// 更新渲染器的尺寸，使其填充整个窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			/**
			 * 动画循环函数
			 * 这是Three.js应用的核心循环，每帧自动调用（通常每秒60次）
			 * 在WebXR模式下，此函数由浏览器XR系统调度
			 * 在桌面模式下，此函数由requestAnimationFrame调度
			 */
			function animate() {
				// 渲染场景：将3D场景通过相机视角绘制到canvas上
				renderer.render(scene, camera);
				// 注意：这里没有更新控制器或手部位置，因为WebXR系统会自动更新
				// XR控制器和手部的位置由浏览器XR API实时提供
			}
		</script>
	</body>
</html>