fayazara/robot-heads

robot-heads – 为React设计的动画3D机器人头部

它是什么

• 一个npm包，提供<RobotHead> React组件。该组件在2D画布（无WebGL）上绘制风格化的机器人头部，并对其进行动画处理以反映代理的状态（空闲、思考、聆听等）。

主要特性

• 四种几何形状 – 矩形、正方形、圆形、六边形 – 共享相同的屏幕、天线、耳朵和运动。
• 状态驱动的面部 – 每个状态（空闲、思考、搜索、聆听、说话、工作、快乐、错误、睡眠）都有自己的LED矩阵面部、运动模式和天线灯颜色。
• 可定制外观 – 外壳、饰边、屏幕的颜色属性；以像素为单位的大小；动画速度；可选的天线、地面阴影，以及用于使多个头部不同步的seed。
• 交互性 – 使用interactive（默认）时，头部会跟随鼠标指针，并在点击时跳跃/旋转；尊重prefers-reduced-motion和paused属性。
• 性能友好 – 所有头部共享一个动画循环，当标签页隐藏时会暂停；相同形状/大小的头部会重用烘焙纹理。
• 可访问性 – 画布获得role="img"和描述当前状态的aria-label。

工作原理

• 头部几何体生成为带圆角的凸多边形，然后车削成3D风格网格（耳朵、天线环）。每帧网格都会被变换，背面剔除，并由简单的演播室照明设置（主光、补光、轮廓光、天空穹顶）和胶片色调曲线照亮。
• 前面屏幕是LED矩阵；面部被渲染清晰，然后进行泛光处理以获得发光效果。
• 所有绘制都在普通的HTML <canvas>元素上完成，避免了繁重的WebGL依赖。

典型用法

import { RobotHead } from 'robot-heads';

function Agent({status}: {status: 'idle' | 'thinking' | 'speaking'}) {
  return <RobotHead state={status} size={160} />;
}

您可以通过属性更改形状、颜色、速度，并启用/禁用天线、阴影或交互性。

开发与游乐场

• 该仓库是一个pnpm工作区，库位于src/，交互式游乐场位于site/（Vite + Cloudflare Worker）。运行pnpm run dev启动游乐场，它会热重载库的更改。
• 使用pnpm run build构建，在dist/中生成可分发的文件。

许可证

• MIT许可证，作者：Fayaz Ahmed。

适合谁

• 构建AI聊天机器人、语音助手或任何交互式代理UI的前端开发人员，他们想要一个轻量级、动画化的视觉提示来表示代理的当前活动。

---

所有细节均直接取自仓库的README。