135 lines
4.3 KiB
Markdown
135 lines
4.3 KiB
Markdown
# Spine 看板娘功能使用指南
|
||
|
||
## 功能说明
|
||
|
||
此功能为博客添加了一个可配置的 Spine 动画看板娘，可以显示在页面的角落位置。
|
||
|
||
## 配置选项
|
||
|
||
在 `src/config.ts` 文件中的 `spineModelConfig` 对象包含以下配置选项：
|
||
|
||
```typescript
|
||
export const spineModelConfig: SpineModelConfig = {
|
||
enable: false, // 是否启用看板娘（默认关闭）
|
||
model: {
|
||
path: "/pio/models/shizuku/shizuku.model.json", // 模型文件路径
|
||
scale: 1.0, // 模型缩放比例
|
||
x: 0, // X轴偏移
|
||
y: 0, // Y轴偏移
|
||
},
|
||
position: {
|
||
corner: "bottom-right", // 显示位置: "bottom-left" | "bottom-right" | "top-left" | "top-right"
|
||
offsetX: 20, // 距离边缘的X轴偏移（像素）
|
||
offsetY: 20, // 距离边缘的Y轴偏移（像素）
|
||
},
|
||
size: {
|
||
width: 280, // 容器宽度（像素）
|
||
height: 400, // 容器高度（像素）
|
||
},
|
||
interactive: {
|
||
enabled: true, // 是否启用交互功能
|
||
clickAnimation: "tap_body", // 点击时播放的动画名称
|
||
idleAnimations: ["idle"], // 待机动画列表
|
||
idleInterval: 10000, // 待机动画切换间隔（毫秒）
|
||
},
|
||
responsive: {
|
||
hideOnMobile: true, // 是否在移动端隐藏
|
||
mobileBreakpoint: 768, // 移动端断点（像素）
|
||
},
|
||
zIndex: 1000, // CSS 层级
|
||
opacity: 1.0, // 透明度（0.0-1.0）
|
||
};
|
||
```
|
||
|
||
## 文件结构要求
|
||
|
||
要使用此功能，您需要准备以下文件：
|
||
|
||
### 1. Spine 运行时库
|
||
将 Spine 运行时 JavaScript 文件放置在：
|
||
- `public/pio/static/spine-player.js`
|
||
|
||
您可以从以下来源获取：
|
||
- [Spine官方运行时](http://esotericsoftware.com/spine-runtimes)
|
||
- [spine-ts运行时](https://github.com/EsotericSoftware/spine-runtimes/tree/4.1/spine-ts)
|
||
|
||
### 2. Spine 模型文件
|
||
将您的 Spine 模型文件放置在：
|
||
- `public/pio/models/[模型名称]/`
|
||
|
||
每个模型需要包含以下文件：
|
||
- `[模型名称].json` - Spine 骨骼数据文件
|
||
- `[模型名称].atlas` - 纹理图集文件
|
||
- `[模型名称].png` - 纹理图像文件
|
||
|
||
例如，对于默认的 shizuku 模型：
|
||
- `public/pio/models/shizuku/shizuku.json`
|
||
- `public/pio/models/shizuku/shizuku.atlas`
|
||
- `public/pio/models/shizuku/shizuku.png`
|
||
|
||
## 启用步骤
|
||
|
||
1. **准备 Spine 文件**：将必要的文件按照上述结构放置在 `public/pio/` 目录中
|
||
|
||
2. **修改配置**：在 `src/config.ts` 中将 `spineModelConfig.enable` 设置为 `true`
|
||
|
||
3. **自定义设置**：根据您的需求调整其他配置选项
|
||
|
||
4. **测试功能**：重新构建并启动项目，查看看板娘是否正常显示
|
||
|
||
## 动画配置
|
||
|
||
### 点击动画
|
||
设置 `clickAnimation` 为您模型中存在的动画名称，用户点击看板娘时会播放此动画。
|
||
|
||
### 待机动画
|
||
在 `idleAnimations` 数组中添加多个动画名称，系统会按照设定的间隔随机播放这些动画。
|
||
|
||
### 常见动画名称参考
|
||
- `idle` - 待机动画
|
||
- `tap_body` - 点击身体
|
||
- `tap_head` - 点击头部
|
||
- `shake` - 摇摆动画
|
||
- `flick_head` - 轻拍头部
|
||
|
||
（具体动画名称取决于您的 Spine 模型文件）
|
||
|
||
## 响应式设计
|
||
|
||
- 默认在移动端隐藏看板娘以提高性能
|
||
- 可以通过 `hideOnMobile` 和 `mobileBreakpoint` 配置响应式行为
|
||
- 支持窗口大小变化时的动态显示/隐藏
|
||
|
||
## 故障排除
|
||
|
||
### 看板娘不显示
|
||
1. 检查 `enable` 是否设置为 `true`
|
||
2. 确认模型文件路径是否正确
|
||
3. 检查浏览器控制台是否有错误信息
|
||
4. 验证 Spine 运行时文件是否正确加载
|
||
|
||
### 动画不播放
|
||
1. 检查动画名称是否与模型文件中的动画匹配
|
||
2. 确认模型文件是否包含所需的动画数据
|
||
3. 查看浏览器控制台的错误信息
|
||
|
||
### 位置或大小问题
|
||
1. 调整 `position.offsetX` 和 `position.offsetY` 来微调位置
|
||
2. 修改 `size.width` 和 `size.height` 来调整容器大小
|
||
3. 使用 `model.scale` 来缩放模型本身
|
||
|
||
## 注意事项
|
||
|
||
- Spine 模型文件可能较大，建议优化文件大小以提高加载速度
|
||
- 在移动端默认隐藏以节省带宽和提高性能
|
||
- 确保您有使用 Spine 模型的适当许可证
|
||
- 某些浏览器可能需要用户交互后才能播放动画
|
||
|
||
## 获取 Spine 模型
|
||
|
||
您可以从以下渠道获取或制作 Spine 模型：
|
||
- [Spine官方网站](http://esotericsoftware.com/)
|
||
- 各种开源 Live2D/Spine 模型资源
|
||
- 自制或委托制作
|
||
|
||
请确保您有合法使用权限的模型文件。 |