@ridp/threejs 1.4.7 → 1.5.1

package/README.md

@@ -180,31 +180,46 @@ new ThreeIns(selector: string, options: ThreeInsOptions)
 
 ##### setView()
 
-设置模型视角。
+设置模型视角 - 通过移动相机位置来实现视角切换。支持预设视角类型和自定义方向向量。
 
 ```javascript
 threeJsIns.setView(
   model: Object3D,
-  viewType: ViewType,
+  viewType: ViewType | Vector3,  // 视角类型：可以是预设枚举或自定义 Vector3 方向
   options?: {
-    scale?: number,        // 缩放比例,1=占满画布,0.5=50%,2=0%(默认: 1)
+    scale?: number,        // 缩放比例,1=占满画布,0.5=50%,2.0=200%(默认: 0.8)
+    position?: string | Vector3,  // 模型在画布中的位置
     showBox?: boolean,     // 是否显示包围盒(默认: false)
-    animate?: boolean,     // 是否启用动画(默认: false)
+    animate?: boolean,     // 是否启用动画(默认: true)
     duration?: number,     // 动画时长(毫秒,默认: 1000)
-    offset?: Vector3       // 中心点偏移
+    offset?: Vector3,      // 额外的手动偏移量
+    boxColor?: number      // 包围盒颜色(默认: 0xffff00)
   }
 ): void
 ```
 
-**视角类型 (ViewType):**
+**视角类型:**
+
+**方式 1: 使用 ViewType 枚举（预设视角）**
 - `ViewType.TOP` - 俯视(从上往下)
 - `ViewType.RIGHT` - 右视图(从右往左)
 - `ViewType.LEFT` - 左侧视(从左往右)
 - `ViewType.ISO` - 等轴测视角(对角线上方俯视)
 
+**方式 2: 使用自定义 Vector3 方向向量**
+- 任意方向向量，如 `Vector3(1, 1, 1)`、`Vector3(2, 0, 1)`
+- 向量会被自动归一化，实现相对模型中心的任意角度查看
+- 支持负值和零值，如 `Vector3(0, -1, 1)` (仰视)、`Vector3(0, 0, 1)` (平视)
+
+**position 参数选项:**
+- 字符串选项：`'center'`（居中）、`'top-left'`（左上）、`'top-right'`（右上）、`'bottom-left'`（左下）、`'bottom-right'`（右下）
+- Vector3：自定义偏移向量
+
 **示例:**
+
+**使用预设 ViewType:**
 ```javascript
-// 设置等轴测视角,模型占满画布
+// 基础用法 - 设置等轴测视角,模型占满画布
 threeJsIns.setView(model, ViewType.ISO, {
   scale: 1.0,
   showBox: true,
@@ -217,8 +232,113 @@ threeJsIns.setView(model, ViewType.TOP, {
   scale: 0.5,
   animate: true
 });
+
+// 使用位置控制 - 左上角显示
+threeJsIns.setView(model, ViewType.ISO, {
+  position: 'top-left',
+  scale: 0.8
+});
+
+// 组合使用 position 和 offset
+threeJsIns.setView(model, ViewType.TOP, {
+  position: 'top-left',     // 先自动定位到左上
+  offset: new THREE.Vector3(50, 0, 0),  // 再额外向右偏移 50
+  scale: 0.8
+});
+```
+
+**使用自定义 Vector3 方向:**
+```javascript
+// 从对角线方向查看模型（类似等轴测）
+threeJsIns.setView(model, new THREE.Vector3(1, 1, 1));
+
+// 从右前方查看模型
+threeJsIns.setView(model, new THREE.Vector3(2, 1, 1));
+
+// 从左侧平视模型
+threeJsIns.setView(model, new THREE.Vector3(0, 0, 1));
+
+// 从下方仰视模型
+threeJsIns.setView(model, new THREE.Vector3(0, -1, 1));
+
+// 自定义方向 + 其他选项
+threeJsIns.setView(model, new THREE.Vector3(1, 2, 1), {
+  scale: 0.6,
+  position: 'center',
+  showBox: true,
+  animate: true,
+  duration: 1500
+});
+
+// 从左前方查看（负值 X）
+threeJsIns.setView(model, new THREE.Vector3(-2, 1, 1));
+
+// 从反方向对角线查看
+threeJsIns.setView(model, new THREE.Vector3(-1, 1, 1));
+```
+
+**两种方式对比:**
+
+| 特性 | ViewType 枚举 | Vector3 自定义方向 |
+|------|--------------|-------------------|
+| 易用性 | ⭐⭐⭐⭐⭐ 简单直观 | ⭐⭐⭐ 需要理解 3D 向量 |
+| 灵活性 | ⭐⭐⭐ 固定 4 种视角 | ⭐⭐⭐⭐⭐ 无限可能 |
+| 适用场景 | 常用标准视角 | 特殊角度查看 |
+| 向量归一化 | 自动处理 | 自动归一化 |
+| 组合使用 | ✅ 支持 | ✅ 支持 |
+
+##### setViewByRotation()
+
+通过旋转物体切换视角 - 保持相机固定，通过旋转物体来实现视角切换。
+
+```javascript
+threeJsIns.setViewByRotation(
+  model: Object3D,
+  viewType: ViewType,
+  options?: {
+    animate?: boolean,      // 是否启用动画(默认: true)
+    duration?: number,      // 动画时长(毫秒,默认: 1000)
+    resetRotation?: boolean // 旋转前是否重置物体旋转(默认: true)
+  }
+): { rotation: object, viewType: string, degrees: object }
+```
+
+**旋转角度配置:**
+- `ViewType.LEFT` - 物体绕 X 轴旋转 45°，Y 轴旋转 45°
+- `ViewType.RIGHT` - 物体绕 Y 轴旋转 90°
+- `ViewType.TOP` - 物体绕 X 轴旋转 90°
+- `ViewType.ISO` - 物体绕 X 轴旋转 45°，Y 轴旋转 45°
+
+**示例:**
+```javascript
+// 左侧视：物体绕 X 轴 45°，Y 轴 45°
+const result = threeJsIns.setViewByRotation(model, ViewType.LEFT);
+
+// 俯视：物体绕 X 轴 90°，无动画
+threeJsIns.setViewByRotation(model, ViewType.TOP, {
+  animate: false
+});
+
+// 自定义动画时间
+threeJsIns.setViewByRotation(model, ViewType.ISO, {
+  duration: 1500
+});
+
+// 不重置旋转，在当前基础上累加
+threeJsIns.setViewByRotation(model, ViewType.LEFT, {
+  resetRotation: false
+});
 ```
 
+**两种视角切换方式对比:**
+
+| 特性 | setView() | setViewByRotation() |
+|------|-----------|---------------------|
+| 实现方式 | 移动相机位置 | 旋转物体 |
+| 相机位置 | 改变 | 固定 |
+| 物体姿态 | 保持不变 | 改变 |
+| 适用场景 | 通用视角切换 | 特殊视觉效果 |
+
 ##### frameArea()
 
 > **⚠️ 已弃用** - 此方法仅为兼容旧版本保留，请使用 `setView()` 方法代替。
@@ -401,6 +521,10 @@ const {
   getMemoryCacheInfo,    // 获取内存缓存统计
   deleteMemoryCache,     // 删除指定模型的内存缓存
 
+  // 缓存迁移和验证 (v1.5.0+)
+  cleanLegacyCache,      // 清理旧版本格式的缓存数据
+  validateCache,         // 验证并修复缓存
+
   // 性能监控
   cacheMonitor       // 缓存监控器实例
 } = loader;
@@ -631,6 +755,92 @@ const model3 = await loader.asyncFetch('/models/car.glb', '1.0.0');
 // [ asyncFetch ] ====> IndexedDB 缓存命中
 ```
 
+##### 缓存迁移和验证 API (v1.5.0+)
+
+**cleanLegacyCache()**
+
+清理旧版本格式的缓存数据，手动触发清理不需要等待数据库版本升级。
+
+```javascript
+const result = await loader.cleanLegacyCache();
+
+// 返回值:
+{
+  total: 10,        // 总记录数
+  deleted: 3,       // 删除的记录数
+  kept: 7,          // 保留的记录数
+  deletedPaths: [   // 被删除的路径列表
+    '/models/old1.glb',
+    '/models/old2.glb',
+    '/models/old3.glb'
+  ]
+}
+```
+
+**validateCache()**
+
+验证并修复缓存完整性。
+
+```javascript
+const result = await loader.validateCache();
+
+// 返回值:
+{
+  total: 10,        // 总记录数
+  valid: 8,         // 有效记录数
+  invalid: 2,       // 无效记录数
+  repairs: 1        // 修复的操作数
+}
+```
+
+**使用场景:**
+
+```javascript
+// 场景 1: 应用启动时验证缓存
+async function initApp() {
+  const { validateCache, asyncFetch } = useGLTFLoader();
+
+  // 验证并修复缓存
+  const result = await validateCache();
+  if (result.invalid > 0) {
+    console.warn(`发现 ${result.invalid} 条无效缓存，已自动清理`);
+  }
+
+  // 继续加载模型
+  const model = await asyncFetch('/models/car.glb', '1.0.0');
+}
+
+// 场景 2: 手动清理旧版本格式
+async function cleanupOldCache() {
+  const { cleanLegacyCache } = useGLTFLoader();
+
+  const result = await cleanLegacyCache();
+  console.log(`清理完成: 删除 ${result.deleted} 条，保留 ${result.kept} 条`);
+}
+
+// 场景 3: 用户遇到缓存问题时一键修复
+async function repairCache() {
+  const { validateCache, cleanLegacyCache } = useGLTFLoader();
+
+  // 先验证
+  const validation = await validateCache();
+  console.log('验证结果:', validation);
+
+  // 如果仍有问题，强制清理旧版本
+  if (validation.invalid > 0) {
+    const cleaned = await cleanLegacyCache();
+    console.log('清理结果:', cleaned);
+  }
+}
+```
+
+**缓存版本说明:**
+
+- **v1-v3 (旧版本)**: 使用序列化对象格式 (`object3DToData`)
+- **v4+ (新版本)**: 直接存储 ArrayBuffer 原始数据
+- **自动迁移**: 数据库会自动从旧版本升级，清理旧格式数据
+- **手动清理**: 可使用 `cleanLegacyCache()` 手动清理
+
 ### useRaycaster()
 
 射线拾取工具,用于鼠标交互和物体选择。
@@ -1332,9 +1542,8 @@ otherObjects.castShadow = false;
 A: 使用 `asyncFetch` 的重试机制:
 
 ```javascript
-const [err, model] = await asyncFetch(url, version, {
-  retryCount: 5,
-  timeout: 60000
+const [err, model] = await asyncFetch(url, version, null, {
+  maxRetries: 5
 });
 
 if (err || !model) {
@@ -1343,7 +1552,50 @@ if (err || !model) {
 }
 ```
 
-### Q: 如何清理模型缓存?
+### Q: 如何清理旧版本缓存数据?
+
+A: 使用 `cleanLegacyCache` 方法手动清理旧版本格式:
+
+```javascript
+import { useGLTFLoader } from '@ridp/threejs';
+
+const { cleanLegacyCache } = useGLTFLoader();
+
+// 清理旧版本序列化格式
+const result = await cleanLegacyCache();
+console.log('清理结果:', result);
+// 输出: { total: 10, deleted: 3, kept: 7, deletedPaths: [...] }
+```
+
+**自动迁移**: 当用户首次使用新版本时，数据库会自动从 v4 升级到 v5，自动清理旧版本格式数据。
+
+### Q: 如何验证缓存完整性?
+
+A: 使用 `validateCache` 方法:
+
+```javascript
+import { useGLTFLoader } from '@ridp/threejs';
+
+const { validateCache } = useGLTFLoader();
+
+// 验证并修复缓存
+const result = await validateCache();
+console.log('验证结果:', result);
+// 输出: { total: 10, valid: 8, invalid: 2, repairs: 1 }
+
+if (result.invalid > 0) {
+  console.warn(`发现 ${result.invalid} 条无效缓存，已自动清理`);
+}
+```
+
+### Q: 升级后原有缓存会被删除吗?
+
+A: 只有旧版本序列化格式的数据会被删除。ArrayBuffer 格式的数据会被保留。自动迁移过程会：
+- ✅ 保留所有 ArrayBuffer 格式的数据
+- ❌ 删除所有旧版本序列化格式的数据
+- 📊 在控制台输出迁移日志
+
+### Q: 如何清空所有缓存?
 
 A: 使用 `clearCache` 方法:
 
@@ -1405,6 +1657,121 @@ function captureScreenshot() {
 
 ## 更新日志
 
+### v1.5.0 (2026-01-12)
+
+**🎉 重大更新:**
+
+- ✨ **增强 setView() 方法 - 支持自定义 Vector3 方向**:
+  - **新增自定义方向支持**: 除了预设的 ViewType 枚举，现在可以直接传入 Vector3 方向向量
+  - **无限视角可能性**: 支持任意相机角度，如 `Vector3(1,1,1)`、`Vector3(2,0,1)` 等
+  - **自动归一化**: 向量会被自动归一化，确保相机距离计算准确
+  - **完整兼容性**: 向后兼容 ViewType 枚举，同时支持新的 Vector3 参数
+  - **灵活组合**: 自定义方向可以与 scale、position、offset 等参数组合使用
+  - 使用示例:
+    ```javascript
+    // 从对角线方向查看
+    threeJsIns.setView(model, new THREE.Vector3(1, 1, 1));
+
+    // 从右前方查看
+    threeJsIns.setView(model, new THREE.Vector3(2, 1, 1));
+
+    // 从左侧平视
+    threeJsIns.setView(model, new THREE.Vector3(0, 0, 1));
+
+    // 从下方仰视
+    threeJsIns.setView(model, new THREE.Vector3(0, -1, 1));
+    ```
+
+- ✨ **新增 setViewByRotation() 方法**: 通过旋转物体切换视角
+  - 提供另一种视角切换方式（与 setView 互补）
+  - 左视图：物体绕 X 轴 45°，Y 轴旋转 45°
+  - 支持动画过渡和旋转重置选项
+  - 适用于特殊视觉效果需求
+
+- ✨ **新增 setView() position 参数**: 控制模型在画布中的位置
+  - 支持 5 种预设位置：`center`、`top-left`、`top-right`、`bottom-left`、`bottom-right`
+  - 支持自定义 Vector3 偏移
+  - 可与 offset 参数组合使用
+
+- ✨ **新增缓存迁移和验证工具**:
+  - 数据库版本升级：v4 → v5
+  - 自动清理旧版本序列化格式数据
+  - 新增 `cleanLegacyCache()` - 手动清理旧版本缓存
+  - 新增 `validateCache()` - 验证并修复缓存完整性
+  - 新增 `cleanLegacyFormats()` - IDBCache 实例方法
+  - 新增 `validateAndRepair()` - IDBCache 实例方法
+
+- 🔧 **增强 setView() 方法**:
+  - **重大增强**: 支持 Vector3 自定义方向向量
+  - 新增 `position` 参数控制模型在画布中的位置
+  - 新增 `boxColor` 参数自定义包围盒颜色
+  - 优化视角偏移计算逻辑
+  - 完善文档和 JSDoc 注释
+
+- 🐛 **修复缓存版本兼容性问题**:
+  - 旧版本（v1-v3）使用序列化对象格式
+  - 新版本（v4+）使用 ArrayBuffer 格式
+  - 自动识别并删除旧格式数据
+  - 添加完整的格式验证逻辑
+
+**API 变更:**
+
+```javascript
+// ============ 新功能：自定义 Vector3 方向 ============
+// 从对角线方向查看模型
+threeJsIns.setView(model, new THREE.Vector3(1, 1, 1));
+
+// 从右前方查看
+threeJsIns.setView(model, new THREE.Vector3(2, 1, 1), {
+  scale: 0.8,
+  position: 'center',
+  animate: true
+});
+
+// 从左侧平视
+threeJsIns.setView(model, new THREE.Vector3(0, 0, 1));
+
+// 从下方仰视
+threeJsIns.setView(model, new THREE.Vector3(0, -1, 1));
+
+// ============ 其他新功能 ============
+// 新增 setViewByRotation
+threeJsIns.setViewByRotation(model, ViewType.LEFT, {
+  animate: true,
+  duration: 1000,
+  resetRotation: true
+});
+
+// setView position 参数
+threeJsIns.setView(model, ViewType.ISO, {
+  position: 'top-left',  // 位置控制
+  scale: 0.8,
+  offset: new THREE.Vector3(50, 0, 0)
+});
+
+// 缓存迁移和验证
+const { cleanLegacyCache, validateCache } = useGLTFLoader();
+await cleanLegacyCache();  // 清理旧版本缓存
+await validateCache();      // 验证和修复缓存
+```
+
+**Breaking Changes:**
+
+无破坏性变更，所有新功能都是向后兼容的增强。
+
+**升级指南:**
+
+- 如果使用预设视角（ViewType），无需修改任何代码
+- 如果需要自定义视角，可以直接传入 Vector3 对象替代 ViewType
+- 建议查看新示例代码了解更多用法
+
+**迁移说明:**
+
+- 数据库会自动从 v4 升级到 v5
+- 旧版本序列化格式数据会被自动删除
+- ArrayBuffer 格式数据会被保留
+- 提供手动清理工具供用户使用
+
 ### v1.4.2 (2026-01-07)
 
 **🎉 重大更新:**