Claude Fable 5 × Three.js:打造沉浸式 3D 键盘电商平台Claude Fable 5 × Three.js: Building an Immersive 3D Keyboard E-commerce Platform


AI free token/AI免费积分

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

项目本身是一个单页应用,核心渲染逻辑集中在 index.html 的内联脚本中,依赖通过 CDN 引入,入口模块由 src/main.js 初始化。整体架构轻量,既适合作为学习 Three.js 工程化实践的参考案例,也可直接扩展为电商级的可视化定制工具。

图片

图片

几年前,做一个这样的交互式产品配置器,还需要一支专门的 3D 开发团队才能实现。而如今,Claude Fable 5 就能做到如此程度的交互与界面表现,实在令人感叹今非昔比。


一、核心功能概览

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

二、快速本地运行

项目使用现代前端工具链(Vite),本地启动步骤如下:

图片
# 1. 克隆仓库
git clone https://github.com/thebuggeddev/modkeys.git
cd modkeys

# 2. 安装依赖
npm install

# 3. 启动开发服务器
npm run dev

启动后访问 Vite 默认地址(通常为 http://localhost:5173)即可看到配置器界面。

注意:Three.js 与 GSAP 通过 CDN 在 index.html 中直接引入,无需额外配置。src/main.js 作为 Vite 入口负责挂载 DOM 交互模块。


三、核心代码解读

3.1 模块化入口示例(src/counter.js)

项目通过 src/counter.js 演示了最基础的模块化写法——一个可复用的点击计数器:

// src/counter.js
export function setupCounter(element) {
  let counter = 0
  const setCounter = (count) => {
    counter = count
    element.innerHTML = `Count is ${counter}`
  }
  element.addEventListener('click', () => setCounter(counter + 1))
  setCounter(0)
}

该函数在 src/main.js 中被引入并挂载到 DOM 元素。虽然功能简单,但它体现了项目中小功能单独封装、主入口统一编排的组织思路。


3.2 Three.js 场景分组(模型层次结构)

3D 场景中,整机被拆解为多个逻辑分组(THREE.Group),每个分组负责一类对象,便于独立控制动画、材质与可见性:

图片
// index.html 内联脚本
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 的子对象,不影响机壳
  • 光效组(keyGlowGroup)可以单独控制混合模式与渲染顺序

地面阴影通过 ShadowMaterial 平面实现,配合额外的贴图层(AO/glow 贴花)让渲染结果更接近真实拍摄效果。


3.3 开关几何体构建(makeSwitch)

每个物理开关由多个 BoxGeometry 拼合而成,分别对应开关箱体、轴心等部件,各部件绑定独立材质:

图片
// 概念性示例,对应 index.html 中 makeSwitch 函数逻辑
function makeSwitch(x, y, z) {
  const body = new THREE.Mesh(
    new THREE.BoxGeometry(0.9, 0.4, 0.9),
    matSwBody   // 开关箱体材质
  );
  const stem = new THREE.Mesh(
    new THREE.BoxGeometry(0.25, 0.3, 0.25),
    matStem     // 轴心材质(通常半透明)
  );
  stem.position.y = 0.3;

  const swGroup = new THREE.Group();
  swGroup.add(body, stem);
  swGroup.position.set(x, y, z);
  switchGroup.add(swGroup);
}

这种几何体组合方式使得每个开关都是独立的子场景,后续可以单独更新轴心颜色或为特定位置的开关应用不同材质。


3.4 颜色平滑过渡(tweenColor + GSAP)

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

图片
// index.html 内联脚本
function tweenColor(mat, hex, duration) {
  const c = sRGB(hex);   // 将十六进制色值转换为线性 sRGB 空间
  gsap.to(mat.color, {
    r: c.r,
    g: c.g,
    b: c.b,
    duration: duration,
    ease: 'power2.out'
  });
}

关键点:Three.js 内部使用线性色彩空间,因此 sRGB() 的转换步骤不可省略,否则过渡色会出现偏差。


3.5 状态驱动重建(apply3D)

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

// 简化示意
function apply3D(patch, animate = true) {
  // 合并到全局状态
  Object.assign(state, patch);

  if (patch.layout !== undefined || patch.profile !== undefined) {
    // 布局或键帽轮廓变化 → 完整重建
    buildKeys();
    rebuildBoard();
    if (animate) popKeys();        // 键帽弹出入场动画
  }

  if (patch.caseColor !== undefined) {
    tweenColor(matCase, patch.caseColor, 0.4);
  }

  if (patch.capsColor !== undefined) {
    tweenColor(matCaps, patch.capsColor, 0.4);
  }
  // ... 其他属性处理
}

两种响应路径:

变更类型
处理方式
颜色 / 材质参数
GSAP 平滑过渡,不重建几何体
布局 / 键帽轮廓
清除旧对象,重新生成几何体,播放入场动画

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


3.6 品牌图案映射(BRAND_MARKS)

项目维护了一个品牌标记集合,将特定按键位置与品牌图案关联:

const BRAND_MARKS = {
  'escape': { brand: 'default', symbol: '⎋' },
  'logo':   { brand: 'modkeys', texture: logoTexture },
  // ...
};

切换品牌选项时,系统遍历 capsGroup 中对应键帽,替换其贴图或几何体上的图案标记。这个机制可以很方便地扩展为支持用户上传自定义 Logo 的功能。


四、界面使用功能很齐全

图片

3D 视图交互

操作
效果
鼠标左键拖拽
旋转视角
滚轮
缩放
右键拖拽
平移(取决于 OrbitControls 配置)

配置面板操作

  • 配色(Colorways)
     :在右侧面板选择预设配色或单项颜色(机壳 / 底板 / 键帽),颜色平滑过渡
  • 布局切换
    :触发机壳与键位完整重建,并播放键帽弹出动画
  • 键帽轮廓(Profile)
     :实时切换键帽高度与轮廓形状,同样触发重建
  • 单键编辑
    :打开 Per-Key Customizer,可上传纹理或调整图案的位置与缩放(Quad Editor)
  • 旋钮配件
    :可独立显隐,旋钮有自己的几何体与材质,不依赖键帽组

五、扩展与二次开发建议

5.1 增加材质预设

当前 PBR 参数(metalness / roughness / clearcoat)已完全暴露。可在面板中添加"阳极铝""亚克力""磨砂塑料"等预设按钮,每个预设对应一组参数值,通过 GSAP 过渡到目标值:

图片

const MATERIAL_PRESETS = {
  anodized:  { metalness: 0.9, roughness: 0.3, clearcoat: 0.0 },
  acrylic:   { metalness: 0.0, roughness: 0.1, clearcoat: 1.0 },
  frosted:   { metalness: 0.0, roughness: 0.8, clearcoat: 0.0 },
};

5.2 键位数据扩展(固件对接)

为 capsGroup 每个子对象的 userData 增加更多字段,便于导出配置或与 QMK/VIA 等固件对接:

keycap.userData = {
  keyCode: 'KC_ESC',
  macro: null,
  rgbColor: '#ff0000',
  layer: 0
};

5.3 性能优化方向

场景
建议
键帽数量多(100+ 键)
使用 THREE.InstancedMesh 替代单独 Mesh
移动端或低端设备
关闭阴影(castShadow = false)、降低 envMap 分辨率
首屏加载慢
预烘焙静态光照贴图,减少实时光源数量
多配置切换频繁
缓存已构建的 Group,切换时复用而非重建

5.4 理清状态同步机制(二次开发首要任务)

如果要做深度修改,建议先在浏览器控制台打印 state 对象,观察每次操作后 patch 的变化内容,再逆向追踪 apply3D 的处理分支。这比直接阅读渲染代码更高效。


最后

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

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

无论是把它当作 Three.js 工程实践的学习案例,还是作为定制键盘电商的可视化底座,MODKEYS 都提供了一个完整且易于扩展的起点。建议从 apply3D 函数入手,理清状态流转后,再根据需求向材质层或几何层延伸。

预览地址:https://modkeys.vercel.app/

代码地址:https://github.com/thebuggeddev/modkeys

 

MODKEYS is a 3D keyboard visual configuration tool that runs entirely in the browser: using Three.js as the rendering core and GSAP to drive animation transitions, it puts options such as colors, materials, keycap profiles, layouts, and accessories directly into the user's hands for a WYSIWYG customization experience.

The project itself is a single-page application. The core rendering logic is concentrated in the inline script of index.html, dependencies are loaded via CDN, and the entry module is initialized by src/main.js. The overall architecture is lightweight, making it suitable both as a reference case for learning Three.js engineering practices and as a directly extensible e-commerce-grade visual customization tool.

图片

图片

A few years ago, building an interactive product configurator like this would have required a dedicated 3D development team. Today, Claude Fable 5 can achieve this level of interaction and interface presentation—it is truly a testament to how times have changed.

I. Core Features Overview

Feature module

Description

Three.js builds the complete keyboard model, including keycaps, switches, knobs, case, and lighting groups.

Fine-tune the material feel through PBR parameters such as roughness / metalness / clearcoat.

Multiple color schemes, with smooth transitions to new colors when switching.

Quad Editor supports uploading and repositioning textures/patterns for individual keys.

Switching layouts or keycap profiles triggers rebuild + popKeys entrance animations.

Accessories such as knobs can be shown or hidden independently, with their own geometries and materials.

The interface calculates the price in real time based on the selected layout and configuration.

II. Quick Local Setup

The project uses a modern frontend toolchain (Vite); the local startup steps are as follows:

图片

After startup, visit Vite's default address (usually http://localhost:5173) to see the configurator interface.

Note: Three.js and GSAP are directly included in index.html via CDN, no additional configuration is required. src/main.js serves as the Vite entry point and is responsible for mounting the DOM interaction module.

III. Core Code Explanation

3.1 Modular Entry Example (src/counter.js)

The project uses src/counter.js to demonstrate the most basic modular pattern—a reusable click counter:

This function is imported in src/main.js and mounted to a DOM element. Although its function is simple, it reflects the project's organizational approach of encapsulating small features separately and orchestrating them from a single main entry.

3.2 Three.js Scene Groups (Model Hierarchy)

In the 3D scene, the entire keyboard is broken down into multiple logical groups (THREE.Group). Each group manages one category of objects, making it easy to independently control animation, materials, and visibility:

图片

Why design it this way?

Operations on a whole category of objects (e.g., hiding all keycaps or batch-updating colors) only need to target the corresponding Group, without traversing the entire scene graph.

The entrance animation (popKeys) can precisely affect the children of capsGroup without affecting the case.

The glow group (keyGlowGroup) can independently control the blend mode and render order.

The ground shadow is implemented using a ShadowMaterial plane, combined with an additional decal layer (AO/glow decals) to make the rendering result closer to real footage.

3.3 Switch geometry construction (makeSwitch)

Each physical switch is assembled from multiple BoxGeometry objects, corresponding to the switch housing, pivot, and other parts. Each part is bound to an independent material:

图片

This geometry combination approach makes each switch an independent sub-scene, allowing the pivot color to be updated individually later or different materials to be applied to switches at specific positions.

3.4 Smooth color transition (tweenColor + GSAP)

Color switching is the most directly perceived feature. The project uses GSAP to directly manipulate the color property of Three.js materials, achieving frame-by-frame interpolation transitions:

图片

Key point: Three.js internally uses a linear color space, so the sRGB() conversion step cannot be omitted, otherwise the transition colors will be inaccurate.

3.5 State-driven rebuild (apply3D)

This is the core dispatch function of the entire configurator. Every selection the user makes on the interface generates a partial state change (patch), and apply3D decides how to respond:

Two response paths:

Change type

Handling method

Color / material parameters

GSAP smooth transition, no geometry rebuild

Layout / keycap outline

Remove old objects, regenerate geometry, play entrance animation

This distinction avoids unnecessary geometry rebuilds and controls performance overhead while maintaining visual effects.

3.6 Brand pattern mapping (BRAND_MARKS)

The project maintains a collection of brand marks, associating specific key positions with brand patterns:

When switching brand options, the system iterates over the corresponding keycaps in capsGroup and replaces the pattern marks on their textures or geometry. This mechanism can be easily extended to support user-uploaded custom logos.

4. The interface is fully featured

图片

3D view interaction

Operation

Effect

Left mouse button drag

Rotate view

Scroll wheel

Zoom

Right-click drag

Pan (depends on OrbitControls configuration)

Configuration panel operations

: Select preset color schemes or individual colors (case / base plate / keycaps) from the right panel; colors transition smoothly

: Trigger a full rebuild of the case and key positions, and play keycap pop-out animation

: Switch keycap height and profile shape in real time, also triggering a rebuild

: Open Per-Key Customizer, allowing texture upload or adjustment of pattern position and scale (Quad Editor)

: Can be independently shown or hidden; the knob has its own geometry and material, independent of the keycap group

5. Extension and secondary development suggestions

5.1 Add material presets

The current PBR parameters (metalness / roughness / clearcoat) are fully exposed. You can add preset buttons such as "Anodized Aluminum", "Acrylic", "Frosted Plastic" to the panel, each corresponding to a set of parameter values, and transition to the target values via GSAP:

图片

5.2 Key data expansion (firmware integration)

Add more fields to the userData of each child object in capsGroup, making it easier to export configurations or integrate with firmware such as QMK/VIA:

5.3 Performance optimization directions

Scenario

Suggestion

Large number of keycaps (100+ keys)

Use THREE.InstancedMesh instead of individual meshes

Mobile or low-end devices

Disable shadows (castShadow = false) and reduce envMap resolution

Slow initial screen loading

Pre-bake static lightmaps to reduce the number of real-time light sources

Frequent configuration switching

Cache built Groups and reuse them when switching instead of rebuilding

5.4 Clarify the state synchronization mechanism (top priority for secondary development)

If deep modifications are needed, it is recommended to first print the state object in the browser console, observe the patch changes after each operation, and then reverse-trace the handling branches in apply3D. This is more efficient than directly reading the rendering code.

Finally

MODKEYS' core design philosophy can be summarized in three sentences:

Group-based management — scene objects are grouped by logical type and remain independent of one another; state-driven — all visual changes are triggered by state transitions, following a one-way data flow; smooth transitions — geometry reconstruction and color transitions are decoupled, ensuring a fluid user experience.

Whether used as a learning case for Three.js engineering practices or as the visual foundation for a custom keyboard e-commerce platform, MODKEYS provides a complete and easily extendable starting point. It is recommended to start with the apply3D function, understand the state flow, and then extend to the material or geometry layers as needed.

Preview URL: https://modkeys.vercel.app/

Code URL: https://github.com/thebuggeddev/modkeys

暂无评论,快来发表第一条评论吧!No comments yet. Be the first!

📮 需求咨询📮 Inquiry