插件开发规范

3. 插件开发规范

3.1背景介绍

#美的IoT开发者平台基于M-Smart协议，共建共享智能家居生态圈。

为了帮助第三方开发者更方便、更快捷的参与美居智能产品插件的开发，提供了一套快速开发weex插件的工具套件。

dolphin-weex-cli 脚手架
dolphin-weex-ui 组件库
dolphin-weex-template 项目模版
dolphin-weex-sample 示例库

3.2搭建开发环境

#第一步:安装 Node.js

weex 项目打包和模块管理基于 Node.js，在开发项目前，首先安装 Node.js

安装 Node.js 方式多种多样，最简单的方式是在 Node.js (opens new window)官网下载可执行程序直接安装即可。

对于 Mac，可以使用 Homebrew (opens new window)进行安装：

brew install node

通常，安装了 Node.js 环境，npm 包管理工具也随之安装了。因此，直接使用 npm 来安装 weex-toolkit。

#第二步:安装 IDE

有几种 weex 开发常用 IDE，比如

一、vs code

1、从官网 (opens new window)下载，下载安装即可使用

#第三步:安装脚手架

安装 dolphin-weex-cli

    npm install -g dolphin-weex-cli
    或
    cnpm install -g dolphin-weex-cli (推荐方式)

#第四步：创建 weex 工程模版

dolphin create | dolphin c
? Project name: (weex-demo-project): 输入项目名称
? Project choice? (Use arrow keys)
> plugin    (选择此项 --> 插件模版)
? version     (版本信息)
? description (项目描述)
? author      (作者)
...loading
New project has been created successfully!
> cd weex-demo-project
        `Run Application`
            npm install (推荐 cnpm install)
            npm start（默认）  or npm run dev

项目目录如下：

├─weex-demo-project
│  ├─.temp ------------------------ webpack打包的临时文件
│  ├─.vscode ------------------------ vscode个性化设置、风格一致
│  ├─configs ------------------------ webpack 打包配置
│  ├─dist ------------------------ webpack打包生成的目录，包含js,image,ttf等
│  ├─assets ------------------------ 静态资源文件夹
│  ├─node_modules ------------------------ 工程依赖的npm package
│  ├─plugin ------------------------ 配置信息
│  ├─src —— 业务代码
│  │  ├─common --------------------- 通用功能文件
│  │  ├─mixin ------------------------ mixins 文件
│  │  ├─component ------------------ 通用组件
│  │  ├─widgets ----------------- 子项目文件夹（工程支持多个品类子项目并行开发）
│  │     ├─demo ---------------------- 插件项目示例，以“T0x<品类码>”命名,例如:T0x13 智能灯
│  │  │    ├─assets ------------------ 项目资源文件夹
│  │  │      │─image ------------------ 项目图片资源文件夹
│  │  │    ├─component -------------- 项目组件文件夹，放置项目自定义组件
│  │  │    ├─config -------------- 项目通用配置
│  │  │    ├─entry -------------- 打包入口配置（views内的页面文件需要和entry一一对应）
│  │  │      │─welcome.js ------------------ 欢迎页入口文件
│  │  │      │─weex.js ------------------ 插件入口文件
│  │  │    ├─util -------------- 辅助
│  │  │      ├─util.js -------------- 封装工具函数
│  │  │    │─views
│  │  │      ├─welcome ----- 欢迎页 （推荐定义方式）
│  │  │          ├─index.js ----- 模块入口
│  │  │          ├─index.vue ----- 模块vue代码
│  │  │      ├─weex.vue -----------插件首页vue文件，必须（app默认寻找weex.js文件作为插件入口）
│  ├─test ------------------------ 单元测试
│  ├─web ------------------------ web端资源文件
│  ├─.gitignore --------------------- git仓库忽略文件配置
│  ├─.babelrc --------------------- 支持ES6语法的配置文件，删除后无法使用ES6，同时支持对象扩展符
│  ├─package.json ------------------ npm的配置文件，里面包含依赖配置、Scripts配置等
│  ├─webpack.config.js ------------- webpack的脚本文件
│  ├─README.md ------------- 项目说明文件

#第五步：创建自己的插件项目

文件夹重命名

复制 demo 文件夹,重命名该文件夹名称。命名规范如下，例如开发一款智能灯插件，智能灯品类码为 0x13, 那么文件夹名称推荐改为 T0x13
关联入口文件

entry 文件夹为 webpack 打包编译的入口文件，views 目录下的文件或者文件夹必须和 entry 下的 js 文件保持一一对应关系，而且 js 内的路径必须和实际保持一致，才能正常启动新的插件项目。 entry 目录下的原 weex.js 的内容应该修改如下：将插件目录名称从 demo 改为 T0x13
```
import App from '@/widgets/T0x13/views/weex.vue'
import dolphinweex from '@/js/dolphinweex.js'
import exceptionReport from '@/js/exceptionReport.js' //错误捕捉、异常上报

Vue.use(dolphinweex)
Vue.use(exceptionReport)
```
entry 目录下的原 welcome.js 的内容应该修改如下：将插件目录名称从 demo 改为 T0x13
```
import App from '@/widgets/T0x13/views/welcome'
import dolphinweex from '@/js/dolphinweex.js'
import exceptionReport from '@/js/exceptionReport.js' //错误捕捉、异常上报

Vue.use(dolphinweex)
Vue.use(exceptionReport)
```
TIP

tips: views 目录下的页面文件要和 entry 下文件一一对应

创建新的页面，例如创建商城页面（shop）

在 entry 目录下新建shop.js。

import App from '@/widgets/T0x13/views/shop'
import dolphinweex from '@/js/dolphinweex.js'
import exceptionReport from '@/js/exceptionReport.js' //错误捕捉、异常上报

Vue.use(dolphinweex)
Vue.use(exceptionReport)

在 views 目录下新建 shop 文件夹，内部新建文件 index.js和index.vue index.js 内容如下：

export { default } from './index.vue'

index.vue 内容如下：

<template>
    <div class="wrapper">
        <text>{{title}}</text>
    </div>
</template>
<script>
export default {
name: 'helloWorld',
data () {
    return {
        title: 'hello, world'
    }
},
methods: {}
}
</script>
<style scoped></style>

工程内切换插件项目
如果要切换打包编译当前工程内的插件项目，打开根目录下的package.json文件，CATE_NAME后面跟随的是插件项目的名称。
如示例中插件名称的默认值是 demo，内容如下：

"scripts": {
    "start": "npm run clean:all && npm run serve",
    "serve": "cross-env CATE_NAME=demo webpack-dev-server --env.NODE_ENV=development --progress",
    "dev": "cross-env CATE_NAME=demo webpack --env.NODE_ENV=common --progress --watch",
    "build": "cross-env CATE_NAME=demo webpack --env.NODE_ENV=common",
    "build:prod": "npm run clean:all && cross-env CATE_NAME=demo webpack --env.NODE_ENV=production && node configs/publish.js",
    "build:prod:web": "cross-env CATE_NAME=demo webpack --env.NODE_ENV=release",
    "clean:all": "rimraf ./.temp && rimraf ./dist && rimraf ./release && rimraf ./publish && rimraf ./publish.zip",
    "lint": "eslint --ext .js,.vue src",
    "lint:fix": "eslint --ext .js,.vue src --fix . && echo 'Lint complete.'"
  },

将其中的CATE_NAME=后面的值改为新创建插件项目的名称，如将demo改为T0x13,效果如下：

"scripts": {
    "start": "npm run clean:all && npm run serve",
    "serve": "cross-env CATE_NAME=T0x13 webpack-dev-server --env.NODE_ENV=development --progress",
    "dev": "cross-env CATE_NAME=T0x13 webpack --env.NODE_ENV=common --progress --watch",
    "build": "cross-env CATE_NAME=T0x13 webpack --env.NODE_ENV=common",
    "build:prod": "npm run clean:all && cross-env CATE_NAME=T0x13 webpack --env.NODE_ENV=production && node configs/publish.js",
    "build:prod:web": "cross-env CATE_NAME=T0x13 webpack --env.NODE_ENV=release",
    "clean:all": "rimraf ./.temp && rimraf ./dist && rimraf ./release && rimraf ./publish && rimraf ./publish.zip",
    "lint": "eslint --ext .js,.vue src",
    "lint:fix": "eslint --ext .js,.vue src --fix . && echo 'Lint complete.'"
  },

然后，执行 npm start新创建的插件项目就可以成功运行了。

#第六步上传插件包

文件夹的名称格式：T + 品类码 + _ + sn8码。
插件包文件夹名称修改，例如：找到 weex 工程dist目录下的插件包文件（例如T0x13文件夹），文件夹T0x13重命名为T0x13_L0000001 ，然后将T0x13_L0000001文件夹以 zip 格式压缩。

1. 在美的 Iot 开发者平台自行上传插件，并完成插件信息的相关配置。（适用于插件自由开发者,平台目前正在完善中）
1. 重命名文件夹并压缩后，联系美的方项目管理人员上传插件到管理后台。（适合第三方与美的合作模式: 小范围的临时方案，如有更改，会及时通知）
1. 产品插件与快捷卡片插件包上传时，会校验目录结构是否符合以下规则：
  
  ①zip插件压缩包解压后有且仅有一个文件夹；
  
  ②zip插件压缩包解压后的文件夹内为代码文件。
  
  正确目录结构范例一：
  ----T0xB1_0BS5051W_2021032301.zip
  ----T0xB1_0BS5051W
  ----weex.js/index.html等代码文件
  
  正确目录结构范例二：
  ----T0xB1_2021032301.zip
  ----T0xB1
  ----weex.js/index.html等代码文件

#第七步美居 app 上加载插件

加载前须知：
- 在开发者平台申请配置品类码和sn8码。（详细操作步骤查看开发者平台官方网站文档）
IOT开发者平台(opens new window)
- 设备需成功接入到美居。
插件接入美居方式：
- 美居配网接入
- 使用美居app扫描二维码配网添加设备
- 云云对接第三方授权接入
- 使用 美居app->我的->第三方平台设备
  通过第三方平台登录账号和密码授权美居app控制第三方的设备。

WARNING

⚠️ 请使用有效的美居账号登录，确保处于登录成功状态，并且没有报错提示，如出现了错误提示，可重新登录重试。

3.3开发指引

本文档适用于有一定 Weex 使用经验的开发者。我们默认你已经掌握 Weex 技术体系，如果你是新手， 你可能需要先熟悉 weex 开发文档 (opens new window)。

#3.3.1 目录规范

插件开发遵循 weex 前端工程化配置（支持多项目并行开发，独立开发，互不干扰）。

前端工程现支持多个插件项目并行开发，如需切换到其他插件，需改动 package.json 文件中 script 指令中的 CATE_NAME 的值为当前插件的文件名，如下图：

├─dolphin-weex-template
│  ├─.temp ------------------------ webpack打包的临时文件
│  ├─.vscode ------------------------ vscode个性化设置、风格一致
│  ├─configs ------------------------ webpack 打包配置
│  ├─dist ------------------------ webpack打包生成的目录，包含js，image，ttf等
│  ├─assets ------------------------ weex官方内置
│  ├─node_modules ------------------------ 工程依赖的npm package
│  ├─plugin ------------------------ 配置信息
│  ├─src —— 业务代码
│  │  ├─common --------------------- 通用功能文件
│  │  │─service
│  │  │  ├─nativeService.js ----- weex和Native交互接口，包括网络请求，页面跳转，本地存储等
│  │  ├─mixin ------------------------ 混入文件
│  │  ├─component ------------------ 通用组件
│  │  ├─widgets ----------------- 子项目文件夹（工程支持多个品类子项目并行开发）
│  │     ├─T0x13 ---------------------- 插件项目文件夹，以“T0x<品类码>”命名，例如:T0x13 智能灯
│  │  │    ├─assets ------------------ 项目资源文件夹
│  │  │      │─image ------------------ 项目图片资源文件夹
│  │  │    ├─component -------------- 项目组件文件夹，放置项目自定义组件
│  │  │    ├─config -------------- 项目通用配置
│  │  │    ├─entry -------------- 打包入口配置（views内的页面文件需要和entry一一对应）
│  │  │      │─welcome.js ------------------ 欢迎页入口文件
│  │  │      │─weex.js ------------------ 插件入口文件
│  │  │    ├─util -------------- 辅助
│  │  │      ├─util.js -------------- 封装工具函数
│  │  │    │─views
│  │  │      ├─welcome ----- 欢迎页 （推荐定义方式）
│  │  │          ├─index.js ----- 模块入口
│  │  │          ├─index.vue ----- 模块vue代码
│  │  │      ├─weex.vue -----------插件首页vue文件，必须（app默认寻找weex.js文件作为插件入口）
│  ├─test ------------------------ 单元测试
│  ├─web ------------------------ 浏览器端资源文件
│  ├─.gitignore --------------------- git仓库忽略文件配置
│  ├─.babelrc --------------------- 支持ES6语法的配置文件，删除后无法使用ES6，同时支持对象扩展符
│  ├─package.json ------------------ npm的配置文件，里面包含依赖配置、Scripts配置等
│  ├─webpack.config.js ------------- webpack的脚本文件
│  ├─README.md ------------- 项目说明文件

注：

tips: views 目录下的页面文件要和 entry 下文件一一对应

#3.3.2 npm 指令

npm start ------ 清空打包文件夹，并启动本地服务项目
npm run serve ------ 启动本地服务项目（配置webpack-dev-server 支持热更新、热刷新）
npm run dev ------ 开启调试模式打包项目文件
npm run build ------ 打包项目文件
npm run build:prod ------ 以生产模式打包项目
npm run clean:all  ------ 清空项目临时文件
npm run lint ------ eslint 代码检查
npm run lint:fix ------ 自动修复不符合规范的项目代码

#3.3.3 代码规范

项目工程中已经配置了代码风格一致，保存时自动格式化代码。
本地代码配置了 vscode 的代码格式化插件的配置，强烈建议使用 vscode 开发工具。

#3.3.4 UI 组件库

目前处于开发和文档完善阶段，因在迭代中，考虑项目稳定性暂不开放。但是示例中的使用的组件可以自行按需复制使用。

#3.3.5 页面开发

Weex 框架要求使用 Vue.js (opens new window)进行页面开发。开发者通过撰写 *.vue 文件，基于 template，style，script 快速构建组件化的应用。

需要注意的是 weex 中 CSS 不支持百分比，屏幕宽度以 750px 为标准，即 100%屏幕宽度为 750px，此外 weex 的字体大小也*2 的大小效果，比如设置 28px 的字体大小，实际物理像素为 14px。

(1) 页面开发模式

weex 页面的开发模式主要分为两种：

第一种：单页面（SPA），通过 Vue-router (opens new window)+ Vuex (opens new window)来实现。此方式通过 Router 进行页面切换。有如下的缺点 1.页面切换没有原生的方式流畅；2.transition 使用之后会影响当前页面，引入其他 bug。
第二种：独立页面，每个页面都独立打出一个 js 文件，通过 navigator 对象进行页面切换，交互效果较好，这也是 weex 官方推荐的开发方式。

推荐的开发模式

整体架构趋同于 Native 的开发方式，即使用独立页面，在 src/App.vue 配置好项目入口。通过 weex 提供的 Navigator module 的 push 和 pop 来切换页面。

(2) 跳转页面实时监听

页面发生跳转后，目标页面代码发生变化后，需要实时刷新以提高开发效率。因项目打包过程中，所有页面需要一个入口，如若需要支持开发过程中被跳转页面自动更新，那么需要给跳转页面提供相应的入口，目录结构为 xx.js，xx.vue，具体可参见目录结构（src/views）

如 test.js

import entry from "./test.vue";

entry.el = "#root";
export default new Vue(entry);

test.vue

<template>
<div>
   <text>test</text>
</div>
</template>
<script>
   module.exports = {
    data () {}，
    methods: {}，
    created () {}
  };
</script>

(3) 组件调用

可以通过组件路径引入组件，如下

<template>
<div>
<midea-cell title="带右边文字"
    rightText="设置"
    :hasTopBorder="true"
    :hasMargin="true"
    @mideaCellClick="itemClicked"
>
</midea-cell>
</div>
</template>
<script>
   import mideaCell from '../component/cell.vue'
   module.exports = {
    components: {mideaCell}，
    data () {}，
    methods: {}，
    created () {}
  };
</script>

(4) 页面跳转

框架封装了 weex 自带的 navigator 模块的 push，pop 实现页面的跳转，主要实现于 src/common/services/nativerSerive.js 的 goTo，goBack 方法

首先引入 nativeService 模块

import nativeService from "../common/services/nativeService";

其次调用 goTo 方法跳转到上一页面，goBack 方法返回到上一页面

方法示例

nativeService.goTo("sample/tab.js");
nativeService.goBack();

(5) 参数传递

本框架 weex 页面传递推荐使用 storage 方式，如 A 页面跳转到 B 页面，可在 A 页面设置 storage，B 页面通过接收 storage 的方式接收数据

A 页面设置数据

nativeService.setItem("name"， obj)// obj可以是字符串也可以是JSON对象，如果{"name":"Tom"}

B 页面接收数据

nativeService.getItem(name， function（obj）{
})//注obj为字符串
}

在实际的使用场景中，由 A 页面跳转到 B 页面，B 页面更改了某些信息，如设备名称，需要同步给 A 页面，有两种方式，一种是通过 goTo 的方式跳转到 A 页面，A 页面重新刷新数据，但这样的体验效果较差，因可能 A 页面有过多的网络请求，又或者是用户滚动到 A 页面某一位置，想跳转回 A 页面时保持原来的滚动位置，所以重新跳转刷新并非理想的方式，另一种方式可以充分利用 BroadcastChannel 方法，即 A 页面启动一个监听，B 页面数据变更时通知 A 页面实时刷新，然后 B 页面通过 goBack 方法回退到 A 页面，相关数据已刷新

A 页面设置监听

var deviceNameChannel = new BroadcastChannel("deviceNamUpdate");
var self = this;
deviceNameChannel.onmessage = function(event) {
  self.deviceDetail.devName = event.data;
};

B 页面发布更新

var deviceNameChannel = new BroadcastChannel("deviceNamUpdate");
deviceNameChannel.postMessage(name);

3.4插件常用接口

#3.4.1 接口分类

设备信息：基础信息
设备状态查询和控制：状态查询与控制
- 美居配网接入：通过 LUA 实现设备状态查询与控制
- 云云对接：云云设备状态查询与控制
设备绑定和解绑：绑定与解绑
状态上报/消息推送
- 插件内监听设备状态上报
- 插件内监听 App 主动推送消息
路由
- 插件页面路由
- 原生页面路由
其他
- 手机长震动
- 手机微震动
蓝牙方案相关
- MSmartBLE蓝牙
- Bluetooth蓝牙

#3.4.2 设备信息：查询设备的基础信息

(1) getDeviceInfo ^6.8

接口描述
- 获取设备信息
请求参数
- N/A
接口调用示例

this.$bridge
  .getDeviceInfo()
  .then(res => {
    this.$toast(res)
  })
  .catch(err => {
    this.$toast(err)
  })

返回参数

Prop	Type	Default	Description
`deviceId`	`String`	`N/A`	设备 ID
`deviceName`	`String`	`N/A`	设备名称
`deviceType`	`String`	`N/A`	设备类型
`deviceSubType`	`String`	`N/A`	设备子类型
`deviceSn`	`String`	`N/A`	设备 SN（加密格式）
`deviceSn8`	`String`	`N/A`	设备 SN8（非加密格式）
`deviceBtToken`	`String`	`N/A`	蓝牙设备的校验 Token
`isOnline`	`Number`	`N/A`	设备是否在线：`0` 离线 /`1` 在线
`mac`	`String`	`N/A`	设备的 mac 地址（`mesh`/`ble`等设备才会有该字段）
`ssid`	`String`	`N/A`	用于蓝牙名称
`roomId` ^5.4.1	`String`	`N/A`	所属房间 ID
`name` ^5.4.1	`String`	`N/A`	所属房间名称
`masterId` ^5.4.1	`String`	`N/A`	设备所属网关 ID

返回示例
- N/A

TIP

该接口在扫码预览模式下因为app安全限制，不能获取到正确数据返回，需将插件包拷贝到App内部插件包保存的路径下,才能获取到正确数据，相关路径参照开发调试文档中关于app插件包位置路径的说明

#3.4.3 设备状态查询和控制

sendLuaRequest ^5.1.2

接口描述
- weex 插件通过 LUA 查询或控制设备状态
请求参数

Props	Type	Required	Default	Description
`参数`	`Object`	`Y`	`{}` 属性： `params:` `operation:`{ Type: String, Default: luaControl, Description: 可选值为`luaQuery`或者`luaControl` } `applianceId:`{ Type: String, Default: N/A, Description: 设备 Id 为`deviceId` } `name:`{ Type: String, Default: N/A, Description: `mock Data`文件名，于`dummy`文件夹下，通过`name`匹配相应模拟数据文件 } `mode:`{// ^5.12 Type: Number, Default: `0`, Description: `0`优先局域网发送，不在局域网则广域网透传(默认);`1`只发送广域网透传，若广域网透传失败，则直接返回错误信息; }	控制状态参数

接口调用示例

let params = {
  operation: 'luaControl', //luaControl：设备控制 luaQuery: 设备查询
  name: 'powerOn',
  // mode：模式，值为0或1
  // 0是默认值，表示优先局域网发送，不在局域网则广域网透传。
  // 1:只发送广域网透传，若广域网透传失败，则直接返回错误信息
  mode: 0, //默认值 0，可省略
  //params参数根据接口的定义传参数
  params: {
    power: 'on'
  }
}

this.$bridge
  .sendLuaRequest(params)
  .then(res => {
    this.$alert(res)
  })
  .catch(err => {
    this.$toast(err)
  })

返回参数

Prop	Type	Required	Default	Description
`result`	`Object`	`N`	`{}` 属性： `error_code:` `version:`	结果
`data`	`Object`	`N`	`N/A`	设备状态十六进制编码
`errorCode`	`Number`	`Y`	`N/A`	错误码： `0` 正常回调 /`-1` 请求超时

tip

如使用 lua 调试工具时，参数的格式应按照 lua 的参数格式说明来传（详情请查看 lua 部分相关的文档）。

sendCloudRequest ^7.6.0

接口描述
- weex 插件通过云云对接 查询或控制设备状态
请求参数

Props	Type	Required	Default	Description
`url`	`String`	`Y`	`N`	`云云对接的服务地址`
`params`	`Object`	`Y`	`N`	`查询和控制的参数`
`option`	`Object`	`N`	`{method:'POST',headers{'Content-Type':'application/json;charset=utf-8'}`	`可选参数：请求配置`

接口调用示例

// 查询设备状态
let url = '/v1/iot/open/skill/delegate' // 插件与云端请求查询和控制接口
let params = {
  plugin_version: '5.12.0.2_20191111', //插件的版本，根据实际情况自定义，app版本和日期组合
  namespace: 'ApplianceState', //查询：ApplianceState，控制： ApplianceControl
  payload: {
    applianceCode: 'xxx', //xxx为设备的deviceId,通过getDeviceInfo接口获取
  }
}
// 控制设备
let url = '/v1/iot/open/skill/delegate' // 插件与云端请求查询和控制接口
let params = {
  plugin_version: '5.12.0.2_20191111', //插件的版本，根据实际情况自定义，app版本和日期组合
  namespace: 'ApplianceControl', //查询：ApplianceState，控制： ApplianceControl
  payload: {
    applianceCode: 'xxx', //xxx为设备的deviceId,通过getDeviceInfo接口获取
    control: {
      power: 'on' // 根据设备profile定义确定，此处设备开关机字段为 power: on | off
    }
  }
}


this.$bridge
  .sendCloudRequest(
    url,
    params,
    options
  )
  .then(res => {
    this.$alert(res)
  })
  .catch(err => {
    this.$toast(err)
  })

返回参数

Prop	Type	Required	Default	Description
`result`	`Object`	`N`	`{}` 属性： `error_code:` `version:`	结果
`data`	`Object`	`N`	`N/A`	设备状态十六进制编码
`errorCode`	`Number`	`Y`	`N/A`	错误码： `0` 正常回调 /`-1` 请求超时

tip

适用于第三方配网接口设备，美居通过云云对接与设备交互的应用场景

#3.4.4 设备解绑解除设备的绑定

unbindDevice ^6.0.0

接口描述
- 解绑设备
- 若是解绑成功，则发出解绑成功的页面刷新事件
请求参数

Prop	Type	Required	Default	Description
`param`	`Object`	`Y`	`{}` 属性： `applianceCode:` `isOtherEquipment:`{ Type: Number, Default: `0`, Description: `0`否 / `1`是(是否为第三方设备) }	请求参数

接口调用示例

let params = {
  applianceCode: 'xxx', //xxx代表传入deviceId,即当前希望解绑的设备Id
  isOtherEquipment: 0 //默认值：0，可选值：0 | 1
}
this.$bridge
  .unbindDevice(params)
  .then(res => {
    this.$alert(res)
  })
  .catch(err => {
    this.$toast(err)
  })

返回参数

成功时返回

Prop	Type	Default	Description
`errorCode`	`Number`	`N/A`	状态码(状态码枚举如下) 0 删除设备成功 1000 未知系统错误 1002 参数为空 1105 账户不存在 1300 设备不存在 1304 设备不属于此用户 1305 用户不是设备的管理员
`data`	`Object`	`{}`	返回结果

失败时返回

Prop	Type	Default	Description
`errorCode`	`Number`	`N/A`	`1`
`errorMessage`	`String`	`N/A`	网络层返回的错误信息

#3.4.5 状态上报和消息推送：监听设备状态上报和 app 消息推送

receiveMessage

接口描述
- 监听设备状态上报
- 此监听 Key 用于接收设备上报信息
- 当插件收到本设备的上报消息时，触发此监听
- 方法返回结果为设备上报的信息
请求参数

N/A
接口调用示例

const globalEvent = weex.requireModule('globalEvent')

export default {
...
created() {
    // 业务逻辑
    globalEvent.addEventListener('receiveMessage', (data) => {
        ...
        if (data.errorCode == 0){
            ...
        }
    })
}
...
}

返回参数

Prop	Type	Default	Description
`errorCode`	`Number`	`N/A`	错误码： `0` 正常回调 /`-1` 请求超时
`deviceId`	`String`	`xxx`	设备 ID（套系的数据上报时有该字段返回）
`result`	`Object`	`{}`	Lua 解析出来的 json 数据
`data`	`Object`	`N/A`	04 上行指令字符串

返回示例
N/A

tip

deviceId字段在套系的数据上报时才有的返回字段，普通的数据上报没有该字段

receiveMessageFromApp

接口描述
- 监听 App 消息推送
- 此监听 Key 用于接收 APP（包括第三方 SDK）主动推送至 Weex 插件的消息数据
- 当 APP 主动调用时，触发此监听
请求参数
- N/A
接口调用示例

    const globalEvent = weex.requireModule('globalEvent')

    export default {
    .....
    created() {
        globalEvent.addEventListener('receiveMessageFromApp', (data) => {
            // 业务逻辑
            .....
            if (data.messageType == 'xxxx'){
                console.log(data.messageBody)
            }
        })
    }
    .....
    }

返回参数

Prop	Type	Default	Description
`messageType`	`String`	`N/A`	H5 用来判断消息类型，然后做相对应的处理
`messageBody`	`Object`	`N/A`	APP 传递的 JSON 对象

注 1：messageType / messageBody参数列表

messageType	messageBody	Description
`applicationWillResignActive`	`N/A`	ios APP 进入后台（只有调用了`this.$native.setBackHandle("on")`才会触发此通知）
`hardwareBackClick`	`{}` 属性： `onlineStatus:`	安卓物理返回键进入后台（只有调用了`this.$native.setBackHandle("on")`才会触发此通知）
`queryStatusFromApp`	`{}`	`App`端主动通知`weex`端重新查询状态（在从控制页反回卡片页时，有些设备状态没同步过来，需要重新查询一次）
`deviceOnlineStatus`	`{}` 属性： `onlineStatus:`	设备上报在线离线状态
`networkStatusChanged`	`{}` 属性： `status:` `type:`	网络状态变化监控
`aiSpeechNotification`	`{}` 属性： `key:` `raw:`, Description: 思必驰原始返回结果对象，其中 raw.conf 为可信任度，范围 0~1 的浮点数，数值越高越可信 }	思必驰语音识别反馈
`aiSpeechAcyionResult`	`{}`	思必驰语音执行结果反馈
`aiSpeechAcyionResult`	`{}` 属性： `key:` `raw:`, Description: 思必驰原始返回结果对象，其中 raw.conf 为可信任度，范围 0~1 的浮点数，数值越高越可信 }	思必驰语音识别过程反馈
`sleepPush`	`{}` 属性： `sceneId:` `homegroupId:`	早睡习惯推送通知
`sleepPushCancel`	`{}`	早睡习惯推送忽略按钮点击通知

返回示例
N/A

tip

deviceId字段在套系的数据上报时才有的返回字段，普通的数据上报没有该字段

#3.4.6 路由跳转与回退

push

接口描述
- 插件内子页面跳转
请求参数：
接口调用示例

Prop	Type	Required	Default	Description
`url`	`String`	`Y`	`N/A`	跳转页面路径（以插件文件夹为根目录的相对路径）
`options`	`Object`	`N`	`animated:` `replace:` `viewTag:`{ Type: String, Default: N/A, Description: 给跳转目标页面设置标识，可用于`路由回退`时指定返回页面 } `bgColor:`	跳转时选项设置
`params`	`Oject`	`N`	{}	url `?`后拼接参数
`callback`	`function`	`N`	()=> {}	跳转后的回调函数

接口调用示例


方式二： let url = 'detail.js', options = { animated: true, replace: false, viewTag: 'detailPage' }, urlParams = { cateId: 'xxxxx', cateIndex: 'xxxxx' }, callback = ()=> { //跳转后的回调函数 }

this.$bridge.push(url,options,urlParams,callback)

~~~text
### pop

- 接口描述

  - <span class="font_style">插件内无刷新页面回退</span>

- 请求参数

| Prop           | Type       | Required | Default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Description                                      |
| :------------- | :--------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------- |
| **`options`**  | `Object`   | `N`      | `viewTag:`<br><span class="font_s">Type: String,</span><br><span class="font_s">Default: N/A,</span><br><span class="font_s">Description: 返回指定页面, 指定页面需要设定有 viewTag</span><br><br>`animated:`<br><span class="font_s">Type: Boolean,</span><br><span class="font_s">Default: true,</span><br><span class="font_s">Description: 是否需要跳转动画</span><br><br>`animatedType:`<br><span class="font_s">Type: String,</span><br><span class="font_s">Default: slide_rightToLeft,</span><br><span class="font_s">Description: `slide_leftToRight`由左到右 / `slide_topToBottom`由上到下 / `slide_rightToLeft`由右到左 / `slide_bottomToTop`由下到上</span><br> | <span class="font_style">跳转参数选项</span>     |
| **`callback`** | `Function` | `N`      | `-`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | <span class="font_style">回退后的回调函数</span> |

- 接口调用示例

```js
//返回插件首页【`weex.js`】

let params = {
  viewTag: 'rootView'
}
this.$bridge.pop(params)
~~~

tip

插件首页`weex.js`默认的`viewTag`是：`"rootView"`，返回插件首页可以使用

**umpNativePage**

打开指定的原生页面

- **参数描述：**

| Type     | Required | Default   | Description |
| :------- | :------- | :-------- | :---------- |
| `Object` | `Y`      | `{}附表1` | 请求参数    |

附表 1：`param`参数

| Prop           | Type     | Required | Default   | Description      |
| :------------- | :------- | :------- | :-------- | :--------------- |
| **`pageName`** | `String` | `Y`      | `见附表2` | 跳转的目标页面   |
| **`url`**      | `String` | `Y`      | `N/A`     | 电商落地页的 url |
| **`data`**     | `String` | `Y`      | `{}附表3` | json 格式字符串  |

附表 2：`pageName`类别

| Value                             | Description                                               |
| :-------------------------------- | :-------------------------------------------------------- |
| **`login`**                       | 登录页面                                                  |
| **`CookbookHome`**                | 菜谱首页                                                  |
| **`CookbookDetail`**              | 菜谱详情                                                  |
| **`jumpToGatewayBindPage`**       | 网关绑定                                                  |
| **`addDevice`**                   | 添加设备                                                  |
| **`onlineService`**               | 在线客服                                                  |
| **`voiceControl`**                | 语音控制                                                  |
| **`deviceDetail`**                | 设备详情页(房间更改、修改名字等)                          |
| **`electronicBusinessPage`**      | 跳转到电商页面                                            |
| **`notificationSettings`** ^5.7.0 | 设置-》设备消息提醒-》对应参数 applianceId 设备的提醒设置 |
| **`gotoPlugin`** ^6.5             | 跳转回首页，从首页跳转插件，显示下载进度                  |

附表 3：`data`参数

| Prop                     | Type      | Required | Default | Description                                                  |
| :----------------------- | :-------- | :------- | :------ | :----------------------------------------------------------- |
| **`recipeId`**           | `String`  | `Y`      | `N/A`   | 食谱 id（跳转`CookbookDetail`时使用）                        |
| **`xxxx`**               | `String`  | `Y`      | `N/A`   | 语音控制`voiceControl`使用自定义欢迎词                       |
| **`useCustomWelcome`**   | `Boolean` | `Y`      | `N/A`   | `voiceControl`是否使用默认：`false` 使用默认/`true` 使用自定义 |
| **`applianceId`** ^5.7.0 | `String`  | `Y`      | `N/A`   | 应用 ID（`pageName`为`notificationSettings`时指定设备设置）  |
| **`deviceId`**           | `String`  | `Y`      | `N/A`   | 设备 ID `pageName`为`deviceDetail`时指定设置                 |

**接口调用示例**

```js
let params = {
  pageName: 'login',
  data: {}
}
this.$bridge
  .jumpNativePage(params)
  .then(res => {
    this.$toast(res)
  })
  .catch(err => {
    this.$toast(err)
  })

#3.4.7 其他关联接口

vibrateLong

接口描述：
- 手机长震动
接口调用示例

this.$bridge.vibrateLong()

vibrateShort

接口描述：
- 手机微震动
接口调用示例

this.$bridge.vibrateShort()

#3.4.8 蓝牙方案相关

MSmartBLE蓝牙： MSmartBLE蓝牙接口相关文档(opens new window)
Bluetooth蓝牙：Bluetooth蓝牙接口相关文档

3.5常见问题

如果这篇文档没找到您想要的内容，请到 dolphin-weex-template/issues (opens new window)进行查找。

#3.5.1 vue-router支持吗

weex页面的开发模式主要分为两种：

第一种：单页面（SPA），通过 Vue-router (opens new window)+ Vuex (opens new window)来实现。此方式通过Router进行页面切换。有如下的缺点 1.页面切换没有原生的方式流畅；2.transition使用之后会影响当前页面，引入其他bug。
第二种：独立页面，每个页面都独立打出一个 js 文件，通过 navigator对象进行页面切换，交互效果较好，这也是weex官方推荐的开发方式。

推荐的开发模式：整体架构趋同于Native的开发方式，即使用独立页面，在 src/App.vue 配置好项目入口。通过 weex 提供的 Navigator module的 push 和 pop 来切换页面。

#3.5.1 样式设置百分比没效果

weex中CSS不支持百分比，屏幕宽度以750px为标准，即100%屏幕宽度为750px，此外weex的字体大小也*2的大小效果，比如设置28px的字体大小，实际物理像素为14px。

#3.5.2 dom操作没效果

Weex 和 Web 的平台差异：

weex没有dom，不支持dom操作，没有Element 、Event 、File 等对象 -不能使用jq，document.querySelector
weex没有bom，不支持window 、screen对象
在weex中能够调用移动设备原生 API，使用方法是通过注册、调用模块来实现。其中有一些模块是weex内置的，如 clipboard 、 navigator 、storage 等。

#3.5.3 在美居上找不到扫一扫功能

请确认是否是最新版本的美居app或沙箱美居app，如果不是，需重新下载。

通过下面方式开启扫一扫测试

安卓：美居 APP-》我的-》设置-》关于美居-》长按美居 logo，下面出现一个"扫一扫"

iOS：美居 APP-》我的-》设置-》关于美居-》连续多次点击美居 logo 旁边的空白地方-》弹出列表选择中选择"扫一扫 weex"

如有其他调试问题请参考开发调试

#3.5.4 什么是插件强制更新

插件非强制更新时，用户可选更新或忽略，忽略之后下一次进入APP会继续提醒，美居页面的展示如下：

插件强制更新时，用户必须下载新插件才能正常使用，美居页面的展示如下：

posted on 2024-12-06 10:18 AtlasLapetos 阅读(19) 评论(0) 编辑收藏举报

插件开发规范

3. 插件开发规范

3.1背景介绍

3.2搭建开发环境

#第一步:安装 Node.js

#第二步:安装 IDE

#第三步:安装脚手架

#第四步：创建 weex 工程模版

#第五步：创建自己的插件项目

#第六步上传插件包

#第七步美居 app 上加载插件

3.3开发指引

#3.3.1 目录规范

#3.3.2 npm 指令

#3.3.3 代码规范

#3.3.4 UI 组件库

#3.3.5 页面开发

3.4插件常用接口

#3.4.1 接口分类

#3.4.2 设备信息：查询设备的基础信息

#3.4.3 设备状态查询和控制

#3.4.4 设备解绑解除设备的绑定

#3.4.5 状态上报和消息推送：监听设备状态上报和 app 消息推送

#3.4.6 路由跳转与回退

#3.4.7 其他关联接口

#3.4.8 蓝牙方案相关

3.5常见问题

#3.5.1 vue-router支持吗

#3.5.1 样式设置百分比没效果

#3.5.2 dom操作没效果

#3.5.3 在美居上找不到扫一扫功能

#3.5.4 什么是插件强制更新

搜索

常用链接

随笔分类

随笔档案

文章分类

阅读排行榜

插件开发规范

3. 插件开发规范

3.1背景介绍

3.2搭建开发环境

#第一步:安装 Node.js

#第二步:安装 IDE

#第三步:安装脚手架

#第四步： 创建 weex 工程模版

#第五步： 创建自己的插件项目

#第六步 上传插件包

#第七步 美居 app 上加载插件

3.3开发指引

#3.3.1 目录规范

#3.3.2 npm 指令

#3.3.3 代码规范

#3.3.4 UI 组件库

#3.3.5 页面开发

3.4插件常用接口

#3.4.1 接口分类

#3.4.2 设备信息 ：查询设备的基础信息

#3.4.3 设备状态查询和控制

#3.4.4 设备解绑 解除设备的绑定

#3.4.5 状态上报和消息推送：监听设备状态上报和 app 消息推送

#3.4.6 路由 跳转与回退

#3.4.7 其他 关联接口

#3.4.8 蓝牙方案相关

3.5常见问题

#3.5.1 vue-router支持吗

#3.5.1 样式设置百分比没效果

#3.5.2 dom操作没效果

#3.5.3 在美居上找不到扫一扫功能

#3.5.4 什么是插件强制更新

搜索

常用链接

随笔分类

随笔档案

文章分类

阅读排行榜

#第四步：创建 weex 工程模版

#第五步：创建自己的插件项目

#第六步上传插件包

#第七步美居 app 上加载插件

#3.4.2 设备信息：查询设备的基础信息

#3.4.4 设备解绑解除设备的绑定

#3.4.6 路由跳转与回退

#3.4.7 其他关联接口