书洞笔记

外观

Threejs 调试利器 GUI

约 923 字大约 3 分钟

2025-03-04

我们发现，如果每次通过修改代码的方式修改属性值效率太低了，所以我们可以使用 lil.GUI 来创建一个图形用户界面，通过拖动滑块、选择下拉菜单、点击按钮等方式来控制应用程序的参数。

介绍

dat.GUI 是一个轻量级的 JavaScript 库，用于在浏览器中创建图形用户界面（GUI）。它允许开发者通过拖动滑块、选择下拉菜单、点击按钮等方式来控制应用程序的参数。dat.GUI 可以与任何 JavaScript 库或框架一起使用，包括 Three.js。

使用

这个 Threejs 里面自带的有，所以直接导入就好。

import { GUI } from "three/examples/jsm/libs/lil-gui.module.min.js";
const gui = new GUI();

API

  • name：GUI 元素的名称。
  • control：要添加的控件。
  • min：控件的最小值。
  • max：控件的最大值。
  • step：控件的变化步长。
  • onChange：控件值改变时的回调函数。
  • onFinishChange：控件值完成改变时的回调函数。
  • listen：是否监听控件值的变化。
  • name：控件的名称。
  • callback：按钮点击时的回调函数。
  • color：颜色选择器的初始颜色。

domElement

获取 GUI 的 DOM 元素。那就意味着，我们可以通过这个元素来操作 GUI 的样式。

gui.domElement.style.position = "absolute";
gui.domElement.style.top = "0";
gui.domElement.style.left = "0";

add

添加一个新的 GUI 元素。

gui.add(camera.position, "x").min(-10).max(10).step(0.1).name("相机X轴位置");
gui.add(camera.position, "y").min(-10).max(10).step(0.1).name("相机Y轴位置");
gui.add(camera.position, "z").min(-10).max(10).step(0.1).name("相机Z轴位置");

add

addFolder

创建一个新的文件夹，用于组织 GUI 元素。

const folder = gui.addFolder("立方体位置");
folder.add(camera.position, "x").min(-10).max(10).step(0.1).name("相机X轴位置");
folder.add(camera.position, "y").min(-10).max(10).step(0.1).name("相机Y轴位置");
folder.add(camera.position, "z").min(-10).max(10).step(0.1).name("相机Z轴位置");

这样可以更好的管理 GUI 元素。

addFolder

addColor

添加一个颜色选择器。

gui.addColor(cube.material, "color");

addColor

onChange

当控件值改变时触发的事件。

//在onChange的回调中
//通过形参获取修改的数值
//使用THREE提供的数学工具，将度转换成弧度
const folder2 = gui.addFolder("立方体旋转(度数)");
const rotation = {
  x: 0,
  y: 0,
  z: 0,
};
folder2
  .add(rotation, "x", -180, 180, 1)
  .name("立方体X轴旋转")
  .onChange((value) => {
    console.log(value);
    cube.rotation.x = THREE.MathUtils.degToRad(value); //将角度转换为弧度
  });
folder2
  .add(rotation, "y", -180, 180, 1)
  .name("立方体Y轴旋转")
  .onChange((value) => {
    console.log(value);
    cube.rotation.y = THREE.MathUtils.degToRad(value); //将角度转换为弧度
  });
folder2
  .add(rotation, "z", -180, 180, 1)
  .name("立方体Z轴旋转")
  .onChange((value) => {
    console.log(value);
    cube.rotation.z = THREE.MathUtils.degToRad(value); //将角度转换为弧度
  });

onChange

onFinishChange

当控件值完成改变时触发的事件。

//会判断属性是否是布尔值，是的话会用选项框展示
gui
  .add(cube.material, "wireframe")
  .name("是否显示线框")
  .onChange(() => {
    console.log("wireframe changed");
  })
  .onFinishChange(() => {
    console.log("wireframe finished changing");
  });

onFinishChange

其它UI交互

正常来说：add方法格式：add(控制对象，对象具体属性，其它参数)

其它参数，可以是一个或多个，数据类型也可以不同，gui会根据数据类型自动判断展示方式。

参数3和参数4分别是一个数字，交互界面是一个鼠标可以拖到的滑块

参数3是一个数组/对象，交互界面是一个下拉菜单

参数3是一个布尔值，交互界面是一个单选框

//参数3是数组
gui.add(camera.position, "x", [-10, 0, 10]);
//参数3是对象
gui.add(camera.position, "y", {
  左侧: -10,
  中间: 0,
  右侧: 10,
})
//参数3是布尔值
let obj = {
  bool:false
}
gui.add(obj,'bool').name('布尔值')

其它UI交互