@ayden-fc2/riffle-bridge-web 1.0.0

package/README.md

@@ -0,0 +1,264 @@
+# @ayden-fc2/riffle-bridge-web
+
+Riffle Bridge Web SDK - WebView 与 React Native 通信桥接库
+
+## 安装
+
+```bash
+npm install @ayden-fc2/riffle-bridge-web
+# 或
+pnpm add @ayden-fc2/riffle-bridge-web
+```
+
+## 快速开始
+
+### 基础使用
+
+```typescript
+import { RiffleBridge } from '@ayden-fc2/riffle-bridge-web';
+
+const bridge = new RiffleBridge();
+
+// 直接使用（如果不在 RN WebView 中会抛出错误）
+await bridge.vibrate('success');
+
+const deviceInfo = await bridge.device.getDeviceInfo();
+console.log(deviceInfo);
+```
+
+### Tweaks 配置系统
+
+```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 },
+};
+
+function App() {
+  // 初始化（必须传入 React）
+  const tweaks = useMemo(() => createTweaks(tweaksConfig, { React }), []);
+  
+  // 响应式获取值
+  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>
+  );
+}
+```
+
+### 错误处理
+
+如果不在 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
+
+主类，提供所有 Native 功能访问。
+
+```typescript
+const bridge = new RiffleBridge();
+
+// 检测
+bridge.isAvailable()           // 是否在 RN WebView 中
+bridge.waitForReady(timeout)   // 等待 Bridge 就绪
+bridge.getVersion()            // SDK 版本
+
+// 便捷方法
+bridge.vibrate(type)           // 震动
+```
+
+### 震动模块 (bridge.haptic)
+
+```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)
+
+```typescript
+// 启动
+await bridge.sensor.start({
+  types: ['accelerometer', 'gyroscope'],
+  interval: 100
+});
+
+// 监听
+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) => { /* ... */ });
+
+// 停止
+await bridge.sensor.stop();
+```
+
+### 设备信息模块 (bridge.device)
+
+```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();
+```
+
+### 文件存储模块 (bridge.fileStorage)
+
+```typescript
+// 初始化
+await bridge.fileStorage.init();
+
+// 拍照/相册
+const photo = await bridge.fileStorage.takePhoto();
+const picked = await bridge.fileStorage.pickFromGallery();
+
+// 文件操作
+const files = await bridge.fileStorage.listFiles('images');
+await bridge.fileStorage.deleteFile(filename, subfolder);
+
+// URL 映射
+await bridge.fileStorage.addCustomFileMapping('local://avatar', uri);
+const cached = await bridge.fileStorage.getLocalFileByUrl('local://avatar');
+
+// 智能下载（自动缓存）
+const result = await bridge.fileStorage.downloadWithCache(url);
+
+// 读取为 Base64
+const base64 = await bridge.fileStorage.readAsBase64(uriOrKey);
+```
+
+### 音频模块 (bridge.audio)
+
+```typescript
+// 播放（智能 URI 解析）
+await bridge.audio.playOnline({ uri: 'https://example.com/audio.mp3' });
+await bridge.audio.playOnline({ uri: 'local://recording/memo' });
+
+// 控制
+await bridge.audio.pause();
+await bridge.audio.resume();
+await bridge.audio.stop();
+await bridge.audio.setVolume(0.5);
+await bridge.audio.setRate(1.5);
+```
+
+### 相机模块 (bridge.camera)
+
+```typescript
+// 打开相机
+await bridge.camera.open({ facing: 'back' });
+
+// 设置透明背景
+document.body.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.close();
+```
+
+### 麦克风模块 (bridge.microphone)
+
+```typescript
+// 请求权限
+const perm = await bridge.microphone.requestPermission();
+
+// 录音
+await bridge.microphone.start({ enableMonitoring: true });
+
+// 监听音量
+bridge.microphone.onVolumeData((data) => {
+  console.log('音量:', data[0].normalizedVolume);
+});
+
+// 停止
+const result = await bridge.microphone.stop();
+console.log('URI:', result.uri);
+```
+
+### 工具函数 (bridge.utils)
+
+```typescript
+// 向量模长
+const mag = bridge.utils.magnitude(x, y, z);
+
+// 倾斜方向
+const tilt = bridge.utils.getTiltDirection(x, y);
+// => 'forward' | 'backward' | 'left' | 'right' | 'center'
+
+// 摇晃强度
+const shake = bridge.utils.getShakeIntensity(x, y, z);
+// => 'none' | 'light' | 'medium' | 'strong'
+```
+
+## 类型定义
+
+完整的 TypeScript 类型支持，无需额外安装 @types 包。
+
+```typescript
+import type {
+  HapticFeedbackType,
+  SensorData,
+  DeviceInfo,
+  TweakConfig,
+  // ... 更多类型
+} from '@ayden-fc2/riffle-bridge-web';
+```
+
+## 与 Native 端配合
+
+此包需要配合 React Native 端的 `RiffleBridge` 和 `GamePlayer` 组件使用。
+
+Native 端需要在 WebView 中注入精简版通信脚本，详见项目文档。
+
+## License
+
+MIT