forked from CarrotSkin/carrotskin
a7dd3a4bc0
- Updated @types/react to version 19.2.7 in package.json and package-lock.json. - Refined animation transitions in EnhancedButton, EnhancedInput, LoadingStates, Navbar, PageTransition, SkinCard, SkinDetailModal, and SkinViewer components by removing unnecessary ease properties for smoother animations. - Added size prop to EnhancedInput for better customization. - Enhanced SkinDetailModal and SkinCard styles for improved UI consistency.
318 lines
6.3 KiB
Markdown
318 lines
6.3 KiB
Markdown
# skinview3d 使用指南
|
||
|
||
skinview3d 是一个基于 Three.js 的 Minecraft 皮肤查看器，支持 3D 皮肤预览、动画效果、披风显示等功能。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
npm install skinview3d
|
||
```
|
||
|
||
## 基本用法
|
||
|
||
### 快速开始
|
||
|
||
```javascript
|
||
import { SkinViewer } from 'skinview3d';
|
||
|
||
// 创建皮肤查看器
|
||
const skinViewer = new SkinViewer({
|
||
canvas: document.getElementById('skin_container'),
|
||
width: 300,
|
||
height: 400,
|
||
skin: 'path/to/skin.png'
|
||
});
|
||
```
|
||
|
||
### React 组件封装
|
||
|
||
项目中已经封装了 React 组件 `SkinViewer`：
|
||
|
||
```tsx
|
||
import SkinViewer from '@/components/SkinViewer';
|
||
|
||
<SkinViewer
|
||
skinUrl="https://example.com/skin.png"
|
||
capeUrl="https://example.com/cape.png" // 可选
|
||
isSlim={false} // 是否为细臂模型
|
||
width={300}
|
||
height={300}
|
||
autoRotate={true} // 自动旋转
|
||
walking={false} // 步行动画
|
||
running={false} // 跑步动画
|
||
jumping={false} // 跳跃动画
|
||
rotation={true} // 允许手动旋转
|
||
/>
|
||
```
|
||
|
||
## 配置选项
|
||
|
||
### 基本配置
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `canvas` | HTMLCanvasElement | 必填 | 画布元素 |
|
||
| `width` | number | 300 | 画布宽度 |
|
||
| `height` | number | 400 | 画布高度 |
|
||
| `skin` | string | null | 皮肤图片URL |
|
||
| `cape` | string | null | 披风图片URL |
|
||
| `model` | string | 'default' | 模型类型：'default' 或 'slim' |
|
||
| `zoom` | number | 1.0 | 缩放比例 |
|
||
|
||
### 背景设置
|
||
|
||
```javascript
|
||
// 设置背景颜色
|
||
skinViewer.background = 0x5a76f3;
|
||
|
||
// 设置背景图片
|
||
skinViewer.loadBackground('path/to/background.png');
|
||
|
||
// 设置全景背景
|
||
skinViewer.loadPanorama('path/to/panorama.png');
|
||
|
||
// 透明背景
|
||
skinViewer.background = null;
|
||
```
|
||
|
||
### 相机设置
|
||
|
||
```javascript
|
||
// 设置视野角度
|
||
skinViewer.fov = 70;
|
||
|
||
// 设置缩放
|
||
skinViewer.zoom = 0.5;
|
||
```
|
||
|
||
## 动画控制
|
||
|
||
### 内置动画类型
|
||
|
||
```javascript
|
||
import {
|
||
WalkingAnimation,
|
||
RunningAnimation,
|
||
FlyingAnimation,
|
||
IdleAnimation
|
||
} from 'skinview3d';
|
||
|
||
// 步行动画
|
||
skinViewer.animation = new WalkingAnimation();
|
||
|
||
// 跑步动画
|
||
skinViewer.animation = new RunningAnimation();
|
||
|
||
// 飞行动画（可用于游泳）
|
||
skinViewer.animation = new FlyingAnimation();
|
||
|
||
// 静止动画
|
||
skinViewer.animation = new IdleAnimation();
|
||
```
|
||
|
||
### 动画控制
|
||
|
||
```javascript
|
||
// 设置动画速度
|
||
skinViewer.animation.speed = 3;
|
||
|
||
// 暂停动画
|
||
skinViewer.animation.paused = true;
|
||
|
||
// 移除动画
|
||
skinViewer.animation = null;
|
||
```
|
||
|
||
### 自动旋转
|
||
|
||
```javascript
|
||
// 启用自动旋转
|
||
skinViewer.autoRotate = true;
|
||
|
||
// 禁用自动旋转
|
||
skinViewer.autoRotate = false;
|
||
```
|
||
|
||
## 交互控制
|
||
|
||
### 鼠标控制
|
||
|
||
```javascript
|
||
// 启用旋转控制
|
||
skinViewer.controls.enableRotate = true;
|
||
|
||
// 启用缩放控制
|
||
skinViewer.controls.enableZoom = true;
|
||
|
||
// 启用平移控制
|
||
skinViewer.controls.enablePan = true;
|
||
```
|
||
|
||
## 光照设置
|
||
|
||
```javascript
|
||
// 设置相机光源强度
|
||
skinViewer.cameraLight.intensity = 0.9;
|
||
|
||
// 设置全局光源强度
|
||
skinViewer.globalLight.intensity = 0.1;
|
||
|
||
// 完全禁用阴影
|
||
globalLight.intensity = 1.0;
|
||
cameraLight.intensity = 0.0;
|
||
```
|
||
|
||
## 高级功能
|
||
|
||
### 耳朵支持
|
||
|
||
skinview3d 支持两种耳朵纹理类型：
|
||
|
||
1. **独立耳朵纹理**：14×7 像素的耳朵图片
|
||
2. **皮肤内置耳朵**：皮肤纹理中包含耳朵（如 deadmau5 皮肤）
|
||
|
||
```javascript
|
||
// 使用独立耳朵纹理
|
||
skinViewer.loadEars('path/to/ears.png', {
|
||
textureType: 'standalone'
|
||
});
|
||
|
||
// 使用皮肤内置耳朵
|
||
skinViewer.loadEars('path/to/skin.png', {
|
||
textureType: 'skin'
|
||
});
|
||
```
|
||
|
||
### 名称标签
|
||
|
||
```javascript
|
||
import { NameTagObject } from 'skinview3d';
|
||
|
||
// 简单名称标签
|
||
skinViewer.nameTag = "PlayerName";
|
||
|
||
// 自定义样式名称标签
|
||
skinViewer.nameTag = new NameTagObject("PlayerName", {
|
||
textStyle: "yellow"
|
||
});
|
||
|
||
// 移除名称标签
|
||
skinViewer.nameTag = null;
|
||
```
|
||
|
||
**注意**：要正确显示名称标签，需要加载 Minecraft 字体：
|
||
|
||
```css
|
||
@font-face {
|
||
font-family: 'Minecraft';
|
||
src: url('/path/to/minecraft.woff2') format('woff2');
|
||
}
|
||
```
|
||
|
||
## 方法参考
|
||
|
||
### 皮肤管理
|
||
|
||
```javascript
|
||
// 加载皮肤
|
||
skinViewer.loadSkin('path/to/skin.png');
|
||
|
||
// 加载皮肤并指定模型
|
||
skinViewer.loadSkin('path/to/skin.png', {
|
||
model: 'slim'
|
||
});
|
||
|
||
// 重置皮肤
|
||
skinViewer.resetSkin();
|
||
```
|
||
|
||
### 披风管理
|
||
|
||
```javascript
|
||
// 加载披风
|
||
skinViewer.loadCape('path/to/cape.png');
|
||
|
||
// 加载鞘翅（使用披风纹理）
|
||
skinViewer.loadCape('path/to/cape.png', {
|
||
backEquipment: 'elytra'
|
||
});
|
||
|
||
// 移除披风
|
||
skinViewer.loadCape(null);
|
||
```
|
||
|
||
### 尺寸调整
|
||
|
||
```javascript
|
||
// 调整查看器尺寸
|
||
skinViewer.setSize(600, 800);
|
||
|
||
// 调整宽度
|
||
skinViewer.width = 600;
|
||
|
||
// 调整高度
|
||
skinViewer.height = 800;
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
项目中封装的 SkinViewer 组件包含了完整的错误处理：
|
||
|
||
```typescript
|
||
// 图片加载失败处理
|
||
const img = new Image();
|
||
img.crossOrigin = 'anonymous';
|
||
|
||
img.onload = () => {
|
||
// 图片加载成功，初始化3D查看器
|
||
setImageLoaded(true);
|
||
};
|
||
|
||
img.onerror = (error) => {
|
||
// 图片加载失败，显示错误状态
|
||
setHasError(true);
|
||
};
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 预加载图片
|
||
在初始化3D查看器之前，先预加载皮肤图片以确保可访问性。
|
||
|
||
### 2. 性能优化
|
||
- 及时清理不再使用的查看器实例
|
||
- 避免同时运行多个动画
|
||
- 合理设置画布尺寸
|
||
|
||
### 3. 用户体验
|
||
- 提供加载状态指示
|
||
- 显示错误信息和重试选项
|
||
- 支持键盘快捷键控制
|
||
|
||
### 4. 响应式设计
|
||
监听容器尺寸变化，动态调整查看器大小：
|
||
|
||
```javascript
|
||
useEffect(() => {
|
||
if (viewerRef.current && canvasRef.current) {
|
||
const rect = canvasRef.current.getBoundingClientRect();
|
||
viewerRef.current.setSize(rect.width, rect.height);
|
||
}
|
||
}, [imageLoaded]);
|
||
```
|
||
|
||
## 项目中的使用示例
|
||
|
||
查看 `[src/components/SkinDetailModal.tsx](src/components/SkinDetailModal.tsx)` 了解完整的皮肤预览实现，包括：
|
||
|
||
- 动画控制面板
|
||
- 键盘快捷键支持
|
||
- 最小化/最大化功能
|
||
- 响应式布局
|
||
- 错误处理和加载状态
|
||
|
||
## 相关资源
|
||
|
||
- [skinview3d GitHub 仓库](https://github.com/bs-community/skinview3d)
|
||
- [skinview3d 在线演示](https://skinview3d-demo.vercel.app)
|
||
- [Three.js 官方文档](https://threejs.org/docs/) |