@ayden-fc2/riffle-bridge-web 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,719 @@
+import * as react from 'react';
+
+/**
+ * Riffle Bridge 核心通信模块
+ *
+ * 处理 WebView 与 Native 之间的消息收发
+ */
+/**
+ * Bridge 核心类 - 处理消息收发
+ */
+declare class BridgeCore {
+    private messageId;
+    private initialized;
+    private sensorHandlers;
+    constructor();
+    /**
+     * 初始化 Bridge
+     */
+    private init;
+    /**
+     * 检查是否在 React Native WebView 环境中
+     */
+    isAvailable(): boolean;
+    /**
+     * 等待 Bridge 就绪
+     */
+    waitForReady(timeout?: number): Promise<boolean>;
+    /**
+     * 确保在 React Native WebView 环境中运行
+     * @throws Error 如果不在 RN WebView 环境中
+     */
+    private ensureAvailable;
+    /**
+     * 发送消息到 Native
+     * @throws Error 如果不在 RN WebView 环境中
+     */
+    send<T = unknown>(module: string, method: string, params?: Record<string, unknown>): Promise<T>;
+    /**
+     * 处理 Native 响应
+     */
+    private handleResponse;
+    /**
+     * 处理传感器数据
+     */
+    private handleSensorData;
+    /**
+     * 订阅传感器数据
+     */
+    onSensorData(sensor: string, callback: (data: unknown[]) => void): () => void;
+    /**
+     * 清除所有传感器订阅
+     */
+    clearSensorSubscriptions(): void;
+}
+/**
+ * 获取 BridgeCore 单例
+ */
+declare function getBridgeCore(): BridgeCore;
+
+/**
+ * Riffle Bridge Web SDK 类型定义
+ */
+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>;
+type TiltDirection = 'forward' | 'backward' | 'left' | 'right' | 'center';
+type ShakeIntensity = 'none' | 'light' | 'medium' | 'strong';
+interface SensorData {
+    x: number;
+    y: number;
+    z: number;
+    timestamp?: number;
+}
+interface BarometerData {
+    pressure: number;
+    relativeAltitude?: number;
+    timestamp?: number;
+}
+interface VolumeData {
+    metering: number;
+    normalizedVolume: number;
+    durationMillis: number;
+    timestamp?: number;
+}
+interface AudioStatus {
+    isLoaded: boolean;
+    isPlaying: boolean;
+    volume: number;
+    rate: number;
+}
+interface DeviceInfo {
+    brand: string | null;
+    manufacturer: string | null;
+    modelName: string | null;
+    modelId: string | null;
+    designName: string | null;
+    productName: string | null;
+    deviceYearClass: number | null;
+    totalMemory: number | null;
+    supportedCpuArchitectures: string[] | null;
+    deviceType: number | null;
+    isDevice: boolean;
+}
+interface BatteryInfo {
+    level: number;
+    state: number;
+    isLowPowerMode: boolean;
+    lowPowerModeSupported: boolean;
+}
+interface NetworkInfo {
+    isConnected: boolean;
+    isInternetReachable: boolean | null;
+    type: string;
+    ipAddress: string | null;
+    isAirplaneMode: boolean | null;
+}
+interface SystemInfo {
+    osName: string | null;
+    osVersion: string | null;
+    osBuildId: string | null;
+    osInternalBuildId: string | null;
+    platformApiLevel: number | null;
+    platform: string;
+    platformVersion: string | number;
+    expoVersion: string | null;
+    expoRuntimeVersion: string | null;
+    sdkVersion: string | null;
+    appOwnership: string | null;
+    executionEnvironment: string;
+    locale: string;
+    locales: string[];
+    timezone: string;
+    isRTL: boolean;
+    region: string;
+}
+interface AppInfo {
+    appName: string | null;
+    appId: string | null;
+    nativeAppVersion: string | null;
+    nativeBuildVersion: string | null;
+}
+interface ScreenInfo {
+    screenWidth: number;
+    screenHeight: number;
+    pixelRatio: number;
+    fontScale: number;
+}
+interface StorageStats {
+    totalFiles: number;
+    totalSize: number;
+    totalSizeFormatted: string;
+    subfolders: Record<string, {
+        files: number;
+        size: number;
+    }>;
+}
+interface FileInfo {
+    filename: string;
+    uri: string;
+    size: number;
+    sizeFormatted: string;
+    width?: number;
+    height?: number;
+    cancelled?: boolean;
+}
+interface CachedFileInfo {
+    exists: boolean;
+    uri?: string;
+    size?: number;
+    sizeFormatted?: string;
+}
+interface DownloadResult {
+    cached: boolean;
+    uri: string;
+    size?: number;
+    sizeFormatted?: string;
+}
+interface Base64Result {
+    base64: string;
+    mimeType: string;
+    dataUrl: string;
+}
+interface PhotoResult {
+    cancelled: boolean;
+    filename?: string;
+    uri?: string;
+    size?: number;
+    sizeFormatted?: string;
+    width?: number;
+    height?: number;
+    facing?: CameraFacing;
+}
+interface RecordingResult {
+    isRecording: boolean;
+    uri?: string;
+    durationMillis?: number;
+}
+interface PermissionResult {
+    granted: boolean;
+    canAskAgain: boolean;
+    status: string;
+}
+type TweakType = 'color' | 'number' | 'boolean' | 'string' | 'select';
+interface SelectOption {
+    label: string;
+    value: string;
+}
+interface TweakConfigBase {
+    name: string;
+    type: TweakType;
+    group?: string;
+    description?: string;
+}
+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 | SelectOption)[];
+}
+type TweakConfig = ColorTweakConfig | NumberTweakConfig | BooleanTweakConfig | StringTweakConfig | SelectTweakConfig;
+type TweaksConfig = Record<string, TweakConfig>;
+interface BridgeMessage {
+    id: string;
+    module: string;
+    method: string;
+    params: Record<string, unknown>;
+    timestamp: number;
+}
+interface BridgeResponse {
+    id: string;
+    module: string;
+    method: string;
+    success: boolean;
+    error: string | null;
+    data: unknown;
+    timestamp: number;
+}
+declare global {
+    interface Window {
+        ReactNativeWebView?: {
+            postMessage: (message: string) => void;
+        };
+        __RIFFLE_CALLBACKS__?: Map<string, (response: BridgeResponse) => void>;
+        __RIFFLE_READY__?: boolean;
+        __RIFFLE_SENSOR_HANDLERS__?: Map<string, Set<(data: unknown[]) => void>>;
+        handleNativeResponse?: (responseStr: string) => void;
+        handleSensorData?: (data: {
+            sensor: string;
+            values: unknown[];
+        }) => void;
+    }
+}
+
+/**
+ * Riffle Bridge 控制器模块
+ */
+
+declare class HapticController {
+    private core;
+    constructor(core: BridgeCore);
+    light(): Promise<void>;
+    medium(): Promise<void>;
+    heavy(): Promise<void>;
+    success(): Promise<void>;
+    warning(): Promise<void>;
+    error(): Promise<void>;
+    selection(): Promise<void>;
+    /**
+     * 播放震动序列
+     */
+    sequence(types: HapticFeedbackType[], interval?: number): Promise<void>;
+    /**
+     * 根据强度震动
+     */
+    intensity(level: number): Promise<void>;
+}
+interface SensorStartOptions {
+    types?: SensorType[];
+    interval?: number;
+}
+declare class SensorController {
+    private core;
+    private isActive;
+    private activeTypes;
+    constructor(core: BridgeCore);
+    /**
+     * 启动传感器
+     */
+    start(options?: SensorStartOptions): Promise<{
+        started: SensorType[];
+        updateInterval: number;
+    }>;
+    /**
+     * 停止传感器
+     */
+    stop(): Promise<{
+        stopped: boolean;
+    }>;
+    /**
+     * 监听加速度计数据
+     */
+    onAccelerometer(callback: (data: SensorData[]) => void): () => void;
+    /**
+     * 监听陀螺仪数据
+     */
+    onGyroscope(callback: (data: SensorData[]) => void): () => void;
+    /**
+     * 监听磁力计数据
+     */
+    onMagnetometer(callback: (data: SensorData[]) => void): () => void;
+    /**
+     * 监听气压计数据
+     */
+    onBarometer(callback: (data: BarometerData[]) => void): () => void;
+    /**
+     * 获取当前状态
+     */
+    getStatus(): {
+        isActive: boolean;
+        activeTypes: SensorType[];
+    };
+}
+declare class DeviceController {
+    private core;
+    constructor(core: BridgeCore);
+    getDeviceInfo(): Promise<DeviceInfo>;
+    getBatteryInfo(): Promise<BatteryInfo>;
+    getNetworkInfo(): Promise<NetworkInfo>;
+    getSystemInfo(): Promise<SystemInfo>;
+    getAppInfo(): Promise<AppInfo>;
+    getScreenInfo(): Promise<ScreenInfo>;
+    getAllInfo(): Promise<{
+        device: Partial<DeviceInfo>;
+        battery: Partial<BatteryInfo>;
+        network: Partial<NetworkInfo>;
+        system: Partial<SystemInfo>;
+        app: Partial<AppInfo>;
+    }>;
+}
+declare class FileStorageController {
+    private core;
+    constructor(core: BridgeCore);
+    init(): Promise<{
+        initialized: boolean;
+    }>;
+    getStorageStats(): Promise<StorageStats>;
+    takePhoto(): Promise<FileInfo>;
+    pickFromGallery(): Promise<FileInfo>;
+    saveFile(sourceUri: string, filename: string, subfolder?: string): Promise<FileInfo>;
+    listFiles(subfolder?: string): Promise<FileInfo[]>;
+    downloadAndSave(url: string, filename: string, subfolder?: string): Promise<FileInfo>;
+    getLocalFileByUrl(url: string): Promise<CachedFileInfo>;
+    clearAppFiles(): Promise<{
+        cleared: boolean;
+    }>;
+    deleteFile(filename: string, subfolder?: string): Promise<{
+        deleted: boolean;
+    }>;
+    loadUrlMappings(): Promise<Array<{
+        url: string;
+        filename: string;
+        path: string;
+    }>>;
+    downloadWithCache(url: string, checkCache?: boolean): Promise<DownloadResult>;
+    clearUrlMappings(): Promise<{
+        cleared: boolean;
+    }>;
+    removeUrlMapping(url: string): Promise<{
+        removed: boolean;
+    }>;
+    addCustomFileMapping(customKey: string, localUri: string): Promise<{
+        added: boolean;
+    }>;
+    readAsBase64(uriOrKey: string): Promise<Base64Result>;
+}
+interface PlayOptions {
+    uri: string;
+    volume?: number;
+    rate?: number;
+    isLooping?: boolean;
+}
+declare class AudioController {
+    private core;
+    private fileStorage;
+    constructor(core: BridgeCore, fileStorage: FileStorageController);
+    /**
+     * 解析 URI，返回可播放的实际路径
+     */
+    private resolveUri;
+    /**
+     * 播放音频（智能解析 URI）
+     */
+    playOnline(options: PlayOptions): Promise<{
+        playing: boolean;
+        uri: string;
+    }>;
+    pause(): Promise<{
+        paused: boolean;
+    }>;
+    resume(): Promise<{
+        resumed: boolean;
+    }>;
+    stop(): Promise<{
+        stopped: boolean;
+    }>;
+    setVolume(volume: number): Promise<{
+        volume: number;
+    }>;
+    setRate(rate: number): Promise<{
+        rate: number;
+    }>;
+    getStatus(): Promise<AudioStatus>;
+}
+declare class CameraController {
+    private core;
+    constructor(core: BridgeCore);
+    open(options?: {
+        facing?: CameraFacing;
+    }): Promise<{
+        isOpen: boolean;
+        facing: CameraFacing;
+    }>;
+    close(): Promise<{
+        isOpen: boolean;
+    }>;
+    toggleFacing(): Promise<{
+        facing: CameraFacing;
+    }>;
+    takePhoto(): Promise<PhotoResult>;
+    setFilter(filter: CameraFilter): Promise<{
+        filter: string;
+        customStyles?: Record<string, unknown>;
+    }>;
+    setFlash(enabled: boolean): Promise<{
+        flash: boolean;
+    }>;
+    toggleFlash(): Promise<{
+        flash: boolean;
+    }>;
+}
+declare class MicrophoneController {
+    private core;
+    private isRecording;
+    constructor(core: BridgeCore);
+    requestPermission(): Promise<PermissionResult>;
+    start(options?: {
+        enableMonitoring?: boolean;
+    }): Promise<RecordingResult>;
+    stop(): Promise<RecordingResult>;
+    pause(): Promise<{
+        paused: boolean;
+    }>;
+    resume(): Promise<{
+        resumed: boolean;
+    }>;
+    getStatus(): Promise<{
+        isRecording: boolean;
+        isDoneRecording?: boolean;
+        durationMillis?: number;
+        canRecord: boolean;
+    }>;
+    /**
+     * 监听音量数据
+     */
+    onVolumeData(callback: (data: VolumeData[]) => void): () => void;
+    getRecordingState(): boolean;
+}
+declare class ConfigController {
+    private core;
+    private currentConfig;
+    constructor(core: BridgeCore);
+    updateParams(configData: Record<string, unknown>): Promise<{
+        received: boolean;
+        configId: number;
+        dataKeys: string[];
+        message: string;
+    }>;
+    getCurrentConfig(): Record<string, unknown> | null;
+    resetToDefaults(): Promise<{
+        reset: boolean;
+    }>;
+}
+
+/**
+ * Riffle Bridge 主类
+ *
+ * 提供完整的 WebView Bridge API
+ */
+
+/**
+ * 工具函数类
+ */
+declare class Utils {
+    /**
+     * 计算向量模长
+     */
+    static magnitude(x: number, y: number, z: number): number;
+    /**
+     * 获取倾斜方向
+     */
+    static getTiltDirection(x: number, y: number, threshold?: number): TiltDirection;
+    /**
+     * 获取摇晃强度
+     */
+    static getShakeIntensity(x: number, y: number, z: number): ShakeIntensity;
+}
+/**
+ * RiffleBridge 主类
+ *
+ * @example
+ * ```typescript
+ * import { RiffleBridge } from '@riffle/bridge-web';
+ *
+ * const bridge = new RiffleBridge();
+ *
+ * // 检查是否可用
+ * if (bridge.isAvailable()) {
+ *   // 震动
+ *   await bridge.vibrate('success');
+ *
+ *   // 使用传感器
+ *   await bridge.sensor.start({ types: ['accelerometer'] });
+ *   bridge.sensor.onAccelerometer((data) => {
+ *     console.log(data);
+ *   });
+ * }
+ * ```
+ */
+declare class RiffleBridge {
+    private core;
+    /** 震动控制器 */
+    readonly haptic: HapticController;
+    /** 传感器控制器 */
+    readonly sensor: SensorController;
+    /** 设备信息控制器 */
+    readonly device: DeviceController;
+    /** 文件存储控制器 */
+    readonly fileStorage: FileStorageController;
+    /** 音频控制器 */
+    readonly audio: AudioController;
+    /** 相机控制器 */
+    readonly camera: CameraController;
+    /** 麦克风控制器 */
+    readonly microphone: MicrophoneController;
+    /** 配置控制器 */
+    readonly config: ConfigController;
+    /** 工具函数 */
+    readonly utils: typeof Utils;
+    constructor();
+    /**
+     * 检查 Bridge 是否可用
+     */
+    isAvailable(): boolean;
+    /**
+     * 等待 Bridge 就绪
+     */
+    waitForReady(timeout?: number): Promise<boolean>;
+    /**
+     * 获取 SDK 版本
+     */
+    getVersion(): string;
+    /**
+     * 便捷方法：震动
+     */
+    vibrate(type?: HapticFeedbackType): Promise<void>;
+}
+/**
+ * 获取 RiffleBridge 单例
+ */
+declare function getRiffleBridge(): RiffleBridge;
+
+type ReactType = typeof react;
+/**
+ * 单个配置项的值包装器
+ */
+declare class TweakValue<T> {
+    private _key;
+    private _config;
+    private _value;
+    private _listeners;
+    private _syncCallback;
+    constructor(_key: string, _config: TweakConfig, syncCallback?: (() => void) | null);
+    /** 获取当前值 */
+    get value(): T;
+    /** 获取配置 */
+    get config(): TweakConfig;
+    /** 获取键名 */
+    get key(): string;
+    /**
+     * 设置值
+     * @param newValue 新值
+     * @param skipSync 是否跳过同步到 Native
+     */
+    set(newValue: T, skipSync?: boolean): void;
+    /**
+     * 内部设置（不触发同步，用于接收 Native 更新）
+     */
+    _setInternal(newValue: T): void;
+    /**
+     * 订阅值变化
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * 监听值变化
+     */
+    onChange(callback: (value: T) => void): () => void;
+    /**
+     * React Hook: 获取响应式值
+     * 需要传入 React 实例或使用 createTweaks 时传入
+     */
+    useState(react?: ReactType): T;
+    private _notifyListeners;
+}
+/**
+ * Tweaks 配置管理器
+ */
+declare class RiffleBridgeTweaks<T extends TweaksConfig> {
+    private _config;
+    private _tweaks;
+    private _syncDebounceTimer;
+    constructor(config: T);
+    /**
+     * 获取指定键的配置项
+     */
+    get<K extends keyof T>(key: K): TweakValue<T[K]['value']>;
+    /**
+     * 获取所有值
+     */
+    getData(): Record<string, unknown>;
+    /**
+     * 获取完整配置（含元数据）
+     */
+    toJSON(): Record<string, {
+        name: string;
+        type: string;
+        value: unknown;
+        [k: string]: unknown;
+    }>;
+    /**
+     * 批量更新值
+     */
+    update(updates: Partial<Record<keyof T, unknown>>): void;
+    /**
+     * 重置为默认值
+     */
+    reset(): void;
+    /**
+     * 获取所有配置键名
+     */
+    keys(): string[];
+    /**
+     * 监听任意参数变化
+     */
+    onAnyChange(callback: (key: string, value: unknown) => void): () => void;
+    /**
+     * 设置消息监听
+     */
+    private _setupMessageListener;
+    /**
+     * 设置全局回调函数（兼容旧版 Native 调用方式）
+     */
+    private _setupGlobalCallbacks;
+    /**
+     * 同步配置到 Native
+     */
+    private _syncToNative;
+}
+type TweaksProxy<T extends TweaksConfig> = RiffleBridgeTweaks<T> & {
+    [K in keyof T]: TweakValue<T[K]['value']>;
+};
+/**
+ * 创建 Tweaks 配置实例
+ *
+ * @example
+ * ```typescript
+ * import React from 'react';
+ * import { createTweaks } from '@riffle/bridge-web';
+ *
+ * const tweaks = createTweaks({
+ *   color: { name: '颜色', type: 'color', value: '#667eea' },
+ *   size: { name: '大小', type: 'number', value: 150, min: 50, max: 300 },
+ *   enabled: { name: '启用', type: 'boolean', value: true },
+ * }, { React });
+ *
+ * function Demo() {
+ *   const color = tweaks.color.useState();
+ *   const size = tweaks.size.useState();
+ *
+ *   return <div style={{ backgroundColor: color, width: size, height: size }} />;
+ * }
+ * ```
+ */
+declare function createTweaks<T extends TweaksConfig>(config: T, options?: {
+    React?: ReactType;
+}): TweaksProxy<T>;
+declare function riffleBridgeTweaks<T extends TweaksConfig>(config: T, options?: {
+    React?: ReactType;
+}): TweaksProxy<T>;
+
+export { type AppInfo, AudioController, type AudioStatus, type BarometerData, type Base64Result, type BatteryInfo, type BooleanTweakConfig, BridgeCore, type BridgeMessage, type BridgeResponse, type CachedFileInfo, CameraController, type CameraFacing, type CameraFilter, type ColorTweakConfig, ConfigController, DeviceController, type DeviceInfo, type DownloadResult, type FileInfo, FileStorageController, HapticController, type HapticFeedbackType, MicrophoneController, type NetworkInfo, type NumberTweakConfig, type PermissionResult, type PhotoResult, type PlayOptions, type RecordingResult, RiffleBridge, RiffleBridgeTweaks, type ScreenInfo, type SelectOption, type SelectTweakConfig, SensorController, type SensorData, type SensorStartOptions, type SensorType, type ShakeIntensity, type StorageStats, type StringTweakConfig, type SystemInfo, type TiltDirection, type TweakConfig, type TweakType, TweakValue, type TweaksConfig, Utils, type VolumeData, createTweaks, getBridgeCore, getRiffleBridge, riffleBridgeTweaks };