元素 API

原生公开接口包括 <orb-z> 标签、文档列出的属性、语音属性、对话方法和动画方法。内部 Shadow DOM 节点与 CSS 变量有意不作为公开的自定义入口。

HTML 属性与 JavaScript 属性

HTML 属性	JavaScript 属性	接受的值	默认值
`state`	`state`	`idle`, `listening`, `thinking`, `speaking`, `asleep`	`idle`
`speech`	`speech`	宿主提供的文本；优先于 `talkFlow`	`undefined`
`size`	`size`	非空 CSS 长度；该属性也接受表示像素的正数	`16rem`
`speed`	`speed`	正数	`1`
`paused`	`paused`	布尔属性是否存在 / `boolean` 属性	`false`
`elevated`	`elevated`	布尔属性是否存在 / `boolean` 属性	`false`
`reduced-motion`	`reducedMotion`	`system`, `always`, `never`	`system`
`preset`	`preset`	规范的 `ORBZ_PRESET_NAMES` 值以及一个已弃用、源于账户名称的别名；参见预设命名	`neongate` (`DEFAULT_ORBZ_PRESET`)
`color-primary`	—	CSS 颜色	Neongate 主色
`color-secondary`	—	CSS 颜色	Neongate 辅色
`color-accent`	—	CSS 颜色	Neongate 强调色
`color-highlight`	—	CSS 颜色	Neongate 高亮色
`color-background`	—	CSS 颜色	Neongate 核心颜色

五个自定义颜色均为原生 HTML 属性，并不是原生元素上单独的 JavaScript 属性。

语音属性

语音配置使用 JavaScript 属性，因为引擎和对话步骤是结构化的值，而不是 HTML 字符串。

属性	类型	默认值
`voiceEngine`	`OrbzVoiceEnginePort \| undefined`	`undefined`
`talkFlow`	`readonly OrbzTalkStep[] \| undefined`	`DEFAULT_TALK_FLOW`
`talkContext`	只读的 `OrbzTalkContext`	空的运行时内存
`intelligence`	`OrbzIntelligencePort \| undefined`	`undefined`

调用 startTalking() 前请先设置引擎。在显式调用该方法之前，连接元素和设置引擎都不会发声。赋值 undefined 会移除已配置的引擎。

状态

状态	视觉意图
`idle`	助手等待时平静的存在感
`listening`	捕获输入时警觉的反馈
`thinking`	处理时专注的动态效果
`speaking`	播放回应时活跃的动态效果
`asleep`	安静、变暗的休息状态或禁用状态


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

不受支持的值会规范化为 idle。当 Orbz 检测到属性值无效且不为 null 时，会将规范化后的值写回该属性。

尺寸与速度

size 属性接受数字或字符串：


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

非有限值或非正数的尺寸会回退为 16rem。字符串会去除首尾空白；请传入有效且非空的 CSS 长度，以获得可预测的布局。

speed 是一个正数倍率。无效值、零、负数或非有限值都会规范化为 1。


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

布尔语义

paused 和 elevated 是标准布尔属性。只要属性存在就表示真，即使属性的字面值是 "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 会冻结当前动画。elevated 会在圆形组件周围添加居中的阴影，不改变布局尺寸。

减少动态效果

值	行为
`system`	遵循 `prefers-reduced-motion` 并响应偏好变化
`always`	始终呈现减少动态效果的样式
`never`	始终呈现完整动态效果

无效值会规范化为 system。paused 与减少动态效果并不相同：暂停会冻结当前画面；减少动态效果则会选择更平静的呈现方式。

预设

名称	主色	辅色	强调色	高亮色	背景色
`neongate`（默认）	`#6C5CFF`	`#00E9FF`	`#FF4DDE`	`#FFB07A`	`#14142B`
`periwinkle`	`#6667AB`	`#8FB8FF`	`#E66FA9`	`#F3ECFF`	`#111226`
`magenta`	`#BB2649`	`#F06A82`	`#29B8A6`	`#FFDCE4`	`#250A12`
`peach`	`#FFBE98`	`#FF8F70`	`#D987A3`	`#FFF0E7`	`#2A1516`
`mocha`	`#A47864`	`#D3A17E`	`#7FA18F`	`#F2E2D7`	`#211613`
`ivory`	`#F0EEE9`	`#AFC7D3`	`#C8B3D4`	`#FFFFFF`	`#171A20`


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

无效预设会规范化为 DEFAULT_ORBZ_PRESET。公开 API 名称为 preset，不存在 palette HTML 属性或 JavaScript 属性。关于已弃用的别名与规范化行为，请参见 Neongate 预设命名。

自定义配色

省略 preset 属性，并设置一种或多种自定义颜色：


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

空值会被移除，缺失的颜色使用 Neongate 默认值。显式预设与自定义颜色互斥。两者同时存在时，预设优先，自定义颜色会被忽略，Orbz 会记录一条冲突错误。移除 preset 后，仍然存在的自定义颜色就会生效。

preset 属性的 getter 始终返回规范化的预设名称，包括属性不存在时的 DEFAULT_ORBZ_PRESET。如果需要区分显式预设模式与自定义颜色模式，请使用 hasAttribute("preset")。通过 setter 将 preset 设为 null 或 undefined 会移除该属性。

方法

方法	效果
`pause()`	暂停当前动画并反映暂停状态
`play()`	恢复当前动画并清除暂停状态
`restart()`	从头重建当前状态的动画
`startTalking()`	朗读宿主的 `speech`，或重置上下文并启动非空 `talkFlow`；否则不执行操作
`receive(input)`	将文本传入当前的提问或回应步骤
`stopTalking()`	停止当前语音引擎与对话执行


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

只有宿主调用 startTalking() 后 Orbz 才启动语音。宿主提供 speech 或非空 talkFlow；speech 优先，两者都没有时调用不执行操作。自定义 ask 步骤把输入保存在当前元素上下文声明的 capture 键中。没有内置姓名提问或默认对话。显式激活、流程和引擎见语音与对话运行时。

观察的属性

ORBZ_OBSERVED_ATTRIBUTES 包含完整且精确的响应式属性列表：


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

元素连接后，修改其中任一属性都会同步组件。常量与 TypeScript 类型请参见包导出项。