fix: update dependencies and improve animation transitions

- 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.
2026-01-09 17:44:21 +08:00
parent f5e4c2a04b
commit a7dd3a4bc0
11 changed files with 409 additions and 94 deletions
--- a/docs/skinview3d-usage.md
+++ b/docs/skinview3d-usage.md
@@ -0,0 +1,318 @@
+# 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/)