@ayden-fc2/riffle-bridge-web 1.0.4 → 1.0.6

package/README.md

@@ -2,16 +2,16 @@
 
 ## 1. tweaks和RiffleBridge用法总览
 
-本文档为当前Web应用提供Bridge使用指导，以连接外层native应用。分为必选的tweaks和可选的RiffleBridge两个API。
+本文档为当前Web应用提供Bridge使用指导，分为必选的tweaks和可选的RiffleBridge两个API，从而与app应用通信。
 
 **安装依赖：**
 ```bash
 npm install @ayden-fc2/riffle-bridge-web
 ```
 
-tweaks用于联通web应用与native的自定义参数，传递支持颜色、数值、文本、布尔、选项类型的JsonSchema格式的tweaksConfig，原则上web应用内的颜色、数值、文本、布尔、选项都要通过tweaks层配置，从而保证native能够响应式控制，使用参考文章第二节。
+tweaks用于联通web应用与app应用的自定义参数，传递支持颜色、数值、文本、布尔、选项类型的JsonSchema格式的tweaksConfig，原则上web应用内的颜色、数值、文本、布尔、选项都要通过tweaks层配置，从而保证app应用能够响应式控制，使用参考文章第二节。
 
-RiffleBridge用于调用震动、音频、相机等模块的native功能，展开对应文章第三节各个模块，根据所需要实现的web应用功能，按需参考模块取用即可；
+RiffleBridge用于调用震动、音频、相机等模块的app应用功能，展开对应文章第三节各个模块，根据所需要实现的web应用功能，按需参考模块取用即可；
 
 ## 2. tweaks 用法
 
@@ -23,20 +23,20 @@ RiffleBridge用于调用震动、音频、相机等模块的native功能，展
 
 ```
 const tweaksConfig = {
-  // 颜色类型 - Native 端显示颜色选择器
+  // 颜色类型 - app应用 端显示颜色选择器
   color: { name: '颜色', type: 'color', value: '#667eea' },
   
-  // 数值类型 - Native 端显示滑块
+  // 数值类型 - app应用 端显示滑块
   size:  { name: '大小', type: 'number', value: 150, min: 50, max: 300 },
   opacity: { name: '透明度', type: 'number', value: 1, min: 0, max: 1, step: 0.1 },
   
-  // 文本类型 - Native 端显示文本输入框
+  // 文本类型 - app应用 端显示文本输入框
   title: { name: '标题', type: 'string', value: 'Hello World' },
   
-  // 布尔类型 - Native 端显示开关
+  // 布尔类型 - app应用 端显示开关
   enabled: { name: '启用', type: 'boolean', value: true },
   
-  // 选项类型 - Native 端显示下拉选择器
+  // 选项类型 - app应用 端显示下拉选择器
   mode: { name: '模式', type: 'select', value: 'normal', options: ['normal', 'fast', 'slow'] },
   vibration: { name: '震动', type: 'select', value: 'medium', options: [
     { label: '轻', value: 'light' },
@@ -48,7 +48,7 @@ const tweaksConfig = {
 
 ### 2.2 初始化（必须传入React实例）
 
-通过 { React } 参数显式传入初始化，保证web和native内外层数据联通，响应式更新，初始化代码如下：
+通过 { React } 参数显式传入初始化，保证web和app应用数据联通，响应式更新，初始化代码如下：
 
 ```
 import React, { useMemo } from 'react';
@@ -64,7 +64,7 @@ const tweaks = useMemo(() => createTweaks(tweaksConfig, { React }), []);
 
 ```
 function Demo() {
-  // .useState() 自动响应式订阅，Native 修改时自动重渲染
+  // .useState() 自动响应式订阅，app应用 修改时自动重渲染
   const color = tweaks.color.useState();
   const size = tweaks.size.useState();
   
@@ -76,7 +76,7 @@ function Demo() {
 
 ## 3. RiffleBridge用法
 
-通过 `RiffleBridge` 类调用 native 功能：
+通过 `RiffleBridge` 类调用app应用功能：
 
 ```
 import { RiffleBridge } from '@ayden-fc2/riffle-bridge-web';
@@ -85,6 +85,8 @@ const bridge = new RiffleBridge();
 
 针对RiffleBridge，分为震动模块、传感器模块、音频模块、相机模块、麦克风模块、文件存储模块、设备信息模块，各自的使用方法与注意事项已经分别说明，根据web应用所需模块，按需阅读使用即可。
 
+**注意音频模块、相机模块、麦克风模块部分依赖于文件存储模块，可以先阅读文件存储模块的代码，辅助理解这三个模块中的文件存储操作**
+
 ### 3.1 震动模块
 
 ```
@@ -112,7 +114,7 @@ await bridge.haptic.intensity(0.5);
 - **y轴**：正值指向设备顶部
 - **z轴**：正值指向屏幕外（朝向用户）
 
-> iOS 和 Android 原始坐标系不同，Bridge 已在 Native 层自动处理，WebView 端收到的数据保持一致。
+> iOS 和 Android 原始坐标系不同，Bridge 已在 app应用 层自动处理，WebView 端收到的数据保持一致。
 
 ```typescript
 // 启动传感器
@@ -160,14 +162,14 @@ const tilt = bridge.utils.getTiltDirection(x, y);
 ```
 
 ### 3.3 音频模块（录音、播放）
-> 特别注意拿到的uri文件资源是webview外的native文件路径，当前webview无法直接播放音频，请参考录音模块代码，先调用readAsBase64转码再播放！
+> 特别注意拿到的uri文件资源是app应用文件路径，当前web应用无法直接播放音频，请参考录音模块代码，先调用readAsBase64转码再播放！
 
 **播放模块：**
 
 单例模式实现，主要用于不需要用户交互就直接播放的背景音乐等，点击音效等仍由web应用本身实现
 
 ```
-// 播放，支持传入 local://xxx 或 file://xxx 的native本地路径，或 https://xxx 的url网址
+// 播放，支持传入 local://xxx 或 file://xxx 的app应用本地路径，或 https://xxx 的url网址
 await bridge.audio.playOnline({ uri: playUri });
 
 // 播放并循环（适用于背景音乐）
@@ -208,14 +210,14 @@ console.log('时长:', result.durationMillis / 1000, '秒');
 
 // 保存录音（以aydens-voice为例，实际可以替换为web应用的独特键，或者result.uri的独特文件名）
 if (result?.uri) {
-  // 保存文件到native应用并记录map
+  // 保存文件到app应用应用并记录map
   await bridge.fileStorage.addCustomFileMapping('local://recording/aydens-voice', result.uri);
 }
 
-// 1. 后续让native层播放
+// 1. 后续让app应用播放
 await bridge.audio.playOnline({ uri: 'local://recording/aydens-voice' });
 
-// 2. 后续直接让web播放
+// 2. 后续直接让web应用播放
 const audioData = await bridge.fileStorage.readAsBase64(result.uri);
 const audio = new Audio(audioData.dataUrl);  // dataUrl 已是完整 'data:audio/mp4;base64,...'
 audio.play();
@@ -227,7 +229,7 @@ audio.play();
 
 ### 3.4 相机模块（实时相机、拍照、相册、闪光灯）
 
->> 特别注意拿到的uri文件资源是webview外的native文件路径，当前webview无法直接渲染，请参考下方**拍照/相册**的代码，先调用readAsBase64转码再渲染！
+>> 特别注意拿到的uri文件资源是app应用件路径，当前web应用无法直接渲染，请参考下方**拍照/相册**的代码，先调用readAsBase64转码再渲染！
 
 **实时相机**
 
@@ -244,7 +246,7 @@ document.getElementById('root')!.style.background = 'transparent';
 
 // 拍照 
 // ⚠️ 拍照后不要直接渲染，参考下方**拍照/相册**的代码，先调用readAsBase64转码再渲染！
-// ⚠️ 拍照后如果需要保存，也参考下方**拍照/相册**的代码调用native的文件存储模块保存并记录map
+// ⚠️ 拍照后如果需要保存，也参考下方**拍照/相册**的代码调用app应用的文件存储模块保存并记录map
 const photo = await bridge.camera.takePhoto();
 
 // 切换摄像头
@@ -292,14 +294,14 @@ await bridge.camera.setFilter('none');
 // 1. 拍照（以aydens-demo-photo为例，实际web应用使用picked.uri文件名或组特的key）
 const photo = await bridge.fileStorage.takePhoto();
 if (!photo?.cancelled) {
-  // 保存文件到native应用并记录map
+  // 保存文件到app应用并记录map
   await bridge.fileStorage.addCustomFileMapping('local://photos/aydens-demo-photo', photo.uri);
 }
 
 // 2. 或从相册选择（以aydens-photo为例，实际web应用使用picked.uri文件名或组特的key）
 const picked = await bridge.fileStorage.pickFromGallery();
 if (!picked?.cancelled) {
-  // 保存文件到native应用并记录map
+  // 保存文件到app应用并记录map
   await bridge.fileStorage.addCustomFileMapping('local://photos/aydens-demo-photo', picked.uri);
 }
 
@@ -309,6 +311,43 @@ const base64 = await bridge.fileStorage.readAsBase64('local://photos/aydens-demo
 <img src={`data:image/jpeg;base64,${base64}`} />
 ```
 
+**保存到系统相册**
+
+将图片或视频保存到用户的系统相册（会请求系统相册写入权限）
+
+`saveToGallery` 支持自动解析多种 URI 格式，web 应用无需关心传入的是真实路径还是虚拟映射键：
+- `file://...` 真实文件路径：直接使用
+- `local://...` 虚拟映射键：自动从 MAP 查询实际路径
+- `http(s)://...` 网络 URL：自动查找缓存文件
+
+```
+// 拍照后保存到系统相册（直接使用 file:// 路径为例）
+const photo = await bridge.fileStorage.takePhoto();
+if (!photo?.cancelled) {
+  // 默认存入系统相册Riffle
+  const result = await bridge.fileStorage.saveToGallery(photo.uri);
+  console.log('保存成功:', result.filename);
+  
+  // 指定自定义相册名
+  const result2 = await bridge.fileStorage.saveToGallery(photo.uri, 'MyApp相册');
+}
+
+```
+
+返回值类型：
+```typescript
+interface SaveToGalleryResult {
+  success: boolean;      // 是否成功
+  assetId?: string;      // 系统相册资产ID
+  uri?: string;          // 保存后的URI
+  filename?: string;     // 文件名
+  mediaType?: string;    // 媒体类型 'photo' | 'video'
+  width?: number;        // 图片宽度
+  height?: number;       // 图片高度
+  duration?: number;     // 视频时长（秒）
+}
+```
+
 **闪光灯**
 
 闪光灯必须打开实时相机才能调用，参考实时相机的说明。
@@ -316,7 +355,7 @@ const base64 = await bridge.fileStorage.readAsBase64('local://photos/aydens-demo
 当应用需要闪光灯而不要实时相机时，可以使用非透明web应用背景来遮挡实时相机
 
 ### 3.5 文件存储模块
->> 特别注意拿到的uri文件资源是webview外的native文件路径，当前webview无法直接渲染图片或播放音频，请参考下方代码，先调用readAsBase64转码再渲染或播放！相机&录音等模块也都有联动说明
+>> 特别注意拿到的uri文件资源是app应用文件路径，当前web应用无法直接渲染图片或播放音频，请参考下方代码，先调用readAsBase64转码再渲染或播放！相机&录音等模块也都有联动说明
 
 文件映射系统维护了一个MAP映射表，支持本地文件和网络资源两种存储，web应用要根据需求选择使用哪种
 
@@ -332,7 +371,7 @@ if (!photo?.cancelled) {
 // 查询（查看是否存在）
 const cached = await bridge.fileStorage.getLocalFileByUrl('local://avatar/123');
 
-// 拿到base64（真正供web使用）
+// 拿到base64
 const base64 = await bridge.fileStorage.readAsBase64('local://avatar/123');
 // 在 Web 中渲染
 <img src={`data:image/jpeg;base64,${base64}`} />
@@ -349,7 +388,7 @@ console.log(result.cached ? '使用缓存' : '已下载', result.uri);
 const base64 = await bridge.fileStorage.readAsBase64(url);
 ```
 
-**读取资源并解码base64，从native传入web**
+**读取资源并解码base64，从app应用传入web应用**
 ```
 // uri为mapRecord记录值
 const base64 = await bridge.fileStorage.readAsBase64(mapRecord);

package/dist/index.d.mts

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -419,6 +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;
+  }
+  /**
+   * 保存图片/视频到系统相册
+   * 自动解析 URI：支持 file:// 真实路径、local:// 虚拟映射键、http(s):// 缓存 URL
+   * @param uri 文件 URI（支持 file://、local:// 或 http(s):// 路径）
+   * @param albumName 相册名称（默认 'Riffle'）
+   */
+  async saveToGallery(uri, albumName = "Riffle") {
+    const resolvedUri = await this.resolveUri(uri);
+    return this.core.send("fileStorage", "saveToGallery", {
+      saveUri: resolvedUri,
+      albumName
+    });
+  }
 };
 var AudioController = class {
   constructor(core, fileStorage) {

package/dist/index.mjs

@@ -377,6 +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;
+  }
+  /**
+   * 保存图片/视频到系统相册
+   * 自动解析 URI：支持 file:// 真实路径、local:// 虚拟映射键、http(s):// 缓存 URL
+   * @param uri 文件 URI（支持 file://、local:// 或 http(s):// 路径）
+   * @param albumName 相册名称（默认 'Riffle'）
+   */
+  async saveToGallery(uri, albumName = "Riffle") {
+    const resolvedUri = await this.resolveUri(uri);
+    return this.core.send("fileStorage", "saveToGallery", {
+      saveUri: resolvedUri,
+      albumName
+    });
+  }
 };
 var AudioController = class {
   constructor(core, fileStorage) {

package/package.json

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

package/src/controllers/index.ts

@@ -301,6 +301,65 @@ export class FileStorageController {
   async readAsBase64(uriOrKey: string): Promise<Base64Result> {
     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;
+  }
+
+  /**
+   * 保存图片/视频到系统相册
+   * 自动解析 URI：支持 file:// 真实路径、local:// 虚拟映射键、http(s):// 缓存 URL
+   * @param uri 文件 URI（支持 file://、local:// 或 http(s):// 路径）
+   * @param albumName 相册名称（默认 'Riffle'）
+   */
+  async saveToGallery(uri: string, albumName = 'Riffle'): Promise<{
+    success: boolean;
+    assetId?: string;
+    uri?: string;
+    filename?: string;
+    mediaType?: string;
+    width?: number;
+    height?: number;
+    duration?: number;
+  }> {
+    // 先解析为实际的 file:// 路径
+    const resolvedUri = await this.resolveUri(uri);
+    
+    return this.core.send('fileStorage', 'saveToGallery', {
+      saveUri: resolvedUri,
+      albumName,
+    });
+  }
 }
 
 // ============================================