更新记录

0.0.1（2025-07-17） 下载此版本

初始化模块

平台兼容性

uni-app

xs-bluebooth SDK 使用文档

1. 安装与引入

将 xs-bluebooth 模块放入 uni_modules 目录后，可直接在项目中引用。

import { useBle } from '@/uni_modules/xs-bluebooth/js_sdk';

2. 快速开始

获取蓝牙实例

const ble = useBle();

useBle 返回响应式的 Ble 单例对象，适合在 Vue 组件中直接使用。

3. 主要类与接口

3.1 Ble（蓝牙核心类）

主要属性

• available：蓝牙适配器是否可用（boolean）
• discovering：是否正在搜索设备（boolean）

主要方法

• check()：检查蓝牙权限和环境支持
• open()：打开蓝牙模块
• close()：关闭蓝牙模块
• startBluetoothDevicesDiscovery(options)：开始搜索附近蓝牙设备
  • options 可选，包含 services、allowDuplicatesKey、interval
• stopBluetoothDevicesDiscovery()：停止搜索
• getBluetoothDevices()：获取已发现的蓝牙设备列表
• findDevice(predicate, timeout)：查找符合条件的设备，predicate 为设备过滤函数，timeout 超时时间（毫秒）

示例

await ble.check();
await ble.open();
await ble.startBluetoothDevicesDiscovery();
const devices = await ble.getBluetoothDevices();
await ble.stopBluetoothDevicesDiscovery();
await ble.close();

3.2 Device（设备对象）

属性

• id：设备ID
• name：设备名称
• pin：设备PIN码
• meta：设备元数据
• connected：是否已连接

方法

• connect()：连接设备（需实现）
• disconnect()：断开设备（需实现）

3.3 Manager（设备管理器）

用于统一管理多个设备对象。

主要方法

• addDevice(options: IDeviceOptions)：添加设备
• getDevice(deviceId: string)：获取指定ID的设备
• removeDevice(deviceId: string)：移除设备
• clearDevice()：清空所有设备

示例

const manager = Manager.getInstance();
await manager.addDevice({ id: 'xxx', name: '设备1' });
const device = await manager.getDevice('xxx');
await manager.removeDevice('xxx');
await manager.clearDevice();

3.4 IDeviceOptions（设备参数接口）

interface IDeviceOptions {
    id: string; // 设备ID
    name?: string; // 设备名称
    pin?: string; // 设备PIN
    meta?: Record<string, any>; // 设备元数据
}

4. 错误处理

所有方法在出错时会抛出自定义的 BleError 或 DeviceError，可通过 try-catch 捕获。

5. 日志

SDK 内部集成了 Logger 日志系统，方便调试。

6. 典型用例

import { useBle } from '@/uni_modules/xs-bluebooth/js_sdk';

const ble = useBle();

async function scanDevices() {
  await ble.check();
  await ble.open();
  await ble.startBluetoothDevicesDiscovery();
  const devices = await ble.getBluetoothDevices();
  await ble.stopBluetoothDevicesDiscovery();
  await ble.close();
  return devices;
}

如需更详细的接口说明或扩展用法，可参考源码或补充需求。