跳转至正文

低功耗蓝牙 Capacitor 插件

功能完备的 BLE 插件,支持扫描、连接、读取、写入蓝牙设备并接收通知

安装

bun add @capgo/capacitor-bluetooth-low-energy bunx cap sync
npm、pnpm 或 yarn
  • npm install @capgo/capacitor-bluetooth-low-energy
  • pnpm add @capgo/capacitor-bluetooth-low-energy
  • yarn add @capgo/capacitor-bluetooth-low-energy

指南

如何在 Capacitor 中使用低功耗蓝牙

使用 @capgo/capacitor-bluetooth-low-energy

Capacitor 低功耗蓝牙插件,用于 BLE 通信。

安装

bun add @capgo/capacitor-bluetooth-low-energy
bunx cap sync

bunx cap sync 将插件的原生 code 复制到你的原生项目中。每次升级插件后都要重新运行。

导入

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

API 概览

方法 描述
initialize 初始化 BLE 插件。必须在调用任何其他方法之前调用。
shimWebBluetooth 在 Capacitor 上安装 Web Bluetooth shim navigator.bluetooth。在 Capacitor 原生应用中使用 Web Bluetooth API 之前,请手动调用此方法。
isAvailable 检查设备上的蓝牙是否可用。
isEnabled 检查设备蓝牙是否已开启。
isLocationEnabled 检查是否已启用定位服务(仅限 Android)。
openAppSettings 打开应用设置页面。
openBluetoothSettings 打开蓝牙设置页面(仅限 Android)。
openLocationSettings 打开位置设置页面(仅限 Android)。
checkPermissions 检查当前权限状态。
requestPermissions 请求蓝牙权限。
startScan 开始扫描 BLE 设备。
stopScan 停止扫描 BLE 设备。
connect 连接到 BLE 设备。
disconnect 断开与 BLE 设备的连接。
createBond 与 BLE 设备建立绑定(仅限 Android)。
isBonded 检查设备是否已绑定(仅限 Android)。
discoverServices 发现已连接设备上的服务。
getServices 获取设备已发现的服务。
getConnectedDevices 获取已连接设备列表。
readCharacteristic 读取特征值。
writeCharacteristic 向特征值写入数据。
startCharacteristicNotifications 开启特征值通知。
stopCharacteristicNotifications 停止某个特征的通知。
readDescriptor 读取描述符的值。
writeDescriptor 向描述符写入一个值。
readRssi 读取已连接设备的 RSSI(信号强度)。
requestMtu 请求更改 MTU 大小(仅限 Android)。
requestConnectionPriority 请求连接优先级(仅限 Android)。
startAdvertising 以外围设备(BLE 服务器)身份开始广播。
stopAdvertising 停止广播。
addGattService 向本地 GATT 服务器添加包含特征值的 GATT 服务。必须在开始广播前以外围设备模式调用。
removeGattService 从本地 GATT 服务器移除 GATT 服务。
setGattCharacteristicValue 设置本地 GATT 特征值的值。
notifyGattCharacteristicChanged 通知已连接的中心设备,本地 GATT 特征值已更改。
startForegroundService 启动前台服务以在后台维持 BLE 连接(仅限 Android)。
stopForegroundService 停止前台服务(仅限 Android)。

示例

initialize()

初始化 BLE 插件。必须在调用任何其他方法之前调用。

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.initialize({ mode: 'central' });

shimWebBluetooth()

在 Capacitor 上安装 Web Bluetooth shim navigator.bluetooth。在 Capacitor 原生应用中使用 Web Bluetooth API 之前,请手动调用此方法。

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

BluetoothLowEnergy.shimWebBluetooth();

isAvailable()

检查设备上的蓝牙是否可用。

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { available } = await BluetoothLowEnergy.isAvailable();

isEnabled()

检查设备蓝牙是否已开启。

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { enabled } = await BluetoothLowEnergy.isEnabled();

isLocationEnabled()

检查是否已启用定位服务(仅限 Android)。

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { enabled } = await BluetoothLowEnergy.isLocationEnabled();

openAppSettings()

打开应用设置页面。

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.openAppSettings();

上表列出了 36 个核心方法。有关监听器、版本辅助函数以及每个方法的完整规范,请参阅 GitHub 仓库.

监听事件

addListener 会返回一个句柄。调用 handle.remove() 在屏幕卸载时,或者调用 BluetoothLowEnergy.removeAllListeners() 以清除所有监听器。

完整参考文档

继续了解如何使用 @capgo/capacitor-bluetooth-low-energy

如果你正在使用 使用 @capgo/capacitor-bluetooth-low-energy 要规划原生插件工作,请将其与 @capgo/capacitor-bluetooth-low-energy 有关 @capgo/capacitor-bluetooth-low-energy 的实现细节, 快速入门 有关“入门指南”中的实现细节, Capgo 插件目录 查看 Capgo 插件目录中的产品工作流, Capgo 提供的 Capacitor 插件 有关 Capgo 开发的 Capacitor 插件的实现细节,以及 添加或更新插件 有关添加或更新插件的实现细节。

常见问题

Bluetooth Low Energy 插件常见问题

如何在 Capacitor 应用中安装 Bluetooth Low Energy 插件?

运行 "bun add @capgo/capacitor-bluetooth-low-energy"(或 "npm install @capgo/capacitor-bluetooth-low-energy"),然后运行 "bunx cap sync",以便 iOS 和 Android 项目获取原生 code。在您的应用 code 中从 "@capgo/capacitor-bluetooth-low-energy" 导入它。

@capgo/capacitor-bluetooth-low-energy 支持 React、Vue 和 Angular 吗?

支持。Bluetooth Low Energy 是一个 Capacitor 包,因此适用于任何在 Capacitor 内运行的 Web 框架,包括 Ionic、React、Vue、Angular、Svelte 和纯 JavaScript。

@capgo/capacitor-bluetooth-low-energy 支持哪个版本的 Capacitor?

Capgo 插件遵循 Capacitor 的主版本号:请使用与 Capacitor 主版本号一致的插件主版本(例如插件 v8 对应 Capacitor 8)。GitHub README 中的兼容性表列出了仍在维护的版本。

@capgo/capacitor-bluetooth-low-energy 是免费且开源的吗?

是的。code 源代码公开在 GitHub 上,地址为 https://github.com/Cap-go/capacitor-bluetooth-low-energy/,并且可以从 npm 免费安装该包。欢迎提交 Bug 报告和 Pull Request。

我可以更新使用 Bluetooth Low Energy 的 code 而无需经过 App Store 审核吗?

安装或升级插件会改动原生 code,因此需要重新做一次商店构建。之后,调用该插件的 JavaScript、HTML 和 CSS 改动就能通过 Capgo live updates 立即发布。

无需等待应用审核,即可发布蓝牙低功耗(BLE)更新

只要插件已包含在你的商店版本中,Capgo live updates 就能在几分钟内把 JavaScript、HTML 和 CSS 的改动推送给用户。

开始使用 Capgo