@seayoo-web/pixi-live2d

基于 pixi-live2d-display 的二次封装库，旨在简化 Live2D 模型的加载与交互。原库 pixi-live2d-display 因维护停滞且依赖复杂，本库对其进行了整理与封装，提供更友好的 API。

特性

• 零 Vue 依赖：纯 TypeScript 实现，可用于任何框架（React, Vue, Vanilla JS）。
• 自动缩放：内置适配 1920x1080 设计稿的响应式缩放逻辑。
• 简单易用：只需传入 Canvas 元素和模型路径即可。
• 交互支持：内置点击交互与动作播放方法。

安装

pnpm add @seayoo-web/pixi-live2d

在你的项目中使用：

基础用法

import { Live2DViewer } from "@seayoo-web/pixi-live2d";

// 方式 1: 传入 Canvas ID
const viewer1 = new Live2DViewer("live2d-canvas", {
  modelPath: "https://cdn.example.com/live2d/model.json",
});

// 方式 2: 传入 HTMLCanvasElement 并配置初始参数
const canvasElement = document.getElementById("my-canvas") as HTMLCanvasElement;
const viewer2 = new Live2DViewer(canvasElement, {
  modelPath: "https://cdn.example.com/live2d/model.json",

  // 初始位置和缩放
  x: 0,
  y: 0,
  scale: 0.2, // 模型缩放比例

  // 设计稿尺寸 (用于自动计算适配比例)
  designWidth: 1920,
  designHeight: 1080,

  autoResize: true,

  onModelLoaded: (model) => {
    console.log("模型加载成功:", model);
  },
  onModelError: (error) => {
    console.error("模型加载失败:", error);
  },
});

API 说明

new Live2DViewer(canvas, options)

• canvas: HTMLCanvasElement | string - 用于渲染的 Canvas 元素或其 ID
• options: Live2DViewerOptions - 配置项

| 属性 | 类型 | 默认值 | 说明 | |Data Type|Type|Default|Description| |---|---|---|---| | modelPath | string | (必填) | Live2D 模型配置文件 (.json) 的路径 | | scale | number | - | 初始缩放比例 | | x | number | 0 | 初始 X 轴偏移 | | y | number | 0 | 初始 Y 轴偏移 | | designWidth | number | 1920 | 设计稿宽度（用于适配计算） | | designHeight | number | 1080 | 设计稿高度（用于适配计算） | | autoResize | boolean | true | 是否监听窗口 resize 事件并自动调整模型大小 | | onModelLoaded | (model) => void | - | 模型加载完成后的回调函数 | | onModelError | (error) => void | - | 模型加载失败的回调函数 |

实例方法

• startMotion(group: string, no: number) 播放指定分组的动作。

  viewer.startMotion("TapBody", 0);

• setScale(scale: number) 设置模型的缩放比例（基于自动计算的基础比例）。

  viewer.setScale(0.2);

• resize() 手动触发一次重新计算布局（通常在容器大小变化但窗口大小未变时使用）。

  viewer.resize();

• destroy() 销毁实例，清理 PIXI 应用及事件监听。

  viewer.destroy();

注意事项

本库依赖 pixi.js v6 版本（与 pixi-live2d-display 兼容），请确保项目中未安装冲突的 PIXI 版本。