Thành phần web gốc

Phần tử gốc <orb-z> là nền tảng của Orbz. Nó hoạt động ở mọi nơi hỗ trợ phần tử tùy chỉnh, dù ứng dụng dùng JavaScript thuần hay framework.

Đăng ký tự động

Import điểm vào trình duyệt một lần trong mã ứng dụng:

main.ts


import "@neongate-ai/orbz/browser";

Mô-đun gọi defineOrbz() cho bạn. Đăng ký có bảo vệ: không làm gì trên máy chủ và trả về hàm khởi tạo hiện có nếu phần khác của trang đã đăng ký orb-z.

Có thể hiển thị thẻ trước hoặc sau khi mô-đun tải. Trình duyệt nâng cấp các thẻ hiện có khi phần tử tùy chỉnh được định nghĩa.


<orb-z state="idle" size="18rem"></orb-z>

Kết nối hoặc nâng cấp phần tử không bao giờ tự phát giọng nói. Ứng dụng chủ phải cấu hình bộ máy giọng nói và gọi startTalking() khi người dùng chủ động chọn.

Đăng ký tường minh

Dùng điểm vào gốc để chọn chính xác thời điểm đăng ký:


import { defineOrbz } from "@neongate-ai/orbz";
 
const OrbzElementClass = defineOrbz();

defineOrbz() trả về hàm khởi tạo phần tử trong trình duyệt và undefined khi không có customElements hoặc HTMLElement. Có thể gọi lặp lại an toàn.

Điều khiển bằng thuộc tính HTML


<orb-z
  state="thinking"
  size="320px"
  speed="1.15"
  preset="periwinkle"
  reduced-motion="system"
  elevated
></orb-z>

Phần tử theo dõi thay đổi, nên cập nhật thuộc tính sẽ đồng bộ giao diện ngay:


const orb = document.querySelector("orb-z");
 
orb?.setAttribute("state", "speaking");
orb?.setAttribute("speed", "1.25");
orb?.toggleAttribute("elevated", true);

Điều khiển bằng thuộc tính JavaScript

Thuộc tính JavaScript thường rõ ràng hơn khi thay đổi trạng thái bằng mã:


import type { OrbzElement } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
if (orb) {
  orb.state = "listening";
  orb.size = 300; // normalized to "300px"
  orb.speed = 1.2;
  orb.reducedMotion = "system";
  orb.elevated = true;
}

Mỗi thuộc tính công khai phản ánh vào thuộc tính HTML tương ứng. size nhận số được đổi sang pixel hoặc chuỗi độ dài CSS như "20rem".

Bộ máy giọng nói và luồng hội thoại chỉ là thuộc tính JavaScript. Chuẩn bị luồng, thêm phần tử, rồi chỉ cấu hình bộ máy và phát giọng nói sau thao tác rõ ràng của người dùng:


import "@neongate-ai/orbz/browser";
import { WebSpeechAdapter, type OrbzElement, type OrbzTalkStep } from "@neongate-ai/orbz";
 
const flow = [
  { id: "welcome", kind: "say", needsAuth: false, text: "Hello." },
  { id: "name", kind: "ask", needsAuth: false, text: "What is your name?", capture: "fullName" },
  { id: "help", kind: "say", needsAuth: false, text: "How can I help, {{fullName}}?" },
  { id: "answer", kind: "respond", needsAuth: false, strategy: "openai", fallback: "I cannot answer that right now." }
] as const satisfies readonly OrbzTalkStep[];
 
const orb = document.createElement("orb-z") as OrbzElement;
orb.talkFlow = flow;
orb.voiceEngine = new WebSpeechAdapter({ language: "en-US" });
document.body.append(orb);
 
const startVoiceButton = document.querySelector<HTMLButtonElement>("[data-start-voice]");
startVoiceButton?.addEventListener("click", async () => {
  await orb.startTalking();
});

Thuộc tính boolean

paused và elevated tuân theo ngữ nghĩa boolean HTML gốc: chỉ cần thuộc tính xuất hiện là đúng, bất kể chuỗi được gán.


<!-- Elevated -->
<orb-z elevated></orb-z>
 
<!-- Also elevated: "false" is still a present attribute -->
<orb-z elevated="false"></orb-z>

Xóa thuộc tính HTML hoặc gán false cho thuộc tính JavaScript:


orb?.removeAttribute("elevated");
 
if (orb) {
  orb.paused = false;
  orb.elevated = false;
}

Preset tích hợp hoặc bảng màu tùy chỉnh

Chọn preset màu tích hợp bằng thuộc tính preset:


<orb-z preset="magenta"></orb-z>

Giao diện mặc định là Neongate; bỏ preset để chọn mặc định qua các phiên bản. Các preset khác gồm periwinkle, magenta, peach, mocha và ivory. Xem tên preset và tương thích phiên bản.

Để dùng bảng màu tùy chỉnh, bỏ preset và đặt bất kỳ thuộc tính nào trong năm thuộc tính màu:


<orb-z
  color-primary="#7C3AED"
  color-secondary="#22D3EE"
  color-accent="#F472B6"
  color-highlight="#FDE68A"
  color-background="#09090B"
></orb-z>

Màu chưa đặt dùng giá trị Neongate mặc định. Không kết hợp preset tường minh với color-*. Nếu có cả hai, preset được ưu tiên và Orbz báo xung đột trong console.

Điều khiển từ máy trạng thái ứng dụng

Giữ ứng dụng làm nguồn dữ liệu chuẩn và để Orbz phản ánh trạng thái đó:


import type { OrbzElement, OrbzState } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
function presentAssistantState(state: OrbzState, message: string) {
  if (orb) orb.state = state;
 
  const status = document.querySelector<HTMLElement>("[data-assistant-status]");
  if (status) status.textContent = message;
}
 
presentAssistantState("thinking", "Assistant is preparing a response");

Năm trạng thái được hỗ trợ là idle, listening, thinking, speaking và asleep. Giá trị không xác định được chuẩn hóa thành idle.

Phương thức phát

Phần tử gốc cung cấp ba phương thức dành riêng cho hoạt ảnh:


orb?.pause();   // freeze the current animation
orb?.play();    // resume it
orb?.restart(); // rebuild the current state's animation

Thuộc tính paused vẫn là lựa chọn khai báo. Dùng phương thức khi tích hợp trình duyệt theo cách mệnh lệnh thuận tiện hơn.

Tùy chọn chuyển động

reduced-motion="system" tuân theo prefers-reduced-motion của người dùng và phản ứng khi thay đổi. Dùng always để luôn giảm chuyển động hoặc never để luôn dùng đầy đủ hoạt ảnh.


<div role="status" aria-live="polite">
  <orb-z state="thinking" reduced-motion="system"></orb-z>
  <span data-assistant-status>Assistant is thinking</span>
</div>

Đặt văn bản có ý nghĩa bên ngoài quả cầu. Thành phần là tín hiệu trực quan, không nên là cách duy nhất để người dùng biết trạng thái trợ lý.

Mẫu cho framework

Vue, Svelte và Angular có thể liên kết giá trị phản ứng trực tiếp vào thẻ gốc sau khi import /browser một lần. Không có adapter framework hoặc runtime dùng chung giữa ứng dụng và Orbz.

Xem ứng dụng hoàn chỉnh trong workspace sandbox .