API Reference

Plugins

Native.js


bluetooth

Bluetooth模块用于管理蓝牙设备，搜索附近蓝牙设备、实现简单数据传输等。

说明：

支持搜索发现所有蓝牙设备，但仅支持低功耗蓝牙ble传输协议，不支持蓝牙设备的配对连接传输大量数据。 如果要连接非ble蓝牙设备，可以使用Native.js调用（请到http://ask.dcloud.net.cn搜索bluetooth相关问答）。

方法：

对象：

回调方法：

模块：

5+功能模块（permissions）


{
// ...
"permissions":{
	// ...
	"Bluetooth": {
		"description": "Bluetooth"
	}
}
}

closeBluetoothAdapter

关闭蓝牙模块


void plus.bluetooth.closeBluetoothAdapter(options);

说明：

断开所有已经建立的连接，释放系统资源，要求在蓝牙功能使用完成后调用（于openBluetoothAdapter成对使用）。 关闭成功后触发options参数中的success回调，失败触发options参数中的fail回调。

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 关闭蓝牙模块
function closeBluetoothAdapter(){
	plus.bluetooth.closeBluetoothAdapter({
		success:function(e){
			console.log('close success: '+JSON.stringify(e));
		},
		fail:function(e){
			console.log('close failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

getBluetoothAdapterState

获取本机蓝牙适配器状态


void plus.bluetooth.getBluetoothAdapterState(options);

说明：

获取成功后触发options参数中的success回调，失败触发options参数中的fail回调。

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 获取蓝牙状态
function getBluetoothState(){
	plus.bluetooth.getBluetoothAdapterState({
		success:function(e){
			console.log('state success: '+JSON.stringify(e));
		},
		fail:function(e){
			console.log('state failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

getBluetoothDevices

获取已搜索到的蓝牙设备


void plus.bluetooth.getBluetoothDevices(options);

说明：

包括已经和本机处于连接状态的设备。 获取成功后触发options参数中的success回调，失败触发options参数中的fail回调。

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 获取已搜索到的蓝牙设备
function getBluetoothDevices(){
	plus.bluetooth.getBluetoothDevices({
		success:function(e){
			var devices = e.devices;
			console.log('get devices success: '+e.length);
			for(var i in devices){
				console.log(i+': '+JSON.stringify(devices[i]));
			}
		},
		fail:function(e){
			console.log('get devices failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

getConnectedBluetoothDevices

根据uuid获取处于已连接的设备


void plus.bluetooth.getConnectedBluetoothDevices(options);

说明：

获取成功后触发options参数中的success回调，失败触发options参数中的fail回调。

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 获取已连接的蓝牙设备
function getConnectedDevices(){
	plus.bluetooth.getConnectedBluetoothDevices({
		success:function(e){
			var devices = e.devices;
			console.log('connected devices success: '+e.length);
			for(var i in devices){
				console.log(i+': '+JSON.stringify(devices[i]));
			}
		},
		fail:function(e){
			console.log('connected devices failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

onBluetoothAdapterStateChange

监听蓝牙适配器状态变化事件


void plus.bluetooth.onBluetoothAdapterStateChange(changeCB);

说明：

蓝牙适配器状态发生变化时触发回调。

参数：

返回值：

void : 无

示例：


// 监听状态变化
function listenerStateChange(){
	plus.bluetooth.onBluetoothAdapterStateChange(function(e){
		console.log('state changed: '+JSON.stringify(e));
	});
}

uni-app使用plus注意事项

onBluetoothDeviceFound

监听搜索到新设备的事件


void plus.bluetooth.onBluetoothDeviceFound(callback);

说明：

搜索到新设备时触发回调。

参数：

返回值：

void : 无

示例：


// 监听发现新设备
function listenerDeviceFound(){
	plus.bluetooth.onBluetoothDeviceFound(function(e){
		var devices = e.devices;
		console.log('device found: '+e.length);
		for(var i in devices){
			console.log(i+': '+JSON.stringify(devices[i]));
		}
	});
}

uni-app使用plus注意事项

openBluetoothAdapter

初始化蓝牙模块


void plus.bluetooth.openBluetoothAdapter(options);

说明：

初始化成功后触发options参数中的success回调，失败触发options参数中的fail回调。

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 打开蓝牙模块
function openBluetoothAdapter(){
	plus.bluetooth.openBluetoothAdapter({
		success:function(e){
			console.log('open success: '+JSON.stringify(e));
		},
		fail:function(e){
			console.log('open failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

startBluetoothDevicesDiscovery

开始搜索附近的蓝牙设备


void plus.bluetooth.startBluetoothDevicesDiscovery(options);

说明：

此操作比较耗费系统资源，请在搜索并连接到设备后调用stopBluetoothDevicesDiscovery方法停止搜索。 搜索成功后触发options参数中的success回调，失败触发options参数中的fail回调。

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 开始搜索蓝牙
function startBluetoothDiscovery(){
	plus.bluetooth.openBluetoothAdapter({
		success:function(e){
			console.log('open success: '+JSON.stringify(e));
			plus.bluetooth.startBluetoothDevicesDiscovery({
				success:function(e){
					console.log('start discovery success: '+JSON.stringify(e));
				},
				fail:function(e){
					console.log('start discovery failed: '+JSON.stringify(e));
				}
			});
		},
		fail:function(e){
			console.log('open failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

stopBluetoothDevicesDiscovery

停止搜寻附近的蓝牙外围设备


void plus.bluetooth.stopBluetoothDevicesDiscovery(options);

说明：

若已经找到需要的蓝牙设备并不需要继续搜索时，应该调用该接口停止蓝牙搜索。 停止成功后触发options参数中的success回调，失败触发options参数中的fail回调。

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 结束搜索蓝牙
function stopBluetoothDiscovery(){
	plus.bluetooth.stopBluetoothDevicesDiscovery({
		success:function(e){
			console.log('stop discovery success: '+JSON.stringify(e));
			plus.bluetooth.closeBluetoothAdapter({
				success:function(e){
					console.log('close success: '+JSON.stringify(e));
				},
				fail:function(e){
					console.log('close failed: '+JSON.stringify(e));
				}
			});
		},
		fail:function(e){
			console.log('stop discovery failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

closeBLEConnection

断开与低功耗蓝牙设备的连接


void plus.bluetooth.closeBLEConnection(options);

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 断开蓝牙设备
function closeConnection(){
	plus.bluetooth.closeBLEConnection({
		deviceId:deviceId,
		success:function(e){
			console.log('close success: '+JSON.stringify(e));
		},
		fail:function(e){
			console.log('close failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

createBLEConnection

连接低功耗蓝牙设备


void plus.bluetooth.createBLEConnection(options);

说明：

若之前已有搜索过某个蓝牙设备，并成功建立连接，可直接传入之前搜索获取的deviceId尝试连接该设备，无需进行搜索操作。

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 蓝牙设备id，可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 连接蓝牙设备
function createConnection(){
	plus.bluetooth.createBLEConnection({
		deviceId:deviceId,
		success:function(e){
			console.log('create connection success: '+JSON.stringify(e));
		},
		fail:function(e){
			console.log('create connection failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

getBLEDeviceCharacteristics

获取蓝牙设备指定服务中所有特征值(characteristic)


void plus.bluetooth.getBLEDeviceCharacteristics(options);

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 蓝牙设备id，可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 蓝牙服务uuid，可通过getBLEDeviceServices方法获取
var serviceId = '';
// 获取蓝牙设备指定服务中所有特征值
function getCharacteristics(){
	plus.bluetooth.getBLEDeviceCharacteristics({
		deviceId:deviceId,
		serviceId:serviceId,
		success:function(e){
			var characteristics = e.characteristics;
			console.log('get characteristics success: '+characteristics.length);
			for(var i in characteristics){
				console.log(i+': '+JSON.stringify(characteristics[i]));
			}
		},
		fail:function(e){
			console.log('get characteristics failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

getBLEDeviceServices

获取蓝牙设备的所有服务(service)


void plus.bluetooth.getBLEDeviceServices(options);

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 蓝牙设备id，可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 获取蓝牙设备的所有服务
function getServices(){
	plus.bluetooth.getBLEDeviceServices({
		deviceId:deviceId,
		success:function(e){
			var services = e.services;
			console.log('get services success: '+services.length);
			for(var i in services){
				console.log(i+': '+JSON.stringify(services[i]));
			}
		},
		fail:function(e){
			console.log('get services failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

notifyBLECharacteristicValueChange

启用低功耗蓝牙设备特征值变化时的notify功能，订阅特征值


void plus.bluetooth.notifyBLECharacteristicValueChange(options);

说明：

蓝牙设备服务的特征值必须支持notify或indicate才可以成功调用。 另外，必须先启用notifyBLECharacteristicValueChange才能监听到设备characteristicValueChange事件,即特征值发生变化时通过onBLECharacteristicValueChange注册的事件回调。

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 蓝牙设备id，可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 蓝牙服务id，可通过getBLEDeviceServices方法获取
var serviceId = '';
// 蓝牙特征值id，可通过getBLEDeviceCharacteristics方法获取
var characteristicId = '';
// 启用低功耗蓝牙设备特征值变化时的notify功能
function startCharacteristicsNotify(){
	// 监听低功耗蓝牙设备的特征值变化 
	plus.bluetooth.onBLECharacteristicValueChange(function(e){
		console.log('onBLECharacteristicValueChange: '+JSON.stringify(e));
		var value = buffer2hex(e.value);
		console.log('value(hex) = '+value);
		if(characteristicId == e.characteristicId){
			// 更新到页面显示
			alert('特征值变化: '+value);
		}
	});
	// 启用notify功能
	plus.bluetooth.notifyBLECharacteristicValueChange({
		deviceId:deviceId,
		serviceId:serviceId,
		characteristicId:characteristicId,
		success:function(e){
			var characteristics = e.characteristics;
			console.log('get characteristics success: '+characteristics.length);
			for(var i in characteristics){
				console.log(i+': '+JSON.stringify(characteristics[i]));
			}
		},
		fail:function(e){
			console.log('get characteristics failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

onBLECharacteristicValueChange

监听低功耗蓝牙设备的特征值变化事件


void plus.bluetooth.onBLECharacteristicValueChange(callback);

参数：

返回值：

void : 无

示例：


// 蓝牙设备id，可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 蓝牙服务id，可通过getBLEDeviceServices方法获取
var serviceId = '';
// 蓝牙特征值id，可通过getBLEDeviceCharacteristics方法获取
var characteristicId = '';

// 启用低功耗蓝牙设备特征值变化时的notify功能
function startCharacteristicsNotify(){
	// 监听低功耗蓝牙设备的特征值变化 
	plus.bluetooth.onBLECharacteristicValueChange(function(e){
		console.log('onBLECharacteristicValueChange: '+JSON.stringify(e));
		var value = buffer2hex(e.value);
		console.log('value(hex) = '+value);
		if(characteristicId == e.characteristicId){
			// 更新到页面显示
			alert('特征值变化: '+value);
		}
	});
	// 启用notify功能
	plus.bluetooth.notifyBLECharacteristicValueChange({
		deviceId:deviceId,
		serviceId:serviceId,
		characteristicId:characteristicId,
		success:function(e){
			var characteristics = e.characteristics;
			console.log('get characteristics success: '+characteristics.length);
			for(var i in characteristics){
				console.log(i+': '+JSON.stringify(characteristics[i]));
			}
		},
		fail:function(e){
			console.log('get characteristics failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

onBLEConnectionStateChange

监听低功耗蓝牙设备连接状态变化事件


void plus.bluetooth.onBLEConnectionStateChange(callback);

说明：

包括开发者主动连接或断开连接，设备丢失，连接异常断开等。

参数：

返回值：

void : 无

示例：


// 监听蓝牙设备连接状态
function listenerConnection(){
	plus.bluetooth.onBLEConnectionStateChange(function(e){
		console.log('connection state changed: '+JSON.stringify(e));
	});
}

uni-app使用plus注意事项

readBLECharacteristicValue

读取低功耗蓝牙设备指定特征值的二进制数据值


void plus.bluetooth.readBLECharacteristicValue(options);

说明：

指定的特征值需支持read操作才可以成功调用。 并行调用多次可能导致读取失败，读取的数据需要在onBLECharacteristicValueChange方法注册的回调中获取。

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 蓝牙设备id，可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 蓝牙服务id，可通过getBLEDeviceServices方法获取
var serviceId = '';
// 蓝牙特征值id，可通过getBLEDeviceCharacteristics方法获取
var characteristicId = '';
// 读取低功耗蓝牙设备的特征值
function readCharacteristics(){
	plus.bluetooth.readBLECharacteristicValue({
		deviceId:deviceId,
		serviceId:serviceId,
		characteristicId:characteristicId,
		success:function(e){
			console.log('read characteristics success: '+JSON.stringify(e));
		},
		fail:function(e){
			console.log('read characteristics failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

writeBLECharacteristicValue

向低功耗蓝牙设备指定特征值写入二进制数据


void plus.bluetooth.writeBLECharacteristicValue(options);

说明：

指定的特征值需支持write操作才可以成功调用。 并行调用多次可能导致读取失败，系统可能会限制单次传输的数据大小，超过最大字节数后可能会发生写入错误，建议每次写入不超过20字节。

参数：

options参数为json类型，包含以下属性：

返回值：

void : 无

示例：


// 蓝牙设备id，可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 蓝牙服务id，可通过getBLEDeviceServices方法获取
var serviceId = '';
// 蓝牙特征值id，可通过getBLEDeviceCharacteristics方法获取
var characteristicId = '';
// 要写入的数据
var value = new ArrayBuffer(8);
var iv = new Int32Array(value);
iv[0] = 120, iv[2]=100;
// 写入低功耗蓝牙设备的特征值
function writeCharacteristics(){
	plus.bluetooth.writeBLECharacteristicValue({
		deviceId:deviceId,
		serviceId:serviceId,
		characteristicId:characteristicId,
		value:value,
		success:function(e){
			console.log('write characteristics success: '+JSON.stringify(e));
		},
		fail:function(e){
			console.log('write characteristics failed: '+JSON.stringify(e));
		}
	});
}

uni-app使用plus注意事项

BluetoothDeviceInfo

蓝牙设备信息


interface BluetoothDeviceInfo {
	readonly attribute String name;
	readonly attribute String deviceId;
	readonly attribute String RSSI;
	readonly attribute ArrayBuffer advertisData;
	readonly attribute Array<String> advertisServiceUUIDs;
	readonly attribute String localName;
	readonly attribute JSON serviceData;
}

属性：

BluetoothService

蓝牙设备服务信息


interface BluetoothService {
	readonly attribute String uuid;
	readonly attribute Boolean isPrimary;
}

属性：

Bluetoothcharacteristic

蓝牙设备特征值


interface Bluetoothcharacteristic {
	readonly attribute String uuid;
	readonly attribute BluetoothcharacteristicProperties properties;
}

属性：

BluetoothcharacteristicProperties

蓝牙设备特征值支持的操作类型


interface BluetoothcharacteristicProperties {
	readonly attribute Boolean read;
	readonly attribute Boolean write;
	readonly attribute Boolean notify;
	readonly attribute Boolean indicate;
}

属性：

BluetoothSuccessCallback

成功回调函数


void onSuccess(JSON event){
}

说明：

不同接口触发的成功回调参数event包含的属性存在差异，具体参考对应的接口描述说明。

参数：

返回值：

void : 无

BluetoothFailCallback

失败回调函数


function void onFail(Exception error){
	// Handle error
	var code = error.code; // 错误编码
	var message = error.message; // 错误描述信息
}

参数：

返回值：

void : 无

BluetoothCompleteCallback

操作完成回调函数


function void onComplete(JSON event){
}

说明：

调用成功或失败都会触发此回调。

参数：

返回值：

void : 无

BluetoothAdapterStateChangeCallback

蓝牙适配器状态变化事件回调函数


function void onStateChange(JSON event){
	// event.available
	// event.discovering
}

说明：

蓝牙适配器状态发生变化时触发此回调。

参数：

返回值：

void : 无

BluetoothDeviceFoundCallback

蓝牙适配器搜索到新设备事件回调函数


function void onDeviceFound(JSON event){
	// event.devices
}

说明：

搜索到蓝牙设备时触发此回调。

参数：

返回值：

void : 无

BLEConnectionStateChangeCallback

低功耗蓝牙设备连接状态变化事件回调函数


function void onStateChange(JSON event){
	// event.deviceId
	// event.connected
}

说明：

蓝牙设备连接状态发生变化时触发此回调。

参数：

返回值：

void : 无

BLECharacteristicValueChangeCallback

低功耗蓝牙设备的特征值变化事件回调函数


function void onValueChange(JSON event){
	// event.deviceId
	// event.serviceId
	// event.characteristicId
	// event.value
}

说明：

蓝牙设备对应的特征值发生变化时触发此回调。

参数：

返回值：

void : 无