@ridp/threejs 1.4.2 → 1.4.4

package/{readme.md → README.md}

@@ -352,9 +352,13 @@ threeJsIns.setView(model, ViewType.ISO, { scale: 1.0, animate: true });
 
 ### useGLTFLoader()
 
-GLTF 模型加载器,支持 IndexedDB 缓存。
+GLTF 模型加载器,支持 IndexedDB 缓存、内存缓存、重试机制和调试模式。
 
 ```javascript
+const loader = useGLTFLoader({
+  debug: false  // 是否开启调试日志(默认: false)
+});
+
 const {
   // 核心加载方法
   load,              // 基础加载方法
@@ -366,30 +370,61 @@ const {
   loadBatch,         // 批量加载模型
   loadBatchSequential, // 顺序批量加载
 
-  // 缓存管理
-  clearCache,        // 清空缓存
+  // IndexedDB 缓存管理
+  clearCache,        // 清空 IndexedDB 缓存
   invalidateCache,   // 使缓存失效
   getCacheStats,     // 获取缓存统计
   logCacheReport,    // 输出缓存性能报告
+  getCache,          // 获取 IDBCache 实例
+  resetCacheStats,   // 重置缓存统计
+
+  // 内存缓存管理 (v1.4.2+)
+  clearMemoryCache,      // 清空内存缓存
+  getMemoryCacheInfo,    // 获取内存缓存统计
+  deleteMemoryCache,     // 删除指定模型的内存缓存
 
   // 性能监控
   cacheMonitor       // 缓存监控器实例
-} = useGLTFLoader();
+} = loader;
+```
+
+**新增功能 (v1.4.2):**
+
+1. **内存缓存机制**: 自动缓存已解析的 3D 模型对象，避免重复解析
+2. **调试模式控制**: 通过初始化参数统一控制所有日志输出
+
+#### 初始化配置
+
+```javascript
+// 生产环境 - 默认静默
+const loader = useGLTFLoader();
+
+// 开发环境 - 开启调试日志
+const loader = useGLTFLoader({
+  debug: true
+});
+
+// 所有操作都会输出详细日志
+const model = await loader.asyncFetch('/models/car.glb', '1.0.0');
+// 输出: [ asyncFetch ] ====> 缓存未命中
+//       [ fetchArrayBuffer ] 加载模型耗时: 150ms
+//       [ 解析模型耗时 ]: 80ms
+//       [ 内存缓存 ] 存储模型 /models/car.glb (version: 1.0.0)
 ```
 
 **常用方法:**
 
 ##### asyncFetch()
 
-推荐的模型加载方法,集成缓存、重试、性能监控和模型优化。
+推荐的模型加载方法,集成 IndexedDB 缓存、内存缓存、重试机制、性能监控和模型优化。
 
 ```javascript
-const [err, model] = await asyncFetch(
+const model = await asyncFetch(
   url: string,        // 模型 URL
   version?: string,   // 模型版本(用于缓存失效)
+  onProgress?: (percent: number) => void,  // 进度回调
   options?: {
-    // 进度和重试
-    onProgress?: (progress: ProgressEvent) => void,
+    // 重试配置
     maxRetries?: number,      // 最大重试次数(默认: 3)
 
     // 模型优化选项
@@ -399,35 +434,40 @@ const [err, model] = await asyncFetch(
     simplifyOptions?: {
       minFaceCount?: number,      // 最小面数阈值,低于此值不简化(默认: 100)
       preserveUVs?: boolean      // 是否保留UV坐标(默认: true)
-    }
+    },
+
+    // 缓存控制
+    useMemoryCache?: boolean  // 是否使用内存缓存(默认: true, v1.4.2+)
   }
-): Promise<[Error | null, THREE.Object3D | null]>
+): Promise<THREE.Object3D | null>
 ```
 
+**缓存层级 (v1.4.2+):**
+
+1. **内存缓存** (最快) - 已解析的 3D 对象，仅需克隆（~2ms）
+2. **IndexedDB 缓存** (快) - ArrayBuffer 数据，需要解析（~200ms）
+3. **网络加载** (慢) - 完整下载 + 解析（~2s）
+
 **示例:**
 ```javascript
 // 基础用法
-const [err, model] = await asyncFetch('/models/car.glb', '1.0.0');
+const model = await asyncFetch('/models/car.glb', '1.0.0');
 if (model) {
   scene.add(model);
 }
 
 // 带进度回调
-const [err, model] = await asyncFetch('/models/car.glb', '1.0.0', {
-  onProgress: (progress) => {
-    const percent = (progress.loaded / progress.total * 100).toFixed(2);
-    console.log(`加载进度: ${percent}%`);
-  },
-  maxRetries: 5
+const model = await asyncFetch('/models/car.glb', '1.0.0', (percent) => {
+  console.log(`加载进度: ${percent}%`);
 });
 
 // 启用材质优化
-const [err, model] = await asyncFetch('/models/car.glb', '1.0.0', {
+const model = await asyncFetch('/models/car.glb', '1.0.0', null, {
   optimizeMaterials: true  // 自动合并相同材质
 });
 
 // 启用几何体简化(适合大型模型)
-const [err, model] = await asyncFetch('/models/large-scene.glb', '1.0.0', {
+const model = await asyncFetch('/models/large-scene.glb', '1.0.0', null, {
   simplifyGeometry: true,      // 启用简化
   simplifyRatio: 0.5,          // 保留 50% 的面
   simplifyOptions: {
@@ -436,18 +476,43 @@ const [err, model] = await asyncFetch('/models/large-scene.glb', '1.0.0', {
   }
 });
 
+// 禁用内存缓存
+const model = await asyncFetch('/models/car.glb', '1.0.0', null, {
+  useMemoryCache: false  // 跳过内存缓存
+});
+
 // 综合优化
-const [err, model] = await asyncFetch('/models/complex.glb', '1.0.0', {
-  optimizeMaterials: true,     // 优化材质
-  simplifyGeometry: true,      // 简化几何体
-  simplifyRatio: 0.7,          // 保留 70% 的面
-  onProgress: (p) => console.log(`加载: ${(p.loaded/p.total*100).toFixed(1)}%`)
+const model = await asyncFetch('/models/complex.glb', '1.0.0', (p) => {
+  console.log(`加载: ${p.toFixed(1)}%`);
+}, {
+  maxRetries: 5,             // 增加重试次数
+  optimizeMaterials: true,   // 优化材质
+  simplifyGeometry: true,    // 简化几何体
+  simplifyRatio: 0.7,        // 保留 70% 的面
+  useMemoryCache: true       // 使用内存缓存(默认)
 });
 ```
 
+**性能对比:**
+
+```javascript
+// 首次加载
+await asyncFetch('/models/car.glb', '1.0.0');
+// 耗时: ~2s (网络 + 解析 + 优化)
+
+// 二次加载 (内存缓存命中)
+await asyncFetch('/models/car.glb', '1.0.0');
+// 耗时: ~2ms (仅克隆对象)
+
+// 二次加载 (仅 IndexedDB 命中,内存缓存被清空)
+loader.clearMemoryCache();
+await asyncFetch('/models/car.glb', '1.0.0');
+// 耗时: ~200ms (从 IndexedDB 读取 + 解析)
+```
+
 ##### logCacheReport()
 
-输出缓存性能报告到控制台。
+输出 IndexedDB 缓存性能报告到控制台。
 
 ```javascript
 logCacheReport(): void
@@ -465,6 +530,89 @@ logCacheReport(): void
   - 缓存节省时间: ~1.5s
 ```
 
+##### 内存缓存管理 API (v1.4.2+)
+
+**getMemoryCacheInfo()**
+
+获取内存缓存统计信息。
+
+```javascript
+const info = loader.getMemoryCacheInfo();
+
+// 返回值:
+{
+  totalPaths: 2,      // 缓存的不同模型路径数量
+  totalModels: 3,     // 缓存的总模型数量
+  details: [
+    {
+      path: '/models/car.glb',
+      versions: ['1.0.0', '1.1.0'],
+      count: 2
+    },
+    {
+      path: '/models/truck.glb',
+      versions: ['1.0.0'],
+      count: 1
+    }
+  ]
+}
+```
+
+**clearMemoryCache()**
+
+清空所有内存缓存，释放已缓存的 3D 模型对象内存。
+
+```javascript
+const count = loader.clearMemoryCache();
+console.log(`释放了 ${count} 个模型`);
+
+// 使用场景: 内存不足时主动释放
+if (info.totalModels > 100) {
+  loader.clearMemoryCache();
+}
+```
+
+**deleteMemoryCache(path, version?)**
+
+删除指定模型的内存缓存。
+
+```javascript
+// 删除特定版本
+loader.deleteMemoryCache('/models/car.glb', '1.0.0');
+
+// 删除所有版本
+loader.deleteMemoryCache('/models/car.glb');
+```
+
+**使用示例:**
+
+```javascript
+import { useGLTFLoader } from '@ridp/threejs/hooks';
+
+const loader = useGLTFLoader({ debug: true });
+
+// 首次加载 - 从网络加载并缓存
+const model1 = await loader.asyncFetch('/models/car.glb', '1.0.0');
+// [ asyncFetch ] ====> 缓存未命中
+// [ 内存缓存 ] 存储模型 /models/car.glb (version: 1.0.0)
+
+// 二次加载 - 从内存缓存获取（极快）
+const model2 = await loader.asyncFetch('/models/car.glb', '1.0.0');
+// [ 内存缓存命中 ] /models/car.glb (version: 1.0.0)
+// [ 内存缓存克隆耗时 ]: 2ms
+
+// 查看内存缓存信息
+const info = loader.getMemoryCacheInfo();
+console.log(`缓存了 ${info.totalModels} 个模型`);
+
+// 清空内存缓存
+loader.clearMemoryCache();
+
+// 再次加载 - 从 IndexedDB 缓存获取
+const model3 = await loader.asyncFetch('/models/car.glb', '1.0.0');
+// [ asyncFetch ] ====> IndexedDB 缓存命中
+```
+
 ### useRaycaster()
 
 射线拾取工具,用于鼠标交互和物体选择。
@@ -1152,7 +1300,61 @@ function captureScreenshot() {
 
 ## 更新日志
 
-### v1.3.3 (2025-01-06)
+### v1.4.2 (2026-01-07)
+
+**🎉 重大更新:**
+
+- ✨ **新增内存缓存机制**: 自动缓存已解析的 3D 模型对象，避免重复解析
+  - 首次加载后，二次加载仅需 ~2ms（对象克隆）
+  - 相比完整加载流程，速度提升可达 **100倍以上**
+  - 新增 `clearMemoryCache()` - 清空内存缓存
+  - 新增 `getMemoryCacheInfo()` - 获取内存缓存统计
+  - 新增 `deleteMemoryCache(path, version?)` - 删除指定缓存
+  - 支持 `useMemoryCache` 选项控制是否使用内存缓存
+
+- ✨ **新增调试模式控制**:
+  - `useGLTFLoader` 现在支持初始化配置 `{ debug: boolean }`
+  - 统一控制所有内部函数的日志输出
+  - 生产环境默认静默，开发环境可开启详细日志
+  - 错误日志始终输出，不受 debug 配置影响
+
+- 🐛 **修复 Web Worker 在 npm 包中无法加载的问题**:
+  - 使用 `?worker` 语法正确导入 Worker
+  - 配置 `base: './'` 使用相对路径解析
+  - Worker 文件正确打包到 `dist/assets/` 目录
+  - 修复了之前 404 错误和 MIME 类型错误的问题
+
+**API 变更:**
+
+```javascript
+// 旧 API (v1.4.1 及之前)
+const loader = useGLTFLoader();
+const model = await loader.asyncFetch(url, version, null, { debug: true });
+
+// 新 API (v1.4.2+)
+const loader = useGLTFLoader({ debug: true });
+const model = await loader.asyncFetch(url, version);
+
+// 新增内存缓存管理
+const info = loader.getMemoryCacheInfo();
+loader.clearMemoryCache();
+loader.deleteMemoryCache(url, version);
+```
+
+**性能提升:**
+
+```
+加载场景 (v1.4.1):
+- 首次: ~2s (网络 + 解析)
+- 二次: ~200ms (IndexedDB 读取 + 解析)
+
+加载场景 (v1.4.2+):
+- 首次: ~2s (网络 + 解析)
+- 二次: ~2ms (内存缓存克隆)
+- 提升: 100倍
+```
+
+### v1.4.1 (2025-XX-XX)
 
 - 🎯 优化 `setView` 方法的 scale 参数计算逻辑
 - 🔧 修复水平 FOV 超过 180° 导致的负数距离问题