要素 API

ネイティブの公開インターフェースは、<orb-z> タグと、文書化された属性、音声プロパティ、対話メソッド、アニメーションメソッドです。内部の Shadow DOM ノードと CSS 変数は、意図的に公開のカスタマイズ対象から除外しています。

属性とプロパティ

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 の中心の色

5つのカスタム色はネイティブの属性です。ネイティブ要素の個別のプロパティではありません。

音声プロパティ

音声の設定には 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 に正規化されます。無効で null ではない属性が検出されると、Orbz は正規化した値を属性に書き戻します。

サイズと速度

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 という属性やプロパティはありません。非推奨のエイリアスと正式名への正規化は、Neongate プリセットの命名を参照してください。

カスタムパレット

preset 属性を省略し、1つ以上のカスタム色を設定します。


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

空の値は削除され、指定のない色には Neongate の既定値が使われます。明示的なプリセットとカスタム色は相互排他的です。両方を指定するとプリセットが優先され、カスタム色は無視され、Orbz は競合エラーを1件記録します。preset を削除すると、残っているカスタム色が有効になります。

preset プロパティの getter は常に正規化されたプリセット名を返し、属性がない場合は DEFAULT_ORBZ_PRESET を返します。明示的なプリセットモードとカスタム色モードを区別する場合は、hasAttribute("preset") を使用してください。setter に 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() を呼んだ時だけ音声が開始します。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 の型は、パッケージのエクスポートを参照してください。