MODKEYS 是一个完全运行在浏览器中的 3D 键盘可视化配置器：以 Three.js 作为渲染核心，以 GSAP 驱动动画过渡，将颜色、材质、键帽轮廓、布局与配件等选项直接交给用户操作，实现所见即所得的定制体验。

几年前，做一个这样的交互式产品配置器，还需要一支专门的 3D 开发团队。而如今，Claude Fable 5 就能做到如此程度的交互与界面表现。

核心功能概览

• 3D 实时预览：Three.js 构建完整键盘模型，含键帽、开关、旋钮、机壳、光效分组。
• 材质调节：通过 roughness / metalness / clearcoat 等 PBR 参数精细控制质感。
• 配色切换：多套配色方案，切换时 GSAP 平滑过渡到新颜色。
• 每键定制：Quad Editor 支持对单个按键的纹理/图案进行上传与位置调整。
• 布局重建：切换布局或键帽轮廓时触发 rebuild + popKeys 入场动画。
• 动态定价：界面根据所选布局与配置实时计算价格。

Three.js 场景分组设计

3D 场景中，整机被拆解为多个逻辑分组（THREE.Group），每个分组负责一类对象：

const caseGroup = new THREE.Group();   // 机壳
const capsGroup = new THREE.Group();   // 键帽
const switchGroup = new THREE.Group(); // 开关
const knobGroup = new THREE.Group();   // 旋钮
const keyGlowGroup = new THREE.Group(); // 键位光效

root.add(caseGroup, capsGroup, switchGroup, knobGroup, keyGlowGroup);

这种设计的优势在于：对某一类对象的整体操作只需操作对应 Group，无需遍历整个场景图；入场动画（popKeys）可以精准作用于 capsGroup，不影响机壳；光效组可以单独控制混合模式与渲染顺序。

颜色平滑过渡：GSAP + Three.js

配色切换是用户感知最直接的功能。项目使用 GSAP 直接操作 Three.js 材质的 color 属性，实现逐帧插值过渡：

function tweenColor(mat, hex, duration) {
  const c = sRGB(hex);
  gsap.to(mat.color, {
    r: c.r, g: c.g, b: c.b,
    duration: duration,
    ease: 'power2.out'
  });
}

关键点：Three.js 内部使用线性色彩空间，因此必须将十六进制色值转换为线性 sRGB 空间，否则过渡色会出现偏差。

状态驱动重建：apply3D 函数

这是整个配置器的核心调度函数。用户在界面上的每一次选择都会生成一个状态变更（patch），由 apply3D 决定如何响应：

• 颜色/材质变更：GSAP 平滑过渡，不重建几何体。
• 布局/键帽轮廓变更：清除旧对象，重新生成几何体，播放键帽弹出入场动画。

这种区分避免了不必要的几何体重建，在保证视觉效果的同时控制了性能开销。

扩展与二次开发建议

增加材质预设：可添加"阳极铝""亚克力""磨砂塑料"等预设按钮，每个预设对应一组 PBR 参数值。

键位数据扩展：为每个键帽增加 keyCode、macro、rgbColor 等字段，便于导出配置或与 QMK/VIA 等固件对接。

性能优化：键帽数量多时使用 THREE.InstancedMesh；移动端关闭阴影、降低 envMap 分辨率；首屏加载慢时预烘焙静态光照贴图。

总结

MODKEYS 的核心设计理念可以用三句话概括：

• 分组管理：场景对象按逻辑类型分组，互不干扰。
• 状态驱动：所有视觉变化由状态变更触发，单向数据流。
• 平滑过渡：几何重建与颜色过渡分离，用户体验流畅。

无论是作为 Three.js 工程实践的学习案例，还是作为定制键盘电商的可视化底座，MODKEYS 都提供了一个完整且易于扩展的起点。

项目地址：github.com/thebuggeddev/modkeys

在线预览：modkeys.vercel.app