完整 API 文档

1. 下载并解压把完整的 morph-bot/ 文件夹放在 HTML 文件旁。
2. 加载组件用一个 type="module" 脚本注册自定义元素。
3. 写标签指定 state、shape 和 size。

<script type="module" src="./morph-bot/morph-bot.js"></script>

<morph-bot
  state="idle"
  shape="blob"
  size="72"
  label="等待任务"
></morph-bot>

组件入口会从同目录加载动画引擎和几何数据，因此不要只复制 morph-bot.js。

路径规则：如果页面和 morph-bot/ 是同级，使用 ./morph-bot/morph-bot.js。框架项目应把整个目录放进公开静态资源目录，再使用对应的公开 URL。

精确控制状态停留与 Morph

每一步都按固定顺序执行：进入 state → 停留 hold 毫秒 → 播放 morph → 保持 morphHold 毫秒 → 进入下一步。省略 morph 就会在停留后直接进入下一状态。

const bot = document.querySelector("#status-bot");
const sequence = [
  { state: "idle", hold: 1000, morph: "gather", morphHold: 700 },
  { state: "thinking", hold: 2400, morph: "send", morphHold: 700 },
  { state: "celebrate", hold: 1600 },
];

// 播放一次；改为 loop: true 可持续循环
bot.playSequence(sequence, { loop: false });

// 随时停止
bot.stopSequence();

用动作标签编排对话

对话脚本是一组有序节点。文字节点逐字播放；动作节点在当前位置改变状态或旋转、触发 Morph，或者插入精确停顿。组件编辑器的“对话导演”会通过 @ 菜单生成同样的数据。

const dialogue = [
  { type: "state", state: "idle", duration: 300 },
  { type: "text", text: "你好，我是 Morph Bot。" },
  { type: "state", state: "thinking", duration: 450 },
  { type: "text", text: "让我想一下……" },
  { type: "rotate", angle: -12, duration: 260 },
  { type: "morph", effect: "wave", duration: 650 },
  { type: "text", text: "有了！" },
];

await bot.performDialogue(dialogue, {
  voice: "playful",
  englishMode: "phonetic", // phonetic | letters
  rate: 1,
});

playful 与 animalese 都使用真正的 animalese-tts 人声 Sprite 合成链路。汉字按整句语境解析为拼音和声调，英文片段自动交给官方 EnglishAnalyzer；phonetic 会组合英文音素，letters 会逐字母拟声。整句采用单一音频时间线、统一响度和 10–12ms 交叉淡化。播放器提前约 60ms 调度音频，字幕和进度读取带设备输出延迟补偿的 AudioContext 播放头；组合英文音素仍逐字显示。首次播放会从组件包本地加载约 1.2 MB 的音频 Sprite。

snapshot() 返回只读的即时信息，适合调试面板和测试，不用于反向修改组件。

状态控制眼形池、眨眼节奏、姿态、运动和默认 Morph。点击右侧 Live API 的“应用状态”可立即检查任意状态。

形状只改变身体轮廓和眼位适配，不改变状态语义。

纯色提供 8 个基础色；渐变包含 8 个经过 OKLab 平滑的线性预设，以及 4 个由雾底和多个柔焦径向色团组成的空间预设；彩虹玻璃提供 5 个由基底、暗部、固定环境高光、边缘色散和内部焦散组成的多层预设。点击任意卡片即可应用到右侧 Live API。

设计依据：预设结构参考 Open Props 的可移植渐变 token 与 WebGradients 的 angle + ordered stops 表达；具体配色与玻璃分层为本项目设计。

bot.setMaterial("gradient", { preset: "electric-dusk" });
bot.setMaterial("gradient", { preset: "porcelain-bloom" });
bot.setMaterial("gradient", {
  start: "#315cf5",
  end: "#34d399",
  angle: 130,
});
bot.setMaterial("rainbow-glass", { preset: "iridescent-orb" });

通过 playMorph() 单独触发，或放进 playSequence() 的步骤中。它们按 RESET → ENTER → HOLD → EXIT → DONE 完整播放。

await bot.playMorph("send", {
  hold: 1200,
  restore: "idle",
});

configure() 接受编辑器导出的 v6 JSON。标签上的 HTML 属性优先，因此可以用一个 preset 保存完整设计，再在每个使用位置覆盖状态、形状、尺寸或材质。

const preset = await fetch("./my-bot.json")
  .then((response) => response.json());

document.querySelector("morph-bot")
  .configure(preset);

• 有业务含义时提供明确的 label，例如“正在生成报告”。
• 按钮旁已有相同文字时，给 Bot 添加 decorative，避免重复朗读。
• loading、progress 和 spawning 默认使用 role="status"。
• 组件遵循系统的 prefers-reduced-motion 设置。
• 真实百分比必须由业务界面另外显示；循环的 progress 不是 0–100% 进度。

• 每个实例使用独立 Shadow DOM 和 SVG clip ID，可同时放置多个 Bot。
• 实例离开视口时通过 IntersectionObserver 自动暂停，重新可见时恢复。
• 从 DOM 移除时清理动画帧、观察器和指针事件。
• 状态、形状、尺寸、材质和速度可在运行时更新，无需重新创建元素。
• 大量实例仍应控制可见数量；目录缩略图使用专用模式关闭粒子发射。

下载包包含 morph-bot.d.ts，并导出组件类、状态/形状/Morph 列表、材质列表、对话声音、中文语音单元分析器与全部预设。

import MorphBotElement, {
  MORPH_BOT_STATES,
  MORPH_BOT_SHAPES,
  MORPH_BOT_EFFECTS,
} from "./morph-bot/morph-bot.js";