<!-- Three.js 3D拖拽控制演示 - 功能说明与技术分析
🎯 项目概述
这是一个基于Three.js和WebGL的交互式3D场景演示，展示了200个随机立方体的动态管理和拖拽交互功能。用户可以通过Shift+Click组合立方体，并使用拖拽控制进行整体或单个操作。

📋 核心功能
1. 基本3D场景构建
随机立方体生成：自动创建200个具有随机位置、旋转、缩放和颜色的立方体

实时渲染：60fps流畅的3D场景渲染

自适应布局：响应式设计，自动适应不同屏幕尺寸

2. 交互控制功能
单个对象拖拽：直接拖动任何立方体进行移动

分组选择：Shift+点击选择多个立方体组成组

分组操作：对选中的立方体组进行整体变换（移动、旋转、缩放）

模式切换：在触摸设备上使用M键切换旋转/平移模式

3. 视觉特效
动态光照：环境光+聚光灯组合照明系统

实时阴影：支持对象阴影投射和接收

选择高亮：被选中的立方体显示发光效果

抗锯齿渲染：平滑的边缘显示

🔧 主要技术点
1. Three.js 核心架构
javascript
// 三大核心组件
const scene = new THREE.Scene();      // 场景容器
const camera = new THREE.PerspectiveCamera();  // 透视相机
const renderer = new THREE.WebGLRenderer();    // WebGL渲染器
2. 对象管理机制
数组管理：objects数组存储所有立方体引用

分组系统：使用THREE.Group实现对象组合

父子关系：通过attach()和detach()动态改变对象层级

3. 交互技术实现
射线投射 (Raycasting)
javascript
// 鼠标坐标归一化
mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;

// 发射射线检测交点
raycaster.setFromCamera(mouse, camera);
const intersections = raycaster.intersectObjects(objects, true);
拖拽控制 (DragControls)
对象绑定：将可拖拽对象数组传递给控制器

事件监听：实时响应拖拽事件

分组变换：transformGroup标志控制整体/个体操作

键盘交互
Shift键检测：键码16，控制选择模式

M键切换：键码77，在触摸设备上切换操作模式

4. 光影系统配置
灯光设置
javascript
// 环境光 - 基础均匀照明
new THREE.AmbientLight(0xaaaaaa);

// 聚光灯 - 定向照明+阴影
const spotLight = new THREE.SpotLight(0xffffff, 10000);
spotLight.castShadow = true;
spotLight.shadow.mapSize.width = 1024;  // 阴影贴图分辨率
材质系统
MeshLambertMaterial：对光照敏感的漫反射材质

放射光属性：material.emissive用于选择高亮效果

5. 性能优化技术
渲染优化
javascript
// 抗锯齿处理
renderer = new THREE.WebGLRenderer({ antialias: true });

// 设备像素比适配
renderer.setPixelRatio(window.devicePixelRatio);

// 高效阴影渲染
renderer.shadowMap.type = THREE.PCFShadowMap;
事件管理
事件委托：在document级别监听点击事件

条件渲染：仅在状态变化时重新渲染

防抖处理：窗口大小变化时的优化重绘

6. 坐标系统转换
text
屏幕坐标系统 → 归一化设备坐标 → 世界坐标系统
(0,0)到(width,height) → (-1,-1)到(1,1) → 3D空间坐标
7. 状态管理模式
javascript
// 状态标志管理
let enableSelection = false;  // 选择模式状态
controls.transformGroup = false;  // 分组变换状态

// 状态同步更新
if (group.children.length === 0) {
    controls.transformGroup = false;  // 空组时禁用分组模式
}
🏗️ 系统架构设计
数据流架构
text
用户输入 → 事件处理 → 状态更新 → 场景更新 → 渲染输出
    ↓         ↓           ↓          ↓          ↓
鼠标/键盘 → 事件监听器 → 状态管理 → 对象变换 → Canvas绘制
对象层级结构
text
Scene (场景根)
├── AmbientLight (环境光)
├── SpotLight (聚光灯)
├── Group (动态分组)
│   ├── Mesh (立方体1)  ← 可动态添加/移除
│   ├── Mesh (立方体2)  ← 可动态添加/移除
│   └── ...
└── Mesh (独立立方体)  ← 200个随机立方体
📊 性能特征
内存管理
几何体复用：所有立方体共享同一个BoxGeometry实例

材质独立：每个立方体有独立的材质实例（支持不同颜色）

对象池：通过数组管理所有对象引用

渲染性能
批量处理：单次渲染调用绘制所有对象

阴影优化：PCF软阴影平衡质量和性能

条件更新：仅在交互时触发重新渲染 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题 -->
		<title>Three.js WebGL - 拖拽控制演示</title>
		<!-- 字符编码设置 -->
		<meta charset="utf-8">
		<!-- 视口设置：禁止用户缩放，确保适应移动设备 -->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 外部CSS样式表链接 -->
		<link type="text/css" rel="stylesheet" href="main.css">
		<!-- 内联CSS样式 -->
		<style>
			/* 页面主体样式 */
			body {
				background-color: #f0f0f0; /* 浅灰色背景 */
				color: #444; /* 深灰色文字 */
			}
			/* 链接样式 */
			a {
				color: #08f; /* 蓝色链接 */
			}
		</style>
	</head>
	<body>

		<!-- 页面信息提示区域 -->
		<div id="info">
			<!-- Three.js链接和标题 -->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> WebGL - 拖拽控制演示<br />
			<!-- 操作说明1：Shift+Click用于对象分组 -->
			使用"Shift+点击"来添加/移除对象到/从分组。<br />
			<!-- 操作说明2：M键用于模式切换（仅触摸设备） -->
			使用"M"键在旋转和平移模式之间切换（仅触摸设备）。<br />
			<!-- 操作说明3：分组对象可以整体变换 -->
			分组的对象可以作为整体进行变换操作。
		</div>

		<!-- 模块导入映射配置（ES6模块规范） -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 主JavaScript模块 -->
		<script type="module">

			// ==================== 导入模块 ====================
			
			// 导入Three.js核心库的所有功能
			// THREE对象包含了所有three.js的核心类和方法
			import * as THREE from 'three';

			// 从three.js的附加组件中导入DragControls类
			// DragControls提供了对象拖拽交互功能
			import { DragControls } from 'three/addons/controls/DragControls.js';

			// ==================== 全局变量声明 ====================
			
			let container;        // DOM容器，用于存放Three.js的canvas元素
			let camera;           // 相机：定义了观察3D场景的视角
			let scene;            // 场景：包含所有3D对象的容器
			let renderer;         // 渲染器：负责将3D场景渲染到2D画布上
			let controls;         // 拖拽控制器：管理对象的拖拽交互
			let group;            // 分组对象：用于将多个对象组合在一起
			let enableSelection = false;  // 选择模式标志：当按下Shift键时为true

			const objects = [];   // 存储所有立方体对象的数组，便于管理和批量操作

			// 鼠标位置向量：存储归一化的鼠标坐标（范围从-1到1）
			const mouse = new THREE.Vector2();
			// 射线投射器：用于检测鼠标点击与3D对象的交点
			const raycaster = new THREE.Raycaster();

			// ==================== 初始化函数调用 ====================
			
			// 应用程序的入口点，初始化所有Three.js组件
			init();

			// ==================== 函数定义 ====================
			
			/**
			 * 初始化函数
			 * 创建Three.js的核心组件：场景、相机、渲染器、灯光、对象等
			 */
			function init() {

				// ---------- 创建DOM容器 ----------
				// 创建一个div元素作为Three.js渲染器的容器
				container = document.createElement( 'div' );
				// 将容器添加到页面的body元素中
				document.body.appendChild( container );

				// ---------- 创建相机 ----------
				/*
				 * 创建透视相机（PerspectiveCamera）
				 * 参数说明：
				 *   70 - 视野角度（FOV），单位是度，较大的值产生鱼眼效果
				 *   window.innerWidth / window.innerHeight - 宽高比（纵横比）
				 *   0.1 - 近裁剪面，相机不会渲染比这更近的对象
				 *   500 - 远裁剪面，相机不会渲染比这更远的对象
				 */
				camera = new THREE.PerspectiveCamera( 70, window.innerWidth / window.innerHeight, 0.1, 500 );
				// 设置相机位置：沿Z轴向后移动25个单位
				camera.position.z = 25;

				// ---------- 创建场景 ----------
				// 创建3D场景对象，所有3D对象（网格、灯光等）都添加到场景中
				scene = new THREE.Scene();
				// 设置场景背景颜色为浅灰色
				scene.background = new THREE.Color( 0xf0f0f0 );

				// ---------- 添加环境光 ----------
				/*
				 * 环境光（AmbientLight）均匀地照亮场景中的所有对象
				 * 参数：0xaaaaaa - 光的颜色（浅灰色），十六进制表示
				 * 环境光没有方向，没有阴影，用于模拟全局光照
				 */
				scene.add( new THREE.AmbientLight( 0xaaaaaa ) );

				// ---------- 创建聚光灯 ----------
				/*
				 * 聚光灯（SpotLight）产生锥形光束，有方向和位置
				 * 参数：
				 *   0xffffff - 光颜色（白色）
				 *   10000 - 光强度，值越大光越亮
				 */
				const light = new THREE.SpotLight( 0xffffff, 10000 );
				// 设置灯光位置：X=0, Y=25, Z=50
				light.position.set( 0, 25, 50 );
				// 设置光束角度：π/9弧度（20度）
				light.angle = Math.PI / 9;

				// 启用聚光灯的阴影投射功能
				light.castShadow = true;
				// 设置阴影相机参数：近裁剪面为10个单位
				light.shadow.camera.near = 10;
				// 设置阴影相机参数：远裁剪面为100个单位
				light.shadow.camera.far = 100;
				// 设置阴影贴图尺寸：宽度1024像素，影响阴影质量
				light.shadow.mapSize.width = 1024;
				// 设置阴影贴图尺寸：高度1024像素
				light.shadow.mapSize.height = 1024;

				// 将聚光灯添加到场景中
				scene.add( light );

				// ---------- 创建分组对象 ----------
				/*
				 * 分组（Group）是一个可以包含多个对象的容器
				 * 分组本身也是一个Object3D，可以有自己的变换（位置、旋转、缩放）
				 * 分组内的所有对象会继承分组的变换
				 */
				group = new THREE.Group();
				// 将分组添加到场景中
				scene.add( group );

				// ---------- 创建立方体几何体 ----------
				// BoxGeometry是立方体的几何形状定义
				const geometry = new THREE.BoxGeometry();

				// ---------- 创建200个随机立方体 ----------
				// 循环创建200个立方体，每个立方体有随机的位置、旋转、缩放和颜色
				for ( let i = 0; i < 200; i ++ ) {

					/*
					 * 创建网格（Mesh）对象
					 * 参数：
					 *   geometry - 几何形状（立方体）
					 *   new THREE.MeshLambertMaterial - 兰伯特材质，对光照有反应
					 *   { color: Math.random() * 0xffffff } - 随机颜色
					 */
					const object = new THREE.Mesh( geometry, new THREE.MeshLambertMaterial( { color: Math.random() * 0xffffff } ) );

					// 设置随机位置：
					// X轴：-15到15之间的随机值
					object.position.x = Math.random() * 30 - 15;
					// Y轴：-7.5到7.5之间的随机值
					object.position.y = Math.random() * 15 - 7.5;
					// Z轴：-10到10之间的随机值
					object.position.z = Math.random() * 20 - 10;

					// 设置随机旋转：
					// 绕X轴随机旋转0到2π弧度（0到360度）
					object.rotation.x = Math.random() * 2 * Math.PI;
					// 绕Y轴随机旋转0到2π弧度
					object.rotation.y = Math.random() * 2 * Math.PI;
					// 绕Z轴随机旋转0到2π弧度
					object.rotation.z = Math.random() * 2 * Math.PI;

					// 设置随机缩放：
					// X轴：1到3之间的随机值
					object.scale.x = Math.random() * 2 + 1;
					// Y轴：1到3之间的随机值
					object.scale.y = Math.random() * 2 + 1;
					// Z轴：1到3之间的随机值
					object.scale.z = Math.random() * 2 + 1;

					// 启用对象的阴影功能：
					object.castShadow = true;      // 对象可以投射阴影
					object.receiveShadow = true;   // 对象可以接收阴影

					// 将立方体对象添加到场景中
					scene.add( object );
					// 将对象添加到objects数组，便于后续管理
					objects.push( object );

				}

				// ---------- 创建WebGL渲染器 ----------
				/*
				 * 创建WebGLRenderer，这是Three.js的主要渲染器
				 * 参数：{ antialias: true } - 启用抗锯齿，使边缘更平滑
				 */
				renderer = new THREE.WebGLRenderer( { antialias: true } );
				// 设置设备像素比，适配高清屏幕（如Retina显示屏）
				renderer.setPixelRatio( window.devicePixelRatio );
				// 设置渲染器尺寸为整个窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );

				// 启用渲染器的阴影映射功能
				renderer.shadowMap.enabled = true;
				// 设置阴影映射类型为PCF（百分比渐进过滤）软阴影
				renderer.shadowMap.type = THREE.PCFShadowMap;

				// 将渲染器的DOM元素（canvas画布）添加到容器中
				container.appendChild( renderer.domElement );

				// ---------- 初始化拖拽控制器 ----------
				/*
				 * 创建DragControls对象
				 * 参数：
				 *   [ ...objects ] - 可拖拽的对象数组（使用扩展运算符创建新数组）
				 *   camera - 用于计算拖拽的相机
				 *   renderer.domElement - 拖拽事件监听的DOM元素（canvas）
				 */
				controls = new DragControls( [ ... objects ], camera, renderer.domElement );
				// 设置旋转速度系数为2（旋转更快）
				controls.rotateSpeed = 2;

				// 监听'drag'事件，当对象被拖拽时调用render函数
				controls.addEventListener( 'drag', render );

				// ================ 事件监听器设置 ================

				// 监听窗口大小变化事件，当窗口大小改变时重新调整渲染
				window.addEventListener( 'resize', onWindowResize );

				// 监听文档点击事件，用于处理对象的选择（Shift+Click）
				document.addEventListener( 'click', onClick );
				// 监听键盘按下事件，检测Shift键和M键
				window.addEventListener( 'keydown', onKeyDown );
				// 监听键盘释放事件，清除选择模式标志
				window.addEventListener( 'keyup', onKeyUp );

				// 执行首次渲染
				render();

			}

			/**
			 * 窗口大小变化处理函数
			 * 当浏览器窗口大小改变时，重新调整相机和渲染器的参数
			 */
			function onWindowResize() {

				// 更新相机的纵横比为新的窗口宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机的投影矩阵（必须调用此方法使更改生效）
				camera.updateProjectionMatrix();

				// 将渲染器的尺寸更新为新的窗口尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );

				// 重新渲染场景
				render();

			}

			/**
			 * 键盘按下事件处理函数
			 * @param {KeyboardEvent} event - 键盘事件对象
			 */
			function onKeyDown( event ) {

				/*
				 * 检查按下的键是否是Shift键（键码16）
				 * 如果按下Shift键，启用选择模式
				 * 键码16对应Shift键，17对应Ctrl键，18对应Alt键
				 */
				enableSelection = ( event.keyCode === 16 ) ? true : false;
			
				/*
				 * 检查按下的键是否是M键（键码77）
				 * M键用于在触摸设备上切换旋转和平移模式
				 * 注意：这个功能仅影响触摸交互，不影响鼠标交互
				 */
				if ( event.keyCode === 77 ) {
					/*
					 * 切换触摸模式：
					 * THREE.TOUCH.PAN - 平移模式（默认）
					 * THREE.TOUCH.ROTATE - 旋转模式
					 * controls.touches.ONE控制单指触摸的行为
					 */
					controls.touches.ONE = ( controls.touches.ONE === THREE.TOUCH.PAN ) ? THREE.TOUCH.ROTATE : THREE.TOUCH.PAN;
				}

			}

			/**
			 * 键盘释放事件处理函数
			 * 当任何键释放时，禁用选择模式
			 */
			function onKeyUp() {
				enableSelection = false;  // 禁用选择模式
			}

			/**
			 * 鼠标点击事件处理函数
			 * 处理Shift+Click操作：添加/移除对象到分组
			 * @param {MouseEvent} event - 鼠标事件对象
			 */
			function onClick( event ) {

				event.preventDefault();  // 阻止浏览器默认的点击行为

				// 只有在选择模式（Shift键按下）下才处理对象选择
				if ( enableSelection === true ) {

					// 获取当前拖拽控制器中的可拖拽对象列表
					const draggableObjects = controls.objects;
					// 清空可拖拽对象列表（准备重新设置）
					draggableObjects.length = 0;

					/*
					 * 将鼠标的屏幕坐标转换为归一化设备坐标（NDC）
					 * NDC坐标范围：X和Y轴都是从-1到1
					 * 左上角：(-1, 1)，右下角：(1, -1)
					 */
					mouse.x = ( event.clientX / window.innerWidth ) * 2 - 1;
					mouse.y = - ( event.clientY / window.innerHeight ) * 2 + 1;

					/*
					 * 使用射线投射器从相机位置向鼠标方向发射射线
					 * 检测射线与哪些3D对象相交
					 */
					raycaster.setFromCamera( mouse, camera );

					/*
					 * 计算射线与所有对象的交点
					 * 参数：
					 *   objects - 要检测的对象数组
					 *   true - 是否检测子对象（如果对象有层级结构）
					 * 返回按距离排序的交点数组，最近的交点在前
					 */
					const intersections = raycaster.intersectObjects( objects, true );

					// 如果射线与至少一个对象相交（点击到了对象）
					if ( intersections.length > 0 ) {

						// 获取最近的交点对应的对象
						const object = intersections[ 0 ].object;

						// 检查对象是否已经在分组中
						if ( group.children.includes( object ) === true ) {
							/*
							 * 如果对象已经在分组中，将其从分组中移除
							 * 1. 将对象的自发光颜色设为黑色（0x000000），移除发光效果
							 */
							object.material.emissive.set( 0x000000 );
							/*
							 * 2. 将对象从分组中分离并重新附加到场景
							 * scene.attach()会将对象从其父级移除并添加到场景
							 */
							scene.attach( object );
						} 
						// 如果对象不在分组中，将其添加到分组
						else {
							/*
							 * 如果对象不在分组中，将其添加到分组
							 * 1. 将对象的自发光颜色设为灰色（0xaaaaaa），添加发光效果表示被选中
							 * 自发光（emissive）使对象看起来像是在发光，不受光照影响
							 */
							object.material.emissive.set( 0xaaaaaa );
							/*
							 * 2. 将对象从场景中分离并附加到分组
							 * group.attach()会将对象从其父级移除并添加到分组
							 */
							group.attach( object );
						}

						/*
						 * 启用分组变换模式
						 * 当transformGroup为true时，拖拽操作会应用于整个分组
						 * 而不是单个对象
						 */
						controls.transformGroup = true;
						// 将分组添加到可拖拽对象列表
						draggableObjects.push( group );

					}

					/*
					 * 检查分组中是否还有对象
					 * 如果分组为空（没有对象被选中），则禁用分组变换模式
					 */
					if ( group.children.length === 0 ) {
						// 禁用分组变换模式
						controls.transformGroup = false;
						// 将所有单个对象添加到可拖拽对象列表
						draggableObjects.push( ...objects );
					}

				}

				// 重新渲染场景以显示最新的状态变化
				render();

			}

			/**
			 * 渲染函数
			 * 将3D场景渲染到2D画布上
			 */
			function render() {
				// 使用渲染器将场景从相机的视角渲染出来
				renderer.render( scene, camera );
			}

		</script>

	</body>
</html>