API phần tử

Giao diện công khai gốc gồm thẻ <orb-z>, các thuộc tính được ghi trong tài liệu, thuộc tính giọng nói, phương thức hội thoại và phương thức hoạt ảnh. Các nút Shadow DOM bên trong và biến CSS được chủ ý loại khỏi những điểm tùy chỉnh công khai.

Thuộc tính HTML và JavaScript

Năm màu tùy chỉnh là các thuộc tính HTML gốc. Chúng không phải những thuộc tính JavaScript riêng biệt trên phần tử gốc.

Thuộc tính giọng nói

Cấu hình giọng nói sử dụng thuộc tính JavaScript vì bộ máy và các bước hội thoại là giá trị có cấu trúc, không phải chuỗi HTML.

Thiết lập bộ máy trước khi gọi startTalking(). Việc kết nối phần tử và gán bộ máy đều không phát âm thanh cho đến khi phương thức này được gọi rõ ràng. Gán undefined sẽ xóa bộ máy đã cấu hình.

Trạng thái

const orb = document.querySelector("orb-z");
if (orb) orb.state = "thinking";

Giá trị không được hỗ trợ sẽ được chuẩn hóa thành idle. Khi phát hiện một thuộc tính không hợp lệ và không phải null, Orbz ghi giá trị đã chuẩn hóa trở lại thuộc tính đó.

Kích thước và tốc độ

Thuộc tính size chấp nhận số hoặc chuỗi:

orb.size = 320;      // "320px"
orb.size = "20rem"; // "20rem"
orb.size = "40vw";  // "40vw"

Kích thước dạng số không hữu hạn hoặc không dương sẽ trở về 16rem. Khoảng trắng ở hai đầu chuỗi được loại bỏ; hãy truyền độ dài CSS hợp lệ, không rỗng để có bố cục dễ dự đoán.

speed là hệ số nhân dương. Giá trị không hợp lệ, bằng không, âm hoặc không hữu hạn được chuẩn hóa thành 1.

orb.speed = 0.8;
orb.speed = 1.25;

Ngữ nghĩa boolean

paused và elevated là thuộc tính boolean tiêu chuẩn. Chỉ cần thuộc tính hiện diện là giá trị đúng, ngay cả khi giá trị chuỗi của thuộc tính là "false".

<orb-z paused></orb-z>
<orb-z elevated></orb-z>

orb.paused = false;   // removes the paused attribute
orb.elevated = true;  // adds the elevated attribute

paused đóng băng hoạt ảnh đang chạy. elevated thêm bóng đổ cân giữa quanh thành phần hình tròn và không thay đổi kích thước bố cục.

Giảm chuyển động

Giá trị không hợp lệ được chuẩn hóa thành system. paused và giảm chuyển động khác nhau: tạm dừng đóng băng hình ảnh hiện tại; giảm chuyển động chọn cách hiển thị nhẹ nhàng hơn.

Bộ màu có sẵn

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

Bộ màu không hợp lệ được chuẩn hóa thành DEFAULT_ORBZ_PRESET. API công khai có tên preset; không có thuộc tính HTML hay JavaScript tên palette. Xem cách đặt tên bộ màu Neongate để biết bí danh cũ và hành vi chuẩn hóa về tên chuẩn.

Bảng màu tùy chỉnh

Bỏ thuộc tính preset và đặt một hoặc nhiều màu tùy chỉnh:

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

Giá trị rỗng bị loại bỏ, màu không được chỉ định dùng giá trị mặc định của Neongate. Bộ màu được chỉ định rõ ràng và màu tùy chỉnh loại trừ lẫn nhau. Khi cả hai cùng hiện diện, bộ màu có sẵn được ưu tiên, màu tùy chỉnh bị bỏ qua và Orbz ghi một lỗi xung đột. Xóa preset sẽ kích hoạt các màu tùy chỉnh vẫn còn hiện diện.

Getter của thuộc tính preset luôn trả về tên bộ màu đã chuẩn hóa, bao gồm DEFAULT_ORBZ_PRESET khi không có thuộc tính. Dùng hasAttribute("preset") khi cần phân biệt chế độ bộ màu được chỉ định rõ ràng với chế độ màu tùy chỉnh. Gán null hoặc undefined cho setter của preset sẽ xóa thuộc tính.

Phương thức

import type { OrbzElement } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
orb?.pause();
orb?.play();
orb?.restart();
await orb?.receive('Jonatas');

Orbz chỉ phát giọng nói khi ứng dụng gọi startTalking(). Cung cấp speech hoặc talkFlow không rỗng; speech ưu tiên và nếu thiếu cả hai thì lời gọi không làm gì. Bước ask tùy chỉnh lưu đầu vào dưới khóa capture đã khai báo trong ngữ cảnh của phần tử. Không có câu hỏi tên hay hội thoại mặc định tích hợp. Xem Giọng nói và runtime hội thoại.

Thuộc tính được theo dõi

ORBZ_OBSERVED_ATTRIBUTES chứa danh sách chính xác các thuộc tính phản ứng với thay đổi:

state, size, speed, speech, paused, elevated, preset, reduced-motion,
color-accent, color-background, color-highlight,
color-primary, color-secondary

Thay đổi một trong các thuộc tính này sau khi kết nối sẽ đồng bộ thành phần. Xem Các mục xuất của gói để biết hằng số và kiểu TypeScript.