Morph Bot API
v0.3.0 返回组件编辑器 下载组件 ↓

FRAMEWORK-FREE WEB COMPONENT

完整 API 文档

用一个 <morph-bot> 标签展示状态、加载过程和任务反馈。组件基于原生 Web Component，可在普通 HTML、React、Vue 或任何能加载 ES Module 的项目中使用。

开始接入 先在编辑器里配置
01

QUICK START

三步看到第一个 Bot

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

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

INSTALLATION

保持文件相对位置

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

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

03

ELEMENT

HTML 属性

属性类型默认值作用
statestringidle选择 39 个状态之一。
shapestringblob选择 18 个身体轮廓之一。
sizenumber96组件边长，范围 12–1024 CSS px。
colorCSS color#0b0b0b身体与 Morph 主色。
eye-colorCSS color#ffffff眼睛颜色。
speednumber1播放倍率，范围 0.1–4。
follow-pointerboolean关闭让视线跟随页面指针。
flipboolean关闭水平翻转组件。
pausedboolean关闭暂停内部仿真时钟。
decorativeboolean关闭作为纯装饰并从无障碍树隐藏。
labelstring自动非装饰组件的无障碍名称。
完整声明
<morph-bot
  state="thinking"
  shape="hex"
  size="64"
  color="#111210"
  eye-color="#ffffff"
  speed="1"
  follow-pointer
  label="正在思考"
></morph-bot>
04

JAVASCRIPT

可读写属性

bot.stateMorphBotState

读取或设置当前状态。赋值会立即开始状态切换。

bot.shapeMorphBotShape

读取或设置当前轮廓。

bot.sizenumber

读取或设置组件尺寸。

bot.speednumber

读取或设置播放倍率。

bot.pausedboolean

读取或设置暂停状态。

05

METHODS

方法

setState(state, options?)

切换到目标状态并返回当前元素。传入 { replay: true } 可重新播放相同状态。

setShape(shape)

切换轮廓并返回当前元素。

replay()

从头重播当前状态。

pause() / play()

暂停或恢复动画，均返回当前元素。

step()

前进一帧并保持暂停，适合逐帧检查。

playMorph(effect, options?)

播放一次 Morph。hold 默认 2500ms；restore 可传状态名、"default" 或 null。返回 Promise。

playSequence(steps, options?)

依次执行状态停留和单次 Morph。每步支持 state、hold、morph、morphHold；{ loop: true } 可循环。

stopSequence()

立即取消当前时间线并退出正在播放的单次 Morph，返回当前元素。

restoreStateMorph()

结束单次 Morph 预览，恢复当前状态自带的 Morph 逻辑。

configure(project)

加载编辑器导出的 v5 preset，并返回当前元素。

snapshot()

返回当前引擎快照；组件尚未连接时返回 null。

精确控制状态停留与 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();
06

EVENTS

事件

事件event.detail触发时机
ready—Shadow DOM 和引擎初始化完成。
statechange{ state }state 属性改变。
shapechange{ shape }shape 属性改变。
morphstart{ effect, hold }单次 Morph 开始。
morphend{ effect }单次 Morph 完成退出。
sequencestart{ steps, loop }时间线开始。
sequencestep{ index, cycle, state, hold, morph, morphHold }进入一个状态步骤。
sequenceend{ cycles }非循环时间线完整结束。
监听状态
bot.addEventListener("statechange", (event) => {
  console.log("当前状态：", event.detail.state);
});
07

RUNTIME

运行快照

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

stateexpressionIndexeyeOpeneyeOpenTargetmorphEffectmorphAmountmorphPhaseelapsedplaybackRatepaused
08

STATE REFERENCE

39 个状态

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

09

SHAPE REFERENCE

18 个形状

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

10

MORPH REFERENCE

14 个单次 Morph

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

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

PRESET

加载编辑器配置

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

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

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

ACCESSIBILITY

无障碍语义

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

LIFECYCLE

性能与生命周期

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

TYPESCRIPT

类型与导出

下载包包含 morph-bot.d.ts，并导出组件类、三个只读名称列表和状态到 Morph 的映射。

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