方法

2026-04-15

47 words

0 min

l2d在初始化之后将返回一个实例，实例中提供了很多方法用来方便操作模型

l2d.load({
  path: 'https://model.hacxy.cn/HK416-1-normal/model.json',
}).then(() => {
  l2d.setPosition(0.2, -0.2); // 重新设置位置
  message.success('模型加载成功');
});

方法

on()

on<K>(event: K, listener: L2DEventMap[K]): L2D

类型参数：

类型 参数名
K extends keyof L2DEventMap

参数：

参数名	类型
event	K
listener	L2DEventMap[K]

返回值类型： L2D

继承自： Emitter.on

---

emit()

protected emit<K>(event: K, ...args: 参数名s<L2DEventMap[K]>): void

类型参数：

类型 参数名
K extends keyof L2DEventMap

参数：

参数名	类型
event	K
...args	参数名s<L2DEventMap[K]>

返回值类型： void

继承自： Emitter.emit

---

load()

load(options: Options): Promise<void>

加载并渲染一个 Live2D 模型，自动识别 Cubism 2 / 6 版本。 加载完成后触发 loaded 事件。

参数：

参数名	类型	描述
options	Options	模型加载选项，参见 Options

返回值类型： Promise<void>

---

create() 已弃用

create(options: Options): Promise<void>

参数：

参数名	类型
options	Options

返回值类型： Promise<void>

---

resize()

resize(): void

返回值类型： void

---

getCanvas()

getCanvas(): HTMLCanvasElement

返回当前绑定的 canvas 元素

返回值类型： HTMLCanvasElement

---

playMotion()

playMotion(group: string, index?: number, priority?: number): void

播放指定动作组中的动作。

参数：

参数名	类型	描述
group	string	动作组名称
index?	number	组内动作索引，省略时随机播放
priority?	number	播放优先级，数值越大越优先

返回值类型： void

---

getMotions()

getMotions(): Record<string, string[]>

获取所有动作，结构为 { 组名: [文件路径, ...] }。

返回值类型： Record<string, string[]>

---

playMotionByFile()

playMotionByFile(file: string, priority?: number): void

通过动作文件路径播放动作，内部自动匹配对应的动作组和索引。

参数：

参数名	类型	描述
file	string	动作文件路径，如 'motions/idle.motion3.json'
priority?	number	播放优先级

返回值类型： void

---

getExpressions()

getExpressions(): string[]

获取所有可用表情的 ID 列表

返回值类型： string[]

---

setExpression()

setExpression(id?: string): void

切换模型表情。

参数：

参数名	类型	描述
id?	string	表情 ID，省略时随机切换

返回值类型： void

---

setVolume()

setVolume(volume: number): void

设置动作声音文件的播放音量，与加载选项中的 volume 作用一致。

参数：

参数名	类型	描述
volume	number	音量，范围 0（静音）~ 1（最大）

返回值类型： void

---

setScale()

setScale(scale: number): void

设置模型缩放比例，与加载选项中的 scale 作用一致。

参数：

参数名	类型	描述
scale	number	缩放比例，1 为原始大小

返回值类型： void

---

setPosition()

setPosition(x: number, y: number): void

设置模型在画布中的位置偏移，与加载选项中的 position 作用一致。

参数：

参数名	类型	描述
x	number	X 轴偏移，范围为-2 ~ 2
y	number	Y 轴偏移，范围为-2 ~ 2

返回值类型： void

---

setParams()

setParams(params: Record<string, number>): void

批量设置模型参数值，参数 ID。

• Cubism 2 模型：打开模型目录下任意一个 .mtn 动作文件（文本格式），其中 $curve 段的每行开头即为参数 ID，例如 PARAM_MOUTH_OPEN_Y。

• Cubism 6 模型：打开模型目录下任意一个 .motion3.json 动作文件，找到 "Curves" 数组，每个对象的 "Id" 即为参数名。

参数：

参数名	类型
params	Record<string, number>

返回值类型： void

示例： l2d.setParams({ ParamEyeLOpen: 0, ParamA: 1 })

---

getParams()

getParams(): ParamInfo[]

获取模型所有参数的当前状态，每帧调用可实现实时追踪。 Cubism 2 / Cubism 6 均支持完整的 id / value / min / max / default。

返回值类型：

ParamInfo[]

---

getHitAreaBounds()

getHitAreaBounds(): object[]

获取所有 hit area 的当前边界（相对 canvas 的 0~1 比例）。 每帧调用可实现实时追踪。

返回值类型： object[]

示例：

// canvas overlay
ctx.strokeRect(b.x * canvas.width, b.y * canvas.height, b.w * canvas.width, b.h * canvas.height)
// div overlay
el.style.left = `${b.x * 100}%`

---

destroy()

destroy(): void

销毁当前模型并释放 WebGL 资源，清空画布。 画布 DOM 节点本身不会被移除。

返回值类型： void