开始

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-bluetooth-low-energy` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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

导入

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

API概述

initialize

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

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

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

shimWebBluetooth

在Capacitor上安装Web蓝牙 shim。 在使用Web蓝牙Capacitor的__CAPGO_KEEP_1__原生应用之前，手动调用此方法。 navigator.bluetooth. Call this manually before using the Web Bluetooth API from a Capacitor native app.

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();

openBluetoothSettings

仅限 Android，开启蓝牙设置页面。

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

await BluetoothLowEnergy.openBluetoothSettings();

openLocationSettings

仅限 Android，开启位置设置页面。

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

await BluetoothLowEnergy.openLocationSettings();

checkPermissions

检查当前权限状态。

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

const { bluetooth, location } = await BluetoothLowEnergy.checkPermissions();

requestPermissions

请求蓝牙权限。

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

const { bluetooth, location } = await BluetoothLowEnergy.requestPermissions();

startScan

复制到剪贴板

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

await BluetoothLowEnergy.startScan({
  services: ['180D'], // Heart Rate Service
  timeout: 10000
});

stopScan

连接设备

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

await BluetoothLowEnergy.stopScan();

connect

复制到剪贴板

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

await BluetoothLowEnergy.connect({ deviceId: 'AA:BB:CC:DD:EE:FF' });

disconnect

断开蓝牙设备

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

await BluetoothLowEnergy.disconnect({ deviceId: 'AA:BB:CC:DD:EE:FF' });

createBond

Android 设备上与BLE设备建立连接。

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

await BluetoothLowEnergy.createBond({ deviceId: 'AA:BB:CC:DD:EE:FF' });

isBonded

检查设备是否已连接 (Android 设备)。

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

const { bonded } = await BluetoothLowEnergy.isBonded({ deviceId: 'AA:BB:CC:DD:EE:FF' });

discoverServices

在已连接设备上发现服务。

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

await BluetoothLowEnergy.discoverServices({ deviceId: 'AA:BB:CC:DD:EE:FF' });

getServices

获取已发现设备的服务。

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

const { services } = await BluetoothLowEnergy.getServices({ deviceId: 'AA:BB:CC:DD:EE:FF' });

getConnectedDevices

获取已连接设备的列表。

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

const { devices } = await BluetoothLowEnergy.getConnectedDevices();

readCharacteristic

读取特征值。

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

const { value } = await BluetoothLowEnergy.readCharacteristic({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A37'
});

writeCharacteristic

向特征写入值。

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

await BluetoothLowEnergy.writeCharacteristic({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A39',
  value: [0x01]
});

startCharacteristicNotifications

开始特征的通知。

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

await BluetoothLowEnergy.startCharacteristicNotifications({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A37'
});

stopCharacteristicNotifications

停止特性通知

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

await BluetoothLowEnergy.stopCharacteristicNotifications({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A37'
});

readDescriptor

读取描述符值

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

const { value } = await BluetoothLowEnergy.readDescriptor({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A37',
  descriptor: '2902'
});

writeDescriptor

写入描述符值

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

await BluetoothLowEnergy.writeDescriptor({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A37',
  descriptor: '2902',
  value: [0x01, 0x00]
});

readRssi

读取连接设备的RSSI（信号强度）

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

const { rssi } = await BluetoothLowEnergy.readRssi({ deviceId: 'AA:BB:CC:DD:EE:FF' });

requestMtu

仅在 Android 上请求 MTU 大小更改。

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

const { mtu } = await BluetoothLowEnergy.requestMtu({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  mtu: 512
});

requestConnectionPriority

仅在 Android 上请求连接优先级。

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

await BluetoothLowEnergy.requestConnectionPriority({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  priority: 'high'
});

startAdvertising

作为 BLE 服务器开始广告。

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

await BluetoothLowEnergy.startAdvertising({
  name: 'MyDevice',
  services: ['180D']
});

stopAdvertising

停止广告。

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

await BluetoothLowEnergy.stopAdvertising();

startForegroundService

在 Android 设备上，开启前台服务以在后台维持 BLE 连接。

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

await BluetoothLowEnergy.startForegroundService({
  title: 'BLE Connection',
  body: 'Maintaining connection...'
});

stopForegroundService

在 Android 设备上，停止前台服务。

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

await BluetoothLowEnergy.stopForegroundService();

Type Reference

InitializeOptions

插件初始化选项。

export interface InitializeOptions {
  /**
   * The mode to initialize the plugin in.
   * - 'central': Act as a BLE central (client)
   * - 'peripheral': Act as a BLE peripheral (server)
   *
   * @default 'central'
   * @since 1.0.0
   */
  mode?: 'central' | 'peripheral';
}

IsAvailableResult

蓝牙低能耗插件的可用性结果。

export interface IsAvailableResult {
  /**
   * Whether Bluetooth is available on the device.
   *
   * @since 1.0.0
   */
  available: boolean;
}

IsEnabledResult

蓝牙启用状态结果。

export interface IsEnabledResult {
  /**
   * Whether Bluetooth is enabled on the device.
   *
   * @since 1.0.0
   */
  enabled: boolean;
}

IsLocationEnabledResult

定位蓝牙低能耗插件的可用性结果。

export interface IsLocationEnabledResult {
  /**
   * Whether location services are enabled on the device.
   *
   * @since 1.0.0
   */
  enabled: boolean;
}

PermissionStatus

蓝牙和位置的权限状态。

export interface PermissionStatus {
  /**
   * Bluetooth permission status.
   *
   * @since 1.0.0
   */
  bluetooth: PermissionState;

  /**
   * Location permission status (Android only).
   *
   * @since 1.0.0
   */
  location: PermissionState;
}

StartScanOptions

开始扫描的选项。

export interface StartScanOptions {
  /**
   * List of service UUIDs to filter by.
   * Only devices advertising these services will be returned.
   *
   * @since 1.0.0
   */
  services?: string[];

  /**
   * Scan timeout in milliseconds.
   * Set to 0 for no timeout.
   *
   * @default 0
   * @since 1.0.0
   */
  timeout?: number;

  /**
   * Whether to allow duplicate scan results.
   *
   * @default false
   * @since 1.0.0
   */
  allowDuplicates?: boolean;
}

ConnectOptions

连接设备的选项。

export interface ConnectOptions {
  /**
   * The device ID (MAC address on Android, UUID on iOS).
   *
   * @since 1.0.0
   */
  deviceId: string;

  /**
   * Whether to automatically connect when the device becomes available.
   *
   * @default false
   * @since 1.0.0
   */
  autoConnect?: boolean;
}

DisconnectOptions

断开设备的连接选项。

export interface DisconnectOptions {
  /**
   * The device ID to disconnect from.
   *
   * @since 1.0.0
   */
  deviceId: string;
}

CreateBondOptions

创建配对的选项。

export interface CreateBondOptions {
  /**
   * The device ID to bond with.
   *
   * @since 1.0.0
   */
  deviceId: string;
}

IsBondedOptions

蓝牙低能耗设备连接状态检查选项。

export interface IsBondedOptions {
  /**
   * The device ID to check.
   *
   * @since 1.0.0
   */
  deviceId: string;
}

IsBondedResult

isBonded方法的结果。

export interface IsBondedResult {
  /**
   * Whether the device is bonded.
   *
   * @since 1.0.0
   */
  bonded: boolean;
}

DiscoverServicesOptions

发现服务选项。

export interface DiscoverServicesOptions {
  /**
   * The device ID to discover services on.
   *
   * @since 1.0.0
   */
  deviceId: string;
}

真实数据来源

本页面是由插件的 src/definitions.ts重新同步公共API时，重新运行同步任务。

继续从 Getting Started

如果您正在使用 Getting Started 来规划仪表板和 API 操作，连接它与 使用 @capgo/capacitor-bluetooth-low-energy 为使用 @capgo/capacitor-bluetooth-low-energy 的原生能力 API 概述 为 API 概述 的实现细节 介绍 为介绍 的实现细节 API 密钥 为API Keys的实现细节,和 设备 为__CAPGO_KEEP_0__ Devices的实现细节