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

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';
@@ -112,7 +112,7 @@ await bridge.haptic.intensity(0.5);
 - **y轴**：正值指向设备顶部
 - **z轴**：正值指向屏幕外（朝向用户）
 
-> iOS 和 Android 原始坐标系不同，Bridge 已在 Native 层自动处理，WebView 端收到的数据保持一致。
+> iOS 和 Android 原始坐标系不同，Bridge 已在 app应用 层自动处理，WebView 端收到的数据保持一致。
 
 ```typescript
 // 启动传感器
@@ -160,14 +160,14 @@ const tilt = bridge.utils.getTiltDirection(x, y);
 ```
 
 ### 3.3 音频模块（录音、播放）
-> 特别注意拿到的uri文件资源是webview外的native文件路径，当前webview无法直接播放音频，请参考录音模块代码，先调用readAsBase64转码再播放！
+> 特别注意拿到的uri文件资源是app应用文件路径，当前web应用无法直接播放音频，请参考录音模块代码，先调用readAsBase64转码再播放！
 
 **播放模块：**
 
 单例模式实现，主要用于不需要用户交互就直接播放的背景音乐等，点击音效等仍由web应用本身实现
 
 ```
-// 播放，支持传入 local://xxx 或 file://xxx 的本地路径，或 https://xxx 的url网址
+// 播放，支持传入 local://xxx 或 file://xxx 的app应用本地路径，或 https://xxx 的url网址
 await bridge.audio.playOnline({ uri: playUri });
 
 // 播放并循环（适用于背景音乐）
@@ -208,13 +208,14 @@ console.log('时长:', result.durationMillis / 1000, '秒');
 
 // 保存录音（以aydens-voice为例，实际可以替换为web应用的独特键，或者result.uri的独特文件名）
 if (result?.uri) {
+  // 保存文件到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();
@@ -226,7 +227,7 @@ audio.play();
 
 ### 3.4 相机模块（实时相机、拍照、相册、闪光灯）
 
->> 特别注意拿到的uri文件资源是webview外的native文件路径，当前webview无法直接渲染，请参考下方**拍照/相册**的代码，先调用readAsBase64转码再渲染！
+>> 特别注意拿到的uri文件资源是app应用件路径，当前web应用无法直接渲染，请参考下方**拍照/相册**的代码，先调用readAsBase64转码再渲染！
 
 **实时相机**
 
@@ -241,7 +242,9 @@ document.body.style.background = 'transparent';
 document.documentElement.style.background = 'transparent';
 document.getElementById('root')!.style.background = 'transparent';
 
-// 拍照 ⚠️ 拍照后不要直接渲染，参考下方**拍照/相册**的代码，先调用readAsBase64转码再渲染！
+// 拍照 
+// ⚠️ 拍照后不要直接渲染，参考下方**拍照/相册**的代码，先调用readAsBase64转码再渲染！
+// ⚠️ 拍照后如果需要保存，也参考下方**拍照/相册**的代码调用app应用的文件存储模块保存并记录map
 const photo = await bridge.camera.takePhoto();
 
 // 切换摄像头
@@ -289,13 +292,14 @@ await bridge.camera.setFilter('none');
 // 1. 拍照（以aydens-demo-photo为例，实际web应用使用picked.uri文件名或组特的key）
 const photo = await bridge.fileStorage.takePhoto();
 if (!photo?.cancelled) {
-  // photo.uri 是沙箱内的本地路径
+  // 保存文件到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) {
+  // 保存文件到app应用并记录map
   await bridge.fileStorage.addCustomFileMapping('local://photos/aydens-demo-photo', picked.uri);
 }
 
@@ -305,6 +309,43 @@ const base64 = await bridge.fileStorage.readAsBase64('local://photos/aydens-demo
 <img src={`data:image/jpeg;base64,${base64}`} />
 ```
 
+**保存到系统相册**
+
+将图片或视频保存到用户的系统相册（会请求系统相册写入权限）
+
+```
+// 拍照后保存到系统相册
+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相册');
+}
+
+// 也可以保存已缓存的文件到系统相册
+const cached = await bridge.fileStorage.getLocalFileByUrl('local://photos/aydens-demo-photo');
+if (cached?.exists && cached.uri) {
+  await bridge.fileStorage.saveToGallery(cached.uri);
+}
+```
+
+返回值类型：
+```typescript
+interface SaveToGalleryResult {
+  success: boolean;      // 是否成功
+  assetId?: string;      // 系统相册资产ID
+  uri?: string;          // 保存后的URI
+  filename?: string;     // 文件名
+  mediaType?: string;    // 媒体类型 'photo' | 'video'
+  width?: number;        // 图片宽度
+  height?: number;       // 图片高度
+  duration?: number;     // 视频时长（秒）
+}
+```
+
 **闪光灯**
 
 闪光灯必须打开实时相机才能调用，参考实时相机的说明。
@@ -312,7 +353,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应用要根据需求选择使用哪种
 
@@ -328,7 +369,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}`} />
@@ -345,6 +386,11 @@ console.log(result.cached ? '使用缓存' : '已下载', result.uri);
 const base64 = await bridge.fileStorage.readAsBase64(url);
 ```
 
+**读取资源并解码base64，从app应用传入web应用**
+```
+// uri为mapRecord记录值
+const base64 = await bridge.fileStorage.readAsBase64(mapRecord);
+```
 
 
 ### 3.6 设备信息模块

package/dist/index.d.mts

@@ -405,6 +405,21 @@ declare class FileStorageController {
         added: boolean;
     }>;
     readAsBase64(uriOrKey: string): Promise<Base64Result>;
+    /**
+     * 保存图片/视频到系统相册
+     * @param uri 文件 URI（支持 file:// 或 local:// 路径）
+     * @param albumName 相册名称（默认 'AIGames'）
+     */
+    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,21 @@ declare class FileStorageController {
         added: boolean;
     }>;
     readAsBase64(uriOrKey: string): Promise<Base64Result>;
+    /**
+     * 保存图片/视频到系统相册
+     * @param uri 文件 URI（支持 file:// 或 local:// 路径）
+     * @param albumName 相册名称（默认 'AIGames'）
+     */
+    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,17 @@ var FileStorageController = class {
   async readAsBase64(uriOrKey) {
     return this.core.send("fileStorage", "readAsBase64", { uriOrKey });
   }
+  /**
+   * 保存图片/视频到系统相册
+   * @param uri 文件 URI（支持 file:// 或 local:// 路径）
+   * @param albumName 相册名称（默认 'AIGames'）
+   */
+  async saveToGallery(uri, albumName = "Riffle") {
+    return this.core.send("fileStorage", "saveToGallery", {
+      saveUri: uri,
+      albumName
+    });
+  }
 };
 var AudioController = class {
   constructor(core, fileStorage) {

package/dist/index.mjs

@@ -377,6 +377,17 @@ var FileStorageController = class {
   async readAsBase64(uriOrKey) {
     return this.core.send("fileStorage", "readAsBase64", { uriOrKey });
   }
+  /**
+   * 保存图片/视频到系统相册
+   * @param uri 文件 URI（支持 file:// 或 local:// 路径）
+   * @param albumName 相册名称（默认 'AIGames'）
+   */
+  async saveToGallery(uri, albumName = "Riffle") {
+    return this.core.send("fileStorage", "saveToGallery", {
+      saveUri: uri,
+      albumName
+    });
+  }
 };
 var AudioController = class {
   constructor(core, fileStorage) {

package/package.json

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

package/src/controllers/index.ts

@@ -301,6 +301,27 @@ export class FileStorageController {
   async readAsBase64(uriOrKey: string): Promise<Base64Result> {
     return this.core.send<Base64Result>('fileStorage', 'readAsBase64', { uriOrKey });
   }
+
+  /**
+   * 保存图片/视频到系统相册
+   * @param uri 文件 URI（支持 file:// 或 local:// 路径）
+   * @param albumName 相册名称（默认 'AIGames'）
+   */
+  async saveToGallery(uri: string, albumName = 'Riffle'): Promise<{
+    success: boolean;
+    assetId?: string;
+    uri?: string;
+    filename?: string;
+    mediaType?: string;
+    width?: number;
+    height?: number;
+    duration?: number;
+  }> {
+    return this.core.send('fileStorage', 'saveToGallery', {
+      saveUri: uri,
+      albumName,
+    });
+  }
 }
 
 // ============================================