@tomiaa/live2d
v1.0.0
Published
开箱即用的 Live2d
Maintainers
tomiaaReadme
@tomiaa/live2d
开箱即用的 Live2D 看板娘组件，支持 Live2D 2.0 和 Live2D 3.0 模型
✨ 特性
- 🎭 支持 Live2D 2.0 和 Live2D 3.0 模型
- 🎨 内置丰富的模型列表，开箱即用
- 🎮 支持点击交互和动画播放
- 👗 支持多服装切换
- 🎯 支持模型切换
- 💬 内置一言（Hitokoto）功能
- 📱 响应式设计，自适应屏幕尺寸
- 🎪 支持拖动和收起/展开功能
- 🔧 高度可配置
- 📦 TypeScript 支持
📦 安装
npm install @tomiaa/live2d
# 或
pnpm add @tomiaa/live2d
# 或
yarn add @tomiaa/live2d🚀 快速开始
基础用法
使用 npm/pnpm/yarn 安装
<!DOCTYPE html>
<html>
<head>
<title>Live2D Demo</title>
</head>
<body>
<div id="live2d"></div>
<script type="module">
import Live2d from '@tomiaa/live2d'
const live2d = new Live2d({
el: '#live2d'
})
</script>
</body>
</html>使用 CDN (unpkg)
直接在浏览器中使用，无需安装：
<!DOCTYPE html>
<html>
<head>
<title>Live2D Demo</title>
</head>
<body>
<div id="live2d"></div>
<script type="module">
import Live2d from 'https://unpkg.com/@tomiaa/live2d@latest/es/index.js'
const live2d = new Live2d({
el: '#live2d'
})
</script>
</body>
</html>在项目中使用
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 配置 |
完整示例
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()
切换人物模型
live2d.switchPerson()switchClothing()
切换当前人物的服装
live2d.switchClothing()loadModel()
重新加载当前模型
live2d.loadModel()collapse()
收起 Live2D（隐藏容器，显示展开按钮）
live2d.collapse()expand()
展开 Live2D（显示容器，重新初始化）
live2d.expand()destroy()
销毁实例
live2d.destroy()属性
live2d.modelList- 模型列表live2d.currentModelOption- 当前模型配置live2d.personIndex- 当前人物索引live2d.clothingIndex- 当前服装索引live2d.model- 当前模型实例live2d.app- PIXI 应用实例
🎨 功能说明
控制栏功能
- 切换人物：点击切换人物图标，切换到下一个模型
- 切换服装：点击切换服装图标，切换当前模型的服装（仅当模型有多个服装时显示）
- 收起：点击收起图标，隐藏 Live2D 容器，显示展开按钮
交互功能
- 点击模型：点击模型的不同部位会触发相应的动画
- 拖动：如果启用了
allowDrag，可以拖动 Live2D 容器 - 一言：显示随机一言句子（需要启用
hitokoto）
📚 文档
详细文档
博客文章
- 🎯 我的博客
- 📝 Live2D 使用教程
🛠️ 开发
# 克隆项目
git clone https://github.com/tomiaa12/live2djs.git
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev
# 构建
pnpm build📝 更新日志
查看 CHANGELOG.md 了解版本更新内容。
🤝 贡献
欢迎提交 Issue 和 Pull Request！
📄 许可证
👤 作者
tomiaa
- 博客: kuangyx.cn
- GitHub: @tomiaa12
🙏 致谢
- pixi-live2d-display - Live2D 渲染库
- pixi.js - 2D WebGL 渲染引擎
⭐ 如果这个项目对你有帮助，请给个 Star！