基本使用方式

lil-gui 是一个轻量级的 JavaScript GUI 库，专门用于创建简单的调试面板或参数调整界面。它非常适合在开发过程中用来快速测试和调整参数，尤其是在图形编程（如 three.js）中非常常见。

1. `lil-gui` 的功能

lil-gui 提供了一个简单的界面，允许用户通过滑块、按钮、下拉菜单等方式动态调整程序中的参数。以下是它的主要功能：

(1) 参数调整

可以绑定程序中的变量到 GUI 控件上。
用户可以通过 GUI 界面实时调整这些变量的值。

(2) 实时反馈

当用户调整 GUI 中的控件时，可以触发回调函数，从而实现对程序行为的实时更新。

(3) 多种控件类型

lil-gui 支持多种类型的控件，包括：

滑块（数值范围调整）
下拉菜单（选择选项）
布尔值开关（勾选框）
输入框（文本输入）
按钮（触发操作）

2. 在 three.js 中的应用

在 three.js 项目中，lil-gui 经常被用来创建一个调试面板，让用户可以动态调整场景中的参数。例如：

调整光源的位置或颜色。
修改物体的材质属性。
控制摄像机的视角。

3. 使用方法

(1) 引入库

首先需要引入 lil-gui 库。如果你使用的是 three.js 的扩展模块，可以直接通过以下方式导入：

import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

如果单独使用 lil-gui，可以从 CDN 引入：

<script type="module">
    import GUI from 'https://cdn.jsdelivr.net/npm/lil-gui/dist/lil-gui.esm.min.js';
</script>

(2) 创建 GUI 实例

创建一个 GUI 对象：

const gui = new GUI();

(3) 定义可调整的参数

定义一个对象来存储需要调整的参数。例如：

const effectController = {
    rotationSpeed: 0.01, // 旋转速度
    color: '#ff0000',   // 颜色
    visible: true       // 是否可见
};

(4) 添加控件

将参数绑定到 GUI 上。例如：

// 添加滑块控件
gui.add(effectController, 'rotationSpeed', 0, 0.1).name('Rotation Speed');

// 添加颜色选择器
gui.addColor(effectController, 'color').name('Color');

// 添加布尔值开关
gui.add(effectController, 'visible').name('Visible');

(5) 监听参数变化

当用户调整 GUI 中的控件时，可以触发回调函数。例如：

gui.add(effectController, 'rotationSpeed', 0, 0.1)
    .name('Rotation Speed')
    .onChange(value => {
        console.log('Rotation speed changed to:', value);
    });

(6) 完整示例

以下是一个完整的示例，展示如何在 three.js 中使用 lil-gui 来调整一个立方体的旋转速度和颜色：

import * as THREE from 'three';
import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

// 创建场景、相机和渲染器
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// 创建立方体
const geometry = new THREE.BoxGeometry();
const material = new THREE.MeshBasicMaterial({ color: 0xff0000 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

camera.position.z = 5;

// 渲染循环
function animate() {
    requestAnimationFrame(animate);
    cube.rotation.x += effectController.rotationSpeed;
    cube.rotation.y += effectController.rotationSpeed;
    renderer.render(scene, camera);
}
animate();

// 创建 GUI
const gui = new GUI();
const effectController = {
    rotationSpeed: 0.01,
    color: '#ff0000',
    visible: true
};

// 添加控件
gui.add(effectController, 'rotationSpeed', 0, 0.1).name('Rotation Speed');
gui.addColor(effectController, 'color').name('Color').onChange(value => {
    material.color.set(value);
});
gui.add(effectController, 'visible').name('Visible').onChange(value => {
    cube.visible = value;
});

4. 常见控件类型

以下是 lil-gui 支持的一些常见控件及其用法：

(1) 滑块

gui.add(target, 'propertyName', min, max).name('Label');

target：目标对象。
propertyName：要调整的属性名。
min 和 max：数值范围。

(2) 下拉菜单

gui.add(target, 'propertyName', options).name('Label');

options：一个数组或对象，表示可选值。

(3) 布尔值开关

gui.add(target, 'propertyName').name('Label');

(4) 颜色选择器

gui.addColor(target, 'propertyName').name('Label');

(5) 按钮

gui.add(target, 'methodName').name('Label');

methodName：目标对象上的方法名。

5. 总结

lil-gui 是一个简单易用的 GUI 库，特别适合在 three.js 或其他图形应用程序中创建调试面板。通过它可以快速实现参数调整、实时反馈等功能，大大简化了开发和调试流程。

例子

以下是一个简单的示例，展示如何在 three.js 中使用 lil-gui 创建一个调试面板，允许用户调整立方体的旋转速度和颜色。

完整代码

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Three.js with lil-gui Example</title>
    <style>
        body { margin: 0; overflow: hidden; }
        canvas { display: block; }
    </style>
</head>
<body>
<script type="module">
    // 导入 three.js 和 lil-gui
    import * as THREE from 'https://cdn.jsdelivr.net/npm/three@0.152/build/three.module.js';
    import { GUI } from 'https://cdn.jsdelivr.net/npm/lil-gui/dist/lil-gui.esm.min.js';

    // 创建场景、相机和渲染器
    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
    const renderer = new THREE.WebGLRenderer({ antialias: true });
    renderer.setSize(window.innerWidth, window.innerHeight);
    document.body.appendChild(renderer.domElement);

    // 创建一个立方体
    const geometry = new THREE.BoxGeometry();
    const material = new THREE.MeshBasicMaterial({ color: 0xff0000 });
    const cube = new THREE.Mesh(geometry, material);
    scene.add(cube);

    // 设置相机位置
    camera.position.z = 5;

    // 渲染循环
    function animate() {
        requestAnimationFrame(animate);

        // 根据 rotationSpeed 更新立方体的旋转角度
        cube.rotation.x += effectController.rotationSpeed;
        cube.rotation.y += effectController.rotationSpeed;

        renderer.render(scene, camera);
    }
    animate();

    // 定义参数对象
    const effectController = {
        rotationSpeed: 0.01, // 初始旋转速度
        color: '#ff0000',   // 初始颜色
        visible: true       // 是否可见
    };

    // 创建 GUI 实例
    const gui = new GUI();

    // 添加滑块控件（调整旋转速度）
    gui.add(effectController, 'rotationSpeed', 0, 0.1).name('Rotation Speed');

    // 添加颜色选择器（调整立方体颜色）
    gui.addColor(effectController, 'color').name('Cube Color').onChange(value => {
        material.color.set(value); // 更新材质颜色
    });

    // 添加布尔值开关（控制立方体是否可见）
    gui.add(effectController, 'visible').name('Visible').onChange(value => {
        cube.visible = value; // 更新立方体的可见性
    });
</script>
</body>
</html>

代码解析

1. 引入依赖

使用 <script type="module"> 导入 three.js 和 lil-gui：

import * as THREE from 'https://cdn.jsdelivr.net/npm/three@0.152/build/three.module.js';
import { GUI } from 'https://cdn.jsdelivr.net/npm/lil-gui/dist/lil-gui.esm.min.js';

2. 初始化 three.js 场景

创建 scene、camera 和 renderer。
添加一个立方体到场景中，并设置初始材质颜色为红色。

3. 渲染循环

使用 requestAnimationFrame 实现动画效果。
根据 effectController.rotationSpeed 的值动态更新立方体的旋转角度。

4. 定义参数对象

创建一个 effectController 对象，存储需要调整的参数：

const effectController = {
    rotationSpeed: 0.01, // 初始旋转速度
    color: '#ff0000',   // 初始颜色
    visible: true       // 是否可见
};

5. 创建 GUI

使用 gui.add() 方法添加控件：
- 滑块控件：调整旋转速度。
- 颜色选择器：调整立方体的颜色。
- 布尔值开关：控制立方体的可见性。

6. 监听变化

使用 .onChange() 方法监听用户对控件的操作，并实时更新场景中的对象属性。例如：

gui.addColor(effectController, 'color').name('Cube Color').onChange(value => {
    material.color.set(value); // 更新材质颜色
});

运行效果

页面加载后，会显示一个红色的旋转立方体。
在页面右侧会弹出一个 lil-gui 调试面板，包含以下控件：
- Rotation Speed：滑块控件，用于调整立方体的旋转速度。
- Cube Color：颜色选择器，用于调整立方体的颜色。
- Visible：布尔值开关，用于控制立方体的可见性。
用户可以通过调试面板实时调整立方体的行为和外观。

总结

这个示例展示了如何将 lil-gui 集成到 three.js 项目中，创建一个简单的调试面板，方便用户动态调整场景中的参数。你可以根据需求扩展此示例，添加更多功能或控件。

posted on 2025-03-04 21:28 joken1310 阅读(554) 评论(0) 收藏举报

刷新页面返回顶部

joken-前端工程师