@seayoo-web/pixi-live2d 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +106 -0
- package/dist/index.js +21742 -0
- package/package.json +57 -0
- package/types/index.d.ts +85 -0
package/README.md
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# @seayoo-web/pixi-live2d
|
|
2
|
+
|
|
3
|
+
基于 `pixi-live2d-display` 的二次封装库，旨在简化 Live2D 模型的加载与交互。原库 `pixi-live2d-display` 因维护停滞且依赖复杂，本库对其进行了整理与封装，提供更友好的 API。
|
|
4
|
+
|
|
5
|
+
## 特性
|
|
6
|
+
|
|
7
|
+
- **零 Vue 依赖**：纯 TypeScript 实现，可用于任何框架（React, Vue, Vanilla JS）。
|
|
8
|
+
- **自动缩放**：内置适配 1920x1080 设计稿的响应式缩放逻辑。
|
|
9
|
+
- **简单易用**：只需传入 Canvas 元素和模型路径即可。
|
|
10
|
+
- **交互支持**：内置点击交互与动作播放方法。
|
|
11
|
+
|
|
12
|
+
## 安装
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
pnpm add @seayoo-web/pixi-live2d
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## 在你的项目中使用：
|
|
19
|
+
|
|
20
|
+
### 基础用法
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
import { Live2DViewer } from "@seayoo-web/pixi-live2d";
|
|
24
|
+
|
|
25
|
+
// 方式 1: 传入 Canvas ID
|
|
26
|
+
const viewer1 = new Live2DViewer("live2d-canvas", {
|
|
27
|
+
modelPath: "https://cdn.example.com/live2d/model.json",
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
// 方式 2: 传入 HTMLCanvasElement 并配置初始参数
|
|
31
|
+
const canvasElement = document.getElementById("my-canvas") as HTMLCanvasElement;
|
|
32
|
+
const viewer2 = new Live2DViewer(canvasElement, {
|
|
33
|
+
modelPath: "https://cdn.example.com/live2d/model.json",
|
|
34
|
+
|
|
35
|
+
// 初始位置和缩放
|
|
36
|
+
x: 0,
|
|
37
|
+
y: 0,
|
|
38
|
+
scale: 0.2, // 模型缩放比例
|
|
39
|
+
|
|
40
|
+
// 设计稿尺寸 (用于自动计算适配比例)
|
|
41
|
+
designWidth: 1920,
|
|
42
|
+
designHeight: 1080,
|
|
43
|
+
|
|
44
|
+
autoResize: true,
|
|
45
|
+
|
|
46
|
+
onModelLoaded: (model) => {
|
|
47
|
+
console.log("模型加载成功:", model);
|
|
48
|
+
},
|
|
49
|
+
onModelError: (error) => {
|
|
50
|
+
console.error("模型加载失败:", error);
|
|
51
|
+
},
|
|
52
|
+
});
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### API 说明
|
|
56
|
+
|
|
57
|
+
#### `new Live2DViewer(canvas, options)`
|
|
58
|
+
|
|
59
|
+
- `canvas`: `HTMLCanvasElement | string` - 用于渲染的 Canvas 元素或其 ID
|
|
60
|
+
- `options`: `Live2DViewerOptions` - 配置项
|
|
61
|
+
|
|
62
|
+
| 属性 | 类型 | 默认值 | 说明 |
|
|
63
|
+
|Data Type|Type|Default|Description|
|
|
64
|
+
|---|---|---|---|
|
|
65
|
+
| `modelPath` | `string` | (必填) | Live2D 模型配置文件 (.json) 的路径 |
|
|
66
|
+
| `scale` | `number` | - | 初始缩放比例 |
|
|
67
|
+
| `x` | `number` | 0 | 初始 X 轴偏移 |
|
|
68
|
+
| `y` | `number` | 0 | 初始 Y 轴偏移 |
|
|
69
|
+
| `designWidth` | `number` | 1920 | 设计稿宽度（用于适配计算） |
|
|
70
|
+
| `designHeight` | `number` | 1080 | 设计稿高度（用于适配计算） |
|
|
71
|
+
| `autoResize` | `boolean` | `true` | 是否监听窗口 resize 事件并自动调整模型大小 |
|
|
72
|
+
| `onModelLoaded` | `(model) => void` | - | 模型加载完成后的回调函数 |
|
|
73
|
+
| `onModelError` | `(error) => void` | - | 模型加载失败的回调函数 |
|
|
74
|
+
|
|
75
|
+
#### 实例方法
|
|
76
|
+
|
|
77
|
+
- **`startMotion(group: string, no: number)`**
|
|
78
|
+
播放指定分组的动作。
|
|
79
|
+
|
|
80
|
+
```typescript
|
|
81
|
+
viewer.startMotion("TapBody", 0);
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
- **`setScale(scale: number)`**
|
|
85
|
+
设置模型的缩放比例（基于自动计算的基础比例）。
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
viewer.setScale(0.2);
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
- **`resize()`**
|
|
92
|
+
手动触发一次重新计算布局（通常在容器大小变化但窗口大小未变时使用）。
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
viewer.resize();
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
- **`destroy()`**
|
|
99
|
+
销毁实例，清理 PIXI 应用及事件监听。
|
|
100
|
+
```typescript
|
|
101
|
+
viewer.destroy();
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## 注意事项
|
|
105
|
+
|
|
106
|
+
本库依赖 `pixi.js` v6 版本（与 `pixi-live2d-display` 兼容），请确保项目中未安装冲突的 PIXI 版本。
|