@bud-fe/h5-native-bridge 1.0.4

package/dist/src/core/index.d.ts

@@ -0,0 +1,172 @@
+export interface PluginContext {
+    bridge: NativeBridgeCore;
+}
+export interface BridgePlugin {
+    name: string;
+    version: string;
+    install: (context: PluginContext) => void;
+}
+export interface BridgeOptions {
+    debug?: boolean;
+    timeout?: number;
+    plugins?: BridgePlugin[];
+    errorHandler?: (error: Error, source: string) => void;
+}
+export interface NativeResponse<T = any> {
+    code: number;
+    message: string;
+    data?: T;
+}
+export interface CallbacksBase<T = any> {
+    success?: (data: T) => void;
+    fail?: (error: Error) => void;
+    complete?: () => void;
+}
+export interface CallNativeOptions {
+    action: string;
+    params?: Record<string, any>;
+    timeout?: number;
+    retryCount?: number;
+    retryDelay?: number;
+}
+export interface PluginMethods {
+}
+type NativeEventHandler = (event: {
+    type: string;
+    data: any;
+}) => void;
+/**
+ * NativeBridge核心类
+ * 提供基础的通信能力和插件系统
+ */
+export declare class NativeBridgeCore {
+    private static instance;
+    private callbackMap;
+    private callbackId;
+    private isReady;
+    private readyCallbacks;
+    private debugMode;
+    private defaultTimeout;
+    private plugins;
+    private pendingCalls;
+    private errorHandler?;
+    private eventListeners;
+    private nativeEventHandlers;
+    readonly VERSION = "1.0.0";
+    readonly API_VERSION = "1";
+    /**
+     * 私有构造函数（单例模式）
+     */
+    private constructor();
+    /**
+     * 获取NativeBridge单例
+     */
+    static getInstance(options?: BridgeOptions): NativeBridgeCore;
+    /**
+     * 注册原生事件监听
+     */
+    onNativeEvent(eventType: string, handler: NativeEventHandler): void;
+    /**
+     * 取消原生事件监听
+     */
+    offNativeEvent(eventType: string, handler: NativeEventHandler): void;
+    /**
+     * 供原生调用，分发事件
+     */
+    dispatchNativeEvent(eventType: string, data: any): void;
+    private methodRegistry;
+    registerMethod<T extends keyof PluginMethods>(name: T, method: PluginMethods[T]): void;
+    /**
+     * 安装插件
+     */
+    use(plugin: BridgePlugin): NativeBridgeCore;
+    /**
+     * 检查插件是否已安装
+     */
+    hasPlugin(name: string): boolean;
+    /**
+     * 获取已安装的插件
+     */
+    getPlugin(name: string): BridgePlugin | undefined;
+    /**
+     * 设置桥接环境
+     */
+    private setupBridge;
+    destroy(): void;
+    /**
+     * 检测是否在App环境中
+     */
+    private checkIsInApp;
+    /**
+     * 等待桥接准备就绪
+     */
+    ready(callback: () => void): void;
+    /**
+     * 调用原生方法
+     */
+    callNative<T = any>(options: CallNativeOptions, callbacks?: CallbacksBase<T>): string;
+    /**
+     * 同步调用原生方法
+     *
+     * 该方法通过不同的桥接方式（iOS WKWebView、Android WebView或iframe）与原生应用通信，
+     * 发送指定的操作指令和参数，并返回处理结果
+     *
+     * @param action - 要执行的原生操作名称
+     * @param params - 传递给原生方法的参数对象
+     * @returns 处理后的原生返回数据
+     * @throws 当发送消息到原生App失败时抛出错误
+     */
+    callNativeSync(action: string, params: any, callbacks: CallbacksBase): any;
+    /**
+     * 发送消息到原生
+     */
+    private sendToNative;
+    /**
+     * 处理原生回调
+     */
+    handleNativeCallback(callbackId: string, type: "success" | "fail", data: any): void;
+    /**
+     * 模拟原生调用（仅用于开发测试）
+     */
+    private mockNativeCall;
+    /**
+     * 释放回调
+     */
+    releaseCallback(callbackId: string): void;
+    /**
+     * 设置调试模式
+     */
+    setDebug(debug: boolean): void;
+    /**
+     * 设置全局错误处理器
+     */
+    setErrorHandler(handler: (error: Error, source: string) => void): void;
+    /**
+     * 获取已安装插件列表
+     */
+    getInstalledPlugins(): string[];
+    /**
+     * 获取当前调试模式状态
+     * @returns 是否开启调试模式
+     */
+    isDebugMode(): boolean;
+    /**
+     * 日志记录 - 信息
+     */
+    log(message: string, ...args: any[]): void;
+    /**
+     * 日志记录 - 警告
+     */
+    warn(message: string, ...args: any[]): void;
+    /**
+     * 日志记录 - 错误
+     */
+    error(source: string, error: Error): void;
+    /**
+     * 获取回调映射表
+     */
+    getCallBackMap(): Map<string, CallbacksBase<any>>;
+}
+export declare const createNativeBridge: (options?: BridgeOptions) => NativeBridgeCore;
+declare const _default: NativeBridgeCore;
+export default _default;

package/dist/src/index.d.ts

@@ -0,0 +1,19 @@
+export { NativeBridgeCore, createNativeBridge } from './core';
+export { default as locationPlugin } from './plugins/location';
+export { default as devicePlugin } from './plugins/device';
+export { default as mediaPlugin } from './plugins/media';
+export { default as navigatePlugin } from './plugins/navigate';
+export { default as userinfoPlugin } from './plugins/userInfo';
+export { default as toastPlugin } from './plugins/toast';
+export { default as bluetoothPlugin } from './plugins/bluetooth';
+export { default as storagePlugin } from './plugins/storage';
+export { default as authenticationPlugin } from './plugins/authentication';
+export { default as requestPlugin } from './plugins/request';
+export { default as wifiPlugin } from './plugins/wifi';
+export type { BridgePlugin, BridgeOptions, PluginContext, CallbacksBase, NativeResponse, CallNativeOptions, PluginMethods, } from './core';
+export type { LocationInfo, GetLocationOptions, } from './plugins/location';
+export type { DeviceInfo, DeviceInfoOptions, GetWifiOptions, WifiListAsyncResult, } from './plugins/device';
+export type { MediaInfo, MediaInfoOptions, } from './plugins/media';
+export type { NavigateInfo } from './plugins/navigate';
+declare const nativeBridge: import('./core').NativeBridgeCore;
+export default nativeBridge;

package/dist/src/plugins/authentication.d.ts

@@ -0,0 +1,30 @@
+import { BridgePlugin, PluginContext, CallbacksBase } from '../core';
+
+export interface AuthenticationResult {
+    photoStatus: number;
+}
+declare module "../core" {
+    interface PluginMethods {
+        exclusiveLiveCheck: (options?: CallbacksBase) => Promise<AuthenticationResult>;
+    }
+    interface NativeBridgeCore extends PluginMethods {
+    }
+}
+declare class AuthenticationPlugin implements BridgePlugin {
+    private context?;
+    readonly name = "authentication";
+    readonly version = "1.0.0";
+    install(context: PluginContext): void;
+    /**
+     * 执行实人认证
+     * @param options - 认证选项，包含成功、失败和完成的回调函数
+     * @property options.success - 认证成功时的回调函数，接收认证结果
+     * @property options.fail - 认证失败时的回调函数，接收错误信息
+     * @property options.complete - 认证完成时的回调函数（无论成功或失败）
+     * @returns Promise<AuthenticationResult> - 返回认证结果的Promise对象
+     * @throws {BridgeError} - 如果插件未正确初始化，抛出BridgeError异常
+     */
+    exclusiveLiveCheck(options?: CallbacksBase): Promise<AuthenticationResult>;
+}
+declare const _default: AuthenticationPlugin;
+export default _default;

package/dist/src/plugins/bluetooth.d.ts

@@ -0,0 +1,399 @@
+import { BridgePlugin, PluginContext, CallbacksBase } from '../core';
+
+export interface OpenBluetoothOptions extends CallbacksBase {
+    /**不传的话默认是true，表示是否在离开当前页面时自动断开蓝牙(仅对android有效)。 */
+    autoClose?: boolean;
+}
+export interface CloseBluetoothOptions extends CallbacksBase {
+}
+export interface OpenBluetoothResponse {
+    /** 是否支持BLE蓝牙 */
+    isSupportBLE?: number;
+}
+export interface StartBluetoothDevicesDiscoveryOptions extends CallbacksBase {
+    allowDuplicatesKey?: boolean;
+    interval?: number;
+    services?: string[];
+}
+export interface BLEDeviceOptions extends CallbacksBase {
+    deviceId: string;
+}
+export interface GetBLEDeviceOptions extends CallbacksBase {
+    success?: (data: BLEDeviceResponse) => void;
+    /**
+       * Android 上为设备 MAC 地址。
+          iOS 上为设备 UUID。
+          */
+    deviceId: string;
+    serviceId: string;
+}
+export interface BLEDeviceResponse {
+    /** 设备特征值列表 */
+    characteristics: Characteristic[];
+}
+export interface Characteristic {
+    characteristicId: string;
+    serviceId: string;
+    value: string;
+    properties: Properties;
+}
+export interface Properties {
+    read: boolean;
+    write: boolean;
+    notify: boolean;
+    indicate: boolean;
+}
+export interface BLEDeviceServicesOptions extends CallbacksBase {
+    success?: (data: BLEDeviceServicesResponse) => void;
+    deviceId: string;
+}
+export interface BLEDeviceServicesResponse {
+    services: Services[];
+}
+export interface Services {
+    serviceId: string;
+    isPrimary: string;
+}
+export interface WriteBLECharacteristicValueOptions extends CallbacksBase {
+    deviceId: string;
+    serviceId: string;
+    characteristicId: string;
+    value: string;
+}
+export interface ReadBLECharacteristicValueOptions extends CallbacksBase {
+    success?: (data: ReadBLECharacteristicValueResponse) => void;
+    deviceId: string;
+    serviceId: string;
+    characteristicId: string;
+}
+export interface ReadBLECharacteristicValueResponse {
+    /** 设备特征值列表 */
+    characteristicId?: string;
+    serviceId?: string;
+    value?: string;
+}
+declare module "../core" {
+    interface PluginMethods {
+        openBluetoothAdapter: (options?: OpenBluetoothOptions) => void;
+        closeBluetoothAdapter: (options?: CloseBluetoothOptions) => void;
+        startBluetoothDevicesDiscovery: (options?: StartBluetoothDevicesDiscoveryOptions) => void;
+        stopBluetoothDevicesDiscovery: (options?: CallbacksBase) => void;
+        onBluetoothDeviceFound: (callback: (devices: any[]) => void) => void;
+        offBluetoothDeviceFound: () => void;
+        connectBLEDevice: (options: BLEDeviceOptions) => void;
+        disconnectBLEDevice: (options: BLEDeviceOptions) => void;
+        getBLEDeviceCharacteristics: (options: GetBLEDeviceOptions) => void;
+        getBLEDeviceServices: (options: BLEDeviceServicesOptions) => void;
+        writeBLECharacteristicValue: (options: WriteBLECharacteristicValueOptions) => void;
+        readBLECharacteristicValue: (options: ReadBLECharacteristicValueOptions) => void;
+        onBLECharacteristicValueChange: (callback: (data: {
+            serviceId: string;
+            characteristicId: string;
+            deviceId: string;
+            value: string;
+        }) => void) => void;
+        offBLECharacteristicValueChange: () => void;
+        onBLEConnectionStateChanged: (callback: (data: {
+            deviceId: string;
+            connected: boolean;
+        }) => void) => void;
+        offBLEConnectionStateChanged: () => void;
+    }
+    interface NativeBridgeCore extends PluginMethods {
+    }
+}
+declare class BluetoothPlugin implements BridgePlugin {
+    readonly name = "bluetooth";
+    readonly version = "1.0.0";
+    private context?;
+    install(context: PluginContext): void;
+    /**
+     * 取消监听蓝牙低功耗连接状态变化事件
+     *
+     * @description 该方法用于移除之前注册的蓝牙低功耗连接状态变化监听器。
+     * 当不再需要监听连接状态变化时，应调用此方法以避免内存泄漏。
+     *
+     * @param callback - 可选的回调函数，当成功取消监听后会被调用
+     * @returns void
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出错误
+     *
+     * @example
+     */
+    offBLEConnectionStateChanged(callback?: () => void): void;
+    /**
+     * 监听BLE设备连接状态变化
+     *
+     * @description 注册一个回调函数来监听蓝牙低功耗(BLE)设备的连接状态变化事件。
+     * 当设备连接或断开时，会触发相应的回调函数。
+     *
+     * @param callback - 连接状态变化时的回调函数
+     * @param callback.data - 回调函数的参数对象
+     * @param callback.data.deviceId - 设备ID，用于标识具体的BLE设备
+     * @param callback.data.connected - 连接状态，true表示已连接，false表示已断开
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出错误
+     *
+     * @example
+     *
+     * @since 1.0.0
+     */
+    onBLEConnectionStateChanged(callback: (data: {
+        deviceId: string;
+        connected: boolean;
+    }) => void): void;
+    /**
+     * 取消监听低功耗蓝牙设备的特征值变化事件
+     *
+     * @description 此方法用于移除之前通过onBLECharacteristicValueChange注册的事件监听器。
+     * 当不再需要监听BLE特征值变化时，应调用此方法以避免内存泄漏和不必要的回调执行。
+     *
+     * @param {Function} [callback] - 可选的回调函数，在成功取消监听后执行
+     * @returns {void} 无返回值
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出错误
+     *
+     * @example
+     */
+    offBLECharacteristicValueChange(callback?: () => void): void;
+    /**
+     * 监听 BLE 特征值变化事件
+     *
+     * 当蓝牙低功耗设备的特征值发生变化时，会触发此回调函数。
+     * 在调用此方法前，需要确保插件已正确初始化。
+     *
+     * @param callback - 特征值变化时的回调函数
+     * @param callback.data - 特征值变化的数据对象
+     * @param callback.data.serviceId - 服务 ID，标识 BLE 服务
+     * @param callback.data.characteristicId - 特征 ID，标识 BLE 特征
+     * @param callback.data.deviceId - 设备 ID，标识 BLE 设备
+     * @param callback.data.value - 特征值，变化后的特征值内容
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出错误
+     *
+     * @example
+     */
+    onBLECharacteristicValueChange(callback: (data: {
+        serviceId: string;
+        characteristicId: string;
+        deviceId: string;
+        value: string;
+    }) => void): void;
+    /**
+     * 读取低功耗蓝牙设备特征值
+     *
+     * @description 从指定的蓝牙设备特征值中读取数据。该方法需要在插件正确初始化后才能使用。
+     *
+     * @param {ReadBLECharacteristicValueOptions} options - 读取BLE特征值的配置选项
+     * @param {string} options.deviceId - 蓝牙设备ID
+     * @param {string} options.serviceId - 蓝牙服务ID
+     * @param {string} options.characteristicId - 蓝牙特征值ID
+     * @param {function} [options.success] - 成功回调函数，参数为读取到的特征值数据
+     * @param {function} [options.fail] - 失败回调函数
+     * @param {function} [options.complete] - 完成回调函数（无论成功或失败都会执行）
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出错误
+     *
+     * @returns {void} 无返回值
+     *
+     * @example
+     */
+    readBLECharacteristicValue(options: ReadBLECharacteristicValueOptions): void;
+    /**
+     * 向低功耗蓝牙设备特征值中写入数据
+     *
+     * @param options - 写入BLE特征值的配置选项
+     * @param options.deviceId - 蓝牙设备 id
+     * @param options.serviceId - 蓝牙特征值对应服务的 uuid
+     * @param options.characteristicId - 蓝牙特征值的 uuid
+     * @param options.value - 蓝牙设备特征值对应的二进制值
+     * @param options.success - 接口调用成功的回调函数
+     * @param options.fail - 接口调用失败的回调函数
+     * @param options.complete - 接口调用结束的回调函数（调用成功、失败都会执行）
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出错误
+     *
+     * @example
+     */
+    writeBLECharacteristicValue(options: WriteBLECharacteristicValueOptions): void;
+    /**
+     * 获取蓝牙低功耗设备的所有服务
+     *
+     * @description 该方法用于获取已连接的BLE设备的所有可用服务列表。
+     * 调用前需要确保设备已经成功连接，否则可能获取失败。
+     *
+     * @param {BLEDeviceServicesOptions} options - 获取BLE设备服务的配置选项
+     * @param {string} options.deviceId - 蓝牙设备标识符，用于指定要获取服务的设备
+     * @param {function} [options.success] - 成功回调函数，参数为BLEDeviceServicesResponse类型
+     * @param {function} [options.fail] - 失败回调函数，参数为错误信息
+     * @param {function} [options.complete] - 完成回调函数，无论成功失败都会调用
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出PLUGIN_NOT_INITIALIZED错误
+     *
+     * @returns {void} 无返回值，结果通过回调函数返回
+     *
+     * @example
+     */
+    getBLEDeviceServices(options: BLEDeviceServicesOptions): void;
+    /**
+     * 连接蓝牙低功耗设备
+     *
+     * @description 此方法用于连接指定的蓝牙低功耗（BLE）设备。在调用前需要确保插件已正确初始化，
+     * 否则会抛出插件未初始化的错误。连接过程是异步的，通过回调函数返回结果。
+     *
+     * @param {BLEDeviceOptions} options - 连接BLE设备的配置选项
+     * @param {Function} [options.success] - 连接成功时的回调函数
+     * @param {Function} [options.fail] - 连接失败时的回调函数
+     * @param {Function} [options.complete] - 连接完成时的回调函数（无论成功或失败都会执行）
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出 PLUGIN_NOT_INITIALIZED 错误
+     *
+     * @returns {void} 无返回值
+     *
+     * @example
+     */
+    connectBLEDevice(options: BLEDeviceOptions): void;
+    /**
+     * 断开蓝牙低功耗设备连接
+     *
+     * @description 断开与指定蓝牙低功耗设备的连接。此方法会调用原生平台的蓝牙断连功能。
+     *
+     * @param {BLEDeviceOptions} options - 断开连接的配置选项
+     * @param {Function} [options.success] - 成功回调函数
+     * @param {Function} [options.fail] - 失败回调函数
+     * @param {Function} [options.complete] - 完成回调函数（无论成功或失败都会执行）
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出错误
+     *
+     * @returns {void}
+     *
+     * @example
+     */
+    disconnectBLEDevice(options: BLEDeviceOptions): void;
+    /**
+     * 获取蓝牙低功耗设备的特征值列表
+     *
+     * @description 用于获取指定蓝牙低功耗设备的所有特征值信息，包括特征值的UUID、属性等。
+     * 该方法需要在蓝牙设备连接成功后调用。
+     *
+     * @param {GetBLEDeviceOptions} options - 获取设备特征值的配置选项
+     * @param {string} options.deviceId - 蓝牙设备ID
+     * @param {string} options.serviceId - 蓝牙服务UUID
+     * @param {function} [options.success] - 成功回调函数，返回特征值列表数据
+     * @param {function} [options.fail] - 失败回调函数
+     * @param {function} [options.complete] - 完成回调函数（无论成功或失败都会执行）
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出错误
+     *
+     * @example
+     *
+     * @since 1.0.0
+     */
+    getBLEDeviceCharacteristics(options: GetBLEDeviceOptions): void;
+    /**
+     * 取消监听蓝牙设备发现事件
+     *
+     * @description 移除对蓝牙设备发现事件的监听，当不再需要接收蓝牙设备发现通知时调用此方法
+     *
+     * @param callback - 可选的回调函数，在成功取消监听后执行
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出错误
+     *
+     * @example
+     *
+     * @returns {void} 无返回值
+     */
+    offBluetoothDeviceFound(callback?: () => void): void;
+    /**
+     * 监听蓝牙设备发现事件
+     *
+     * 当发现新的蓝牙设备时，会触发回调函数并传入设备列表。
+     * 该方法需要在插件正确初始化后调用，否则会抛出异常。
+     *
+     * @param callback - 设备发现回调函数
+     * @param callback.devices - 发现的蓝牙设备列表
+     * @throws {BridgeError} 当插件未正确初始化时抛出 PLUGIN_NOT_INITIALIZED 错误
+     *
+     * @example
+     */
+    onBluetoothDeviceFound(callback: (devices: any[]) => void): void;
+    /**
+     * 停止搜索蓝牙设备
+     *
+     * @description 停止搜索附近的蓝牙外围设备。若已经找到需要连接的蓝牙设备并不需要继续搜索时，建议调用该接口停止蓝牙搜索。
+     *
+     * @param options - 可选的回调函数配置对象
+     * @param options.success - 接口调用成功的回调函数
+     * @param options.fail - 接口调用失败的回调函数
+     * @param options.complete - 接口调用结束的回调函数（调用成功、失败都会执行）
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出异常
+     *
+     * @example
+     */
+    stopBluetoothDevicesDiscovery(options?: CallbacksBase): void;
+    /**
+     * 开启蓝牙适配器
+     *
+     * @description 开启本机蓝牙适配器模块，允许设备进行蓝牙操作。调用该方法前需要确保插件已正确初始化。
+     *
+     * @param {OpenBluetoothOptions} [options={}] - 开启蓝牙适配器的配置选项
+     * @param {Function} [options.success] - 接口调用成功的回调函数
+     * @param {Function} [options.fail] - 接口调用失败的回调函数
+     * @param {Function} [options.complete] - 接口调用结束的回调函数（调用成功、失败都会执行）
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出错误
+     *
+     * @returns {void}
+     *
+     * @example
+     */
+    startBluetoothDevicesDiscovery(options?: StartBluetoothDevicesDiscoveryOptions): void;
+    /**
+     * 关闭蓝牙适配器
+     *
+     * @description 关闭本机蓝牙适配器模块，断开所有已建立的连接。调用该方法将会断开所有蓝牙连接，
+     * 释放系统资源。建议在不需要使用蓝牙功能时及时调用此方法。
+     *
+     * @param {CloseBluetoothOptions} [options={}] - 关闭蓝牙适配器的配置选项
+     * @param {Function} [options.success] - 接口调用成功的回调函数
+     * @param {Function} [options.fail] - 接口调用失败的回调函数
+     * @param {Function} [options.complete] - 接口调用结束的回调函数（调用成功、失败都会执行）
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出错误
+     *
+     * @returns {void}
+     *
+     * @example
+     */
+    closeBluetoothAdapter(options?: CloseBluetoothOptions): void;
+    /**
+     * 开启蓝牙功能
+     *
+     * 此方法用于启用设备的蓝牙功能。调用前需要确保插件已正确初始化，
+     * 否则会抛出相应的错误。方法会通过桥接器调用原生蓝牙开启功能。
+     *
+     * @param options - 开启蓝牙的配置选项
+     * @param options.success - 成功回调函数，当蓝牙成功开启时调用
+     * @param options.fail - 失败回调函数，当蓝牙开启失败时调用
+     * @param options.complete - 完成回调函数，无论成功或失败都会调用
+     *
+     * @throws {BridgeError} 当插件未正确初始化时抛出 PLUGIN_NOT_INITIALIZED 错误
+     *
+     * @returns {void} 无返回值
+     *
+     * @example
+     */
+    openBluetoothAdapter(options?: OpenBluetoothOptions): void;
+    /**
+     * 搜索到新蓝牙时触发
+     * 当发现新的蓝牙设备时，会触发回调函数并传入设备列表。
+     * 该方法需要在插件正确初始化后调用，否则会抛出异常。
+     * @param callback - 新蓝牙搜索到时触发的回调函数
+     * @param callback.devices - 发现的蓝牙设备列表
+     * @throws {BridgeError} 当插件未正确初始化时抛出 PLUGIN_NOT_INITIALIZED 错误
+     */
+    getBluetoothDevices(callback: (devices: any[]) => void): void;
+}
+export declare const bluetooth: BluetoothPlugin;
+export default bluetooth;