本篇主要学习内容 :

1. 认识gui.js库(可视化改变三维场景)
2. 体验gui快速创建控制三维场景的UI交互界面
3. gui调试页面多种方式

点赞 + 关注 + 收藏 = 学会了

1.认识gui.js库(可视化改变三维场景)

dat.gui.js是一个前端js库，对HTML、CSS和JavaScript进行了封装，学习开发的时候，借助dat.gui.js可以快速创建控制三维场景的UI交互界面

// 导入lil.gui
import {
    
     GUI } from 'three/examples/jsm/libs/lil-gui.module.min.js'

2.体验gui快速创建控制三维场景的UI交互界面

// 实例化一个gui对象
const gui = new GUI();
//lil gui 调试开发3d效果
let eventObj = {
    
    
    Fullscreen: () => {
    
    
        document.body.requestFullscreen()
    },
    ExitFullscreen: () => {
    
    
        document.exitFullscreen()
    },
}
// 创建GUI   （用gui替代上一节点击事件）
const gui = new GUI()
gui.add(eventObj, 'Fullscreen').name('全屏')
gui.add(eventObj, 'ExitFullscreen').name('退出全屏')

3. 使用gui调试页面

像下面这样，可以进行分组，点击、单选、拖拽选取值、颜色调整

// 控制立方体位置
let folder = gui.addFolder('立方体位置') //生成文件夹  添加分组
// gui.add(cube.position, 'x', -5, 5).name('立方体x轴位置')//没有大小限制有小数点
folder
    .add(cube.position, 'x')
    .min(-10)
    .max(10)
    .step(1)
    .name('立方体x轴位置')
    .onChange((val) => {
    
    
        console.log(val, '立方体位置')
    })
folder
    .add(cube.position, 'y')
    .min(-10)
    .max(10)
    .step(1)
    .name('立方体y轴位置')
    .onFinishChange((val) => {
    
    
        console.log(val, '立方体位置')
    })
folder.add(cube.position, 'z').min(-10).max(10).step(1).name('立方体z轴位置')
gui.add(parMaterial, 'wireframe').name('父元素线框模式')

let colorParams = {
    
    
    cubeColor: '0xff0000',
}
gui.addColor(colorParams, 'cubeColor')
    .name('立方体颜色')
    .onChange((val) => {
    
    
        cube.material.color.set(val)
    })

三、避坑指南

3.1 控件不显示？

• 检查CSS的z-index设置，确保面板不被其他元素遮挡
• 确认初始化时没有设置container: hidden属性

3.2 数值调整无反应？

// 错误示例：直接绑定原始值
gui.add(cube.rotation, 'x') // 不会自动更新

// 正确做法：通过中间对象代理
const proxy = {
    
     rotationX: 0 }
gui.add(proxy, 'rotationX').onChange(v => cube.rotation.x = v)

3.3 颜色设置异常

// 错误：直接使用0x开头字符串
controls.cubeColor = '0xff0000' // 无法解析！

// 正确：使用#符号或颜色名称
controls.cubeColor = 'red' 
controls.cubeColor = '#FF0000'

---

四、调试小技巧

1. ​实时刷新：在onChange回调中更新render()方法
2. ​状态保存：使用gui.remember()保存调试参数
3. ​移动适配：设置touchStyles: true优化触屏操作
4. ​样式定制：通过CSS覆盖修改面板样式

// 自定义面板样式
.gui-container {
    
    
    opacity: 0.9;
    background: linear-gradient(to right, #2c3e50, #3498db);
    border-radius: 10px;
    padding: 15px;
}