# @tomiaa/live2d
> 开箱即用的 Live2D 看板娘组件，支持 Live2D 2.0 和 Live2D 3.0 模型
[](https://www.npmjs.com/package/@tomiaa/live2d)
[](LICENSE)
## ✨ 特性
- 🎭 支持 Live2D 2.0 和 Live2D 3.0 模型
- 🎨 内置丰富的模型列表，开箱即用
- 🎮 支持点击交互和动画播放
- 👗 支持多服装切换
- 🎯 支持模型切换
- 💬 内置一言（Hitokoto）功能
- 📱 响应式设计，自适应屏幕尺寸
- 🎪 支持拖动和收起/展开功能
- 🔧 高度可配置
- 📦 TypeScript 支持
## 📦 安装
```bash
npm install @tomiaa/live2d
# 或
pnpm add @tomiaa/live2d
# 或
yarn add @tomiaa/live2d
```
## 🚀 快速开始
### 基础用法
#### 使用 npm/pnpm/yarn 安装
```html
Live2D Demo
```
#### 使用 CDN (unpkg)
直接在浏览器中使用，无需安装：
```html
Live2D Demo
```
### 在项目中使用
```javascript
import Live2d from '@tomiaa/live2d'
const live2d = new Live2d({
el: '#live2d',
showControl: true,
hitokoto: true,
allowDrag: true,
randomPeople: true
})
```
## 📖 配置选项
### Live2dOptions
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `el` | `string \| HTMLElement` | `"#live2d"` | 容器选择器或元素 |
| `jsBaseURL` | `string` | `"https://tomiaa12.github.io/live2d/public"` | JS 依赖地址 |
| `live2d_2_ModelBaseURL` | `string` | 使用 `jsBaseURL` | Live2D 2.0 模型地址 |
| `live2d_3_ModelBaseURL` | `string` | 使用 `jsBaseURL` | Live2D 3.0 模型地址 |
| `loadLive2d_2` | `boolean` | `true` | 是否加载 Live2D 2.0 模型列表 |
| `loadLive2d_3` | `boolean` | `true` | 是否加载 Live2D 3.0 模型列表 |
| `playLoadingAnimation` | `boolean` | `true` | 加载后是否播放登场动画 |
| `showLoading` | `boolean` | `true` | 显示加载动画 |
| `showControl` | `boolean` | `true` | 显示控制栏 |
| `maxWidth` | `number` | `400` | 容器最大宽度（px） |
| `minWidth` | `number` | `200` | 容器最小宽度（px） |
| `aspectRatio` | `[number, number]` | `[10, 9]` | 默认宽高比 |
| `randomPeople` | `boolean` | `true` | 是否随机选择人物 |
| `allowDrag` | `boolean` | `true` | 允许拖动 |
| `hitokoto` | `boolean` | `true` | 显示一言 |
| `hitokotoOptions` | `HitokotoOptions` | - | 一言配置选项 |
| `beforeInit` | `function` | - | 初始化前回调 |
| `afterInit` | `function` | - | 初始化后回调 |
| `iApplicationOptions` | `IApplicationOptions` | `{}` | PIXI.Application 配置 |
### 完整示例
```javascript
import Live2d from '@tomiaa/live2d'
const live2d = new Live2d({
el: '#live2d',
jsBaseURL: 'https://your-cdn.com/live2d',
showControl: true,
showLoading: true,
hitokoto: true,
allowDrag: true,
randomPeople: false,
maxWidth: 400,
minWidth: 200,
aspectRatio: [10, 9],
beforeInit: (data) => {
console.log('初始化前:', data)
},
afterInit: (data) => {
console.log('初始化完成:', data)
console.log('当前模型:', data.currentModelOption.name)
}
})
```
## 🎮 API
### 方法
#### `switchPerson()`
切换人物模型
```javascript
live2d.switchPerson()
```
#### `switchClothing()`
切换当前人物的服装
```javascript
live2d.switchClothing()
```
#### `loadModel()`
重新加载当前模型
```javascript
live2d.loadModel()
```
#### `collapse()`
收起 Live2D（隐藏容器，显示展开按钮）
```javascript
live2d.collapse()
```
#### `expand()`
展开 Live2D（显示容器，重新初始化）
```javascript
live2d.expand()
```
#### `destroy()`
销毁实例
```javascript
live2d.destroy()
```
### 属性
- `live2d.modelList` - 模型列表
- `live2d.currentModelOption` - 当前模型配置
- `live2d.personIndex` - 当前人物索引
- `live2d.clothingIndex` - 当前服装索引
- `live2d.model` - 当前模型实例
- `live2d.app` - PIXI 应用实例
## 🎨 功能说明
### 控制栏功能
- **切换人物**：点击切换人物图标，切换到下一个模型
- **切换服装**：点击切换服装图标，切换当前模型的服装（仅当模型有多个服装时显示）
- **收起**：点击收起图标，隐藏 Live2D 容器，显示展开按钮
### 交互功能
- **点击模型**：点击模型的不同部位会触发相应的动画
- **拖动**：如果启用了 `allowDrag`，可以拖动 Live2D 容器
- **一言**：显示随机一言句子（需要启用 `hitokoto`）
## 📚 文档
### 详细文档
- 📖 [完整文档](https://kuangyx.cn/docs/%E6%96%87%E7%AB%A0/JS%20Lib/Live2d.html)
- 📖 [Documentation](https://kuangyx.cn/docs/%E6%96%87%E7%AB%A0/JS%20Lib/Live2d.html)
### 博客文章
- 🎯 [我的博客](https://kuangyx.cn)
- 📝 [Live2D 使用教程](https://kuangyx.cn/docs/%E6%96%87%E7%AB%A0/JS%20Lib/Live2d.html)
## 🛠️ 开发
```bash
# 克隆项目
git clone https://github.com/tomiaa12/live2djs.git
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev
# 构建
pnpm build
```
## 📝 更新日志
查看 [CHANGELOG.md](./CHANGELOG.md) 了解版本更新内容。
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
## 📄 许可证
[MIT](./LICENSE)
## 👤 作者
**tomiaa**
- 博客: [kuangyx.cn](https://kuangyx.cn)
- GitHub: [@tomiaa12](https://github.com/tomiaa12)
## 🙏 致谢
- [pixi-live2d-display](https://github.com/guansss/pixi-live2d-display) - Live2D 渲染库
- [pixi.js](https://pixijs.com/) - 2D WebGL 渲染引擎
---
⭐ 如果这个项目对你有帮助，请给个 Star！