<!-- Three.js CSS3D 沙箱演示 - 详细功能与技术分析
🌟 核心功能概述
1. 混合3D渲染系统
这是一个双渲染器架构的Three.js演示程序，同时使用：

WebGL渲染器：渲染3D线框网格（传统3D图形）

CSS3D渲染器：将HTML/CSS元素渲染为3D对象

2. 主要功能模块
3D场景创建：生成10个随机分布的3D对象

实时交互控制：通过鼠标拖拽、滚轮实现3D场景导航

动态参数调整：可视化控制面板调节渲染参数

响应式布局：自动适应浏览器窗口大小变化

视口偏移演示：展示高级相机控制功能

🔧 主要技术点详解
1. Three.js 核心架构
场景管理
javascript
// 两个独立但同步的场景
scene = new THREE.Scene();      // WebGL场景（线框）
scene2 = new THREE.Scene();     // CSS3D场景（HTML元素）
相机系统
透视相机（PerspectiveCamera）：模拟人眼视角

相机参数：

FOV: 45度（视野角度）

近裁剪面: 1单位

远裁剪面: 1000单位

初始位置: (200, 200, 200)

渲染器组合
javascript
// WebGL渲染器（用于3D图形）
renderer = new THREE.WebGLRenderer({ antialias: true });

// CSS3D渲染器（用于HTML元素）
renderer2 = new CSS3DRenderer();
// CSS3D渲染器覆盖在WebGL渲染器之上
2. CSS3D 技术实现
CSS3DObject 工作原理
javascript
// 将普通HTML元素转换为3D对象
const element = document.createElement('div');
element.style.cssText = 'width:100px; height:100px; background:red;';
const object = new CSS3DObject(element);
技术原理：

使用CSS transform: matrix3d() 实现3D变换

元素仍保留完整的HTML/CSS功能

可以响应鼠标事件、显示文本、播放视频等

渲染机制
CSS3D渲染器创建容器div

将CSS3DObject的DOM元素作为子元素

通过CSS 3D变换矩阵定位每个元素

与WebGL内容分层合成显示

3. 交互控制系统
TrackballControls 特点
无限制旋转：可任意角度旋转相机

鼠标控制：

左键拖拽：旋转场景

右键拖拽：平移场景

滚轮：缩放场景

惯性效果：拖拽后有缓动效果

事件处理
javascript
// 窗口大小变化响应
window.addEventListener('resize', onWindowResize);

// 控制器每帧更新
controls.update();
4. 视口偏移技术（Viewport Offset）
应用场景
分屏显示（多视角）

画中画效果

VR左右眼分别渲染

渲染到纹理指定区域

实现原理
javascript
camera.setViewOffset(
  fullWidth,   // 虚拟完整画布宽度
  fullHeight,  // 虚拟完整画布高度
  offsetX,     // 视口水平偏移
  offsetY,     // 视口垂直偏移
  width,       // 视口宽度
  height       // 视口高度
);
示例：

完整画布：1920×1080

视口设置：offsetX=960, offsetY=0, width=960, height=1080

结果：只渲染右半边的1080×1080区域

5. GUI 控制面板
使用 lil-gui 库
轻量级控制面板库

支持数字滑块、按钮、文件夹等控件

实时参数调整和反馈

面板结构
text
相机视口偏移设置（文件夹）
├── [按钮] 设置视口偏移
├── [滑块] 完整宽度 (禁用)
├── [滑块] 完整高度 (禁用)
├── [滑块] X偏移 (禁用)
├── [滑块] Y偏移 (禁用)
├── [滑块] 视口宽度 (禁用)
├── [滑块] 视口高度 (禁用)
└── [按钮] 清除视口偏移
🎯 技术特色与优势
1. 混合渲染的优势
HTML内容：支持文本、表单、视频、iframe等

WebGL内容：高性能3D图形、着色器效果

完美结合：两者在同一3D空间中协调工作

2. 性能优化
CSS3D硬件加速：利用GPU加速CSS变换

分层渲染：WebGL和CSS3D分别渲染，互不干扰

高效更新：只有变换属性变化时触发重排

3. 兼容性考虑
模块化导入：使用ES6模块和importmap

响应式设计：适应不同屏幕尺寸

降级处理：即使CSS3D不支持，WebGL仍可工作

📊 应用场景示例
实际应用场景
数据可视化仪表板

CSS3D：显示数据卡片、图表标签

WebGL：渲染3D图表、网络拓扑

产品展示网站

CSS3D：产品描述、价格标签

WebGL：3D产品模型旋转查看

教育应用

CSS3D：显示注释、说明文字

WebGL：展示3D模型、科学模拟

游戏UI

CSS3D：游戏菜单、血条、分数显示

WebGL：游戏场景、角色、特效

🛠️ 关键技术配置
Import Maps（导入映射）
html
<script type="importmap">
{
  "imports": {
    "three": "../build/three.module.js",
    "three/addons/": "./jsm/"
  }
}
</script>
作用：将模块导入路径映射到实际文件位置，支持裸模块说明符。

渲染器配置细节
javascript
// WebGL抗锯齿配置
renderer.setPixelRatio(window.devicePixelRatio);

// CSS3D渲染器定位
renderer2.domElement.style.position = 'absolute';
renderer2.domElement.style.top = 0;
🔄 程序执行流程
初始化阶段
创建相机和两个场景

生成10个随机CSS3D对象+WebGL线框

创建并配置两个渲染器

初始化轨道控制器

设置窗口大小监听器

创建GUI控制面板

动画循环阶段
请求下一帧动画

更新控制器状态

先渲染WebGL场景

再渲染CSS3D场景（覆盖在上层）

循环执行

用户交互流程
text
用户操作 → TrackballControls处理 → 更新相机参数
    ↓
下一帧渲染 → 两个渲染器使用新相机参数
    ↓
更新显示 → 用户看到交互结果 -->


<!DOCTYPE html>
<!-- 
  这是一个使用Three.js库的CSS3D沙箱示例页面
  该示例展示了如何将HTML/CSS元素渲染为3D对象，并与WebGL线框结合
  使用ES6模块化方式导入Three.js及相关插件
-->
<html>
	<head>
		<!-- 页面元数据 -->
		<meta charset="utf-8">  <!-- 设置字符编码为UTF-8 -->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 
		  viewport设置说明：
		  width=device-width: 视口宽度等于设备宽度
		  user-scalable=no: 禁止用户缩放页面
		  minimum-scale=1.0, maximum-scale=1.0: 将缩放比例锁定为1.0
		-->
		<title>Three.js CSS3D 沙箱演示 - 混合3D渲染示例</title>  <!-- 页面标题 -->
		<link type="text/css" rel="stylesheet" href="main.css">  <!-- 外部样式表链接 -->
		<style>
			/* 内联样式 */
			body {
				color: #000;  /* 设置文本颜色为黑色 */
				/* 注意：这里没有设置背景色，body背景默认透明 */
			}
			a {
				color: #080;  /* 设置链接颜色为深绿色 (#080 = #008800) */
				/* 这个颜色会应用到页面中所有<a>标签 */
			}
			/* 注意：CSS3D渲染器生成的元素样式在JavaScript中动态设置 */
		</style>
	</head>
	<body>
		<!-- 页面信息栏 -->
		<!-- 
		  id="info": 用于CSS选择器或JavaScript操作
		  包含一个链接，指向Three.js官网
		  target="_blank": 在新标签页打开链接
		  rel="noopener": 安全特性，防止新页面通过window.opener访问原页面
		-->
		<div id="info">
			Three.js CSS3D 沙箱演示 - 
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js官方网站</a>
		</div>
		<!-- 
		  提示：这个div会显示在页面左上角（默认位置）
		  实际位置可能被后续渲染的canvas元素覆盖
		-->

		<!-- 
		  导入映射表 (Import Maps)
		  这是ES6模块系统的一部分，允许重定向导入路径
		  现代浏览器原生支持，用于解决模块路径问题
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
		  主JavaScript代码模块
		  type="module": 表示这是一个ES6模块，支持import/export语法
		  模块代码会延迟执行，在HTML解析完成后才执行
		-->
		<script type="module">
			// ====================== 模块导入部分 ======================
			// 导入Three.js核心库的所有导出，命名为THREE对象
			// THREE对象包含所有Three.js的核心类和方法
			import * as THREE from 'three';

			// 导入轨道球控制器（TrackballControls）
			// 这是一种3D场景控制器，允许用户通过鼠标拖拽、滚轮缩放等方式控制相机
			// 相比OrbitControls，TrackballControls允许相机任意旋转，没有上下限制
			import { TrackballControls } from 'three/addons/controls/TrackballControls.js';

			// 导入CSS3D渲染器和CSS3D对象
			// CSS3DRenderer: 专门用于渲染CSS3DObject的渲染器
			// CSS3DObject: 将HTML元素包装为3D对象的类
			import { CSS3DRenderer, CSS3DObject } from 'three/addons/renderers/CSS3DRenderer.js';

			// 导入GUI库（轻量级控制面板库）
			// 用于创建交互式控制面板，方便调试和参数调整
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

			// ====================== 全局变量声明 ======================
			// 注意：这些变量在整个模块作用域内可用
			
			// WebGL渲染相关变量
			let camera;      // 透视相机，用于3D场景的视角控制
			let scene;       // WebGL场景，包含所有WebGL渲染的3D对象
			let renderer;    // WebGL渲染器，负责将3D场景渲染到canvas上

			// CSS3D渲染相关变量
			let scene2;      // CSS3D场景，包含所有CSS3DObject对象
			let renderer2;   // CSS3D渲染器，负责渲染CSS3D场景

			// 控制器变量
			let controls;    // 轨道球控制器，用于用户交互控制相机

			// ====================== 主程序流程 ======================
			// 1. 调用初始化函数，创建所有必要的对象和设置
			init();
			// 2. 启动动画循环，开始渲染场景
			animate();

			/**
			 * 初始化函数
			 * 这是整个程序的起点，负责：
			 * 1. 创建相机、场景、渲染器
			 * 2. 创建3D对象并添加到场景
			 * 3. 设置事件监听器
			 * 4. 创建GUI控制面板
			 * 5. 执行其他一次性设置
			 */
			function init() {
				// ---------- 创建相机 ----------
				// 创建透视相机（PerspectiveCamera）
				// 参数说明：
				// 45 - 视野角度（Field of View），单位是度，类似人眼的视角
				// window.innerWidth / window.innerHeight - 宽高比，根据窗口大小动态计算
				// 1 - 近裁剪面，距离相机小于1的单位不会被渲染
				// 1000 - 远裁剪面，距离相机大于1000的单位不会被渲染
				camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 1, 1000);
				// 设置相机初始位置
				// 参数：(x, y, z)坐标
				// 将相机放在(200, 200, 200)位置，朝向原点(0,0,0)
				camera.position.set(200, 200, 200);

				// ---------- 创建WebGL场景 ----------
				// Scene是所有3D对象的容器，包含要渲染的所有物体、光源、相机等
				scene = new THREE.Scene();
				// 设置场景背景颜色为浅灰色（十六进制颜色0xf0f0f0 = RGB(240,240,240)）
				scene.background = new THREE.Color(0xf0f0f0);

				// ---------- 创建CSS3D场景 ----------
				// 第二个场景，专门用于存放CSS3D对象
				// CSS3D场景和WebGL场景是独立的，但可以使用同一个相机
				scene2 = new THREE.Scene();

				// ---------- 创建线框材质 ----------
				// 这个材质将用于WebGL渲染的平面网格
				// 材质参数说明：
				// color: 0x000000 - 黑色（十六进制表示）
				// wireframe: true - 启用线框模式，只渲染网格线不渲染面
				// wireframeLinewidth: 1 - 线框线宽为1像素
				// side: THREE.DoubleSide - 双面渲染，从正面和背面都能看到
				const material = new THREE.MeshBasicMaterial({ 
					color: 0x000000, 
					wireframe: true, 
					wireframeLinewidth: 1, 
					side: THREE.DoubleSide 
				});

				// ---------- 创建10个CSS3D对象和对应的WebGL线框 ----------
				// 循环创建10个对象，每个对象包括：
				// 1. 一个CSS3DObject（彩色的DIV元素）
				// 2. 一个对应的WebGL线框平面（用于视觉参考）
				for (let i = 0; i < 10; i++) {
					// --- 第1步：创建HTML元素（CSS3D对象的内容）---
					const element = document.createElement('div');
					// 设置DIV元素样式
					element.style.width = '100px';  // 宽度100像素
					element.style.height = '100px'; // 高度100像素
					// 设置透明度：前5个对象半透明(0.5)，后5个不透明(1)
					// 这样可以看到对象之间的层次关系
					element.style.opacity = (i < 5) ? 0.5 : 1;
					// 生成随机颜色作为背景
					// Math.random() * 0xffffff: 生成0到0xffffff之间的随机数
					// new THREE.Color(): 创建颜色对象
					// .getStyle(): 转换为CSS颜色字符串（如"rgb(255,0,0)"）
					element.style.background = new THREE.Color(Math.random() * 0xffffff).getStyle();
					// 注意：这个DIV元素还没有添加到DOM中，稍后由CSS3D渲染器管理

					// --- 第2步：创建CSS3D对象 ---
					// CSS3DObject将HTML元素包装成可以在3D场景中变换的对象
					const object = new CSS3DObject(element);
					
					// 设置随机位置
					// Math.random()返回0到1之间的随机数
					// Math.random() * 200 - 100 产生-100到100之间的随机数
					object.position.x = Math.random() * 200 - 100; // X轴：-100到100
					object.position.y = Math.random() * 200 - 100; // Y轴：-100到100
					object.position.z = Math.random() * 200 - 100; // Z轴：-100到100
					
					// 设置随机旋转（以弧度为单位）
					// Math.random()返回0到1之间的随机数，对应0到1弧度（约0°到57°）
					object.rotation.x = Math.random(); // 绕X轴旋转
					object.rotation.y = Math.random(); // 绕Y轴旋转
					object.rotation.z = Math.random(); // 绕Z轴旋转
					
					// 设置随机缩放
					// Math.random() + 0.5 产生0.5到1.5之间的随机数
					// 这样可以避免对象太小或太大
					object.scale.x = Math.random() + 0.5; // X轴缩放：0.5到1.5倍
					object.scale.y = Math.random() + 0.5; // Y轴缩放：0.5到1.5倍
					
					// 将CSS3D对象添加到CSS3D场景
					scene2.add(object);

					// --- 第3步：创建对应的WebGL线框平面 ---
					// 这个平面与CSS3D对象位置、旋转、缩放完全一致
					// 作为CSS3D对象的参考框架，帮助理解3D空间位置
					
					// 创建平面几何体
					// PlaneGeometry参数：(宽度, 高度)
					// 这里创建100x100单位的平面
					const geometry = new THREE.PlaneGeometry(100, 100);
					
					// 创建网格（几何体+材质）
					const mesh = new THREE.Mesh(geometry, material);
					
					// 复制CSS3D对象的变换到网格
					mesh.position.copy(object.position);  // 复制位置
					mesh.rotation.copy(object.rotation);  // 复制旋转
					mesh.scale.copy(object.scale);        // 复制缩放
					
					// 将网格添加到WebGL场景
					scene.add(mesh);
				}
				// 循环结束后，我们有：
				// scene: 包含10个黑色线框平面
				// scene2: 包含10个彩色CSS3D矩形

				// ---------- 创建WebGL渲染器 ----------
				// WebGLRenderer使用WebGL API在canvas上渲染3D场景
				renderer = new THREE.WebGLRenderer({ 
					antialias: true  // 开启抗锯齿，使边缘更平滑
				});
				// 设置设备像素比
				// window.devicePixelRatio返回设备的物理像素与CSS像素的比率
				// 在高DPI屏幕（如Retina屏）上，这个值可能是2或3
				// 设置这个值可以使渲染更清晰
				renderer.setPixelRatio(window.devicePixelRatio);
				// 设置渲染器大小为整个窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				// 将渲染器的canvas元素添加到页面body中
				// renderer.domElement是canvas元素的引用
				document.body.appendChild(renderer.domElement);

				// ---------- 创建CSS3D渲染器 ----------
				// CSS3DRenderer专门渲染CSS3DObject
				// 它不创建canvas，而是操作DOM元素的CSS 3D变换
				renderer2 = new CSS3DRenderer();
				// 同样设置大小为整个窗口
				renderer2.setSize(window.innerWidth, window.innerHeight);
				// 设置CSS3D渲染器DOM元素的样式
				// 关键点：使用绝对定位覆盖在WebGL渲染器上方
				renderer2.domElement.style.position = 'absolute';
				renderer2.domElement.style.top = '0';
				// 注意：CSS3D渲染器生成的DOM结构是一个div，包含所有CSS3DObject
				document.body.appendChild(renderer2.domElement);
				// 渲染顺序：CSS3D渲染器在WebGL渲染器之后添加，所以会显示在上层

				// ---------- 创建轨道球控制器 ----------
				// 将控制器绑定到CSS3D渲染器的DOM元素
				// 这样用户可以在CSS3D元素上直接交互
				// 第二个参数是控制器监听的DOM元素
				controls = new TrackballControls(camera, renderer2.domElement);
				// 控制器会自动处理鼠标/触摸事件，更新相机位置

				// ---------- 添加窗口大小变化监听器 ----------
				// 当用户调整浏览器窗口大小时，需要重新调整渲染
				window.addEventListener('resize', onWindowResize);
				// resize事件会在窗口大小改变时触发
				
				// ---------- 创建GUI控制面板 ----------
				createPanel();
				// 初始化完成，所有对象都已创建并设置好
			}

			/**
			 * 窗口大小变化事件处理函数
			 * 当浏览器窗口大小改变时，这个函数被调用
			 * 需要更新相机、渲染器等相关设置
			 */
			function onWindowResize() {
				// 1. 更新相机的宽高比
				// 相机需要知道渲染区域的宽高比来计算正确的透视
				camera.aspect = window.innerWidth / window.innerHeight;
				// 2. 更新相机的投影矩阵
				// 当相机参数改变后，必须调用updateProjectionMatrix()来更新内部矩阵
				camera.updateProjectionMatrix();

				// 3. 更新两个渲染器的尺寸
				// 使渲染区域填满整个窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
				renderer2.setSize(window.innerWidth, window.innerHeight);
				
				// 注意：控制器可能也需要更新，但TrackballControls会自动处理
			}

			/**
			 * 动画循环函数
			 * 这是Three.js应用的核心，通过循环调用来实现动画效果
			 * 使用requestAnimationFrame实现与浏览器刷新率同步的循环
			 */
			function animate() {
				// 1. 请求下一帧动画
				// requestAnimationFrame是浏览器提供的API，在下次重绘前调用指定函数
				// 通常每秒调用60次（与显示器刷新率同步）
				// 将animate函数自身作为回调，形成循环
				requestAnimationFrame(animate);

				// 2. 更新控制器
				// 控制器需要每帧更新，以处理用户输入和惯性等效果
				controls.update();
				// TrackballControls.update()会基于用户输入更新相机的位置和朝向

				// 3. 渲染两个场景
				// 首先渲染WebGL场景
				renderer.render(scene, camera);
				// 然后渲染CSS3D场景
				renderer2.render(scene2, camera);
				// 注意：两个场景使用同一个相机，所以视角完全一致
				// CSS3D渲染器会覆盖在WebGL渲染器上面
				
				// 循环继续，下一帧再次执行这个过程
			}

			/**
			 * 创建GUI控制面板函数
			 * 使用lil-gui库创建交互式控制面板
			 * 主要用于调试和演示相机视口偏移功能
			 */
			function createPanel() {
				// 创建GUI实例
				// GUI会在页面右上角创建一个可折叠的控制面板
				const panel = new GUI();
				// 添加一个文件夹（分类）
				// 参数：文件夹名称，默认关闭状态
				const folder1 = panel.addFolder('相机视口偏移设置').close();
				// 文件夹可以展开/折叠，组织相关控制项

				// 创建控制面板的数据对象
				// 这个对象的属性和方法会绑定到GUI控制项
				const settings = {
					/**
					 * 设置视口偏移（方法）
					 * 点击按钮时，启用所有相关控制项并设置合理的初始值
					 */
					'setViewOffset'() {
						// folder1.children 包含文件夹中的所有控制项
						// 通过索引访问每个控制项（按添加顺序）
						// 启用控制项并设置值
						folder1.children[1].enable().setValue(window.innerWidth);   // fullWidth: 完整宽度设为窗口宽度
						folder1.children[2].enable().setValue(window.innerHeight);  // fullHeight: 完整高度设为窗口高度
						folder1.children[3].enable().setValue(0);                   // offsetX: X偏移设为0
						folder1.children[4].enable().setValue(0);                   // offsetY: Y偏移设为0
						folder1.children[5].enable().setValue(window.innerWidth);   // width: 视口宽度设为窗口宽度
						folder1.children[6].enable().setValue(window.innerHeight);  // height: 视口高度设为窗口高度
						// 这相当于设置了一个"全屏"视口，没有偏移
					},
					
					// 以下属性会绑定到数值滑块
					'fullWidth': 0,      // 完整宽度：虚拟的完整渲染区域宽度
					'fullHeight': 0,     // 完整高度：虚拟的完整渲染区域高度
					'offsetX': 0,        // X偏移：视口左上角在完整区域中的X坐标
					'offsetY': 0,        // Y偏移：视口左上角在完整区域中的Y坐标
					'width': 0,          // 视口宽度：实际渲染区域的宽度
					'height': 0,         // 视口高度：实际渲染区域的高度
					
					/**
					 * 清除视口偏移（方法）
					 * 重置所有值，禁用控制项，并清除相机的视口偏移设置
					 */
					'clearViewOffset'() {
						// 重置所有控制项的值为0并禁用它们
						folder1.children[1].setValue(0).disable(); // fullWidth
						folder1.children[2].setValue(0).disable(); // fullHeight
						folder1.children[3].setValue(0).disable(); // offsetX
						folder1.children[4].setValue(0).disable(); // offsetY
						folder1.children[5].setValue(0).disable(); // width
						folder1.children[6].setValue(0).disable(); // height
						// 调用相机的clearViewOffset方法，恢复默认渲染
						camera.clearViewOffset();
					}
				};

				// ========== 向文件夹添加控制项 ==========
				
				// 1. 添加按钮：设置视口偏移
				// 参数：settings对象，'setViewOffset'方法名
				// 点击这个按钮会调用settings.setViewOffset()
				folder1.add(settings, 'setViewOffset')
					.name('设置视口偏移');  // 设置显示名称
				
				// 2. 添加数值滑块：完整宽度
				// 参数：settings对象，'fullWidth'属性名，最小值，最大值，步长
				folder1.add(settings, 'fullWidth', 
					window.screen.width / 4,      // 最小值：屏幕宽度的1/4
					window.screen.width * 2,      // 最大值：屏幕宽度的2倍
					1                             // 步长：每次调整增减1
				)
				.onChange((val) => updateCameraViewOffset({ fullWidth: val }))  // 值变化时的回调
				.disable()  // 初始状态：禁用
				.name('完整宽度');  // 显示名称
				
				// 3. 添加数值滑块：完整高度
				folder1.add(settings, 'fullHeight', 
					window.screen.height / 4,     // 最小值：屏幕高度的1/4
					window.screen.height * 2,     // 最大值：屏幕高度的2倍
					1                             // 步长
				)
				.onChange((val) => updateCameraViewOffset({ fullHeight: val }))
				.disable()
				.name('完整高度');
				
				// 4. 添加数值滑块：X偏移
				folder1.add(settings, 'offsetX', 
					0,       // 最小值：0
					256,     // 最大值：256像素
					1        // 步长：1像素
				)
				.onChange((val) => updateCameraViewOffset({ x: val }))
				.disable()
				.name('X偏移');
				
				// 5. 添加数值滑块：Y偏移
				folder1.add(settings, 'offsetY', 
					0,       // 最小值：0
					256,     // 最大值：256像素
					1        // 步长：1像素
				)
				.onChange((val) => updateCameraViewOffset({ y: val }))
				.disable()
				.name('Y偏移');
				
				// 6. 添加数值滑块：视口宽度
				folder1.add(settings, 'width', 
					window.screen.width / 4,      // 最小值
					window.screen.width * 2,      // 最大值
					1                             // 步长
				)
				.onChange((val) => updateCameraViewOffset({ width: val }))
				.disable()
				.name('视口宽度');
				
				// 7. 添加数值滑块：视口高度
				folder1.add(settings, 'height', 
					window.screen.height / 4,     // 最小值
					window.screen.height * 2,     // 最大值
					1                             // 步长
				)
				.onChange((val) => updateCameraViewOffset({ height: val }))
				.disable()
				.name('视口高度');
				
				// 8. 添加按钮：清除视口偏移
				folder1.add(settings, 'clearViewOffset')
					.name('清除视口偏移');
					
				// GUI创建完成，用户可以通过面板交互控制相机视口偏移
				// 初始状态下，除了两个按钮外，其他控制项都是禁用的
			}

			/**
			 * 更新相机视口偏移
			 * 这个函数处理相机视口偏移参数的更新
			 * 视口偏移允许渲染一个大场景的部分区域，常用于分屏、画中画等效果
			 * 
			 * @param {Object} params - 视口偏移参数对象
			 * @param {number} [params.fullWidth] - 虚拟完整渲染区域的宽度
			 * @param {number} [params.fullHeight] - 虚拟完整渲染区域的高度
			 * @param {number} [params.x] - 视口左上角在完整区域中的X坐标（水平偏移）
			 * @param {number} [params.y] - 视口左上角在完整区域中的Y坐标（垂直偏移）
			 * @param {number} [params.width] - 实际渲染区域的宽度
			 * @param {number} [params.height] - 实际渲染区域的高度
			 */
			function updateCameraViewOffset({ fullWidth, fullHeight, x, y, width, height }) {
				// 检查相机是否已经设置了视口偏移
				// camera.view属性在调用setViewOffset后会被设置
				if (!camera.view) {
					// 情况1：相机还没有视口偏移设置
					// 创建新的视口偏移设置
					
					// camera.setViewOffset参数说明：
					// 1. fullWidth: 完整虚拟区域的宽度
					// 2. fullHeight: 完整虚拟区域的高度
					// 3. x: 视口左上角的X坐标
					// 4. y: 视口左上角的Y坐标
					// 5. width: 实际渲染区域的宽度
					// 6. height: 实际渲染区域的高度
					
					// 使用传入的参数，如果参数未提供则使用默认值
					camera.setViewOffset(
						fullWidth || window.innerWidth,     // 如果未提供fullWidth，使用窗口宽度
						fullHeight || window.innerHeight,   // 如果未提供fullHeight，使用窗口高度
						x || 0,                             // 如果未提供x，使用0
						y || 0,                             // 如果未提供y，使用0
						width || window.innerWidth,         // 如果未提供width，使用窗口宽度
						height || window.innerHeight        // 如果未提供height，使用窗口高度
					);
					// 这相当于设置了一个视口，可能只渲染完整区域的一部分
				} else {
					// 情况2：相机已经有视口偏移设置
					// 更新现有的视口偏移
					
					// 使用传入的参数，如果参数未提供则保持当前值不变
					camera.setViewOffset(
						fullWidth || camera.view.fullWidth,     // 新完整宽度或当前宽度
						fullHeight || camera.view.fullHeight,   // 新完整高度或当前高度
						x || camera.view.offsetX,               // 新X偏移或当前X偏移
						y || camera.view.offsetY,               // 新Y偏移或当前Y偏移
						width || camera.view.width,             // 新宽度或当前宽度
						height || camera.view.height            // 新高度或当前高度
					);
				}
				
				// 更新相机的宽高比
				// 即使设置了视口偏移，相机仍然需要知道实际渲染区域的宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机的投影矩阵
				// 当相机参数（包括视口偏移）改变时，必须调用此方法
				camera.updateProjectionMatrix();
				// 更新后，下一帧渲染会使用新的视口设置
				
				// 视口偏移的应用场景：
				// 1. 多视图渲染（如3D建模软件的多视图）
				// 2. 画中画效果
				// 3. 虚拟现实中的左右眼分别渲染
				// 4. 渲染到纹理的一部分
			}
			// ====================== 模块代码结束 ======================
		</script>
	</body>
</html>