模型事件

2026-04-13

114 words

1 min

通过模型实例的 on 方法来监听模型事件.

生命周期

从调用 load() 到调用 destroy()，模型会经历以下生命周期，每个阶段都有对应的事件可以监听：

事件列表

以下列出了所有的模型事件列表, 以 motionstart 为例:

l2d.load({
  path: 'https://model.hacxy.cn/shizuku/shizuku.model.json',
});

l2d.on('motionstart', (group, index, duration, file) => {
  message.info(`动作开始: ${group}[${index}]${file ? ` - ${file}` : ''}${duration !== null ? ` (${duration}ms)` : ''}`);
});

tap

tap: (areaName: string) => void

用户点击 canvas 且命中 hit area 时触发，areaName 为命中的区域名称

参数：

参数名	类型
areaName	string

返回值类型： void

案例：

l2d.load({
  path: 'https://model.hacxy.cn/shizuku/shizuku.model.json',
});

l2d.on('tap', areaName => {
  message.info(`点击区域: ${areaName}`);
});

---

loadstart

loadstart: (total: number) => void

调用 load() 后，模型文件开始下载前触发，total 为需要加载的文件总数

参数：

参数名	类型
total	number

返回值类型： void

案例：

l2d.on('loadstart', total => {
  message.info(`开始加载，共 ${total} 个文件`);
});

l2d.load({
  path: 'https://model.hacxy.cn/cat-black/model.json',
});

---

loadprogress

loadprogress: (loaded: number, total: number, file: string) => void

每个文件下载完成时触发

参数：

参数名	类型
loaded	number
total	number
file	string

返回值类型： void

案例：

let progressMsg: ReturnType<typeof message.loading> | null = null;

l2d.on('loadprogress', (loaded, total, file) => {
  const filename = file.split('/').pop() || file;
  if (!progressMsg) {
    progressMsg = message.loading(`${loaded}/${total}  ${filename}`, { duration: 0 });
  }
  else {
    progressMsg.content = `${loaded}/${total}  ${filename}`;
  }
});

l2d.on('loaded', () => {
  progressMsg?.destroy();
});

l2d.load({
  path: 'https://model.hacxy.cn/cat-black/model.json',
});

---

loaded

loaded: () => void

所有资源下载完毕、模型初始化完成并开始首帧渲染时触发

返回值类型： void

案例：

l2d.on('loaded', () => {
  message.success('模型加载完成，开始渲染');
});

l2d.load({
  path: 'https://model.hacxy.cn/cat-black/model.json',
});

---

expressionstart

expressionstart: (id: string) => void

调用 setExpression() 后，表情过渡动画开始播放时触发，id 为表情 ID

参数：

参数名	类型
id	string

返回值类型： void

案例：

l2d.on('expressionstart', id => {
  message.info(`表情开始播放: ${id}`);
});

l2d.load({
  path: 'https://model.hacxy.cn/shizuku/shizuku.model.json',
}).then(() => {
  const [first] = l2d.getExpressions();
  if (first)
    l2d.setExpression(first);
});

---

expressionend

expressionend: () => void

表情过渡动画播放结束时触发

返回值类型： void

案例：

l2d.on('expressionend', () => {
  message.info('表情播放结束');
});

l2d.load({
  path: 'https://model.hacxy.cn/shizuku/shizuku.model.json',
}).then(() => {
  const [first] = l2d.getExpressions();
  if (first)
    l2d.setExpression(first);
});

---

motionstart

motionstart: (group: string, index: number, duration: number | null, file: string | null) => void

调用 playMotion() 或随机动作被触发后，动作开始播放时触发

参数：

参数名	类型
group	string
index	number
duration	number | null
file	string | null

返回值类型： void

案例：

l2d.load({
  path: 'https://model.hacxy.cn/shizuku/shizuku.model.json',
});

l2d.on('motionstart', (group, index, duration, file) => {
  message.info(`动作开始: ${group}[${index}]${file ? ` - ${file}` : ''}${duration !== null ? ` (${duration}ms)` : ''}`);
});

---

motionend

motionend: (group: string, index: number, file: string | null) => void

当前动作播放完毕时触发

参数：

参数名	类型
group	string
index	number
file	string | null

返回值类型： void

案例：

l2d.on('motionend', (group, index, file) => {
  message.info(`动作结束: ${group}[${index}]${file ? ` - ${file}` : ''}`);
});

l2d.load({
  path: 'https://model.hacxy.cn/shizuku/shizuku.model.json',
});

---

destroy

destroy: () => void

调用 destroy() 后，WebGL 资源释放完成时触发

返回值类型： void

案例：

l2d.on('destroy', () => {
  message.info('模型已销毁，WebGL 资源释放完成');
});

l2d.load({
  path: 'https://model.hacxy.cn/cat-black/model.json',
});