qcloud-iotexplorer-h5-panel-sdk

qcloud-iotexplorer-h5-panel-sdk

腾讯连连小程序自定义H5面板SDK开发文档

开始使用

npm i qcloud-iotexplorer-h5-panel-sdk

引入sdk

import sdk from 'qcloud-iotexplorer-h5-panel-sdk';

// or
const sdk = require('qcloud-iotexplorer-h5-panel-sdk');

API

sdk.controlDeviceData: (data, deviceId?: string) => Promise

• data: any;
• deviceId?: string; 可选，不传则使用当前设备deviceId

控制设备属性，如：

sdk.controlDeviceData({
    power_switch: 1
});

sdk.getDeviceDataHistory: (options) => Promise<{ RequestId: string, Context: string, FieldName: string, Listover: boolean, Results: any[] }>

• options.FieldName: string; 查询的属性名称
• options.MaxTime: number; 结束时间，毫秒时间戳
• options.MinTime: number; 开始时间，毫秒时间戳
• options.Context?: string; 翻页游标，首次查询时，可不带
• options.Limit: number; 单页数据量

查询设备历史数据，具体用法参见: AppGetDeviceDataHistory 接口文档

sdk.getUserInfo()

拉取用户信息，具体用法参考 AppGetUser 接口文档

sdk.getProductInfo: ({ productId?: string }) => Promise

• productId?: string; 可选，不传则使用当前产品 ProductId

拉取设备所属产品信息，具体用法参考 AppGetProducts 接口文档

sdk.getDeviceInfo: ({ deviceId?: string }) => Promise

• deviceId?: string; 可选，不传则使用当前设备deviceId

拉取设备信息

sdk.getDeviceData: ({ deviceId?: string }) => Promise

• deviceId?: string; 可选，不传则使用当前设备deviceId

拉取设备最新的属性，具体用法参考 AppGetDeviceData 接口文档

sdk.getDeviceStatus: ({ deviceId?: string }) => Promise<0 | 1>

• deviceId?: string; 可选，不传则使用当前设备deviceId

拉取设备当前在线状态，0 - 离线，1 - 在线

sdk.deleteDevice: ({ deviceId?: string }) => Promise

删除设备，deviceId可选，不传则使用当前设备deviceId

sdk.getShareParams({ deviceId?: string }) => Promise

若该设备是分享设备，且分享方设置了自定义分享参数，则被分享人在接受分享后可通过调用该接口获取自定义分享参数

sdk.showDeviceDetail(options) => void;

• options.deviceInfo?: Object; 展示详情的设备信息，不传则使用当前设备信息
• options.labelWidth?: number; 设备详情的label宽度，默认 110，单位 px
• options.marginTop?: number; 设备详情的上间距，默认 10，单位 px
• options.shareParams?: object | string; 自定义分享参数
• options.extendItems?: ExtendItemConfig[]; 自定义菜单配置
• options.extendItems.labelIcon?: string; 展示在 label 前的 icon 地址
• options.extendItems.label: string; 自定义菜单项的标题
• options.extendItems.content?: string; 自定义菜单项的内容
• options.extendItems.className?: string; 自定义菜单项的样式类名
• options.extendItems.onClick?: () => any; 点击自定义菜单项后触发的回调
• options.extendButtons?: ExtendButtonConfig[]; 自定义按钮配置
• options.extendButtons.text: string; 自定义按钮文案
• options.extendButtons.className?: string; 自定义按钮的样式类名
• options.extendButtons.type?: 'danger' | 'primary' | 'warning'; 自定义按钮的风格
• options.extendButtons.onClick: () => any; 自定义按钮点击后触发的回调
• options.containerClassName?: string; 容器的样式名

在当前 H5 展示一个铺满全屏的设备详情视图，支持自定义拓展菜单项及按钮。

sdk.hideDeviceDetail() => void;

关闭设备详情视图

sdk.requestTokenApi: (action, data, options) => Promise

• action: string 具体api名称，如：AppGetUser
• data: object 接口调用参数
• options: 参数参考 appDevSdk.requestApi 文档

sdk.goDeviceDetailPage: (options) => void

• options.reload?: boolean; 如果传了 reload=true，则进入详情页后会重新拉取一次该设备的数据
• options.deviceId?: string; 可选，不传则使用当前设备deviceId
• options.isShareDevice?: boolean; 可选，设备是否分享设备，不传则使用当前 sdk.isShareDevice
• options.shareParams?: object | string; 可选，设备自定义分享参数

跳转到腾讯连连通用的产品详情页（小程序页面）

sdk.goFeedBackPage()

前往连连小程序反馈页面

sdk.goDeviceInfoPage: ({ deviceId?: string }) => Promise

• deviceId?: string; 可选，不传则使用当前设备deviceId

前往设备信息页

sdk.goEditDeviceNamePage: ({ deviceId?: string, name?: string }) => Promise

• deviceId?: string; 可选，不传则使用当前设备deviceId
• name?: string; 可选，不传则使用当前设备的aliasName

前往修改设备名称页

sdk.goRoomSettingPage: ({ deviceId?: string }) => Promise

• deviceId?: string; 可选，不传则使用当前设备deviceId

前往房间设置页

sdk.goShareDevicePage: ({ deviceId?: string, shareParams?: object | string }) => Promise

• deviceId?: string; 可选，不传则使用当前设备deviceId
• shareParams?: object | string; 可选，自定义分享参数

前往设备分享页

sdk.reloadAfterUnmount()

退出当前h5页面返回连连小程序后，让小程序主动刷新一次当前数据。

sdk.setShareConfig: ({ title, imgUrl }) => Promise

• title: string 分享的标题
• imgUrl?: string 分享图片的地址，默认会取当前页面截图

设置当前页面的分享内容，通过 wx.miniProgram.postMessage 向小程序推送分享信息，具体参考 小程序页面分享文档

sdk.navBack: () => Promise

调用 wx.miniProgram.navigateBack 返回上一级页面

sdk.appDevSdk

应用开发 SDK 实例，H5面板sdk底层依赖 应用开发小程序端SDK，更多调用能力请参考应用开发SDK文档

sdk.wx

微信 JS-SDK 实例，具体用法参考官方文档，使用前必须保证已经调用 sdk.wxSdkReady 方法

sdk.wxSdkReady: () => Promise

确保微信 jssdk 已注册完成，完成后会触发 resolve，该方法多次调用，若成功会返回缓存的 Promise 对象，如：

sdk.wxSdkReady().then(() => wx.miniProgram.navigateBack());

sdk.on(EventName, callback)

sdk.off(EventName, callback)

监听/解绑事件

事件

Event: 'wsClose'

• code: number;
• reason: string;

websocket 的 close 事件

Event: 'wsError'

• error websocket的错误事件

websocket 的 error 事件

Event: 'wsControl'

• deviceId 设备id
• deviceData 设备数据

当 websocket 收到 control 指令后触发

Event: 'wsReport'

• deviceId 设备id
• deviceData 设备数据

当 websocket 收到 report 指令后触发

Event: 'wsStatusChange'

• deviceId 设备id
• deviceStatus: 0 | 1; 设备状态

当 websocket 收到 wsStatusChange 后触发

Event: 'appShow'

当 App.onShow 执行后触发

Event: 'appHide'

当 App.onHide 执行后触发

Event: 'pageShow'

当 Page.onShow 执行后触发

Event: 'pageHide'

当 Page.onHide 执行后触发

(Deprecated) sdk.onWsClose: (callback) => void;

已废弃，请用 sdk.on('wsClose', callback) 代替

• callback: ({ code, reason }) => void;

当 websocket close 事件触发后执行回调

(Deprecated) sdk.onWsError: (callback) => void;

已废弃，请用 sdk.on('wsError', callback) 代替

• callback: (error) => void;

当 websocket 触发 error 事件后触发回调

(Deprecated) sdk.onWsControl: (callback) => void;

已废弃，请用 sdk.on('wsControl', callback) 代替

• callback: ({ deviceId, deviceData }) => void;

当 websocket 收到 control 指令后触发

(Deprecated) sdk.onWsReport: (callback) => void;

已废弃，请用 sdk.on('wsReport', callback) 代替

• callback: ({ deviceId, deviceData }) => void;

当 websocket 收到 report 指令后触发

(Deprecated) sdk.onWsStatusChange: (callback) => void;

已废弃，请用 sdk.on('wsStatusChange', callback) 代替

• callback: ({ deviceId, deviceStatus }) => void;

当 websocket 收到设备状态改变推送后触发回调

sdk.tips

tips模块，样式和风格与连连小程序一致

sdk.tips.show: (message, options) => Promise

• options.type?: 'info' | 'danger' | 'loading' | 'success';
• options.waitForHide?: boolean; 若为true，则 show 方法返回一个Promise，并且当关闭后才会触发 resolve
• options.duration?: number; 展示提示的时间，单位毫秒，默认 1500
• options.delayDuration?: number; 默认0，单位毫秒，提示会在该延时后展示
• options.canClickClose?: boolean; 默认true，点击mask是否能够关闭提示
• options.canBeReplace?: boolean; 默认false，为false时上一个提示未关闭前，再次调用 tips.show会被忽略

展示tips

sdk.tips.hide: () => Promise

关闭tips

sdk.tips.showLoading: (message, options) => Promise

封装后的 tips.show 方法，等价于：

this.show(message, {
    type: 'loading',
    canBeReplace: true,
    duration: 0,
    delayDuration: 200,
    canClickClose: false,
    ...options,
})

sdk.tips.hideLoading: () => Promise

关闭loading tips

注意，showLoading后必须主动调用hideLoading，否则tips永远不会消失

sdk.tips.showSuccess: (message, options) => Promise

封装后的 tips.show 方法，等价于：

this.show(message, { type: 'success', ...opts });

sdk.tips.showInfo: (message, options) => Promise

封装后的 tips.show 方法，等价于：

this.show(message, { type: 'info', ...options });

sdk.tips.showError: (error, options) => Promise

• error: any; 可以为一个原生Error对象，可以为标准的api响应 { code, msg }，也可以为一个字符串。

会先标准化处理错误展示信息后展示tips，等价于：

sdk.tips.showModal: (options: ShowModalOptions) => Promise

• ShowModalOptions.title?: string; 弹窗标题
• ShowModalOptions.content? string; 弹窗内容
• ShowModalOptions.showCancel?: boolean; 是否展示取消按钮，默认为 true
• ShowModalOptions.cancelText?: string; 取消按钮文案，默认："取消"
• ShowModalOptions.cancelColor?: string; 取消按钮颜色，默认："#888"
• ShowModalOptions.confirmText?: string; 确认按钮文案，默认："确定"
• ShowModalOptions.confirmColor?: string; 确认按钮颜色，默认: "#0052D9"

展示一个弹窗，参数、功能、样式同小程序原生 showModal 基本一致，返回一个 Promise，为 true 代表用户点击确认，返回 false 表示用户点击取消。

sdk.tips.confirm: (title, content, options) => Promise

• title?: string;
• content?: string;
• options?: ShowModalOptions;

基于 showModal 封装，用于向用户进行二次确认操作时使用，用法：

const isConfirm = await sdk.tips.confirm('确认删除该设备吗？')

if (isConfirm) {
    // do something
}

sdk.tips.alert: (content, options) => Promise

• content?: string;
• options?: ShowModalOptions;

基于 showModal 封装，用于向用户进行消息提示操作时使用，用法：

await sdk.tips.alert('该功能暂时无法使用，请稍后再试');

// do something else

sdk.offlineTip

设备离线提示组件，样式和风格与连连小程序一致

sdk.offlineTip.show: () => void;

展示离线提示

sdk.showOfflineTip: () => void;

用法同 sdk.offlineTip.show()

sdk.offlineTip.hide: () => void;

关闭离线提示

sdk.hideOfflineTip: () => void;

用法同 sdk.offlineTip.hide()

属性

sdk.deviceId: string

设备id，由 {productId}/{deviceName} 组成

sdk.productId: string

产品id

sdk.deviceName: string

设备名称

sdk.deviceInfo

设备信息，如：

{
    AliasName: "设备别名",
    CreateTime: 1583739344,
    DeviceId: "{productId}/{deviceName}",
    DeviceName: "{deviceName}",
    DeviceType: 0,
    FamilyId: "家庭ID",
    IconUrl: "设备ICON",
    ProductId: "{productId}",
    RoomId: "房间id",
    UpdateTime: 1583739344,
    UserID: "用户Id"
}

sdk.roomList

当前家庭的房间列表

sdk.roomName

当前设备的房间名称

sdk.dataTemplate

设备所在产品的物模型，如：

{
    "version": "1.0",
    "profile": {
        "ProductId": "xxxx",
        "CategoryId": "1"
    },
    "properties": [
        {
            "id": "int",
            "name": "int",
            "desc": "",
            "mode": "rw",
            "define": {
                "type": "int",
                "min": "0",
                "max": "100",
                "start": "0",
                "step": "1",
                "unit": ""
            },
            "required": false
        },
    ],
    "events": [],
    "actions": []
}

sdk.deviceStatus: number

设备在线状态，在线: 1，非在线: 0

sdk.deviceDisplayName: string

设备展示名称，会依次取：AliasName > productInfo.name > deviceName 来展示

sdk.isShareDevice: boolean

是否是分享设备

sdk.familyId: string

设备所在家庭id，如果是分享设备则无此值

sdk.roomId: string;

设备所在房间id，如果是分享设备则无此值

sdk.familyInfo

设备所在家庭详情，如果是分享设备则无此值

sdk.isFamilyOwner: boolean

用户是否是当前家庭的管理员

sdk.userInfo

用户信息，如：

{
    Avatar: "头像url",
    CountryCode: "国家代码",
    Email: "email",
    NickName: "昵称",
    PhoneNumber: "电话号码",
    UserID: "用户id"
}

蓝牙模块

由于h5中无法直接调用小程序蓝牙相关接口，sdk封装了特殊的蓝牙模块，通过一个单独的websocket通道打通了h5到小程序直接的蓝牙通信

名词介绍

介绍蓝牙模块中使用到的一些名词

serviceId

服务id，蓝牙服务的uuid，搜索设备时主要通过 serviceId 来过滤我们需要的设备。

deviceId

小程序api搜索出来的设备的标识，连接设备时主要通过 deviceId 来标识需要连接的设备

explorerDeviceId

物联网开发平台侧定义的设备ID，查询设备数据和上报设备数据时以该 id 作为设备标识。

BlueToothAdapter 蓝牙适配器

全局单例，实例上声明了蓝牙搜索、连接等方法

DeviceAdapter 设备适配器

真正用来连接设备以及跟设备进行通信的模块，每一个设备连接对应一个设备适配器实例，设备适配器会在连接设备后实例化，并在设备断开连接后销毁。

根据不同的 serviceId 来区别不同类型设备的适配器构造函数。

API

sdk.blueToothAdapter

sdk.addAdapter: (DeviceAdapter) => void;

添加一个设备适配器，默认无任何设备适配器，使用时需要根据具体设备情况创建一个设备适配器，并将其构造函数添加到蓝牙适配器中。

如：

class DemoDeviceAdapter extends DeviceAdapter {
	static serviceId = '0000FFF0-0000-1000-8000-00805F9B34CC';

	static deviceFilter(deviceInfo) {
		if (deviceInfo.advertisServiceUUIDs) {
			const matchedServiceId = deviceInfo.advertisServiceUUIDs.find(id => id === DemoDeviceAdapter.serviceId);

			if (matchedServiceId && deviceInfo.advertisData) {
				try {
					const macArr = deviceInfo.advertisData.slice(2);
					const mac = macArr.join(':');

					return {
						...deviceInfo,
						deviceName: mac,
						serviceId: matchedServiceId,
					}
				} catch (err) {
					console.error('parse mac error', err);
				}
			}
		}
	}

	handleBLEMessage(hex) {
        return {
          type: 'unknown',
          data: hex,
        };
	}
}

sdk.bluetoothAdapter.addAdapter(DemoDeviceAdapter);

sdk.blueToothAdapter.init() => Promise;

初始化蓝牙模块，包括初始化蓝牙模块，打通小程序间蓝牙通信，注册全局回调等。返回一个带缓存的Promise，可重复调用，可在每次使用前调用

sdk.blueToothAdapter.startSearch(startSearchParams) => Promise

开始搜索蓝牙设备（将会调用 wx.startBluetoothDevicesDiscovery，比较耗费系统资源，务必在不需要搜索后调用 blueToothAdapter.stopSearch，如离开页面后）

该方法返回一个 Promise，注意务必要等待 Promise 响应 resolve 才代表操作指行成功。

startSearchParams.serviceId?: string;

startSearchParams.serviceIds?: string[];

指定需要搜索的serviceId，不传的话会使用当前支持的所有 DeviceAdapter 的 serviceId 来匹配。

startSearchParams.ignoreDeviceIds?: string[]

可选，需要过滤掉的 deviceId 列表（比如刚添加完的设备），搜索结果中将不会出现这些设备

startSearchParams.onSearch: (DeviceInfo[]) => void;

当搜索结果更新后调用，返回搜索到的设备列表

startSearchParams.onError: (Error) => void;

当搜索过程中发生错误后调用，触发后设备搜索将会中止

startSearchParams.timeout: number

可选，默认 20000，单位毫秒，超过多久没搜索到设备后将会触发超时错误

blueToothAdapter.stopSearch() => void;

停止搜索设备

blueToothAdapter.searchDevice(searchDeviceParams) => Promise

搜索蓝牙设备，并将在找到第一个满足条件的设备后 resolve，与 startSearch 的区别在于 searchDevice 在搜到第一个匹配设备后即会中止搜索。 该方法常用于已经绑定过设备后，在连接设备时来定向搜索该设备。

startSearchParams.serviceId?: string;

startSearchParams.serviceIds?: string[];

指定需要搜索的serviceId，不传的话会使用当前支持的所有 DeviceAdapter 的 serviceId 来匹配。

searchDeviceParams.deviceName

指定需要搜索的设备 deviceName

searchDeviceParams.ignoreDeviceIds

同 startSearchParams.ignoreDeviceIds

blueToothAdapter.connectDevice(DeviceInfo) => Promise

连接指定设备，传入 searchDevice 或 startSearch 接口搜索出来的 DeviceInfo，连接成功后返回设备适配器

blueToothAdapter.getDeviceAdapter(deviceId) => deviceAdapter

根据 deviceId 查询对应的设备适配器实例，如果设备未连接或已断开，则返回空

事件

blueToothAdapter.on('adapterStateChange', ({ available, discovering }) => {})

当适配器状态变化时触发。

DeviceAdapter

设备适配器构造函数

DeviceAdapter.serviceId

子类在继承基类后需要设置该属性，代表该设备的主服务ID

DeviceAdapter.deviceFilter: (deviceInfo: DeviceInfo) => { deviceName: string, serviceId: string, ...deviceInfo }

子类在继承基类后需要实现该静态方法，在搜索蓝牙设备时会将每个搜出的设备信息传入该方法，如果判断是本产品的设备，则需在除入参deviceInfo之外返回设备唯一标识 deviceName 及 serviceId，否则返回空；

deviceAdapter

设备适配器

deviceAdapter.explorerDeviceId

getter，设备的 explorerDeviceId

deviceAdapter.isConnected

getter，设备当前是否连接状态

deviceAdapter.deviceId

getter，设备的 deviceId

deviceAdapter.serviceId

getter，设备的主服务ID，实际上既是挂在构造函数上的静态属性 DeviceAdapter.serviceId

deviceAdapter.originName

getter，设备的原始名称，即小程序接口搜索出来时的 name 字段

deviceAdapter.explorerDeviceId

getter，设备的 explorerDeviceId

deviceAdapter.disconnectDevice() => void

主动断开设备连接

deviceAdapter.write: (hexString) => Promise

• hexString: string; 需要写给蓝牙设备的16进制字符串

往蓝牙设备写数据。

deviceAdapter.handleBLEMessage: (hexString) => { reportData?: any, ...any }

子类继承基类后需要实现该方法，用于处理收到 onBLECharacteristicValueChange 回调后的协议解析。

返回值中如果返回 reportData，则会将该部分数据上报到云端（注意需与产品定义物模型匹配），其他字段则会透传到 message 事件的 payload 中。

deviceAdapter 事件

Event: 'connect'

设备连接后触发

Event: 'disconnect'

设备断开后触发

Event: 'message'

• timestamp: number; 收到设备消息的时间戳，单位毫秒
• dataReported: boolean; 收到设备的消息是否已上报云端
• 其他; handleBLEMessage 函数返回的其他参数将会透传到 message 事件中

当收到 onBLECharacteristicValueChange 回调，并经过 handleBLEMessage 处理后触发

Event: 'bLEConnectionStateChange'

• connected: boolean; 设备是否连接

当 onBleConnectionStateChange 触发时触发，若 connected 为 true，则接下来会触发事件 'connect'，否则会触发事件 'disconnect'

设备分享时设置自定义分享参数

1. 前往设备详情/分享列表页时，带上 shareParams 参数
2. 被分享人接受分享后，可通过调用 sdk.getShareParams() 方法获取分享时设置的 shareParams 参数