Trạng thái trợ lý

state chọn một trong năm cấu hình chuyển động. Trạng thái truyền đạt ý nghĩa trực quan, không bật micrô, gọi mô hình hay phát âm thanh.

Đặt trạng thái

Dùng thuộc tính HTML:

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

Hoặc cập nhật thuộc tính JavaScript tương ứng:

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 và Next.js hiển thị cùng thẻ gốc sau khi import điểm vào trình duyệt:

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

Đổi state thay hoạt ảnh hiện tại bằng cấu hình trạng thái mới. Nếu có paused, Orbz hiển thị trạng thái mới và giữ hoạt ảnh tạm dừng.

Giữ trạng thái miền bên ngoài Orbz

Trợ lý thực tế có nhiều trạng thái hơn quả cầu cần: xin quyền, kết nối lại, chờ công cụ, khôi phục lỗi hoặc bị ngắt. Giữ các trạng thái miền trong ứng dụng và ánh xạ sang ý nghĩa trực quan gần nhất.

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;

Chi tiết lỗi nên xuất hiện trong văn bản hoặc điều khiển thực. Chỉ đổi màu hay chuyển động không đủ để giải thích lỗi.

Giá trị không hợp lệ hoặc thiếu

Mặc định là idle. Xóa state hoặc gán giá trị không hỗ trợ qua mã không có kiểu sẽ chuẩn hóa về idle. Dùng OrbzState hoặc ORBZ_STATES trong TypeScript để tránh giá trị không hợp lệ.

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);
}

Trạng thái cũng cần cảm nhận được

Chuyển động là cách trình bày, không phải thông báo. Kết hợp quả cầu với văn bản trạng thái hiển thị và vùng thông báo trực tiếp khi thay đổi quan trọng với người dùng:

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

Mẫu này vẫn có ý nghĩa khi hoạt ảnh bị giảm, tạm dừng, không hỗ trợ hoặc không hiển thị. Đọc tiếp Chuyển động và trợ năng.