@hekr/sdk-h5

v0.1.3-alpha.5

Published

3 years ago

Hekr H5 software development kit

Downloads

0High
0Medium
0Low

xkloveme

hekr h5 sdk

sdk-h5

氦氪前端开发工具库

属性

所有属性除了options之外，其余都只能在ready之后调用

| 名称 | 类型 | 说明 | | --- | --- | --- | | app | object | app相关信息 | | URL | object | api请求相关的地址 | | device | object | 设备相关的数据 | | options | object | 从地址栏获取到的参数和初始化传递进入类的参数 | | fetch | object | api相关请求挂载的对象 | | i18nUI | object | 自动化布局相关配置 | | protocol | object | 设备协议 | | support | obejct | 当前环境支持的特性 |

support属性: 用于探测是否支持某个方法，如大可设备详情页面在旧版本App上不支持，所以应在页面上隐藏可参考：

http://gitlab.hekr.me/i18nUI/air-cleaner/blob/e5986af1362e933c64fe884adcbb398b476e2046/src/views/home.vue#L5
http://gitlab.hekr.me/i18nUI/air-cleaner/blob/e5986af1362e933c64fe884adcbb398b476e2046/src/views/home.vue#L79
http://gitlab.hekr.me/i18nUI/air-cleaner/blob/e5986af1362e933c64fe884adcbb398b476e2046/src/views/home.vue#L127
http://gitlab.hekr.me/i18nUI/air-cleaner/blob/e5986af1362e933c64fe884adcbb398b476e2046/src/views/home.vue#L258

{
  openPage: true/false
}

方法

| 名称 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | close | - | - | 关闭页面 | | decode | | object/string | 解码数据 | | emit | (enent: string) | - | 触发事件 | | encode | | object/string | 编码数据 | | off | (enent: string, fn: function) | - | 移除事件监听 | | on | (enent: string, fn: function) | - | 添加事件监听 | | once | (enent: string, fn: function) | - | 只监听一次事件 | | query | (...arg: string) | object | 获取地址栏search数据字段 | | send | (data: object) | - | 发送数据到云端 | | setStatusBarColor | (color: string) | - | 设置状态栏颜色，颜色格式为16进制形式，如setStatusBarColor('#0088ff') | | setTaskURL | (url: string) | - | 设置预约请求主域地址，可以自定义请求主域地址，需在ready回调之后调用才有效 | | openPage | (page?: string, params?: object) | - | 打开App原生页面, 如果不传参数默认打开设备详情页面 | | ready | (callback?: function) | Promise<void> | sdk准备完毕之后运行回调，如果失败会让Promise reject | | reloadGroup | - | - | 群控页面调用，用来在控制页面中刷新APP设备列表页面 |

事件

| 名称 | 回调参数 | 说明 | | --- | --- | --- | | loading | 返回boolean值，用来控制是否显示加载中浮层 | 控制命令下发超时的时候浮层显示控制 | | online | - | 设备上线 | | offline | - | 设备离线 | | error | 错误帧内容 | 收到errorResp帧时触发 | | back | - | 安卓设备点击物理返回键时触发 | | devSend | 1.设备上报帧信息，2.设备上报数据解码之后的内容 | 接收到上报帧时触发 | | [上报帧名称] | 上报数据内容 | 收到上报帧后触发，事件名称为上报帧的cmdtTag |

使用

在使用模块化的开发方式时，推荐使用 NPM 安装 SDK，能够和 Webpack 等模块打包器配合使用。

# 更改 npm 源
$ npm config set registry http://npm.hekr.me

# 稳定版
$ npm install @hekr/sdk-h5

# 开发版
$ npm install @hekr/sdk-h5@beta

之后，在项目文件中注入以下代码。

// main.js
import { Hekr, Matrix } from '@hekr/sdk-h5'

// 调试时才会运行，生成环境不会有
if (process.env.NODE_ENV !== 'production') {
  const keys = require('../keys.json')
  // 这里也可以传入参数重写URL地址
  window.Matrix = new Matrix({
    ...keys, // 传入devTid，token等信息
    URL: { // 重写默认URL地址，没有传的就是用默认值
      ws: 'wss://asia-app.hekr.me:186', // websocket地址
      uaa: 'https://uaa-openapi.hekr.me', // uaa地址
      user: 'https://user-openapi.hekr.me', // user地址
      console: 'https://console-openapi.hekr.me', // console地址
      task: 'https://uaa-openapi.hekr.me' // 自定义预约请求主域，不设置默认为https://uaa-openapi.hekr.me加上区域信息
    }
  })
}

Vue.prototype.$Hekr = window.$Hekr = new Hekr({
  query: { // 定义发送自动查询
    frame: { // 查询帧的帧内容
      cmdId: 0
    },
    duration: 30, // 查询自动查询帧时间间隔
    auto: true, // 是否自动循环发送
    timeService: [], // 授时查询，当项目需要在查询帧中带上授时时修改此参数，可选时间参数有 `year`, `month`, `week`, `day`, `hour`, `minute`
    fn: frame => frame // 查询帧函数，当授时查询不能满足项目需求或其他情况时，在此参数中传入一个函数，在查询发送前进行最后的修改操作。
  },
  protocol: ,// 协议，传入此参数就不需要再向云端请求协议
  decode: undefined, // 自定义帧的解码函数
  encode: undefined, // 自定义帧的编码函数
  i18nUI: false // 定义是否去拉取i18nUI配置，默认不拉取
})

参数信息

当 SDK 启动后，在此对象中可以获取与当前用户和设备有关的参数，用于请求等。

URL

Hekr请求api域

{
  ws: 'wss://asia-app.hekr.me:186',
  uaa: 'https://uaa-openapi.hekr.me',
  user: 'https://user-openapi.hekr.me',
  console: 'https://console-openapi.hekr.me',
  task: 'https://uaa-openapi.hekr.me'
}

options

Hekroptions参数

{
  appId: '', // 地址栏获取的appId
  lang: '',  // 地址栏获取的lang
  devTid: '', // 地址栏获取的devTid
  subDevTid: '', // 地址栏获取的subDevTid
  group: true/false, // 地址栏获取的group参数，表示是否为群控
  groupId: '', // 地址栏获取的groupId
  runVirtual: runVirtual ? Number(runVirtual) : 0, // 地址栏获取的runVirtual参数，为1表示运行虚拟设备，为0不运行
  /**
   * 以下内容是hekr初始化时传进来的参数与默认值合并之后的内容
   */
  query: { // 定义发送自动查询
    frame: { // 查询帧的帧内容
      cmdId: 0
    },
    duration: 30, // 查询自动查询帧时间间隔
    auto: true, // 是否自动循环发送
    timeService: [], // 授时查询，当项目需要在查询帧中带上授时时修改此参数，可选时间参数有 `year`, `month`, `week`, `day`, `hour`, `minute`
    fn: frame => frame, // 查询帧函数，当授时查询不能满足项目需求或其他情况时，在此参数中传入一个函数，在查询发送前进行最后的修改操作。
  },
  protocol: null,// 协议，传入此参数就不需要再向云端请求协议
  decode: undefined, // 自定义帧的解码函数
  encode: undefined, // 自定义帧的编码函数
  i18nUI: false
}

fetch

Hekr发送请求的Api，可直接调用$hekr.fetch({...})发送请求，使用方式和axios一样(就是对axios的封装)，使用示例可参考云端 API部分

{
  QRCode: { // 授权二维码
    get: Function,
    format: Function
  },
  preferences: { // 偏好
    get: Function,
    set: Function,
    format: Function
  },
  schedulerTask: { // 预约
    get: Function,
    set: Function,
    del: Function,
    format: Function
  },
  snapshot: { // 快照
    get: Function,
    format: Function
  },
  statistics: { // 统计数据
    get: Function,
    format: Function
  },
  warnings: { // 告警日志
    get: Function,
    format: Function
  },
  weather: { // 天气接口
    get: Function,
    format: Function
  },
  device: Function, // 拉取设备
  protocol: Function // 拉取协议
}

app

用户信息参数在 Hekr.app 中查看。

{
  appTid: '...',
  token: '...',
  mode: 'Cloud/LAN',
  network: 'WiFi/WWAN/NotReachable',
  platform: 'iOS/Android'
}

device

设备信息参数在 Hekr.device 中查看，格式详见列举设备列表。

{
  device: {
    deviceName: '...',
    devTid: '...',
    ...
  }
}

template

协议信息参数在 Hekr.template 中查看，格式详见获取产品协议模板。

{
  template: {
    protocol: {
      ...
    },
    workModeType: '...',
    ...
  }
}

设备通信

针对不同的项目，在 console 平台对应的产品页面中，会建立不同的协议模板，SDK 根据这个协议模板来进行协议的编码和解码。

例如，某产品有如下协议模板：

参数

| 名称 | 类型 | 单位 | 取值范围 | 参数描述 | |:-----|:-------|:-----|:--------------|:---------| | sw | NUMBER | | · 0 关 · 1 开 | 开关 |

命令

| 名称 | 命令ID | 帧类型 | 示例帧 | 命令描述 | |:----------|:-------|:-------|:-------|:-------------| | queryDev | 0 | 下发帧 | 查看 | 设备状态查询 | | reportDev | 1 | 上报帧 | 查看 | 上报设备状态 | | setSw | 2 | 下发帧 | 查看 | 设置开关 |

通常，当设备接收到 queryDev 的查询帧，或 setSw 的下发帧导致设备状态改变时，设备会主动发送 reportDev 的上报帧。

发送数据

调用 Hekr.send 方法来发送数据，传入一个带有命令名称 cmdTag 和命令所需参数的对象，SDK 会自动根据协议类型进行编码并发送。其中，命令名称 cmdTag: 'setSw' 也可以替换成命令ID cmdId: 2，但建议使用命令名称 cmdTag。

$Hekr.send({
  cmdTag: 'setSw',
  sw: 1
})

此外，发送数据时的 action 默认为 appSend，当项目为群控(地址栏参数有group=true&groupId=121232)时action会被自动指定为 appGroupSend，不需要额外的设置，和单独控制调用完全一样。

接收数据

调用 Hekr.on 方法来监听命令，传入上报帧的命令名称和回调函数，SDK 接收到数据后，会自动根据协议类型进行解码并触发回调函数。通常来说，开发者只需要接收上报帧，但也可以监听下发帧来满足某些特殊情况。

$Hekr.on('reportDev', data => {
  console.log(data)
})

SDK 也提供与 on 方法对应的，同属事件系统的 off、once 和 emit 方法。

// 监听单次事件
$Hekr.once('reportDev', data => {
  console.log(data)
})

// 移除所有事件
$Hekr.off()
// 移除某一事件
$Hekr.off('reportDev')
// 移除某一事件下的某一回调函数
$Hekr.off('reportDev', fn)

// 主动触发事件
$Hekr.emit('reportDev', data)

自定义查询帧

查询帧是一种特殊的下发帧。通常情况下，需要每隔 30 秒查询一次。SDK 预设了一种没有其他参数、且每 30 秒发送一次的查询帧。此外，开发者可对查询帧进行自定义，满足不同项目的需求。

// 默认查询帧格式
{ cmdId: 0 }

// 自定义查询帧
new Hekr({
  query: {
    frame: {
      cmdId: 0
    },
    duration: 30,
    auto: true,
    timeService: [],
    fn: frame => frame
  }
})

自定义参数

frame

查询帧格式，当查询帧不为 { cmdId: 0 } 时修改此参数。

duration

查询周期，当查询帧不为每30秒发送时修改此参数。

auto

是否自动查询，当项目不需要自动查询或只需手动发送一帧时修改此参数。

timeService

授时查询，当项目需要在查询帧中带上授时时修改此参数，可选时间参数有 year, month, week, day, hour, minute。

查询帧函数，当授时查询不能满足项目需求或其他情况时，在此参数中传入一个函数，在查询发送前进行最后的修改操作。

自定义编解码函数

对于协议类型为 JSON透传协议不校验raw 的项目，需要开发者自行编写自定义的编解码函数，请先阅读理解串口透传协议。

// 默认函数
new Hekr({
  decode: raw => raw,
  encode: data => data.raw
})

自定义编解码时，只需关注产品业务数据部分，数据头和数据尾会由 SDK 自动补全。例如：

自定义解码

函数中的参数 raw 为帧格式中的产品业务数据部分，并非完整的帧。

// 如果接收的数据为 '48070101010052'
// Hekr 会预先截取产品业务数据部分，即 '0100'
function decode (raw) {
  // raw 为　'0100'
  // ...
  // 最后应该返回 { cmdTag: 'reportDev', cmdId: 1, sw: 0 }
  return decoded
}

自定义编码

函数中的参数 data 为调用 Hekr.send 时所传的数据，且只需要返回帧格式中的产品业务数据部分，并非完整的帧。

// 如果发送的数据为 { cmdId: 2, sw: 1 }　
function encode (data) {
  // ...
  // 最后应该返回 '0201'
  return encoded
}
// Hekr 会补全数据头和数据尾后再发送，即 '48070201020155'

协议模板

在丛云 App 中开发具有局域网功能的控制页面时，需要从本地将协议模板打包到项目中，建议使用 hekr-cli 快速获取协议模板。

const protocol = require('./path/to/protocol.json')

new Hekr({
  protocol
})

openPage函数

调用打开app原生页面

$Hekr.openPage(page?: string, params?: object)

// 直接调用不传参数时打开设备详情
$Hekr.openPage()

支持参数组合 | page | params | | --- | --- | | device | { divTid: '', ctrlKey: ''} |

ready函数

SDK 提供一个 ready 方法，用于在完成准备阶段，获取到所有必需参数后，触发回调函数。开发者在页面加载完毕时进行的接口请求等操作，需要在这个回调函数里执行。此外，在没有提供回调函数的情况下返回 Promise。

$Hekr.ready(() => {
  // ...
}).catch(err => {
  // ...
})

// 或

$Hekr.ready()
  .then(() => {
    // ...
  })
  .catch(err => {
    // ...
  })

URL 参数查询

SDK 提供了 query 方法，满足开发者在页面的 URL 中快速进行参数查询，与客户端进行某些联动。

// http://localhost.com?q=1&w=2&e=3

$Hekr.query('q') // { q: 1 }

$Hekr.query('q', 'w') // { q: 1, w: 2 }

$Hekr.query() // { q: 1, w: 2, e: 3 }

云端 API

SDK 对一些常用的云端接口请求进行了封装，并提供了相应的格式化方法，方便开发者调用。

定时预约

预约任务通常用于某些设备的定时触发任务，有单次预约和循环预约两种方式。

查询预约

$Hekr.fetch.schedulerTask.get()
  .then(res => {
    const tasks = $Hekr.fetch.schedulerTask.format(res)
    // ...
  })

添加或编辑预约

当传入的任务对象中没有 taskId 字段时，为添加预约任务，否则为编辑预约任务。

// 添加单次预约
$Hekr.fetch.schedulerTask.set({
  taskName: '未命名',   // 默认任务名称为 '未命名'
  desc: '备注',         // 默认任务描述为 '备注'
  code: {              // 任务触发代码，必传
    cmdTag: 'queryDev'
  },
  date: new Date(),     // 任务触发时间，为 Date 对象，必传
  data: {               // 或一个有 'hour'、'minute'、'second' 的对象
    hour: 12,
    minute: 0
  },
  enable: true          // 任务是否启用，默认为启动
})
  .then(res => {
    const tasks = $Hekr.fetch.schedulerTask.format(res)
    // ...
  })

//　编辑循环预约
$Hekr.fetch.schedulerTask.set({
  taskId: null,         // 当有该字段时为编辑预约任务
  code: {        
    cmdTag: 'queryDev'
  },
  data: {               // 当有 'repeatList' 字段时为循环预约任务
    hour: 12,
    minute: 0,
    repeatList: ['MON', 'TUE', 'WES', 'THU', 'FRI', 'SAT', 'SUN']
  }
})
  .then(res => {
    const tasks = $Hekr.fetch.schedulerTask.format(res)
    // ...
  })

删除预约

删除预约任务时，可直接传入预约任务对象，当参数为空时会删除所有预约任务。

$Hekr.fetch.schedulerTask.del(task)
  .then(res => {
    const tasks = $Hekr.fetch.schedulerTask.format(res)
    // ...
  })

获取最近将要触发的预约

// next为null表示没有能够触发的预约
// 如存在next为：{hour: ,minte: , secend: ,next: {}}
const next = $Hekr.fetch.schedulerTask.next(task)

设备快照

设备快照通常用于获取设备状态，优先于设备上报帧，在页面上展示设备状态。

$Hekr.fetch.snapshot.get()
  .then(res => {
    const snapshot = $Hekr.fetch.snapshot.format(res)
    // ...
  })

统计数据

统计数据通常用于图表数据展示，有 hourly、daily、weekly、monthly、yearly 五种频率。

$Hekr.fetch.statistics.get(
  frequency: string, // hourly、daily、weekly、monthly、yearly
  tag: string | string[], // 数据参数名称（协议里面对应的字段名称），可以用数组形式传参，如：lightness或[lightness]
)

$Hekr.fetch.statistics.format(
  data: [], // 云端返回统计原始数据
  frequency: string, // hourly、daily、weekly、monthly、yearly
  tag: string | string[], // 数据参数名称（协议里面对应的字段名称），可以用数组形式传参，如：lightness或[lightness]
  xStep?: number // x轴分度值
)
// 获取一天内 'lightness' 的统计数据
$Hekr.fetch.statistics.get('daily', 'lightness')
  .then(res => {
    const statistics = $Hekr.fetch.statistics.format(res, 'daily', 'lightness')
    // ...
  })

// 获取一月内每 5 天的 'lightness' 和 'humidity' 的统计数据
$Hekr.fetch.statistics.get('monthly', ['lightness', 'humidity'])
  .then(res => {
    const statistics = $Hekr.fetch.statistics.format(res, 'monthly', 5)
    // ...
  })

告警日志

告警日志属于 'WARNING' 级别的用户通知，通常用于展示设备的告警记录。

const page = 0 // page 默认为 0
const size = 20 // size 默认为 20

// 获取第一页的 20 条告警日志
$Hekr.fetch.warnings.get(page, size)
  .then(res => {
    const warnings = $Hekr.fetch.warnings.format(res)
    // ...
  })

设备偏好

设备偏好通常用于存储用户的配置等数据，需要先在 console 中提前定义好字段名。

获取设备偏好

$Hekr.fetch.preferences.get()
  .then(res => {
    const preferences = $Hekr.fetch.preferences.format(res)
    // ...
  })

设置设备偏好

$Hekr.fetch.preferences.set(preferences)
  .then(res => {
    const preferences = $Hekr.fetch.preferences.format(res)
    // ...
  })

天气实况

天气实况通常用于获取设备所在城市的室外温湿度等参数。

if ($Hekr.device.gis) {
  // 获取设备所在城市
  const location = $Hekr.device.gis.ip.city

  // 获取设备当地的天气实况, 参数 lang, unit 非必传
  $Hekr.fetch.weather.get(location, 'zh-Hans', 'c')
    .then(res => {
      const weather = $Hekr.fetch.weather.format(res)
      // ...
    })
}

授权管理

反向授权创建通常用于创建二维码，供用户进行授权分享。

// 参数 expire 为有效时间，非必传
$Hekr.fetch.QRCode.get(86400)
  .then(res => {
    const code = $Hekr.fetch.QRCode.format(res)
    // ...
  })