@fww_123/uni-ble-scanner 1.0.0

package/src/types.ts

@@ -0,0 +1,178 @@
+/**
+ * 蓝牙设备信息
+ */
+export interface BLEDevice {
+  /** 设备ID */
+  deviceId: string;
+  /** 设备名称 */
+  name?: string;
+  /** 信号强度 */
+  RSSI: number;
+  /** 广播数据 */
+  advertisData?: ArrayBuffer;
+  /** 广播数据 (Base64) */
+  advertisDataBase64?: string;
+  /** 制造商数据 */
+  manufacturerData?: Record<string, ArrayBuffer>;
+  /** 服务UUID列表 */
+  serviceUuids?: string[];
+  /** 本地名称 */
+  localName?: string;
+  /** 是否可连接 */
+  isConnectable?: boolean;
+  /** 发射功率 */
+  txPowerLevel?: number;
+  /** 平台特定数据 */
+  platformData?: Record<string, any>;
+}
+
+/**
+ * 扫描配置选项
+ */
+export interface ScanOptions {
+  /** 扫描超时时间 (毫秒)，默认 10000 */
+  timeout?: number;
+  /** 是否允许重复上报同一设备 */
+  allowDuplicates?: boolean;
+  /** 要扫描的服务UUID列表 */
+  services?: string[];
+  /** 设备名称过滤器 */
+  nameFilter?: string | string[];
+  /** 信号强度阈值 (dBm)，低于此值的设备将被过滤 */
+  rssiThreshold?: number;
+  /** 制造商数据过滤器 */
+  manufacturerFilter?: number | number[];
+}
+
+/**
+ * 扫描状态
+ */
+export enum ScanState {
+  IDLE = 'idle',
+  SCANNING = 'scanning',
+  STOPPING = 'stopping',
+  ERROR = 'error'
+}
+
+/**
+ * 平台类型
+ */
+export enum Platform {
+  ANDROID = 'android',
+  IOS = 'ios',
+  HARMONY = 'harmony',
+  UNKNOWN = 'unknown'
+}
+
+/**
+ * 蓝牙适配器状态
+ */
+export interface AdapterState {
+  /** 是否可用 */
+  available: boolean;
+  /** 是否已开启 */
+  discovering: boolean;
+}
+
+/**
+ * 扫描事件回调
+ */
+export interface ScanCallbacks {
+  /** 发现设备回调 */
+  onDeviceFound?: (device: BLEDevice) => void;
+  /** 扫描开始回调 */
+  onScanStart?: () => void;
+  /** 扫描停止回调 */
+  onScanStop?: () => void;
+  /** 扫描超时回调 */
+  onTimeout?: () => void;
+  /** 错误回调 */
+  onError?: (error: BLEError) => void;
+}
+
+/**
+ * 蓝牙错误
+ */
+export interface BLEError {
+  /** 错误码 */
+  code: number;
+  /** 错误信息 */
+  message: string;
+  /** 平台特定错误码 */
+  platformCode?: number;
+  /** 原始错误 */
+  originalError?: any;
+}
+
+/**
+ * 蓝牙扫描器接口
+ */
+export interface IBLEScanner {
+  /** 初始化蓝牙适配器 */
+  init(): Promise<void>;
+  /** 开始扫描 */
+  startScan(options?: ScanOptions, callbacks?: ScanCallbacks): Promise<void>;
+  /** 停止扫描 */
+  stopScan(): Promise<void>;
+  /** 获取已发现的设备列表 */
+  getDiscoveredDevices(): BLEDevice[];
+  /** 清空设备列表 */
+  clearDevices(): void;
+  /** 获取当前扫描状态 */
+  getState(): ScanState;
+  /** 获取当前平台 */
+  getPlatform(): Platform;
+  /** 检查蓝牙权限 */
+  checkPermissions(): Promise<boolean>;
+  /** 请求蓝牙权限 */
+  requestPermissions(): Promise<boolean>;
+  /** 监听适配器状态变化 */
+  onAdapterStateChange(callback: (state: AdapterState) => void): void;
+  /** 销毁扫描器 */
+  destroy(): void;
+}
+
+/**
+ * 平台特定配置
+ */
+export interface PlatformConfig {
+  /** 安卓配置 */
+  android?: {
+    /** 扫描模式 */
+    scanMode?: number;
+    /** 回调类型 */
+    callbackType?: number;
+    /** 匹配模式 */
+    matchMode?: number;
+    /** 是否使用旧版扫描API */
+    useLegacyScan?: boolean;
+  };
+  /** iOS配置 */
+  ios?: {
+    /** 是否允许后台扫描 */
+    allowBackgroundScan?: boolean;
+    /** 恢复标识 */
+    restoreIdentifier?: string;
+  };
+  /** 鸿蒙配置 */
+  harmony?: {
+    /** 扫描过滤器 */
+    filter?: any;
+  };
+}
+
+/**
+ * 扫描结果过滤器
+ */
+export interface DeviceFilter {
+  /** 按名称过滤 */
+  name?: string | string[] | RegExp;
+  /** 按服务UUID过滤 */
+  serviceUuid?: string | string[];
+  /** 按制造商ID过滤 */
+  manufacturerId?: number | number[];
+  /** 按信号强度过滤 */
+  minRssi?: number;
+  /** 自定义过滤函数 */
+  custom?: (device: BLEDevice) => boolean;
+}

package/src/utils/data-parser.ts

@@ -0,0 +1,217 @@
+import { BLEDevice } from '../types';
+
+/**
+ * 解析广播数据
+ */
+export function parseAdvertisementData(data: ArrayBuffer | string): {
+  manufacturerData?: Record<string, ArrayBuffer>;
+  serviceUuids?: string[];
+  localName?: string;
+  txPowerLevel?: number;
+  isConnectable?: boolean;
+} {
+  const result: ReturnType<typeof parseAdvertisementData> = {};
+  
+  if (!data) {
+    return result;
+  }
+  
+  let buffer: ArrayBuffer;
+  if (typeof data === 'string') {
+    // Base64 解码
+    buffer = base64ToArrayBuffer(data);
+  } else {
+    buffer = data;
+  }
+  
+  const view = new DataView(buffer);
+  let offset = 0;
+  
+  const manufacturerData: Record<string, ArrayBuffer> = {};
+  const serviceUuids: string[] = [];
+  
+  while (offset < view.byteLength) {
+    const length = view.getUint8(offset);
+    if (length === 0) break;
+    
+    const type = view.getUint8(offset + 1);
+    const dataOffset = offset + 2;
+    const dataLength = length - 1;
+    
+    switch (type) {
+      case 0x01: // Flags
+        const flags = view.getUint8(dataOffset);
+        result.isConnectable = (flags & 0x02) !== 0;
+        break;
+        
+      case 0x02: // 16-bit Service UUIDs (partial)
+      case 0x03: // 16-bit Service UUIDs (complete)
+        for (let i = 0; i < dataLength; i += 2) {
+          const uuid = view.getUint16(dataOffset + i, true).toString(16).padStart(4, '0');
+          serviceUuids.push(`0000${uuid}-0000-1000-8000-00805f9b34fb`);
+        }
+        break;
+        
+      case 0x04: // 32-bit Service UUIDs (partial)
+      case 0x05: // 32-bit Service UUIDs (complete)
+        for (let i = 0; i < dataLength; i += 4) {
+          const uuid = view.getUint32(dataOffset + i, true).toString(16).padStart(8, '0');
+          serviceUuids.push(`${uuid}-0000-1000-8000-00805f9b34fb`);
+        }
+        break;
+        
+      case 0x06: // 128-bit Service UUIDs (partial)
+      case 0x07: // 128-bit Service UUIDs (complete)
+        for (let i = 0; i < dataLength; i += 16) {
+          const uuid = parseUUID(buffer.slice(dataOffset + i, dataOffset + i + 16));
+          serviceUuids.push(uuid);
+        }
+        break;
+        
+      case 0x08: // Shortened Local Name
+      case 0x09: // Complete Local Name
+        result.localName = decodeUTF8(buffer.slice(dataOffset, dataOffset + dataLength));
+        break;
+        
+      case 0x0A: // TX Power Level
+        result.txPowerLevel = view.getInt8(dataOffset);
+        break;
+        
+      case 0xFF: // Manufacturer Specific Data
+        const companyId = view.getUint16(dataOffset, true);
+        const companyIdHex = companyId.toString(16).padStart(4, '0');
+        manufacturerData[companyIdHex] = buffer.slice(dataOffset + 2, dataOffset + dataLength);
+        break;
+    }
+    
+    offset += length + 1;
+  }
+  
+  if (Object.keys(manufacturerData).length > 0) {
+    result.manufacturerData = manufacturerData;
+  }
+  if (serviceUuids.length > 0) {
+    result.serviceUuids = serviceUuids;
+  }
+  
+  return result;
+}
+
+/**
+ * Base64 转 ArrayBuffer
+ */
+export function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  const binary = atob(base64);
+  const buffer = new ArrayBuffer(binary.length);
+  const view = new Uint8Array(buffer);
+  for (let i = 0; i < binary.length; i++) {
+    view[i] = binary.charCodeAt(i);
+  }
+  return buffer;
+}
+
+/**
+ * ArrayBuffer 转 Base64
+ */
+export function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * 解析 UUID
+ */
+function parseUUID(buffer: ArrayBuffer): string {
+  const view = new DataView(buffer);
+  const parts = [
+    view.getUint32(0, false).toString(16).padStart(8, '0'),
+    view.getUint16(4, false).toString(16).padStart(4, '0'),
+    view.getUint16(6, false).toString(16).padStart(4, '0'),
+    view.getUint16(8, false).toString(16).padStart(4, '0'),
+    view.getUint32(10, false).toString(16).padStart(8, '0') +
+    view.getUint16(14, false).toString(16).padStart(4, '0'),
+  ];
+  return `${parts[0]}-${parts[1]}-${parts[2]}-${parts[3]}-${parts[4]}`;
+}
+
+/**
+ * UTF-8 解码
+ */
+function decodeUTF8(buffer: ArrayBuffer): string {
+  const decoder = new TextDecoder('utf-8');
+  return decoder.decode(buffer);
+}
+
+/**
+ * 标准化设备数据
+ */
+export function normalizeDeviceData(device: any): BLEDevice {
+  const normalized: BLEDevice = {
+    deviceId: device.deviceId || '',
+    name: device.name || device.localName,
+    RSSI: device.RSSI || device.rssi || -100,
+  };
+  
+  // 处理广播数据
+  if (device.advertisData) {
+    normalized.advertisData = device.advertisData;
+    if (typeof device.advertisData === 'string') {
+      normalized.advertisDataBase64 = device.advertisData;
+    } else {
+      normalized.advertisDataBase64 = arrayBufferToBase64(device.advertisData);
+    }
+    
+    // 解析广播数据
+    const parsed = parseAdvertisementData(device.advertisData);
+    Object.assign(normalized, parsed);
+  }
+  
+  // 处理制造商数据
+  if (device.manufacturerData) {
+    normalized.manufacturerData = device.manufacturerData;
+  }
+  
+  // 处理服务UUID
+  if (device.serviceUuids) {
+    normalized.serviceUuids = device.serviceUuids;
+  }
+  
+  // 平台特定数据
+  normalized.platformData = {
+    raw: device,
+  };
+  
+  return normalized;
+}
+
+/**
+ * 格式化 UUID (统一格式)
+ */
+export function formatUUID(uuid: string): string {
+  // 移除所有非十六进制字符
+  const clean = uuid.toLowerCase().replace(/[^0-9a-f]/g, '');
+  
+  if (clean.length === 4) {
+    // 16-bit UUID
+    return `0000${clean}-0000-1000-8000-00805f9b34fb`;
+  } else if (clean.length === 8) {
+    // 32-bit UUID
+    return `${clean}-0000-1000-8000-00805f9b34fb`;
+  } else if (clean.length === 32) {
+    // 128-bit UUID
+    return `${clean.slice(0, 8)}-${clean.slice(8, 12)}-${clean.slice(12, 16)}-${clean.slice(16, 20)}-${clean.slice(20)}`;
+  }
+  
+  return uuid;
+}
+
+/**
+ * 检查 UUID 是否匹配
+ */
+export function matchUUID(uuid1: string, uuid2: string): boolean {
+  return formatUUID(uuid1) === formatUUID(uuid2);
+}

package/src/utils/errors.ts

@@ -0,0 +1,105 @@
+import { BLEError } from '../types';
+
+/**
+ * 错误码定义
+ */
+export const ErrorCodes: Record<string, number> = {
+  // 通用错误
+  UNKNOWN_ERROR: 1000,
+  NOT_INITIALIZED: 1001,
+  ALREADY_SCANNING: 1002,
+  NOT_SCANNING: 1003,
+  PERMISSION_DENIED: 1004,
+  BLUETOOTH_DISABLED: 1005,
+  UNSUPPORTED_PLATFORM: 1006,
+  
+  // 蓝牙特定错误
+  ADAPTER_NOT_AVAILABLE: 2001,
+  SCAN_FAILED: 2002,
+  DEVICE_NOT_FOUND: 2003,
+  CONNECTION_FAILED: 2004,
+  
+  // 平台特定错误
+  ANDROID_ERROR: 3000,
+  IOS_ERROR: 4000,
+  HARMONY_ERROR: 5000,
+};
+
+/**
+ * 创建错误对象
+ */
+export function createError(
+  code: number,
+  message: string,
+  platformCode?: number,
+  originalError?: any
+): BLEError {
+  return {
+    code,
+    message,
+    platformCode,
+    originalError
+  };
+}
+
+/**
+ * 通用错误
+ */
+export const Errors = {
+  notInitialized: () => createError(
+    ErrorCodes.NOT_INITIALIZED,
+    '蓝牙适配器未初始化，请先调用 init()'
+  ),
+  alreadyScanning: () => createError(
+    ErrorCodes.ALREADY_SCANNING,
+    '扫描已在进行中'
+  ),
+  notScanning: () => createError(
+    ErrorCodes.NOT_SCANNING,
+    '扫描未在进行中'
+  ),
+  permissionDenied: () => createError(
+    ErrorCodes.PERMISSION_DENIED,
+    '蓝牙权限被拒绝'
+  ),
+  bluetoothDisabled: () => createError(
+    ErrorCodes.BLUETOOTH_DISABLED,
+    '蓝牙未开启'
+  ),
+  unsupportedPlatform: () => createError(
+    ErrorCodes.UNSUPPORTED_PLATFORM,
+    '当前平台不支持蓝牙功能'
+  ),
+  adapterNotAvailable: () => createError(
+    ErrorCodes.ADAPTER_NOT_AVAILABLE,
+    '蓝牙适配器不可用'
+  ),
+  scanFailed: (reason?: string) => createError(
+    ErrorCodes.SCAN_FAILED,
+    `扫描失败: ${reason || '未知原因'}`
+  ),
+};
+
+/**
+ * 处理平台特定错误
+ */
+export function handlePlatformError(error: any, platform: string): BLEError {
+  const platformCode = error?.code || error?.errCode;
+  const message = error?.message || error?.errMsg || '未知错误';
+  
+  let code = ErrorCodes.UNKNOWN_ERROR;
+  
+  switch (platform) {
+    case 'android':
+      code = ErrorCodes.ANDROID_ERROR;
+      break;
+    case 'ios':
+      code = ErrorCodes.IOS_ERROR;
+      break;
+    case 'harmony':
+      code = ErrorCodes.HARMONY_ERROR;
+      break;
+  }
+  
+  return createError(code, `${platform}平台错误: ${message}`, platformCode, error);
+}