@ayden-fc2/riffle-bridge-web 1.0.5 → 1.0.7

package/README.md

@@ -85,6 +85,8 @@ const bridge = new RiffleBridge();
 
 针对RiffleBridge，分为震动模块、传感器模块、音频模块、相机模块、麦克风模块、文件存储模块、设备信息模块，各自的使用方法与注意事项已经分别说明，根据web应用所需模块，按需阅读使用即可。
 
+**注意音频模块、相机模块、麦克风模块部分依赖于文件存储模块，可以先阅读文件存储模块的代码，辅助理解这三个模块中的文件存储操作**
+
 ### 3.1 震动模块
 
 ```
@@ -313,23 +315,23 @@ const base64 = await bridge.fileStorage.readAsBase64('local://photos/aydens-demo
 
 将图片或视频保存到用户的系统相册（会请求系统相册写入权限）
 
+`saveToGallery` 支持自动解析多种 URI 格式，web 应用无需关心传入的是真实路径还是虚拟映射键：
+- `file://...` 真实文件路径：直接使用
+- `local://...` 虚拟映射键：自动从 MAP 查询实际路径
+- `http(s)://...` 网络 URL：自动查找缓存文件
+
 ```
-// 拍照后保存到系统相册
+// 拍照后保存到系统相册（直接使用 file:// 路径为例）
 const photo = await bridge.fileStorage.takePhoto();
 if (!photo?.cancelled) {
-  // 保存到系统相册（默认相册名 'Riffle'）
+  // 默认存入系统相册Riffle
   const result = await bridge.fileStorage.saveToGallery(photo.uri);
   console.log('保存成功:', result.filename);
   
-  // 或指定自定义相册名
+  // 指定自定义相册名
   const result2 = await bridge.fileStorage.saveToGallery(photo.uri, 'MyApp相册');
 }
 
-// 也可以保存已缓存的文件到系统相册
-const cached = await bridge.fileStorage.getLocalFileByUrl('local://photos/aydens-demo-photo');
-if (cached?.exists && cached.uri) {
-  await bridge.fileStorage.saveToGallery(cached.uri);
-}
 ```
 
 返回值类型：

package/dist/index.d.mts

@@ -405,10 +405,16 @@ declare class FileStorageController {
         added: boolean;
     }>;
     readAsBase64(uriOrKey: string): Promise<Base64Result>;
+    /**
+     * 解析 URI，返回实际的 file:// 路径
+     * @param uri 支持 file://、local:// 或其他映射键
+     */
+    private resolveUri;
     /**
      * 保存图片/视频到系统相册
-     * @param uri 文件 URI（支持 file:// 或 local:// 路径）
-     * @param albumName 相册名称（默认 'AIGames'）
+     * 自动解析 URI：支持 file:// 真实路径、local:// 虚拟映射键、http(s):// 缓存 URL、data: base64 dataUrl
+     * @param uri 文件 URI（支持 file://、local://、http(s):// 或 data: base64）
+     * @param albumName 相册名称（默认 'Riffle'）
      */
     saveToGallery(uri: string, albumName?: string): Promise<{
         success: boolean;

package/dist/index.d.ts

@@ -405,10 +405,16 @@ declare class FileStorageController {
         added: boolean;
     }>;
     readAsBase64(uriOrKey: string): Promise<Base64Result>;
+    /**
+     * 解析 URI，返回实际的 file:// 路径
+     * @param uri 支持 file://、local:// 或其他映射键
+     */
+    private resolveUri;
     /**
      * 保存图片/视频到系统相册
-     * @param uri 文件 URI（支持 file:// 或 local:// 路径）
-     * @param albumName 相册名称（默认 'AIGames'）
+     * 自动解析 URI：支持 file:// 真实路径、local:// 虚拟映射键、http(s):// 缓存 URL、data: base64 dataUrl
+     * @param uri 文件 URI（支持 file://、local://、http(s):// 或 data: base64）
+     * @param albumName 相册名称（默认 'Riffle'）
      */
     saveToGallery(uri: string, albumName?: string): Promise<{
         success: boolean;

package/dist/index.js

@@ -419,14 +419,44 @@ var FileStorageController = class {
   async readAsBase64(uriOrKey) {
     return this.core.send("fileStorage", "readAsBase64", { uriOrKey });
   }
+  /**
+   * 解析 URI，返回实际的 file:// 路径
+   * @param uri 支持 file://、local:// 或其他映射键
+   */
+  async resolveUri(uri) {
+    if (!uri) throw new Error("URI is required");
+    if (uri.startsWith("file://")) {
+      return uri;
+    }
+    if (!uri.startsWith("http://") && !uri.startsWith("https://")) {
+      const cached = await this.getLocalFileByUrl(uri);
+      if (cached?.exists && cached.uri) {
+        return cached.uri;
+      }
+      throw new Error(`File mapping not found: ${uri}`);
+    }
+    try {
+      const cached = await this.getLocalFileByUrl(uri);
+      if (cached?.exists && cached.uri) {
+        return cached.uri;
+      }
+    } catch {
+    }
+    return uri;
+  }
   /**
    * 保存图片/视频到系统相册
-   * @param uri 文件 URI（支持 file:// 或 local:// 路径）
-   * @param albumName 相册名称（默认 'AIGames'）
+   * 自动解析 URI：支持 file:// 真实路径、local:// 虚拟映射键、http(s):// 缓存 URL、data: base64 dataUrl
+   * @param uri 文件 URI（支持 file://、local://、http(s):// 或 data: base64）
+   * @param albumName 相册名称（默认 'Riffle'）
    */
   async saveToGallery(uri, albumName = "Riffle") {
+    let resolvedUri = uri;
+    if (!uri.startsWith("data:")) {
+      resolvedUri = await this.resolveUri(uri);
+    }
     return this.core.send("fileStorage", "saveToGallery", {
-      saveUri: uri,
+      saveUri: resolvedUri,
       albumName
     });
   }

package/dist/index.mjs

@@ -377,14 +377,44 @@ var FileStorageController = class {
   async readAsBase64(uriOrKey) {
     return this.core.send("fileStorage", "readAsBase64", { uriOrKey });
   }
+  /**
+   * 解析 URI，返回实际的 file:// 路径
+   * @param uri 支持 file://、local:// 或其他映射键
+   */
+  async resolveUri(uri) {
+    if (!uri) throw new Error("URI is required");
+    if (uri.startsWith("file://")) {
+      return uri;
+    }
+    if (!uri.startsWith("http://") && !uri.startsWith("https://")) {
+      const cached = await this.getLocalFileByUrl(uri);
+      if (cached?.exists && cached.uri) {
+        return cached.uri;
+      }
+      throw new Error(`File mapping not found: ${uri}`);
+    }
+    try {
+      const cached = await this.getLocalFileByUrl(uri);
+      if (cached?.exists && cached.uri) {
+        return cached.uri;
+      }
+    } catch {
+    }
+    return uri;
+  }
   /**
    * 保存图片/视频到系统相册
-   * @param uri 文件 URI（支持 file:// 或 local:// 路径）
-   * @param albumName 相册名称（默认 'AIGames'）
+   * 自动解析 URI：支持 file:// 真实路径、local:// 虚拟映射键、http(s):// 缓存 URL、data: base64 dataUrl
+   * @param uri 文件 URI（支持 file://、local://、http(s):// 或 data: base64）
+   * @param albumName 相册名称（默认 'Riffle'）
    */
   async saveToGallery(uri, albumName = "Riffle") {
+    let resolvedUri = uri;
+    if (!uri.startsWith("data:")) {
+      resolvedUri = await this.resolveUri(uri);
+    }
     return this.core.send("fileStorage", "saveToGallery", {
-      saveUri: uri,
+      saveUri: resolvedUri,
       albumName
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayden-fc2/riffle-bridge-web",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Riffle Bridge Web SDK - WebView 与 Native 通信桥接库",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/controllers/index.ts

@@ -302,10 +302,45 @@ export class FileStorageController {
     return this.core.send<Base64Result>('fileStorage', 'readAsBase64', { uriOrKey });
   }
 
+  /**
+   * 解析 URI，返回实际的 file:// 路径
+   * @param uri 支持 file://、local:// 或其他映射键
+   */
+  private async resolveUri(uri: string): Promise<string> {
+    if (!uri) throw new Error('URI is required');
+
+    // file:// 协议直接使用
+    if (uri.startsWith('file://')) {
+      return uri;
+    }
+
+    // 非 http/https 协议（如 local://），从 MAP 查询
+    if (!uri.startsWith('http://') && !uri.startsWith('https://')) {
+      const cached = await this.getLocalFileByUrl(uri);
+      if (cached?.exists && cached.uri) {
+        return cached.uri;
+      }
+      throw new Error(`File mapping not found: ${uri}`);
+    }
+
+    // http/https URL，先查缓存
+    try {
+      const cached = await this.getLocalFileByUrl(uri);
+      if (cached?.exists && cached.uri) {
+        return cached.uri;
+      }
+    } catch {
+      // 查询失败，继续使用原始 URL
+    }
+
+    return uri;
+  }
+
   /**
    * 保存图片/视频到系统相册
-   * @param uri 文件 URI（支持 file:// 或 local:// 路径）
-   * @param albumName 相册名称（默认 'AIGames'）
+   * 自动解析 URI：支持 file:// 真实路径、local:// 虚拟映射键、http(s):// 缓存 URL、data: base64 dataUrl
+   * @param uri 文件 URI（支持 file://、local://、http(s):// 或 data: base64）
+   * @param albumName 相册名称（默认 'Riffle'）
    */
   async saveToGallery(uri: string, albumName = 'Riffle'): Promise<{
     success: boolean;
@@ -317,8 +352,15 @@ export class FileStorageController {
     height?: number;
     duration?: number;
   }> {
+    // base64 dataUrl 直接透传给 native 处理
+    let resolvedUri = uri;
+    if (!uri.startsWith('data:')) {
+      // 非 base64 才需要解析为实际的 file:// 路径
+      resolvedUri = await this.resolveUri(uri);
+    }
+    
     return this.core.send('fileStorage', 'saveToGallery', {
-      saveUri: uri,
+      saveUri: resolvedUri,
       albumName,
     });
   }