助手状态

state 选择五种动效之一。状态传达视觉意图，不会开启麦克风、调用模型或播放音频。

状态	视觉意图	典型应用信号
`idle`	平静且可用	已准备好下一次交互
`listening`	专注接收	正在采集输入
`thinking`	集中处理	请求或工具链正在执行
`speaking`	有活力的语音式运动	正在播放合成或流式音频
`asleep`	安静、暗淡的休息	助手不可用或有意休眠

设置状态

使用 HTML 属性：


<orb-z state="listening"></orb-z>

或更新对应的 JavaScript 属性：


import "@neongate-ai/orbz/browser";
import type { OrbzElement } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
if (orb) {
  orb.state = "thinking";
}

React 与 Next.js 在导入浏览器入口后渲染相同原生标签：


import "@neongate-ai/orbz/browser";
import type { OrbzState } from "@neongate-ai/orbz";
 
export function AssistantPresence({ state }: { state: OrbzState }) {
  return <orb-z state={state} />;
}

更改 state 会用新状态动效替换当前动画。若存在 paused，Orbz 渲染新状态并保持暂停。

在 Orbz 外维护领域状态

真实助手的状态多于视觉球体所需：请求权限、重连、等待工具、错误恢复或被中断。应在应用中维护这些领域状态，并映射到最接近的视觉意图。


type SessionPhase =
  | "booting"
  | "ready"
  | "capturing"
  | "transcribing"
  | "requesting"
  | "playing"
  | "offline"
  | "failed";
 
const visualState = {
  booting: "idle",
  ready: "idle",
  capturing: "listening",
  transcribing: "thinking",
  requesting: "thinking",
  playing: "speaking",
  offline: "asleep",
  failed: "idle",
} as const;

错误详情应显示在真实文字或控件中。只改变颜色或动效不足以解释故障。

无效或缺失值

默认状态是 idle。移除 state，或通过无类型运行时代码赋不支持的值，会归一化回 idle。TypeScript 使用者可导入 OrbzState 或 ORBZ_STATES 防止无效值。


import { ORBZ_STATES, type OrbzState } from "@neongate-ai/orbz";
 
function setState(state: OrbzState) {
  // state is one of the five documented values
}
 
for (const state of ORBZ_STATES) {
  console.log(state);
}

状态还必须可被感知

动效是呈现，不是播报。当状态变化与用户有关时，应为球体搭配可见状态文字和实时区域：


<div role="status" aria-live="polite">
  <orb-z state="thinking"></orb-z>
  <span>Assistant is thinking</span>
</div>

无论动画被减少、暂停、不支持或不可见，此模式仍能传达含义。继续阅读动效与无障碍。