Leva 可视化控制面板快速入门指南

Leva 可视化控制面板快速入门指南

leva 🌋 React-first components GUI 项目地址: https://gitcode.com/gh_mirrors/le/leva

什么是 Leva

Leva 是一个轻量级的 React 组件库，用于快速创建美观且功能强大的可视化控制面板。它特别适合用于 Three.js 场景调试、参数调整和原型开发。通过简单的 API，开发者可以轻松地为应用添加交互式控制面板。

安装 Leva

使用 npm 或 yarn 安装 Leva 非常简单：

npm install leva
# 或者
yarn add leva

基础用法

基本控制面板创建

Leva 的核心是 useControls 钩子函数。在任何 React 组件中使用它，就能自动生成对应的控制面板：

import { useControls } from 'leva'

function MyComponent() {
  // 创建一个数值滑块控制项，默认值为10
  const { myValue } = useControls({ myValue: 10 })
  
  return <div>当前值: {myValue}</div>
}

多组件控制

Leva 会自动收集应用中所有 useControls 调用，将它们合并到一个统一的面板中：

function AnotherComponent() {
  // 创建一个文本输入控制项
  const { anotherValue } = useControls({ anotherValue: 'alive!!' })

  return <div>状态: {anotherValue}</div>
}

function MyApp() {
  return (
    <>
      <MyComponent />
      <AnotherComponent />
    </>
  )
}

注意事项

1. 组件挂载：只有当前渲染的组件中的控制项才会出现在面板中
2. 顺序问题：控制项在面板中的顺序取决于它们在代码中被调用的顺序

输入类型自动推断

Leva 会根据你提供的默认值自动选择最合适的输入控件类型：

• 数字 → 滑块
• 布尔值 → 开关
• 字符串 → 文本输入
• 颜色值 → 颜色选择器
• 枚举值 → 下拉选择

条件显示控制项

你可以根据其他控制项的值动态显示或隐藏某些控制项：

useControls({
  check: false,
  myNumber: 4,
  color: { 
    value: '#ffffffff', 
    render: (get) => get('check') && get('myNumber') > 5 
  },
})

在这个例子中，color 颜色选择器只会在 check 为 true 且 myNumber 大于5时显示。

使用文件夹组织控制项

当控制项较多时，可以使用文件夹来组织它们，使面板更加清晰。

基本文件夹

useControls('显示设置', {
  showLighting: true,
  showStats: false,
})

嵌套文件夹

对于更复杂的组织结构，可以使用 folder 函数创建嵌套文件夹：

import { folder, useControls } from 'leva'

const { showLighting, showStats } = useControls('全局设置', {
  光照: folder({
    showLighting: true,
  }),
  性能: folder({
    showStats: false,
  }),
})

文件夹使用注意事项

1. 所有控制项的值会被平铺返回，不考虑文件夹结构
2. 不同文件夹中的控制项不能重名，否则会产生冲突

最佳实践建议

1. 命名规范：为控制项和文件夹使用清晰的命名
2. 合理分组：将相关控制项放在同一文件夹中
3. 默认值：设置合理的默认值，方便用户理解参数范围
4. 条件控制：善用条件显示功能，减少面板复杂度

通过以上介绍，你应该已经掌握了 Leva 的基本使用方法。这个轻量级工具可以极大地提升开发效率，特别是在需要频繁调整参数的场景中。

leva 🌋 React-first components GUI 项目地址: https://gitcode.com/gh_mirrors/le/leva