@fww_123/uni-ble-scanner 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 uni-ble-scanner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# uni-ble-scanner
+
+跨平台蓝牙低功耗（BLE）扫描组件，支持 Android、HarmonyOS 和 iOS 三大平台。
+
+## 特性
+
+- 🚀 **跨平台支持**：一套代码同时支持 Android、HarmonyOS 和 iOS
+- 📱 **多模式扫描**：支持 UniApp 标准 API 和原生 API 两种模式
+- 🔧 **灵活配置**：丰富的扫描选项和过滤器
+- 🎯 **类型安全**：完整的 TypeScript 类型支持
+- 📦 **轻量级**：无额外依赖，体积小巧
+- 🔋 **低功耗优化**：支持低功耗扫描模式
+
+## 安装
+
+```bash
+npm install uni-ble-scanner
+```
+
+## 快速开始
+
+### 1. 基础用法
+
+```typescript
+import { createScanner, ScanState } from 'uni-ble-scanner';
+
+// 创建扫描器
+const scanner = createScanner();
+
+// 初始化
+await scanner.init();
+
+// 开始扫描
+await scanner.startScan(
+  {
+    timeout: 10000,           // 扫描超时时间（毫秒）
+    allowDuplicates: false,   // 是否允许重复上报
+    rssiThreshold: -80,       // 信号强度阈值
+  },
+  {
+    onDeviceFound: (device) => {
+      console.log('发现设备:', device.name, device.deviceId, device.RSSI);
+    },
+    onScanStart: () => {
+      console.log('扫描开始');
+    },
+    onScanStop: () => {
+      console.log('扫描停止');
+    },
+    onTimeout: () => {
+      console.log('扫描超时');
+    },
+    onError: (error) => {
+      console.error('扫描错误:', error);
+    },
+  }
+);
+
+// 停止扫描
+await scanner.stopScan();
+
+// 获取已发现的设备
+const devices = scanner.getDiscoveredDevices();
+
+// 销毁扫描器
+scanner.destroy();
+```
+
+### 2. 使用过滤器
+
+```typescript
+await scanner.startScan(
+  {
+    // 按名称过滤
+    nameFilter: ['Device', /Sensor/],
+    
+    // 按服务 UUID 过滤
+    services: ['0000180F-0000-1000-8000-00805F9B34FB'], // 电池服务
+    
+    // 按制造商 ID 过滤
+    manufacturerFilter: [0x004C], // Apple
+    
+    // 信号强度阈值
+    rssiThreshold: -70,
+  },
+  {
+    onDeviceFound: (device) => {
+      console.log('符合条件的设备:', device);
+    },
+  }
+);
+```
+
+### 3. 平台特定配置
+
+```typescript
+import { createScanner, Platform } from 'uni-ble-scanner';
+
+const scanner = createScanner({
+  type: 'native', // 使用原生 API
+  platformConfig: {
+    // Android 配置
+    android: {
+      scanMode: 2, // SCAN_MODE_LOW_LATENCY
+      callbackType: 1, // CALLBACK_TYPE_ALL_MATCHES
+    },
+    // iOS 配置
+    ios: {
+      allowBackgroundScan: true,
+      restoreIdentifier: 'com.example.ble-scanner',
+    },
+    // 鸿蒙配置
+    harmony: {
+      // 鸿蒙特定配置
+    },
+  },
+});
+```
+
+### 4. 权限处理
+
+```typescript
+// 检查权限
+const hasPermission = await scanner.checkPermissions();
+if (!hasPermission) {
+  // 请求权限
+  const granted = await scanner.requestPermissions();
+  if (!granted) {
+    console.log('用户拒绝了蓝牙权限');
+    return;
+  }
+}
+```
+
+### 5. 监听适配器状态
+
+```typescript
+scanner.onAdapterStateChange((state) => {
+  console.log('蓝牙适配器状态:', state);
+  // state.available: 是否可用
+  // state.discovering: 是否正在扫描
+});
+```
+
+## API 文档
+
+### createScanner(options?)
+
+创建蓝牙扫描器实例。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| options.type | `'auto' \| 'uniapp' \| 'native'` | 扫描器类型，默认 `'auto'` |
+| options.platformConfig | `PlatformConfig` | 平台特定配置 |
+
+**返回值：** `IBLEScanner`
+
+### IBLEScanner 接口
+
+#### 方法
+
+| 方法 | 返回值 | 说明 |
+|------|--------|------|
+| `init()` | `Promise<void>` | 初始化蓝牙适配器 |
+| `startScan(options?, callbacks?)` | `Promise<void>` | 开始扫描 |
+| `stopScan()` | `Promise<void>` | 停止扫描 |
+| `getDiscoveredDevices()` | `BLEDevice[]` | 获取已发现的设备列表 |
+| `clearDevices()` | `void` | 清空设备列表 |
+| `getState()` | `ScanState` | 获取当前扫描状态 |
+| `getPlatform()` | `Platform` | 获取当前平台 |
+| `checkPermissions()` | `Promise<boolean>` | 检查蓝牙权限 |
+| `requestPermissions()` | `Promise<boolean>` | 请求蓝牙权限 |
+| `onAdapterStateChange(callback)` | `void` | 监听适配器状态变化 |
+| `destroy()` | `void` | 销毁扫描器 |
+
+#### ScanOptions
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| timeout | `number` | `10000` | 扫描超时时间（毫秒） |
+| allowDuplicates | `boolean` | `false` | 是否允许重复上报同一设备 |
+| services | `string[]` | - | 要扫描的服务 UUID 列表 |
+| nameFilter | `string \| string[] \| RegExp` | - | 设备名称过滤器 |
+| rssiThreshold | `number` | - | 信号强度阈值（dBm） |
+| manufacturerFilter | `number \| number[]` | - | 制造商 ID 过滤器 |
+
+#### BLEDevice
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| deviceId | `string` | 设备 ID（MAC 地址或 UUID） |
+| name | `string` | 设备名称 |
+| RSSI | `number` | 信号强度（dBm） |
+| advertisData | `ArrayBuffer` | 广播数据 |
+| advertisDataBase64 | `string` | 广播数据（Base64） |
+| manufacturerData | `Record<string, ArrayBuffer>` | 制造商数据 |
+| serviceUuids | `string[]` | 服务 UUID 列表 |
+| localName | `string` | 本地名称 |
+| isConnectable | `boolean` | 是否可连接 |
+| txPowerLevel | `number` | 发射功率 |
+
+## 平台支持
+
+| 平台 | UniApp API | 原生 API |
+|------|------------|----------|
+| Android | ✅ | ✅ |
+| iOS | ✅ | ✅ |
+| HarmonyOS | ✅ | ✅ |
+| 微信小程序 | ✅ | ❌ |
+| H5 | ⚠️ | ❌ |
+
+## 注意事项
+
+### Android
+
+1. **权限要求**：
+   - Android 12+ 需要 `BLUETOOTH_SCAN` 和 `BLUETOOTH_CONNECT` 权限
+   - Android 11 及以下需要 `BLUETOOTH` 和 `BLUETOOTH_ADMIN` 权限
+   - 所有版本都需要位置权限
+
+2. **配置 `manifest.json`**：
+```json
+{
+  "permissions": {
+    "Bluetooth": {
+      "description": "使用蓝牙功能"
+    }
+  }
+}
+```
+
+### iOS
+
+1. **Info.plist 配置**：
+```xml
+<key>NSBluetoothAlwaysUsageDescription</key>
+<string>需要使用蓝牙扫描设备</string>
+<key>NSBluetoothPeripheralUsageDescription</key>
+<string>需要使用蓝牙扫描设备</string>
+```
+
+### HarmonyOS
+
+1. **module.json5 配置**：
+```json
+{
+  "requestPermissions": [
+    {
+      "name": "ohos.permission.ACCESS_BLUETOOTH"
+    },
+    {
+      "name": "ohos.permission.LOCATION"
+    }
+  ]
+}
+```
+
+## 示例项目
+
+查看 `examples` 目录获取更多使用示例：
+
+- `basic-scan` - 基础扫描示例
+- `filtered-scan` - 带过滤器的扫描
+- `multi-platform` - 多平台配置示例
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 更新日志
+
+### v1.0.0
+
+- 初始版本发布
+- 支持 Android、HarmonyOS、iOS 三大平台
+- 支持 UniApp 标准 API 和原生 API
+- 提供完整的 TypeScript 类型支持

package/dist/core/base-scanner.d.ts

@@ -0,0 +1,99 @@
+import { BLEDevice, ScanOptions, ScanState, ScanCallbacks, IBLEScanner, AdapterState, Platform, PlatformConfig } from '../types';
+/**
+ * 扫描器基类
+ */
+export declare abstract class BaseScanner implements IBLEScanner {
+    protected state: ScanState;
+    protected discoveredDevices: Map<string, BLEDevice>;
+    protected callbacks: ScanCallbacks;
+    protected options: ScanOptions;
+    protected platformConfig: PlatformConfig;
+    protected initialized: boolean;
+    protected timeoutId: number | null;
+    protected adapterStateListeners: ((state: AdapterState) => void)[];
+    /**
+     * 获取当前平台
+     */
+    abstract getPlatform(): Platform;
+    /**
+     * 初始化蓝牙适配器
+     */
+    abstract init(): Promise<void>;
+    /**
+     * 平台特定的开始扫描实现
+     */
+    protected abstract startScanInternal(): Promise<void>;
+    /**
+     * 平台特定的停止扫描实现
+     */
+    protected abstract stopScanInternal(): Promise<void>;
+    /**
+     * 检查蓝牙权限
+     */
+    abstract checkPermissions(): Promise<boolean>;
+    /**
+     * 请求蓝牙权限
+     */
+    abstract requestPermissions(): Promise<boolean>;
+    /**
+     * 监听适配器状态变化
+     */
+    abstract onAdapterStateChange(callback: (state: AdapterState) => void): void;
+    /**
+     * 开始扫描
+     */
+    startScan(options?: ScanOptions, callbacks?: ScanCallbacks): Promise<void>;
+    /**
+     * 停止扫描
+     */
+    stopScan(): Promise<void>;
+    /**
+     * 获取已发现的设备列表
+     */
+    getDiscoveredDevices(): BLEDevice[];
+    /**
+     * 清空设备列表
+     */
+    clearDevices(): void;
+    /**
+     * 获取当前扫描状态
+     */
+    getState(): ScanState;
+    /**
+     * 销毁扫描器
+     */
+    destroy(): void;
+    /**
+     * 处理发现的设备
+     */
+    protected handleDeviceFound(rawDevice: any): void;
+    /**
+     * 过滤设备
+     */
+    protected filterDevice(device: BLEDevice): boolean;
+    /**
+     * 处理超时
+     */
+    protected handleTimeout(): void;
+    /**
+     * 处理错误
+     */
+    protected handleError(error: any): void;
+    /**
+     * 设置状态
+     */
+    protected setState(state: ScanState): void;
+    /**
+     * 清除超时定时器
+     */
+    protected clearTimeout(): void;
+    /**
+     * 获取默认选项
+     */
+    protected getDefaultOptions(): ScanOptions;
+    /**
+     * 触发适配器状态变化
+     */
+    protected emitAdapterStateChange(state: AdapterState): void;
+}
+//# sourceMappingURL=base-scanner.d.ts.map

package/dist/core/base-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-scanner.d.ts","sourceRoot":"","sources":["../../src/core/base-scanner.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,WAAW,EACX,SAAS,EACT,aAAa,EACb,WAAW,EACX,YAAY,EAEZ,QAAQ,EACR,cAAc,EAEf,MAAM,UAAU,CAAC;AAIlB;;GAEG;AACH,8BAAsB,WAAY,YAAW,WAAW;IACtD,SAAS,CAAC,KAAK,EAAE,SAAS,CAAkB;IAC5C,SAAS,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAa;IAChE,SAAS,CAAC,SAAS,EAAE,aAAa,CAAM;IACxC,SAAS,CAAC,OAAO,EAAE,WAAW,CAAM;IACpC,SAAS,CAAC,cAAc,EAAE,cAAc,CAAM;IAC9C,SAAS,CAAC,WAAW,UAAS;IAC9B,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC1C,SAAS,CAAC,qBAAqB,EAAE,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC,EAAE,CAAM;IAExE;;OAEG;IACH,QAAQ,CAAC,WAAW,IAAI,QAAQ;IAEhC;;OAEG;IACH,QAAQ,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAE9B;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAErD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAEpD;;OAEG;IACH,QAAQ,CAAC,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,oBAAoB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI;IAE5E;;OAEG;IACG,SAAS,CAAC,OAAO,GAAE,WAAgB,EAAE,SAAS,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CxF;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB/B;;OAEG;IACH,oBAAoB,IAAI,SAAS,EAAE;IAInC;;OAEG;IACH,YAAY,IAAI,IAAI;IAIpB;;OAEG;IACH,QAAQ,IAAI,SAAS;IAIrB;;OAEG;IACH,OAAO,IAAI,IAAI;IASf;;OAEG;IACH,SAAS,CAAC,iBAAiB,CAAC,SAAS,EAAE,GAAG,GAAG,IAAI;IA2BjD;;OAEG;IACH,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO;IA4DlD;;OAEG;IACH,SAAS,CAAC,aAAa,IAAI,IAAI;IAK/B;;OAEG;IACH,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAMvC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAI1C;;OAEG;IACH,SAAS,CAAC,YAAY,IAAI,IAAI;IAO9B;;OAEG;IACH,SAAS,CAAC,iBAAiB,IAAI,WAAW;IAO1C;;OAEG;IACH,SAAS,CAAC,sBAAsB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;CAG5D"}

package/dist/factory.d.ts

@@ -0,0 +1,44 @@
+import { IBLEScanner, Platform, PlatformConfig } from './types';
+import { getPlatform, isApp } from './utils/platform';
+/**
+ * 扫描器类型
+ */
+export type ScannerType = 'auto' | 'uniapp' | 'native';
+/**
+ * 创建扫描器的选项
+ */
+export interface CreateScannerOptions {
+    /** 扫描器类型 */
+    type?: ScannerType;
+    /** 平台特定配置 */
+    platformConfig?: PlatformConfig;
+}
+/**
+ * 创建蓝牙扫描器
+ * @param options 创建选项
+ * @returns 蓝牙扫描器实例
+ */
+export declare function createScanner(options?: CreateScannerOptions): IBLEScanner;
+/**
+ * 创建 UniApp 扫描器
+ * 使用 UniApp 标准蓝牙 API，兼容所有平台
+ */
+export declare function createUniAppScanner(platformConfig?: PlatformConfig): IBLEScanner;
+/**
+ * 创建原生扫描器
+ * 使用平台原生 API，功能更强大但需要特定条件
+ */
+export declare function createNativeScanner(platformConfig?: PlatformConfig): IBLEScanner;
+/**
+ * 获取当前平台
+ */
+export { getPlatform, Platform };
+/**
+ * 检查当前环境是否支持蓝牙
+ */
+export declare function isBluetoothSupported(): boolean;
+/**
+ * 检查当前环境是否是 APP
+ */
+export { isApp };
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAKhE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY;IACZ,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,aAAa;IACb,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,WAAW,CA2C7E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,WAAW,CAEhF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,WAAW,CAEhF;AAED;;GAEG;AACH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AAEjC;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAc9C;AAED;;GAEG;AACH,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export type { BLEDevice, ScanOptions, ScanCallbacks, AdapterState, BLEError, IBLEScanner, PlatformConfig, DeviceFilter, CreateScannerOptions, } from './types';
+export { ScanState, Platform } from './types';
+export { createScanner, createUniAppScanner, createNativeScanner, getPlatform, isBluetoothSupported, isApp, } from './factory';
+export { ErrorCodes, createError, Errors } from './utils/errors';
+export { parseAdvertisementData, base64ToArrayBuffer, arrayBufferToBase64, formatUUID, matchUUID, } from './utils/data-parser';
+export { checkPermissions, requestPermissions } from './utils/permissions';
+export { isPlatform, getPlatformName } from './utils/platform';
+export { BaseScanner } from './core/base-scanner';
+export { UniAppScanner } from './platforms/uniapp-scanner';
+export { AndroidNativeScanner } from './platforms/android-native';
+export { IOSNativeScanner } from './platforms/ios-native';
+export { HarmonyNativeScanner } from './platforms/harmony-native';
+import { createScanner } from './factory';
+export default createScanner;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,WAAW,EACX,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,cAAc,EACd,YAAY,EACZ,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG9C,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,oBAAoB,EACpB,KAAK,GACN,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGjE,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,SAAS,GACV,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG3E,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAG/D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAGlE,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,eAAe,aAAa,CAAC"}