R
视觉与动效MatrixOrbCanvas状态机语音助手

点阵光球

一个由点阵构成的光球，可以在 idle、listening、thinking 三个状态之间动画切换，常用于语音助手入口。

待机

上面的组件正在页面上实时运行，可以直接交互。

安装

在项目根目录执行下面的命令，组件源码会写入 @/components/ui/matrix-orb.tsx。

npx shadcn@latest add swamimalode07/rare-ui/matrix-orb

用法

组件默认导出（或具名导出）即可直接使用，不需要额外的 Provider。

matrix-orb.tsx
import { useState } from "react"
import MatrixOrb, { type MatrixOrbState } from "@/components/ui/matrix-orb"


const LABELS = { idle: "待机", listening: "聆听中", thinking: "思考中" }


export function Demo() {
  const [state, setState] = useState<MatrixOrbState>("idle")


  return (
    <div className="flex flex-col items-center gap-6">
      <MatrixOrb state={state} size={180} color="#fc4c01" labels={LABELS} />
      <div className="flex gap-2">
        {(["idle", "listening", "thinking"] as const).map((s) => (
          <button key={s} onClick={() => setState(s)}>
            {LABELS[s]}
          </button>
        ))}
      </div>
    </div>
  )
}

属性

下表列出了该组件公开的主要属性，所有未列出的原生属性都会透传到根元素。

属性类型默认值说明
state"idle" | "listening" | "thinking""idle"当前状态，切换时自动过渡。
levelnumber—0–1 的强度，通常绑定音量。
sizenumber160画布尺寸（px）。
colorstring—点阵颜色。
dotsnumber—点阵密度。
labelsPartial<Record<MatrixOrbState, string>>—自定义状态文案。