vite-uni-dev-tool 1.1.0 → 1.2.0

package/dist/v3/hooks/useBluetooth/index.ts

@@ -1,561 +1,561 @@
-import type { DevTool } from '../../../type';
-import { ref, onUnmounted, watch } from 'vue';
-
-const useBluetooth = () => {
-  const devices = ref<DevTool.BluetoothItem[]>([]);
-  const isSearching = ref(false);
-  const error = ref<string | null>(null);
-  const adapterOpened = ref(false);
-  const connectedDeviceIds = ref<Set<string>>(new Set());
-  const pairedDeviceIds = ref<Set<string>>(new Set());
-
-  /**
-   * 检查当前平台是否支持蓝牙 API
-   */
-  const checkSupport = (_tag?: string) => {
-    const isSupported = typeof uni.openBluetoothAdapter === 'function';
-    if (!isSupported) {
-      error.value = '当前环境不支持蓝牙功能';
-      return false;
-    }
-    return true;
-  };
-
-  /**
-   * 初始化蓝牙适配器
-   * 在 uni-app 中，开启适配器会同时拉起经典和 BLE 的底层准备。
-   */
-  const openBluetoothAdapter = () => {
-    return new Promise((resolve, reject) => {
-      if (!checkSupport('openBluetoothAdapter')) {
-        return reject(new Error('不支持蓝牙'));
-      }
-      uni.openBluetoothAdapter({
-        // 当 mode 为 central 时不仅限于低功耗，默认会尽可能扫双模
-        mode: 'central',
-        success: (res) => {
-          adapterOpened.value = true;
-          error.value = null;
-
-          // 顺便获取本机的蓝牙适配器状态
-          if (typeof uni.getBluetoothAdapterState === 'function') {
-            uni.getBluetoothAdapterState({
-              success: (stateRes) => {
-                if (!stateRes.available) {
-                  error.value = '本机蓝牙不可用，请检查设置';
-                }
-              },
-            });
-          }
-
-          resolve(res);
-        },
-        fail: (err) => {
-          error.value = `初始化蓝牙适配器失败: ${err.errMsg}`;
-          reject(err);
-        },
-      });
-    });
-  };
-
-  /**
-   * 开始搜索附近的蓝牙外围设备
-   */
-  const startBluetoothDevicesDiscovery = () => {
-    if (!checkSupport('startDiscovery')) return;
-    if (isSearching.value) return;
-
-    const start = () => {
-      onBluetoothDeviceFound();
-
-      uni.startBluetoothDevicesDiscovery({
-        allowDuplicatesKey: false, // 改为 false，部分手机开启为 true 会搜不到经典蓝牙比如耳机
-        interval: 0, // 上报设备的间隔，0 为立即上报，部分低版本对并发有限制
-        powerLevel: 'high', // 尝试使用高功率扫描以囊括更远或信号较弱的经典蓝牙设备
-        success: () => {
-          isSearching.value = true;
-          error.value = null;
-
-          // 延迟获取一次补偿，以防部分设备被系统缓存而不会触发 onBluetoothDeviceFound
-          // 给到更宽裕的时间（3秒）让底层蓝牙扫描有足够时间建立连接与发现回调
-          setTimeout(() => {
-            if (isSearching.value) {
-              getBluetoothDevices();
-            }
-          }, 3000);
-        },
-        fail: (err: any) => {
-          let errorMsg = err.errMsg || '未知错误';
-          // 针对小程序及跨端环境补充典型的权限及硬件未开错误解释
-          if (err.errCode === 10001) {
-            errorMsg = '当前设备蓝牙未开或无权访问，请检查开关与位置权限';
-          }
-          error.value = `开始搜索失败: ${errorMsg} (${Date.now()})`; // 加时间戳强制触发 watch
-          uni.showToast({ title: errorMsg, icon: 'none', duration: 3000 });
-        },
-      });
-    };
-
-    if (!adapterOpened.value) {
-      openBluetoothAdapter()
-        .then(() => {
-          fetchConnectedDevices(); // 初始化蓝牙后立即拉取一次已连接
-          start();
-        })
-        .catch(() => {});
-    } else {
-      fetchConnectedDevices(); // 直接开启也会拉取一次
-      start();
-    }
-  };
-
-  /**
-   * 停止搜索附近的蓝牙外围设备
-   */
-  const stopBluetoothDevicesDiscovery = () => {
-    if (!checkSupport('stopDiscovery')) return;
-    if (!isSearching.value) return;
-    uni.stopBluetoothDevicesDiscovery({
-      success: () => {
-        isSearching.value = false;
-      },
-      fail: (err) => {
-        error.value = `停止搜索失败: ${err.errMsg}`;
-      },
-    });
-  };
-
-  /**
-   * 猜测设备类型
-   */
-  const guessDeviceType = (rawDevice: unknown) => {
-    const device = rawDevice as Record<string, unknown>;
-    const name = (
-      (device.name as string) ||
-      (device.localName as string) ||
-      ''
-    ).toLowerCase();
-
-    // 耳机、音响类特征
-    if (
-      name.includes('airpods') ||
-      name.includes('buds') ||
-      name.includes('headphones') ||
-      name.includes('ear') ||
-      name.includes('headset') ||
-      name.includes('audio') ||
-      name.includes('speaker') ||
-      /[\u8033\u673a\u97f3\u54cd]/.test(name)
-    ) {
-      return '蓝牙耳机/音响';
-    }
-
-    // 手机、平板电脑类特征
-    if (
-      name.includes('iphone') ||
-      name.includes('ipad') ||
-      name.includes('mac') ||
-      name.includes('android') ||
-      name.includes('phone') ||
-      name.includes('tablet') ||
-      name.includes('pixel') ||
-      name.includes('galaxy') ||
-      /[\u624b\u673a\u5e73\u677f\u7535\u8111]/.test(name)
-    ) {
-      return '手机/电脑/平板';
-    }
-
-    // 手表、手环类特征
-    if (
-      name.includes('watch') ||
-      name.includes('band') ||
-      name.includes('bracelet') ||
-      /[\u624b\u8868\u624b\u73af]/.test(name)
-    ) {
-      return '智能手表/手环';
-    }
-
-    // 如果没有任何特征且没有低功耗服务，我们再降级到经典蓝牙
-    const isProbablyClassic =
-      !(device.advertisServiceUUIDs as string[])?.length &&
-      !device.localName &&
-      !device.name;
-
-    if (isProbablyClassic) {
-      return '未知外设(经典蓝牙?)';
-    }
-
-    return 'BLE/常规外设';
-  };
-
-  /**
-   * 监听寻找到新设备的事件
-   */
-  const onBluetoothDeviceFound = () => {
-    if (!checkSupport('onDeviceFound')) return;
-    uni.onBluetoothDeviceFound((res) => {
-      if (res.devices) {
-        res.devices.forEach((device) => {
-          const enhancedDevice = {
-            ...device,
-            _guessType: guessDeviceType(device),
-            _isConnected: connectedDeviceIds.value.has(device.deviceId),
-            isPaired:
-              !!(device as unknown as Record<string, unknown>).isPaired ||
-              pairedDeviceIds.value.has(device.deviceId),
-          } as unknown as DevTool.BluetoothItem;
-
-          const index = devices.value.findIndex(
-            (d) => d.deviceId === device.deviceId,
-          );
-          if (index === -1) {
-            devices.value.push(
-              enhancedDevice as unknown as DevTool.BluetoothItem,
-            );
-          } else {
-            devices.value[index] =
-              enhancedDevice as unknown as DevTool.BluetoothItem;
-          }
-        });
-      }
-    });
-  };
-
-  /**
-   * 获取在蓝牙模块生效期间所有已发现的蓝牙设备
-   */
-  const getBluetoothDevices = () => {
-    if (!checkSupport('getBluetoothDevices')) return;
-    uni.getBluetoothDevices({
-      success: (res) => {
-        if (res.devices) {
-          res.devices.forEach((device) => {
-            const enhancedDevice = {
-              ...device,
-              _guessType: guessDeviceType(device),
-              _isConnected: connectedDeviceIds.value.has(device.deviceId),
-              isPaired:
-                !!(device as unknown as Record<string, unknown>).isPaired ||
-                pairedDeviceIds.value.has(device.deviceId),
-            } as unknown as DevTool.BluetoothItem;
-
-            const index = devices.value.findIndex(
-              (d) => d.deviceId === device.deviceId,
-            );
-            if (index === -1) {
-              devices.value.push(
-                enhancedDevice as unknown as DevTool.BluetoothItem,
-              );
-            } else {
-              devices.value[index] =
-                enhancedDevice as unknown as DevTool.BluetoothItem;
-            }
-          });
-        }
-      },
-      fail: (err) => {
-        error.value = `获取设备列表失败: ${err.errMsg}`;
-      },
-    });
-  };
-
-  /**
-   * 获取当前处于已连接状态的设备
-   */
-  const fetchConnectedDevices = () => {
-    if (!checkSupport()) return;
-    // 微信小程序平台不传 services 可以获取当前所以已经配对或者连接的设备
-    // @ts-ignore
-    uni.getConnectedBluetoothDevices({
-      success: (res) => {
-        const ids = new Set(res.devices.map((d) => d.deviceId));
-        connectedDeviceIds.value = ids;
-
-        // 无论如何，这些在连接系统池里拿到的绝对存在配对关系
-        res.devices.forEach((d) => pairedDeviceIds.value.add(d.deviceId));
-
-        // 如果获取到了已连接（或已配对）的设备，即便它没有出现在 discovery 广播里，也可以强行把它加入了展示列表中
-        res.devices.forEach((device) => {
-          const deviceExt = device as unknown as Record<string, unknown>;
-
-          const enhancedDevice = {
-            ...deviceExt,
-            _guessType: guessDeviceType(deviceExt),
-            _isConnected: true,
-            isPaired: true, // 能获取到 connected 肯定也代表配对或者已链接过
-          } as unknown as DevTool.BluetoothItem;
-
-          const index = devices.value.findIndex(
-            (d) => d.deviceId === device.deviceId,
-          );
-          if (index === -1) {
-            devices.value.push(enhancedDevice);
-          } else {
-            // 如果已经在列表中，只需更新连接与配对状态
-            (devices.value[index] as Record<string, unknown>)._isConnected =
-              true;
-            (devices.value[index] as Record<string, unknown>).isPaired = true;
-          }
-        });
-      },
-      fail: (err) => {
-        console.error(
-          '[Bluetooth Debug] fetchConnectedDevices 获取由于底层限制失败: ',
-          err,
-        );
-      },
-    });
-  };
-
-  /**
-   * 连接蓝牙设备 (低功耗蓝牙)
-   */
-  const connectDevice = (deviceId: string) => {
-    return new Promise((resolve, reject) => {
-      if (!checkSupport()) return reject(new Error('未支持 API'));
-
-      // 在尝试连接前最好先停止搜索，可以提高连接成功率
-      stopBluetoothDevicesDiscovery();
-
-      uni.createBLEConnection({
-        deviceId,
-        timeout: 5000,
-        success: (res) => {
-          connectedDeviceIds.value.add(deviceId);
-
-          // 更新本地列表状态
-          const index = devices.value.findIndex((d) => d.deviceId === deviceId);
-          if (index !== -1) {
-            (devices.value[index] as Record<string, unknown>)._isConnected =
-              true;
-          }
-
-          resolve(res);
-        },
-        fail: (err) => {
-          error.value = `连接设备失败: ${err.errMsg || '未知错误'}`;
-          reject(err);
-        },
-      });
-    });
-  };
-
-  /**
-   * 断开蓝牙设备连接
-   */
-  const disconnectDevice = (deviceId: string) => {
-    return new Promise((resolve, reject) => {
-      uni.closeBLEConnection({
-        deviceId,
-        success: (res) => {
-          connectedDeviceIds.value.delete(deviceId);
-          const index = devices.value.findIndex((d) => d.deviceId === deviceId);
-          if (index !== -1) {
-            (devices.value[index] as Record<string, unknown>)._isConnected =
-              false;
-          }
-          resolve(res);
-        },
-        fail: (err) => {
-          error.value = `断开连接失败: ${err.errMsg || '未知错误'}`;
-          reject(err);
-        },
-      });
-    });
-  };
-
-  /**
-   * 发起蓝牙配对
-   * 注意：在 uni-app/小程序 底层通常不支持前台主动进行单纯的"配对"(makePair)。
-   * 标准流程是通过直接发起 `createBLEConnection` (这里复用 connectDevice)，
-   * 底层系统底层需要权限时会自动弹出配对 PIN 输入框。
-   */
-  const pairDevice = (deviceId: string) => {
-    // 某些特定的 App 或 框架可能支持 `uni.makeBluetoothPair`，这里做平滑兼容
-    if (typeof (uni as any).makeBluetoothPair === 'function') {
-      return new Promise((resolve, reject) => {
-        (uni as any).makeBluetoothPair({
-          deviceId,
-          success: (res: any) => {
-            pairedDeviceIds.value.add(deviceId);
-            const index = devices.value.findIndex(
-              (d) => d.deviceId === deviceId,
-            );
-            if (index !== -1) {
-              (devices.value[index] as Record<string, unknown>).isPaired = true;
-            }
-            resolve(res);
-          },
-          fail: (err: any) => {
-            error.value = `请求配对失败: ${err.errMsg || '未知错误'}`;
-            reject(err);
-          },
-        });
-      });
-    } else {
-      // 否则回退到直接调用连接，系统在必要的 GATT 特征下会自动转为系统级配对弹窗
-      return connectDevice(deviceId);
-    }
-  };
-
-  /**
-   * 获取蓝牙设备的所有服务 (Services)
-   */
-  const getBLEServices = (deviceId: string) => {
-    return new Promise<unknown[]>((resolve, reject) => {
-      uni.getBLEDeviceServices({
-        deviceId,
-        success: (res) => resolve(res.services),
-        fail: (err) => {
-          error.value = `获取服务失败: ${err.errMsg || '未知错误'}`;
-          reject(err);
-        },
-      });
-    });
-  };
-
-  /**
-   * 获取某个服务下的所有特征值 (Characteristics)
-   */
-  const getBLECharacteristics = (deviceId: string, serviceId: string) => {
-    return new Promise<unknown[]>((resolve, reject) => {
-      uni.getBLEDeviceCharacteristics({
-        deviceId,
-        serviceId,
-        success: (res) => resolve(res.characteristics as unknown[]),
-        fail: (err) => {
-          error.value = `获取特征值失败: ${err.errMsg || '未知错误'}`;
-          reject(err);
-        },
-      });
-    });
-  };
-
-  /**
-   * 向指定的特征值发送(写入)消息
-   */
-  const writeBLEMessage = (
-    deviceId: string,
-    serviceId: string,
-    characteristicId: string,
-    buffer: ArrayBuffer,
-    writeType?: 'write' | 'writeNoResponse',
-  ) => {
-    return new Promise((resolve, reject) => {
-      // 强制克隆一份彻底规避 Proxy，同时确保它是普通 ArrayBuffer 的底层形态
-      const cloneBuffer = new ArrayBuffer(buffer.byteLength);
-      const dataView = new DataView(cloneBuffer);
-      const sourceView = new Uint8Array(buffer);
-      for (let i = 0; i < sourceView.length; i++) {
-        dataView.setUint8(i, sourceView[i]);
-      }
-
-      const params: any = {
-        deviceId,
-        serviceId,
-        characteristicId,
-        value: cloneBuffer, // 送入完全干净的原生构造 Buffer
-        success: (res: any) => resolve(res),
-        fail: (err: any) => {
-          error.value = `发送消息失败: ${err.errMsg || '未知错误'}`;
-          reject(err);
-        },
-      };
-
-      if (writeType) {
-        params.writeType = writeType;
-      }
-
-      uni.writeBLECharacteristicValue(params);
-    });
-  };
-
-  /**
-   * 订阅特征值的消息变化 (Notify)
-   */
-  const subscribeBLEMessage = (
-    deviceId: string,
-    serviceId: string,
-    characteristicId: string,
-    state = true,
-  ) => {
-    return new Promise((resolve, reject) => {
-      uni.notifyBLECharacteristicValueChange({
-        deviceId,
-        serviceId,
-        characteristicId,
-        state,
-        success: (res) => resolve(res),
-        fail: (err) => {
-          error.value = `订阅消息失败: ${err.errMsg || '未知错误'}`;
-          reject(err);
-        },
-      });
-    });
-  };
-
-  /**
-   * 监听全局接收到的蓝牙设备消息
-   */
-  const onBLEMessageReceived = (callback: (res: unknown) => void) => {
-    if (typeof uni.onBLECharacteristicValueChange === 'function') {
-      uni.onBLECharacteristicValueChange(callback as any);
-    }
-  };
-
-  /**
-   * 关闭蓝牙模块
-   */
-  const closeBluetoothAdapter = () => {
-    if (!checkSupport()) return;
-    uni.closeBluetoothAdapter({
-      success: () => {
-        adapterOpened.value = false;
-        isSearching.value = false;
-        devices.value = [];
-        connectedDeviceIds.value.clear();
-        pairedDeviceIds.value.clear();
-      },
-    });
-  };
-
-  onUnmounted(() => {
-    if (typeof uni.stopBluetoothDevicesDiscovery === 'function') {
-      stopBluetoothDevicesDiscovery();
-    }
-  });
-
-  watch(error, (newMsg) => {
-    if (newMsg) {
-      uni.showToast({
-        title: newMsg,
-        icon: 'none',
-        duration: 2000,
-      });
-    }
-  });
-
-  return {
-    devices,
-    isSearching,
-    error,
-    adapterOpened,
-    checkSupport,
-    openBluetoothAdapter,
-    startBluetoothDevicesDiscovery,
-    stopBluetoothDevicesDiscovery,
-    getBluetoothDevices,
-    fetchConnectedDevices,
-    connectDevice,
-    disconnectDevice,
-    pairDevice,
-    getBLEServices,
-    getBLECharacteristics,
-    writeBLEMessage,
-    subscribeBLEMessage,
-    onBLEMessageReceived,
-    closeBluetoothAdapter,
-  };
-};
-
-export default useBluetooth;
+import type { DevTool } from '../../../type';
+import { ref, onUnmounted, watch } from 'vue';
+
+const useBluetooth = () => {
+  const devices = ref<DevTool.BluetoothItem[]>([]);
+  const isSearching = ref(false);
+  const error = ref<string | null>(null);
+  const adapterOpened = ref(false);
+  const connectedDeviceIds = ref<Set<string>>(new Set());
+  const pairedDeviceIds = ref<Set<string>>(new Set());
+
+  /**
+   * 检查当前平台是否支持蓝牙 API
+   */
+  const checkSupport = (_tag?: string) => {
+    const isSupported = typeof uni.openBluetoothAdapter === 'function';
+    if (!isSupported) {
+      error.value = '当前环境不支持蓝牙功能';
+      return false;
+    }
+    return true;
+  };
+
+  /**
+   * 初始化蓝牙适配器
+   * 在 uni-app 中，开启适配器会同时拉起经典和 BLE 的底层准备。
+   */
+  const openBluetoothAdapter = () => {
+    return new Promise((resolve, reject) => {
+      if (!checkSupport('openBluetoothAdapter')) {
+        return reject(new Error('不支持蓝牙'));
+      }
+      uni.openBluetoothAdapter({
+        // 当 mode 为 central 时不仅限于低功耗，默认会尽可能扫双模
+        mode: 'central',
+        success: (res) => {
+          adapterOpened.value = true;
+          error.value = null;
+
+          // 顺便获取本机的蓝牙适配器状态
+          if (typeof uni.getBluetoothAdapterState === 'function') {
+            uni.getBluetoothAdapterState({
+              success: (stateRes) => {
+                if (!stateRes.available) {
+                  error.value = '本机蓝牙不可用，请检查设置';
+                }
+              },
+            });
+          }
+
+          resolve(res);
+        },
+        fail: (err) => {
+          error.value = `初始化蓝牙适配器失败: ${err.errMsg}`;
+          reject(err);
+        },
+      });
+    });
+  };
+
+  /**
+   * 开始搜索附近的蓝牙外围设备
+   */
+  const startBluetoothDevicesDiscovery = () => {
+    if (!checkSupport('startDiscovery')) return;
+    if (isSearching.value) return;
+
+    const start = () => {
+      onBluetoothDeviceFound();
+
+      uni.startBluetoothDevicesDiscovery({
+        allowDuplicatesKey: false, // 改为 false，部分手机开启为 true 会搜不到经典蓝牙比如耳机
+        interval: 0, // 上报设备的间隔，0 为立即上报，部分低版本对并发有限制
+        powerLevel: 'high', // 尝试使用高功率扫描以囊括更远或信号较弱的经典蓝牙设备
+        success: () => {
+          isSearching.value = true;
+          error.value = null;
+
+          // 延迟获取一次补偿，以防部分设备被系统缓存而不会触发 onBluetoothDeviceFound
+          // 给到更宽裕的时间（3秒）让底层蓝牙扫描有足够时间建立连接与发现回调
+          setTimeout(() => {
+            if (isSearching.value) {
+              getBluetoothDevices();
+            }
+          }, 3000);
+        },
+        fail: (err: any) => {
+          let errorMsg = err.errMsg || '未知错误';
+          // 针对小程序及跨端环境补充典型的权限及硬件未开错误解释
+          if (err.errCode === 10001) {
+            errorMsg = '当前设备蓝牙未开或无权访问，请检查开关与位置权限';
+          }
+          error.value = `开始搜索失败: ${errorMsg} (${Date.now()})`; // 加时间戳强制触发 watch
+          uni.showToast({ title: errorMsg, icon: 'none', duration: 3000 });
+        },
+      });
+    };
+
+    if (!adapterOpened.value) {
+      openBluetoothAdapter()
+        .then(() => {
+          fetchConnectedDevices(); // 初始化蓝牙后立即拉取一次已连接
+          start();
+        })
+        .catch(() => {});
+    } else {
+      fetchConnectedDevices(); // 直接开启也会拉取一次
+      start();
+    }
+  };
+
+  /**
+   * 停止搜索附近的蓝牙外围设备
+   */
+  const stopBluetoothDevicesDiscovery = () => {
+    if (!checkSupport('stopDiscovery')) return;
+    if (!isSearching.value) return;
+    uni.stopBluetoothDevicesDiscovery({
+      success: () => {
+        isSearching.value = false;
+      },
+      fail: (err) => {
+        error.value = `停止搜索失败: ${err.errMsg}`;
+      },
+    });
+  };
+
+  /**
+   * 猜测设备类型
+   */
+  const guessDeviceType = (rawDevice: unknown) => {
+    const device = rawDevice as Record<string, unknown>;
+    const name = (
+      (device.name as string) ||
+      (device.localName as string) ||
+      ''
+    ).toLowerCase();
+
+    // 耳机、音响类特征
+    if (
+      name.includes('airpods') ||
+      name.includes('buds') ||
+      name.includes('headphones') ||
+      name.includes('ear') ||
+      name.includes('headset') ||
+      name.includes('audio') ||
+      name.includes('speaker') ||
+      /[\u8033\u673a\u97f3\u54cd]/.test(name)
+    ) {
+      return '蓝牙耳机/音响';
+    }
+
+    // 手机、平板电脑类特征
+    if (
+      name.includes('iphone') ||
+      name.includes('ipad') ||
+      name.includes('mac') ||
+      name.includes('android') ||
+      name.includes('phone') ||
+      name.includes('tablet') ||
+      name.includes('pixel') ||
+      name.includes('galaxy') ||
+      /[\u624b\u673a\u5e73\u677f\u7535\u8111]/.test(name)
+    ) {
+      return '手机/电脑/平板';
+    }
+
+    // 手表、手环类特征
+    if (
+      name.includes('watch') ||
+      name.includes('band') ||
+      name.includes('bracelet') ||
+      /[\u624b\u8868\u624b\u73af]/.test(name)
+    ) {
+      return '智能手表/手环';
+    }
+
+    // 如果没有任何特征且没有低功耗服务，我们再降级到经典蓝牙
+    const isProbablyClassic =
+      !(device.advertisServiceUUIDs as string[])?.length &&
+      !device.localName &&
+      !device.name;
+
+    if (isProbablyClassic) {
+      return '未知外设(经典蓝牙?)';
+    }
+
+    return 'BLE/常规外设';
+  };
+
+  /**
+   * 监听寻找到新设备的事件
+   */
+  const onBluetoothDeviceFound = () => {
+    if (!checkSupport('onDeviceFound')) return;
+    uni.onBluetoothDeviceFound((res) => {
+      if (res.devices) {
+        res.devices.forEach((device) => {
+          const enhancedDevice = {
+            ...device,
+            _guessType: guessDeviceType(device),
+            _isConnected: connectedDeviceIds.value.has(device.deviceId),
+            isPaired:
+              !!(device as unknown as Record<string, unknown>).isPaired ||
+              pairedDeviceIds.value.has(device.deviceId),
+          } as unknown as DevTool.BluetoothItem;
+
+          const index = devices.value.findIndex(
+            (d) => d.deviceId === device.deviceId,
+          );
+          if (index === -1) {
+            devices.value.push(
+              enhancedDevice as unknown as DevTool.BluetoothItem,
+            );
+          } else {
+            devices.value[index] =
+              enhancedDevice as unknown as DevTool.BluetoothItem;
+          }
+        });
+      }
+    });
+  };
+
+  /**
+   * 获取在蓝牙模块生效期间所有已发现的蓝牙设备
+   */
+  const getBluetoothDevices = () => {
+    if (!checkSupport('getBluetoothDevices')) return;
+    uni.getBluetoothDevices({
+      success: (res) => {
+        if (res.devices) {
+          res.devices.forEach((device) => {
+            const enhancedDevice = {
+              ...device,
+              _guessType: guessDeviceType(device),
+              _isConnected: connectedDeviceIds.value.has(device.deviceId),
+              isPaired:
+                !!(device as unknown as Record<string, unknown>).isPaired ||
+                pairedDeviceIds.value.has(device.deviceId),
+            } as unknown as DevTool.BluetoothItem;
+
+            const index = devices.value.findIndex(
+              (d) => d.deviceId === device.deviceId,
+            );
+            if (index === -1) {
+              devices.value.push(
+                enhancedDevice as unknown as DevTool.BluetoothItem,
+              );
+            } else {
+              devices.value[index] =
+                enhancedDevice as unknown as DevTool.BluetoothItem;
+            }
+          });
+        }
+      },
+      fail: (err) => {
+        error.value = `获取设备列表失败: ${err.errMsg}`;
+      },
+    });
+  };
+
+  /**
+   * 获取当前处于已连接状态的设备
+   */
+  const fetchConnectedDevices = () => {
+    if (!checkSupport()) return;
+    // 微信小程序平台不传 services 可以获取当前所以已经配对或者连接的设备
+    // @ts-ignore
+    uni.getConnectedBluetoothDevices({
+      success: (res) => {
+        const ids = new Set(res.devices.map((d) => d.deviceId));
+        connectedDeviceIds.value = ids;
+
+        // 无论如何，这些在连接系统池里拿到的绝对存在配对关系
+        res.devices.forEach((d) => pairedDeviceIds.value.add(d.deviceId));
+
+        // 如果获取到了已连接（或已配对）的设备，即便它没有出现在 discovery 广播里，也可以强行把它加入了展示列表中
+        res.devices.forEach((device) => {
+          const deviceExt = device as unknown as Record<string, unknown>;
+
+          const enhancedDevice = {
+            ...deviceExt,
+            _guessType: guessDeviceType(deviceExt),
+            _isConnected: true,
+            isPaired: true, // 能获取到 connected 肯定也代表配对或者已链接过
+          } as unknown as DevTool.BluetoothItem;
+
+          const index = devices.value.findIndex(
+            (d) => d.deviceId === device.deviceId,
+          );
+          if (index === -1) {
+            devices.value.push(enhancedDevice);
+          } else {
+            // 如果已经在列表中，只需更新连接与配对状态
+            (devices.value[index] as Record<string, unknown>)._isConnected =
+              true;
+            (devices.value[index] as Record<string, unknown>).isPaired = true;
+          }
+        });
+      },
+      fail: (err) => {
+        console.error(
+          '[Bluetooth Debug] fetchConnectedDevices 获取由于底层限制失败: ',
+          err,
+        );
+      },
+    });
+  };
+
+  /**
+   * 连接蓝牙设备 (低功耗蓝牙)
+   */
+  const connectDevice = (deviceId: string) => {
+    return new Promise((resolve, reject) => {
+      if (!checkSupport()) return reject(new Error('未支持 API'));
+
+      // 在尝试连接前最好先停止搜索，可以提高连接成功率
+      stopBluetoothDevicesDiscovery();
+
+      uni.createBLEConnection({
+        deviceId,
+        timeout: 5000,
+        success: (res) => {
+          connectedDeviceIds.value.add(deviceId);
+
+          // 更新本地列表状态
+          const index = devices.value.findIndex((d) => d.deviceId === deviceId);
+          if (index !== -1) {
+            (devices.value[index] as Record<string, unknown>)._isConnected =
+              true;
+          }
+
+          resolve(res);
+        },
+        fail: (err) => {
+          error.value = `连接设备失败: ${err.errMsg || '未知错误'}`;
+          reject(err);
+        },
+      });
+    });
+  };
+
+  /**
+   * 断开蓝牙设备连接
+   */
+  const disconnectDevice = (deviceId: string) => {
+    return new Promise((resolve, reject) => {
+      uni.closeBLEConnection({
+        deviceId,
+        success: (res) => {
+          connectedDeviceIds.value.delete(deviceId);
+          const index = devices.value.findIndex((d) => d.deviceId === deviceId);
+          if (index !== -1) {
+            (devices.value[index] as Record<string, unknown>)._isConnected =
+              false;
+          }
+          resolve(res);
+        },
+        fail: (err) => {
+          error.value = `断开连接失败: ${err.errMsg || '未知错误'}`;
+          reject(err);
+        },
+      });
+    });
+  };
+
+  /**
+   * 发起蓝牙配对
+   * 注意：在 uni-app/小程序 底层通常不支持前台主动进行单纯的"配对"(makePair)。
+   * 标准流程是通过直接发起 `createBLEConnection` (这里复用 connectDevice)，
+   * 底层系统底层需要权限时会自动弹出配对 PIN 输入框。
+   */
+  const pairDevice = (deviceId: string) => {
+    // 某些特定的 App 或 框架可能支持 `uni.makeBluetoothPair`，这里做平滑兼容
+    if (typeof (uni as any).makeBluetoothPair === 'function') {
+      return new Promise((resolve, reject) => {
+        (uni as any).makeBluetoothPair({
+          deviceId,
+          success: (res: any) => {
+            pairedDeviceIds.value.add(deviceId);
+            const index = devices.value.findIndex(
+              (d) => d.deviceId === deviceId,
+            );
+            if (index !== -1) {
+              (devices.value[index] as Record<string, unknown>).isPaired = true;
+            }
+            resolve(res);
+          },
+          fail: (err: any) => {
+            error.value = `请求配对失败: ${err.errMsg || '未知错误'}`;
+            reject(err);
+          },
+        });
+      });
+    } else {
+      // 否则回退到直接调用连接，系统在必要的 GATT 特征下会自动转为系统级配对弹窗
+      return connectDevice(deviceId);
+    }
+  };
+
+  /**
+   * 获取蓝牙设备的所有服务 (Services)
+   */
+  const getBLEServices = (deviceId: string) => {
+    return new Promise<unknown[]>((resolve, reject) => {
+      uni.getBLEDeviceServices({
+        deviceId,
+        success: (res) => resolve(res.services),
+        fail: (err) => {
+          error.value = `获取服务失败: ${err.errMsg || '未知错误'}`;
+          reject(err);
+        },
+      });
+    });
+  };
+
+  /**
+   * 获取某个服务下的所有特征值 (Characteristics)
+   */
+  const getBLECharacteristics = (deviceId: string, serviceId: string) => {
+    return new Promise<unknown[]>((resolve, reject) => {
+      uni.getBLEDeviceCharacteristics({
+        deviceId,
+        serviceId,
+        success: (res) => resolve(res.characteristics as unknown[]),
+        fail: (err) => {
+          error.value = `获取特征值失败: ${err.errMsg || '未知错误'}`;
+          reject(err);
+        },
+      });
+    });
+  };
+
+  /**
+   * 向指定的特征值发送(写入)消息
+   */
+  const writeBLEMessage = (
+    deviceId: string,
+    serviceId: string,
+    characteristicId: string,
+    buffer: ArrayBuffer,
+    writeType?: 'write' | 'writeNoResponse',
+  ) => {
+    return new Promise((resolve, reject) => {
+      // 强制克隆一份彻底规避 Proxy，同时确保它是普通 ArrayBuffer 的底层形态
+      const cloneBuffer = new ArrayBuffer(buffer.byteLength);
+      const dataView = new DataView(cloneBuffer);
+      const sourceView = new Uint8Array(buffer);
+      for (let i = 0; i < sourceView.length; i++) {
+        dataView.setUint8(i, sourceView[i]);
+      }
+
+      const params: any = {
+        deviceId,
+        serviceId,
+        characteristicId,
+        value: cloneBuffer, // 送入完全干净的原生构造 Buffer
+        success: (res: any) => resolve(res),
+        fail: (err: any) => {
+          error.value = `发送消息失败: ${err.errMsg || '未知错误'}`;
+          reject(err);
+        },
+      };
+
+      if (writeType) {
+        params.writeType = writeType;
+      }
+
+      uni.writeBLECharacteristicValue(params);
+    });
+  };
+
+  /**
+   * 订阅特征值的消息变化 (Notify)
+   */
+  const subscribeBLEMessage = (
+    deviceId: string,
+    serviceId: string,
+    characteristicId: string,
+    state = true,
+  ) => {
+    return new Promise((resolve, reject) => {
+      uni.notifyBLECharacteristicValueChange({
+        deviceId,
+        serviceId,
+        characteristicId,
+        state,
+        success: (res) => resolve(res),
+        fail: (err) => {
+          error.value = `订阅消息失败: ${err.errMsg || '未知错误'}`;
+          reject(err);
+        },
+      });
+    });
+  };
+
+  /**
+   * 监听全局接收到的蓝牙设备消息
+   */
+  const onBLEMessageReceived = (callback: (res: unknown) => void) => {
+    if (typeof uni.onBLECharacteristicValueChange === 'function') {
+      uni.onBLECharacteristicValueChange(callback as any);
+    }
+  };
+
+  /**
+   * 关闭蓝牙模块
+   */
+  const closeBluetoothAdapter = () => {
+    if (!checkSupport()) return;
+    uni.closeBluetoothAdapter({
+      success: () => {
+        adapterOpened.value = false;
+        isSearching.value = false;
+        devices.value = [];
+        connectedDeviceIds.value.clear();
+        pairedDeviceIds.value.clear();
+      },
+    });
+  };
+
+  onUnmounted(() => {
+    if (typeof uni.stopBluetoothDevicesDiscovery === 'function') {
+      stopBluetoothDevicesDiscovery();
+    }
+  });
+
+  watch(error, (newMsg) => {
+    if (newMsg) {
+      uni.showToast({
+        title: newMsg,
+        icon: 'none',
+        duration: 2000,
+      });
+    }
+  });
+
+  return {
+    devices,
+    isSearching,
+    error,
+    adapterOpened,
+    checkSupport,
+    openBluetoothAdapter,
+    startBluetoothDevicesDiscovery,
+    stopBluetoothDevicesDiscovery,
+    getBluetoothDevices,
+    fetchConnectedDevices,
+    connectDevice,
+    disconnectDevice,
+    pairDevice,
+    getBLEServices,
+    getBLECharacteristics,
+    writeBLEMessage,
+    subscribeBLEMessage,
+    onBLEMessageReceived,
+    closeBluetoothAdapter,
+  };
+};
+
+export default useBluetooth;