@ayden-fc2/riffle-bridge-web 1.0.1 → 1.0.2

package/README.md

@@ -1,264 +1,483 @@
-# @ayden-fc2/riffle-bridge-web
+# Riffle Bridge API
 
-Riffle Bridge Web SDK - WebView 与 React Native 通信桥接库
+## 1. tweaks和RiffleBridge用法总览
 
-## 安装
+本文档为Web应用提供Bridge使用指导，以连接外层native应用。分为必选的tweaks和可选的RiffleBridge两个API。
 
+**安装依赖：**
 ```bash
 npm install @ayden-fc2/riffle-bridge-web
-# 或
-pnpm add @ayden-fc2/riffle-bridge-web
 ```
 
-## 快速开始
+tweaks用于联通web应用与native的自定义参数，传递支持颜色、数值、文本、布尔、选项类型的JsonSchema格式的tweaksConfig，原则上web应用内的颜色、数值、文本、布尔、选项都要通过tweaks层配置，从而保证native能够响应式控制，使用参考文章第二节。
 
-### 基础使用
+RiffleBridge用于调用震动、音频、相机等模块的native功能，展开对应文章第三节各个模块，根据所需要实现的web应用功能，按需参考模块取用即可；
 
-```typescript
-import { RiffleBridge } from '@ayden-fc2/riffle-bridge-web';
+## 2. tweaks 用法
 
-const bridge = new RiffleBridge();
+使用 `createTweaks` 创建配置实例，使用步骤如下：
 
-// 直接使用（如果不在 RN WebView 中会抛出错误）
-await bridge.vibrate('success');
+### 2.1 定义配置
+
+抽离出web应用中颜色、数值、文本、布尔、选项类型的参数，使用JsonSchema格式组织，示例如下：
 
-const deviceInfo = await bridge.device.getDeviceInfo();
-console.log(deviceInfo);
 ```
+const tweaksConfig = {
+  // 颜色类型 - Native 端显示颜色选择器
+  color: { name: '颜色', type: 'color', value: '#667eea' },
+  
+  // 数值类型 - Native 端显示滑块
+  size:  { name: '大小', type: 'number', value: 150, min: 50, max: 300 },
+  opacity: { name: '透明度', type: 'number', value: 1, min: 0, max: 1, step: 0.1 },
+  
+  // 文本类型 - Native 端显示文本输入框
+  title: { name: '标题', type: 'string', value: 'Hello World' },
+  
+  // 布尔类型 - Native 端显示开关
+  enabled: { name: '启用', type: 'boolean', value: true },
+  
+  // 选项类型 - Native 端显示下拉选择器
+  mode: { name: '模式', type: 'select', value: 'normal', options: ['normal', 'fast', 'slow'] },
+  vibration: { name: '震动', type: 'select', value: 'medium', options: [
+    { label: '轻', value: 'light' },
+    { label: '中', value: 'medium' },
+    { label: '重', value: 'heavy' },
+  ]},
+};
+```
+
+### 2.2 初始化（必须传入React实例）
 
-### Tweaks 配置系统
+通过 { React } 参数显式传入初始化，保证web和native内外层数据联通，响应式更新，初始化代码如下：
 
-```tsx
+```
 import React, { useMemo } from 'react';
 import { createTweaks } from '@ayden-fc2/riffle-bridge-web';
 
-// 定义配置
-const tweaksConfig = {
-  color: { name: '颜色', type: 'color' as const, value: '#667eea' },
-  size: { name: '大小', type: 'number' as const, value: 150, min: 50, max: 300 },
-  enabled: { name: '启用', type: 'boolean' as const, value: true },
-};
+// 传入 React 以启用 useSyncExternalStore 响应式订阅
+const tweaks = useMemo(() => createTweaks(tweaksConfig, { React }), []);
+```
 
-function App() {
-  // 初始化（必须传入 React）
-  const tweaks = useMemo(() => createTweaks(tweaksConfig, { React }), []);
-  
-  // 响应式获取值
+### 2.3 在组件中使用
+
+使用 ${初始化的tweaks实例}.${tweaksConfig参数}.useState()，示例代码如下：
+
+```
+function Demo() {
+  // .useState() 自动响应式订阅，Native 修改时自动重渲染
   const color = tweaks.color.useState();
   const size = tweaks.size.useState();
-  const enabled = tweaks.enabled.useState();
-  
-  if (!enabled) return null;
   
-  return (
-    <div style={{ backgroundColor: color, width: size, height: size }}>
-      Hello Tweaks!
-    </div>
-  );
+  return <div style={{ backgroundColor: color, width: size, height: size }} />;
 }
 ```
 
-### 错误处理
-
-如果不在 React Native WebView 环境中运行，SDK 会抛出明确的错误：
-
-```typescript
-try {
-  await bridge.vibrate('success');
-} catch (error) {
-  // [RiffleBridge] Not available. This SDK requires React Native WebView environment.
-  console.error(error.message);
-}
-```
 
-## API 文档
 
-### RiffleBridge
+## 3. RiffleBridge用法
 
-主类，提供所有 Native 功能访问。
+通过 `RiffleBridge` 类调用 native 功能：
 
-```typescript
+```
+import { RiffleBridge } from '@ayden-fc2/riffle-bridge-web';
 const bridge = new RiffleBridge();
+```
+
+针对RiffleBridge，分为震动模块、传感器模块、音频模块、相机模块、麦克风模块、文件存储模块、设备信息模块，各自的使用方法与注意事项已经分别说明，根据web应用所需模块，按需阅读使用即可。
 
-// 检测
-bridge.isAvailable()           // 是否在 RN WebView 中
-bridge.waitForReady(timeout)   // 等待 Bridge 就绪
-bridge.getVersion()            // SDK 版本
+### 3.1 震动模块
 
-// 便捷方法
-bridge.vibrate(type)           // 震动
+```
+// 7种震动类型
+await bridge.vibrate('light');      // 普通-轻触
+await bridge.vibrate('medium');     // 普通-中等
+await bridge.vibrate('heavy');      // 普通-重
+await bridge.vibrate('selection');  // 选择
+await bridge.vibrate('success');    // 成功 ✓
+await bridge.vibrate('warning');    // 警告 ⚠
+await bridge.vibrate('error');      // 错误 ✗
+
+// 震动序列（依次播放，间隔300ms）
+await bridge.haptic.sequence(['light', 'medium', 'heavy'], 300);
+
+// 按强度震动（0-1，自动映射到 light/medium/heavy）
+await bridge.haptic.intensity(0.5);
 ```
 
-### 震动模块 (bridge.haptic)
+### 3.2 传感器模块
 
-```typescript
-await bridge.haptic.light();
-await bridge.haptic.medium();
-await bridge.haptic.heavy();
-await bridge.haptic.success();
-await bridge.haptic.warning();
-await bridge.haptic.error();
-await bridge.haptic.selection();
-
-// 序列震动
-await bridge.haptic.sequence(['light', 'medium', 'heavy'], 200);
-
-// 根据强度震动
-await bridge.haptic.intensity(0.5); // 0-1
-```
+**坐标系约定（已跨平台统一）：**
 
-### 传感器模块 (bridge.sensor)
+- **x轴**：正值指向设备右侧
+- **y轴**：正值指向设备顶部
+- **z轴**：正值指向屏幕外（朝向用户）
+
+> iOS 和 Android 原始坐标系不同，Bridge 已在 Native 层自动处理，WebView 端收到的数据保持一致。
 
 ```typescript
-// 启动
+// 启动传感器
 await bridge.sensor.start({
-  types: ['accelerometer', 'gyroscope'],
-  interval: 100
+  types: ['accelerometer', 'gyroscope', 'magnetometer', 'barometer'],
+  interval: 100  // 更新间隔 ms
 });
 
-// 监听
+// 监听数据（回调参数是数组，取最后一个为最新值）
 bridge.sensor.onAccelerometer((data) => {
   const { x, y, z } = data[data.length - 1];
   console.log('加速度:', x, y, z);
 });
 
-bridge.sensor.onGyroscope((data) => { /* ... */ });
-bridge.sensor.onMagnetometer((data) => { /* ... */ });
-bridge.sensor.onBarometer((data) => { /* ... */ });
+bridge.sensor.onGyroscope((data) => {
+  const { x, y, z } = data[data.length - 1];
+  console.log('陀蝗仪:', x, y, z);
+});
 
-// 停止
-await bridge.sensor.stop();
-```
+bridge.sensor.onMagnetometer((data) => {
+  const { x, y, z } = data[data.length - 1];
+  console.log('磁力计:', x, y, z);
+});
 
-### 设备信息模块 (bridge.device)
+bridge.sensor.onBarometer((data) => {
+  const { pressure, relativeAltitude } = data[data.length - 1];
+  console.log('气压:', pressure, 'hPa');
+});
 
-```typescript
-const device = await bridge.device.getDeviceInfo();
-const battery = await bridge.device.getBatteryInfo();
-const network = await bridge.device.getNetworkInfo();
-const system = await bridge.device.getSystemInfo();
-const app = await bridge.device.getAppInfo();
-const screen = await bridge.device.getScreenInfo();
-const all = await bridge.device.getAllInfo();
+// 停止传感器
+await bridge.sensor.stop();
 ```
 
-### 文件存储模块 (bridge.fileStorage)
+**工具函数：**
 
 ```typescript
-// 初始化
-await bridge.fileStorage.init();
+// 计算向量模长
+const mag = bridge.utils.magnitude(x, y, z);
 
-// 拍照/相册
-const photo = await bridge.fileStorage.takePhoto();
-const picked = await bridge.fileStorage.pickFromGallery();
+// 摇晃强度 → 'none' | 'light' | 'medium' | 'strong'
+const shake = bridge.utils.getShakeIntensity(x, y, z);
 
-// 文件操作
-const files = await bridge.fileStorage.listFiles('images');
-await bridge.fileStorage.deleteFile(filename, subfolder);
+// 倾斜方向 → 'forward' | 'backward' | 'left' | 'right' | 'center'
+const tilt = bridge.utils.getTiltDirection(x, y);
+```
 
-// URL 映射
-await bridge.fileStorage.addCustomFileMapping('local://avatar', uri);
-const cached = await bridge.fileStorage.getLocalFileByUrl('local://avatar');
+### 3.3 音频模块（录音、播放）
 
-// 智能下载（自动缓存）
-const result = await bridge.fileStorage.downloadWithCache(url);
+**播放模块：**
+
+单例模式实现，主要用于不需要用户交互就直接播放的背景音乐等，点击音效等仍由web应用本身实现
 
-// 读取为 Base64
-const base64 = await bridge.fileStorage.readAsBase64(uriOrKey);
 ```
+// 播放，支持传入 local://xxx 或 file://xxx 的本地路径，或 https://xxx 的url网址
+await bridge.audio.playOnline({ uri: playUri });
 
-### 音频模块 (bridge.audio)
+// 播放并循环（适用于背景音乐）
+await bridge.audio.playOnline({ uri: playUri, isLooping: true });
 
-```typescript
-// 播放（智能 URI 解析）
-await bridge.audio.playOnline({ uri: 'https://example.com/audio.mp3' });
-await bridge.audio.playOnline({ uri: 'local://recording/memo' });
-
-// 控制
+// 调用playOnline后调整播放状态，音量，速度等
 await bridge.audio.pause();
 await bridge.audio.resume();
 await bridge.audio.stop();
-await bridge.audio.setVolume(0.5);
-await bridge.audio.setRate(1.5);
+await bridge.audio.setVolume(0.5);  // 0-1
+await bridge.audio.setRate(1.5);   // 0.5-2.0
+await bridge.audio.setLooping(true);  // 动态开启/关闭循环
 ```
 
-### 相机模块 (bridge.camera)
+**录音模块：**
 
-```typescript
+```
+// 请求麦克风权限
+const perm = await bridge.microphone.requestPermission();
+if (!perm.granted) return;
+
+// 开始录音
+await bridge.microphone.start({ enableMonitoring: true });
+
+// 监听音量
+bridge.microphone.onVolumeData((data) => {
+  const vol = Array.isArray(data) ? data[0] : data;
+  console.log('音量:', vol.normalizedVolume);  // 0-1
+});
+
+// 暂停 / 恢复
+await bridge.microphone.pause();
+await bridge.microphone.resume();
+
+// 停止录音
+const result = await bridge.microphone.stop();
+console.log('时长:', result.durationMillis / 1000, '秒');
+
+// 保存录音（以aydens-voice为例，实际可以替换为web应用的独特键，或者result.uri的独特文件名）
+if (result?.uri) {
+  await bridge.fileStorage.addCustomFileMapping('local://recording/aydens-voice', result.uri);
+}
+
+// 后续直接播放
+await bridge.audio.playOnline({ uri: 'local://recording/aydens-voice' });
+```
+
+### 3.4 相机模块（实时相机、拍照、相册、闪光灯）
+
+**实时相机**
+
+相机采用「透明 WebView + 原生相机层」实现，**打开相机时必须设置web应用背景透明**。
+
+```
 // 打开相机
-await bridge.camera.open({ facing: 'back' });
+await bridge.camera.open({ facing: 'back' });  // 或 'front'
 
-// 设置透明背景
+// ⚠️ 设置透明背景
 document.body.style.background = 'transparent';
+document.documentElement.style.background = 'transparent';
+document.getElementById('root')!.style.background = 'transparent';
 
 // 拍照
 const photo = await bridge.camera.takePhoto();
 
-// 切换
+// 切换摄像头
 await bridge.camera.toggleFacing();
-await bridge.camera.toggleFlash();
 
-// 滤镜
-await bridge.camera.setFilter('grayscale');
+// 闪光灯控制
+await bridge.camera.setFlash(true);   // 开启闪光灯
+await bridge.camera.setFlash(false);  // 关闭闪光灯
+const result = await bridge.camera.toggleFlash(); // 切换闪光灯
+console.log('闪光灯状态:', result.flash); // true | false
 
-// 关闭
+// 关闭相机（恢复背景）
 await bridge.camera.close();
+document.body.style.background = '';
 ```
 
-### 麦克风模块 (bridge.microphone)
+**实时相机滤镜**
 
-```typescript
-// 请求权限
-const perm = await bridge.microphone.requestPermission();
+注意：滤镜是通过覆盖在相机层上的 View 实现，支持 RN 样式属性（`backgroundColor`、`opacity` 等），不支持 CSS `filter` 属性。、
 
-// 录音
-await bridge.microphone.start({ enableMonitoring: true });
+```
+// 预设滤镜
+await bridge.camera.setFilter('grayscale');  // 'sepia' | 'invert' | 'none'
 
-// 监听音量
-bridge.microphone.onVolumeData((data) => {
-  console.log('音量:', data[0].normalizedVolume);
+// 自定义样式（React Native View 样式对象）
+await bridge.camera.setFilter({
+  backgroundColor: 'rgba(255, 0, 0, 0.3)',  // 红色蒙版
+  opacity: 0.8
 });
 
-// 停止
-const result = await bridge.microphone.stop();
-console.log('URI:', result.uri);
+// 渐变蒙版效果
+await bridge.camera.setFilter({
+  backgroundColor: 'rgba(0, 0, 0, 0.5)',
+});
+
+// 关闭滤镜
+await bridge.camera.setFilter('none');
 ```
 
-### 工具函数 (bridge.utils)
+**拍照/相册**
 
-```typescript
-// 向量模长
-const mag = bridge.utils.magnitude(x, y, z);
+不打开实时相机时，拍照/从相册选择图片
 
-// 倾斜方向
-const tilt = bridge.utils.getTiltDirection(x, y);
-// => 'forward' | 'backward' | 'left' | 'right' | 'center'
+```
+// 1. 拍照（以aydens-demo-photo为例，实际web应用使用picked.uri文件名或组特的key）
+const photo = await bridge.fileStorage.takePhoto();
+if (!photo?.cancelled) {
+  // photo.uri 是沙箱内的本地路径
+  await bridge.fileStorage.addCustomFileMapping('local://photos/aydens-demo-photo', photo.uri);
+}
 
-// 摇晃强度
-const shake = bridge.utils.getShakeIntensity(x, y, z);
-// => 'none' | 'light' | 'medium' | 'strong'
+// 2. 或从相册选择（以aydens-photo为例，实际web应用使用picked.uri文件名或组特的key）
+const picked = await bridge.fileStorage.pickFromGallery();
+if (!picked?.cancelled) {
+  await bridge.fileStorage.addCustomFileMapping('local://photos/aydens-demo-photo', picked.uri);
+}
+
+// web应用中拿到图片文件并渲染
+const base64 = await bridge.fileStorage.readAsBase64('local://photos/aydens-demo-photo');
+// 在 Web 中渲染
+<img src={`data:image/jpeg;base64,${base64}`} />
 ```
 
-## 类型定义
+**闪光灯**
 
-完整的 TypeScript 类型支持，无需额外安装 @types 包。
+闪光灯必须打开实时相机才能调用，参考实时相机的说明。
 
-```typescript
-import type {
-  HapticFeedbackType,
-  SensorData,
-  DeviceInfo,
-  TweakConfig,
-  // ... 更多类型
-} from '@ayden-fc2/riffle-bridge-web';
+当应用需要闪光灯而不要实时相机时，可以使用非透明web应用背景来遮挡实时相机
+
+### 3.5 文件存储模块
+
+文件映射系统维护了一个MAP映射表，支持本地文件和网络资源两种存储，web应用要根据需求选择使用哪种
+
+**本地文件（手动管理Map映射，以avatar/123为例）**
+
+```
+// 本地文件添加
+const photo = await bridge.fileStorage.takePhoto();
+if (!photo?.cancelled) {
+  await bridge.fileStorage.addCustomFileMapping('local://avatar/123', photo.uri);
+}
+
+// 查询（查看是否存在）
+const cached = await bridge.fileStorage.getLocalFileByUrl('local://avatar/123');
+
+// 拿到base64（真正供web使用）
+const base64 = await bridge.fileStorage.readAsBase64('local://avatar/123');
+// 在 Web 中渲染
+<img src={`data:image/jpeg;base64,${base64}`} />
+```
+
+**网络资源（利用Map自动管理缓存，避免重复下载）**
+
+```
+// 智能下载（命中缓存直接返回）
+const result = await bridge.fileStorage.downloadWithCache(url);
+console.log(result.cached ? '使用缓存' : '已下载', result.uri);
+
+// 拿到base64
+const base64 = await bridge.fileStorage.readAsBase64(url);
+```
+
+
+
+### 3.6 设备信息模块
+
+拿到json信息，内部内容不保证，因此谨慎处理获取到的信息的格式
+
+```
+const device = await bridge.device.getDeviceInfo();   // 设备型号
+const battery = await bridge.device.getBatteryInfo(); // 电池状态
+const network = await bridge.device.getNetworkInfo(); // 网络类型
+const system = await bridge.device.getSystemInfo();   // 系统版本
+const app = await bridge.device.getAppInfo();         // 应用信息
+const screen = await bridge.device.getScreenInfo();   // 屏幕尺寸
+const all = await bridge.device.getAllInfo();         // 全部信息
 ```
 
-## 与 Native 端配合
+## 4. 主要类型定义
 
-此包需要配合 React Native 端的 `RiffleBridge` 和 `GamePlayer` 组件使用。
+```typescript
+// 基础类型
+type HapticFeedbackType = 'light' | 'medium' | 'heavy' | 'selection' | 'success' | 'warning' | 'error';
+type SensorType = 'accelerometer' | 'gyroscope' | 'magnetometer' | 'barometer';
+type CameraFacing = 'front' | 'back';
+type CameraFilter = 'none' | 'grayscale' | 'sepia' | 'invert' | Record<string, unknown>;
+
+// 传感器数据
+interface SensorData {
+  x: number;
+  y: number;
+  z: number;
+  timestamp?: number;
+}
 
-Native 端需要在 WebView 中注入精简版通信脚本，详见项目文档。
+interface BarometerData {
+  pressure: number;
+  relativeAltitude?: number;
+  timestamp?: number;
+}
+
+// 音频相关
+interface VolumeData {
+  metering: number;
+  normalizedVolume: number;
+  durationMillis: number;
+  timestamp?: number;
+}
 
-## License
+interface AudioStatus {
+  isLoaded: boolean;
+  isPlaying: boolean;
+  isLooping?: boolean;
+  volume: number;
+  rate: number;
+  durationMillis?: number;
+  positionMillis?: number;
+}
+
+interface RecordingResult {
+  isRecording: boolean;
+  isDoneRecording?: boolean;
+  durationMillis?: number;
+  canRecord: boolean;
+  isPaused?: boolean;
+  uri?: string;
+}
+
+// 文件存储相关
+interface UrlMapping {
+  url: string;
+  localUri: string;
+  size?: number;
+  sizeFormatted?: string;
+  createdAt?: number;
+}
+
+interface CachedFileInfo {
+  exists: boolean;
+  uri?: string;
+  size?: number;
+  sizeFormatted?: string;
+}
+
+interface DownloadResult {
+  cached: boolean;
+  uri: string;
+  size?: number;
+  sizeFormatted?: string;
+}
+
+interface PhotoResult {
+  cancelled: boolean;
+  filename?: string;
+  uri?: string;
+  size?: number;
+  sizeFormatted?: string;
+  width?: number;
+  height?: number;
+  facing?: CameraFacing;
+}
+
+// 权限
+interface PermissionResult {
+  granted: boolean;
+  canAskAgain: boolean;
+  status: string;
+}
+
+// Tweaks 配置
+interface TweakConfigBase {
+  name: string;
+  type: 'color' | 'number' | 'boolean' | 'string' | 'select';
+  group?: string;
+  description?: string;
+  index?: number;
+}
+
+interface ColorTweakConfig extends TweakConfigBase {
+  type: 'color';
+  value: string;
+}
+
+interface NumberTweakConfig extends TweakConfigBase {
+  type: 'number';
+  value: number;
+  min?: number;
+  max?: number;
+  step?: number;
+}
+
+interface BooleanTweakConfig extends TweakConfigBase {
+  type: 'boolean';
+  value: boolean;
+}
+
+interface StringTweakConfig extends TweakConfigBase {
+  type: 'string';
+  value: string;
+}
+
+interface SelectTweakConfig extends TweakConfigBase {
+  type: 'select';
+  value: string;
+  options: (string | { label: string; value: string })[];
+}
+
+type TweakConfig = ColorTweakConfig | NumberTweakConfig | BooleanTweakConfig | StringTweakConfig | SelectTweakConfig;
+type TweaksConfig = Record<string, TweakConfig>;
+```
 
-MIT

package/dist/index.d.mts

@@ -86,6 +86,7 @@ interface VolumeData {
 interface AudioStatus {
     isLoaded: boolean;
     isPlaying: boolean;
+    isLooping?: boolean;
     volume: number;
     rate: number;
     durationMillis?: number;
@@ -441,6 +442,12 @@ declare class AudioController {
     setRate(rate: number): Promise<{
         rate: number;
     }>;
+    /**
+     * 设置循环播放
+     */
+    setLooping(isLooping: boolean): Promise<{
+        isLooping: boolean;
+    }>;
     getStatus(): Promise<AudioStatus>;
 }
 declare class CameraController {

package/dist/index.d.ts

@@ -86,6 +86,7 @@ interface VolumeData {
 interface AudioStatus {
     isLoaded: boolean;
     isPlaying: boolean;
+    isLooping?: boolean;
     volume: number;
     rate: number;
     durationMillis?: number;
@@ -441,6 +442,12 @@ declare class AudioController {
     setRate(rate: number): Promise<{
         rate: number;
     }>;
+    /**
+     * 设置循环播放
+     */
+    setLooping(isLooping: boolean): Promise<{
+        isLooping: boolean;
+    }>;
     getStatus(): Promise<AudioStatus>;
 }
 declare class CameraController {

package/dist/index.js

@@ -485,6 +485,12 @@ var AudioController = class {
   async setRate(rate) {
     return this.core.send("audio", "setRate", { rate });
   }
+  /**
+   * 设置循环播放
+   */
+  async setLooping(isLooping) {
+    return this.core.send("audio", "setLooping", { isLooping });
+  }
   async getStatus() {
     return this.core.send("audio", "getStatus");
   }

package/dist/index.mjs

@@ -443,6 +443,12 @@ var AudioController = class {
   async setRate(rate) {
     return this.core.send("audio", "setRate", { rate });
   }
+  /**
+   * 设置循环播放
+   */
+  async setLooping(isLooping) {
+    return this.core.send("audio", "setLooping", { isLooping });
+  }
   async getStatus() {
     return this.core.send("audio", "getStatus");
   }

package/package.json

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

package/src/controllers/index.ts

@@ -399,6 +399,13 @@ export class AudioController {
     return this.core.send('audio', 'setRate', { rate });
   }
 
+  /**
+   * 设置循环播放
+   */
+  async setLooping(isLooping: boolean): Promise<{ isLooping: boolean }> {
+    return this.core.send('audio', 'setLooping', { isLooping });
+  }
+
   async getStatus(): Promise<AudioStatus> {
     return this.core.send<AudioStatus>('audio', 'getStatus');
   }

package/src/types.ts

@@ -70,6 +70,7 @@ export interface VolumeData {
 export interface AudioStatus {
   isLoaded: boolean;
   isPlaying: boolean;
+  isLooping?: boolean;
   volume: number;
   rate: number;
   durationMillis?: number;