小程序文档整理之 -- API（设备）

设备

系统信息

wx.getSystemInfo(OBJECT)

获取系统信息

wx.getSystemInfo({  success: function(res) {    res.brand//手机品牌    res.model//手机型号    res.pixelRatio//设备像素比    res.screenWidth//屏幕宽度    res.screenHeight//屏幕高度    res.windowWidth//可使用窗口宽度    res.windowHeight//可使用窗口高度    res.language//微信设置的语言    res.version//微信版本号    res.system//操作系统版本    res.platform//客户端平台    res.fontSizeSetting//用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准，单位：px    res.SDKVersion//客户端基础库版本  }})

wx.getSystemInfoSync()

获取系统信息同步接口

wx.getSystemInfoSync({  success: function(res) {    res.brand//手机品牌    res.model//手机型号    res.pixelRatio//设备像素比    res.screenWidth//屏幕宽度    res.screenHeight//屏幕高度    res.windowWidth//可使用窗口宽度    res.windowHeight//可使用窗口高度    res.language//微信设置的语言    res.version//微信版本号    res.system//操作系统版本    res.platform//客户端平台    res.fontSizeSetting//用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准，单位：px    res.SDKVersion//客户端基础库版本  }})

wx.canIUse(String)

判断小程序的API，回调，参数，组件等是否在当前版本可用
String参数说明： 使用API.{method}.param.{options}或者component.{attribute}.${option}方式来调用，例如：

• ${API} 代表 API 名字
• ${method} 代表调用方式，有效值为return, success, object, callback
• ${param} 代表参数或者返回值
• ${options} 代表参数的可选值
• ${component} 代表组件名字
• ${attribute} 代表组件属性
• ${option} 代表组件属性的可选值

wx.canIUse('openBluetoothAdapter')wx.canIUse('getSystemInfoSync.return.screenWidth')wx.canIUse('getSystemInfo.success.screenWidth')wx.canIUse('showToast.object.image')wx.canIUse('onCompassChange.callback.direction')wx.canIUse('request.object.method.GET')wx.canIUse('contact-button')wx.canIUse('text.selectable')wx.canIUse('button.open-type.contact')

网络状态

wx.getNetworkType(OBJECT)

获取网络类型

wx.getNetworkType({  success: function(res) {    // 返回网络类型, 有效值：    // wifi/2g/3g/4g/unknown(Android下不常见的网络类型)/none(无网络)    var networkType = res.networkType//网络类型  }})

wx.onNetworkStatusChange(CALLBACK)

监听网络状态变化

wx.onNetworkStatusChange(function(res) {  res.isConnected//当前是否有网络连接  res.networkType//网络类型,wifi/2g/3g/4g/none(无网络)/unknown(Android下不常见的网络类型)})

加速度计

wx.onAccelerometerChange(CALLBACK)

监听加速度数据，频率：5次/秒，接口调用后会自动开始监听，可使用 wx.stopAccelerometer 停止监听

wx.onAccelerometerChange(function(res) {    res.x//X 轴    res.y//Y 轴    res.z//Z 轴})

wx.startAccelerometer(OBJECT)

开始监听加速度数据

wx.onAccelerometerChange(function(res) {    res.x//X 轴    res.y//Y 轴    res.z//Z 轴})

wx.stopAccelerometer(OBJECT)

停止监听加速度数据

wx.stopAccelerometer()

罗盘

wx.onCompassChange(CALLBACK)

监听罗盘数据，频率：5次/秒，接口调用后会自动开始监听，可使用wx.stopCompass停止监听

wx.onCompassChange(function (res) {  console.log(res.direction)})

wx.startCompass(OBJECT)

开始监听罗盘数据

wx.startCompass()

wx.stopCompass(OBJECT)

停止监听罗盘数据

wx.stopCompass()

拨打电话

wx.makePhoneCall(OBJECT)

wx.makePhoneCall({  phoneNumber: '1340000' //需要拨打的电话号码  success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数  }})

扫码

wx.scanCode(OBJECT)

调起客户端扫码界面，扫码成功后返回对应的结果

// 只允许从相机扫码wx.scanCode({  onlyFromCamera: true,//是否只能从相机扫码，不允许从相册选择图片,无此项则允许从相机和相册扫码  success: (res) => {    res.result //所扫码的内容    res.scanType //所扫码的类型    res.charSet //所扫码的字符集    res.path //当所扫的码为当前小程序的合法二维码时，会返回此字段，内容为二维码携带的 path  }})

剪贴板

wx.setClipboardData(OBJECT)

设置系统剪贴板的内容

wx.getClipboardData(OBJECT)

获取系统剪贴板内容

wx.setClipboardData({//设置系统剪贴板的内容  data: 'data',//(必要)需要设置的内容  success: function(res) {    wx.getClipboardData({//获取系统剪贴板内容      success: function(res) {        res.data //剪贴板的内容      }    })  }})

蓝牙

wx.openBluetoothAdapter(OBJECT)

初始化蓝牙适配器

wx.openBluetoothAdapter({    success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数    }})

注意：由于系统的问题，目前仅在 mac 版的开发工具上支持蓝牙调试

wx.closeBluetoothAdapter(OBJECT)

关闭蓝牙模块。调用该方法将断开所有已建立的链接并释放系统资源

wx.closeBluetoothAdapter({    success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数    }})

wx.getBluetoothAdapterState(OBJECT)

获取本机蓝牙适配器状态

wx.getBluetoothAdapterState({  success: function (res) {    res.discovering//是否正在搜索设备    res.available//蓝牙适配器是否可用    res.errMsg//成功：ok，错误：详细信息  }})

wx.onBluetoothAdapterStateChange(CALLBACK)

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

wx.onBluetoothAdapterStateChange(function(res) {   res.discovering//蓝牙适配器是否处于搜索状态   res.available//蓝牙适配器是否可用})

wx.startBluetoothDevicesDiscovery(OBJECT)

开始搜寻附近的蓝牙外围设备。注意，该操作比较耗费系统资源，请在搜索并连接到设备后调用 stop 方法停止搜索

// 以微信硬件平台的蓝牙智能灯为例，主服务的 UUID 是 FEE7。传入这个参数，只搜索主服务 UUID 为 FEE7 的设备wx.startBluetoothDevicesDiscovery({  services: ['FEE7'],//蓝牙设备主 service 的 uuid 列表  allowDuplicatesKey//是否允许重复上报同一设备， 如果允许重复上报，则onDeviceFound 方法会多次上报同一设备，但是 RSSI 值会有不同  interval//上报设备的间隔，默认为0，意思是找到新设备立即上报，否则根据传入的间隔上报  success: function (res) {    res.errMsg//成功：ok，错误：详细信息    res.isDiscovering//当前蓝牙适配器是否处于搜索状态  }})

wx.stopBluetoothDevicesDiscovery(OBJECT)

停止搜寻附近的蓝牙外围设备。请在确保找到需要连接的设备后调用该方法停止搜索

wx.stopBluetoothDevicesDiscovery({  success: function (res) {//(必要)成功则返回本机蓝牙适配器状态    res.errMsg//成功：ok，错误：详细信息  }})

wx.getBluetoothDevices(OBJECT)

获取所有已发现的蓝牙设备，包括已经和本机处于连接状态的设备

wx.getBluetoothDevices({  success: function (res) {//(必要)成功则返回本机蓝牙适配器状态    res.devices//uuid 对应的的已连接设备列表    /*{    * name//蓝牙设备名称，某些设备可能没有    * localName//功耗设备广播名称，某些设备可能没有    * deviceId//用于区分设备的 id    * RSSI//当前蓝牙设备的信号强度    * advertisData//当前蓝牙设备的广播内容（注意：vConsole 无法打印出 ArrayBuffer 类型数据）    *}    */    res.errMsg//成功：ok，错误：详细信息  }})

1、 Mac系统可能无法获取advertisData及RSSI，请使用真机调试
2、 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址，iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

wx.onBluetoothDeviceFound(CALLBACK)

监听寻找到新设备的事件

wx.onBluetoothDeviceFound(function(devices) {  devices//新搜索到的设备列表})device对象    deviceId//蓝牙设备 id，参考 device 对象    name//蓝牙设备名称，某些设备可能没有    localName//功耗设备广播名称，某些设备可能没有    deviceId//用于区分设备的 id    RSSI//当前蓝牙设备的信号强度    advertisData//当前蓝牙设备的广播内容（注意：vConsole 无法打印出 ArrayBuffer 类型数据）

1、 Mac系统可能无法获取advertisData及RSSI，请使用真机调试
2、 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址，iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

wx.getConnectedBluetoothDevices(OBJECT)

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

wx.getConnectedBluetoothDevices({  services//蓝牙设备主 service 的 uuid 列表  success: function (res) {    res.devices //搜索到的设备列表    errMsg//成功：ok，错误：详细信息  }})device对象蓝牙设备信息name//蓝牙设备名称，某些设备可能没有deviceId//用于区分设备的 id

1、 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址，iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

低功耗蓝牙接口

wx.createBLEConnection(OBJECT)
连接低功耗蓝牙设备

wx.createBLEConnection({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,//(必要)蓝牙设备 id，参考 getDevices 接口  success: function (res) {//成功则返回本机蓝牙适配器状态    res.errMsg//成功：ok，错误：详细信息  }})

1.安卓手机上如果多次调用create创建连接，有可能导致系统持有同一设备多个连接的实例，导致调用close的时候并不能真正的断开与设备的连接。因此请保证尽量成对的调用create和close接口

wx.closeBLEConnection(OBJECT)

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

wx.closeBLEConnection({  deviceId: deviceId,//(必要)蓝牙设备 id，参考 getDevices 接口  success: function (res) {//(必要)成功则返回本机蓝牙适配器状态    res.errMsg//成功：ok，错误：详细信息  }})

wx.getBLEDeviceServices(OBJECT)

获取蓝牙设备所有 service（服务）

wx.getBLEDeviceServices({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,//(必要)蓝牙设备 id，参考 getDevices 接口  success: function (res) {//(必要)成功则返回本机蓝牙适配器状态    res.errMsg//成功：ok，错误：详细信息    res.services//设备服务列表    res.uuid//蓝牙设备服务的 uuid    res.isPrimary//该服务是否为主服务  }})

wx.getBLEDeviceCharacteristics(OBJECT)

获取蓝牙设备所有 characteristic（特征值）

wx.getBLEDeviceCharacteristics({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,//(必要)蓝牙设备 id，参考 device 对象  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,//(必要)蓝牙服务 uuid  success: function (res) {//(必要)    res.errMsg//成功：ok，错误：详细信息    res.characteristics//设备特征值列表    res.characteristics.uuid//蓝牙设备特征值的 uuid    res.characteristics.properties//该特征值支持的操作类型    res.characteristics.properties.read//该特征值是否支持 read 操作    res.characteristics.properties.write//该特征值是否支持 write 操作    res.characteristics.properties.notify//该特征值是否支持 notify 操作    res.characteristics.properties.indicate//该特征值是否支持 indicate 操作  }})

wx.readBLECharacteristicValue(OBJECT)

读取低功耗蓝牙设备的特征值的二进制数据值。注意：必须设备的特征值支持read才可以成功调用，具体参照 characteristic 的 properties 属性

// 必须在这里的回调才能获取wx.onBLECharacteristicValueChange(function(characteristic) {  console.log('characteristic value comed:', characteristic)})wx.readBLECharacteristicValue({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,//(必要)蓝牙设备 id，参考 device 对象  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,//(必要)蓝牙特征值对应服务的 uuid  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取  characteristicId: characteristicId,//(必要)蓝牙特征值的 uuid  success: function (res) {//(必要)    res.errMsg//成功：ok，错误：详细信息    res.characteristic//设备特征值信息    res.characteristic.characteristicId//蓝牙设备特征值的 uuid    res.characteristic.serviceId//蓝牙设备特征值对应服务的 uuid    res.characteristic.value//蓝牙设备特征值对应的二进制值（注意：vConsole 无法打印出 ArrayBuffer 类型数据）  }})

1、 并行调用多次读写接口存在读写失败的可能性。
2、read接口读取到的信息需要在onBLECharacteristicValueChange方法注册的回调中获取。

wx.writeBLECharacteristicValue(OBJECT)

向低功耗蓝牙设备特征值中写入二进制数据。注意：必须设备的特征值支持write才可以成功调用，具体参照 characteristic 的 properties 属性

tips: 并行调用多次读写接口存在读写失败的可能性

// 这里的回调可以获取到 write 导致的特征值改变wx.onBLECharacteristicValueChange(function(characteristic) {  console.log('characteristic value changed:', characteristic)})// 向蓝牙设备发送一个0x00的16进制数据let buffer = new ArrayBuffer(1)let dataView = new DataView(buffer)dataView.setUint8(0, 0)wx.writeBLECharacteristicValue({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取   deviceId: deviceId,//(必要)蓝牙设备 id，参考 device 对象  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,//(必要)蓝牙特征值对应服务的 uuid  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取  characteristicId: characteristicId,//(必要)蓝牙特征值的 uuid  // 这里的value是ArrayBuffer类型  value: buffer,//蓝牙设备特征值对应的二进制值（注意：vConsole 无法打印出 ArrayBuffer 类型数据）  success: function (res) {    res.errMsg//成功：ok，错误：详细信息  }})

wx.notifyBLECharacteristicValueChange(OBJECT)

启用低功耗蓝牙设备特征值变化时的 notify 功能。注意：必须设备的特征值支持notify才可以成功调用，具体参照 characteristic 的 properties 属性

另外，必须先启用notify才能监听到设备 characteristicValueChange 事件

wx.notifyBLECharacteristicValueChange({   state: true, //(必要)true: 启用 notify; false: 停用 notify  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取   deviceId: deviceId,//(必要)蓝牙设备 id，参考 device 对象  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,//(必要)蓝牙特征值对应服务的 uuid  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取  characteristicId: characteristicId,//(必要)蓝牙特征值的 uuid  // 这里的value是ArrayBuffer类型  value: buffer,//蓝牙设备特征值对应的二进制值（注意：vConsole 无法打印出 ArrayBuffer 类型数据）  success: function (res) {    res.errMsg//成功：ok，错误：详细信息  }})

wx.onBLEConnectionStateChange(CALLBACK)

监听低功耗蓝牙连接的错误事件，包括设备丢失，连接异常断开等等

wx.onBLEConnectionStateChange(function(res) {  // 该方法回调中可以用于处理连接意外断开等异常情况  res.deviceId//蓝牙设备 id，参考 device 对象  res.connected//连接目前的状态})

wx.onBLECharacteristicValueChange(CALLBACK)

监听低功耗蓝牙设备的特征值变化。必须先启用notify接口才能接收到设备推送的notification

wx.onBLECharacteristicValueChange(function(res) {  deviceId//蓝牙设备 id，参考 device 对象  serviceId//特征值所属服务 uuid  characteristicId//特征值 uuid  value//特征值最新的值（注意：vConsole 无法打印出 ArrayBuffer 类型数据）})

蓝牙错误码(errCode)列表

错误码       备注0           正常10000       未初始化蓝牙适配器10001       当前蓝牙适配器不可用10002       没有找到指定设备10003       连接失败10004       没有找到指定服务10005       没有找到指定特征值10006       当前连接已断开10007       当前特征值不支持此操作10008       其余所有系统上报的异常10009       Android 系统特有，系统版本低于 4.3 不支持BLE10010       没有找到指定描述符10011       Android6.0以上系统因未打开定位导致搜寻蓝牙设备（startBluetoothDevicesDiscovery ）失败

IBeacon

wx.startBeaconDiscovery(OBJECT)

开始搜索附近的iBeacon设备

wx.startBeaconDiscovery({    uuids//(必要)iBeacon设备广播的 uuids    success(res) {        res.errMsg//调用结果    }})

wx.stopBeaconDiscovery(OBJECT)

停止搜索附近的iBeacon设备

wx.stopBeaconDiscovery(function(res) {  res.available//服务目前是否可用  res.discovering//目前是否处于搜索状态})

wx.getBeacons(OBJECT)

获取所有已搜索到的iBeacon设备

wx.onBeaconUpdate(CALLBACK)

监听 iBeacon 设备的更新事件

wx.onBeaconServiceChange(CALLBACK)

监听 iBeacon 服务的状态变化

wx.onBeaconServiceChange({    available   Boolean 服务目前是否可用discovering Boolean 目前是否处于搜索状态})

错误码列表

0           正常11000       系统或设备不支持11001       蓝牙服务不可用11002       位置服务不可用11003       已经开始搜索

屏幕亮度

wx.setScreenBrightness(OBJECT)

设置屏幕亮度

wx.getScreenBrightness(OBJECT)

获取屏幕亮度

wx.setKeepScreenOn(OBJECT)

设置是否保持常亮状态。仅在当前小程序生效，离开小程序后设置失效。

// 保持屏幕常亮wx.setKeepScreenOn({    keepScreenOn: true//(必要)是否保持屏幕常亮})

用户截屏事件

wx.onUserCaptureScreen(CALLBACK)

监听用户主动截屏事件，用户使用系统截屏按键截屏时触发此事件

wx.onUserCaptureScreen(function(res) {    console.log('用户截屏了')})

振动

wx.vibrateLong(OBJECT)

使手机发生较长时间的振动（400ms）

wx.vibrateShort(OBJECT)

使手机发生较短时间的振动（15ms）

1、vibrateShort 接口仅在 iPhone7/iPhone7Plus 及 Android 机型生效
2、 getScreenBrightness 接口若安卓系统设置中开启了自动调节亮度功能，则屏幕亮度会根据光线自动调整，该接口仅能获取自动调节亮度之前的值，而非实时的亮度值。

手机联系人

wx.addPhoneContact(OBJECT)

调用后，用户可以选择将该表单以“新增联系人”或“添加到已有联系人”的方式，写入手机系统通讯录，完成手机通讯录联系人和联系方式的增加

wx.addPhoneContact({    photoFilePath   //头像本地文件路径    nickName    //昵称    lastName    //姓氏    middleName  //中间名    firstName   //(必要)名字    remark  //备注    mobilePhoneNumber   //手机号    weChatNumber    //微信号    addressCountry  //联系地址国家    addressState    //联系地址省份    addressCity //联系地址城市    addressStreet   //联系地址街道    addressPostalCode   //联系地址邮政编码    organization    //公司    title   //职位    workFaxNumber   //工作传真    workPhoneNumber //工作电话    hostNumber  //公司电话    email   //电子邮件    url String  //网站    workAddressCountry  //工作地址国家    workAddressState    //工作地址省份    workAddressCity //工作地址城市    workAddressStreet   //工作地址街道    workAddressPostalCode   //工作地址邮政编码    homeFaxNumber   //住宅传真    homePhoneNumber //住宅电话    homeAddressCountry  //住宅地址国家    homeAddressState    //住宅地址省份    homeAddressCity //住宅地址城市    homeAddressStreet   //住宅地址街道    homeAddressPostalCode   //住宅地址邮政编码    success(res) {    }})