小程序文档整理之 -- 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 不支持BLE
10010       没有找到指定描述符
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) {
    }
})