从 1.0 版本升级
介绍
本文档是小程序 API 从 Zepp OS 1.0 至 Zepp OS 2.0 的升级指南。
提示
在阅读本文档前,建议先完成 2.0 API 介绍 的阅读。尤其是 API_LEVEL
兼容性部分!
信息
为了方便开发者进行快速迁移,Zepp OS 团队提供了提高迁移效率的命令行工具 @zeppos/zmt
。
升级 2.0 API 的优势
- 可以用到 Zepp OS 最新的开放能力
- Zepp OS 团队通过
API_LEVEL
对 API 兼容性进行保证,在后续版本升级中保证API_LEVEL
的向下兼容性 - 开发者无需关心固件版本号、Zepp OS 版本号,只需要对
API_LEVEL
做出兼容性适配,极大地简化了兼容性适配工作量
开始迁移
影响范围
首先明确升级 Zepp OS 2.0 JS API 所影响的的范围。
此次升级的小程序 API 仅适用于设备应用,即设置应用和伴生服务的开发模式与 1.0 版本相同,无需修改。
设备应用的开发语言是遵循 ES6 标准的 JavaScript,只有需要改动使用 Zepp OS 系统能力相关的代码。
举个例子,在 1.0 中,Zepp OS 系统能力通过全局变量如 hmUI
、hmApp
等对外暴露,凡是使用了系统能力的地方,均需要进行改动。
迁移思路
2.0 JS API 的能力是 1.0 JS API 的超集,所有的 1.0 JS API 的能力都可以在 2.0 JS API 中找到对应的方式,针对不同类型的 1.0 JS API,有不同的升级方式,下文将分为几类,分别用不同的方式进行处理。
情况 1:引用方式替换(仅适用于 hmUI
和 hmBle
模块)
hmUI
和 hmBle
模块,目前只是对引用方式进行了变换,在文件头部替换引用方式即可。
举个例子:
v1.0page.js
Page({
build() {
const text = hmUI.createWidget(hmUI.widget.TEXT, {
x: 96,
y: 120,
w: 288,
h: 46,
color: 0xffffff,
text_size: 36,
align_h: hmUI.align.CENTER_H,
align_v: hmUI.align.CENTER_V,
text_style: hmUI.text_style.NONE,
text: 'HELLO ZEPPOS'
})
}
})
在头部加入一句 ESM 形式的引用即可。
v2.0page.js
import * as hmUI from '@zos/ui'
Page({
build() {
const text = hmUI.createWidget(hmUI.widget.TEXT, {
x: 96,
y: 120,
w: 288,
h: 46,
color: 0xffffff,
text_size: 36,
align_h: hmUI.align.CENTER_H,
align_v: hmUI.align.CENTER_V,
text_style: hmUI.text_style.NONE,
text: 'HELLO ZEPPOS'
})
}
})
情况 2:方法名称替换
一部分方法功能保持不变,仅仅是方法名称的修改,添加相关方法引用语句之后,修改调用方法名和参数即可。
1.0 API | 2.0 API | 2.0 API 所在模块 |
---|---|---|
hmApp.gotoHome | home | @zos/router |
hmApp.goBack | back | @zos/router |
hmApp.exit | exit | @zos/router |
hmApp.alarmCancel | clearLaunchAppTimeout | @zos/router |
hmFS.open_asset | openAssetsSync | @zos/fs |
hmFS.open | openSync | @zos/fs |
hmFS.close | closeSync | @zos/fs |
hmFS.remove | rmSync | @zos/fs |
hmFS.rename | renameSync | @zos/fs |
hmFS.mkdir | mkdirSync | @zos/fs |
hmApp.setScreenKeep | setWakeUpRelaunch | @zos/display |
hmSetting.setScreenAutoBright | setAutoBrightness | @zos/display |
hmSetting.getScreenAutoBright | getAutoBrightness | @zos/display |
hmSetting.setBrightness | setBrightness | @zos/display |
hmSetting.getBrightness | getBrightness | @zos/display |
hmSetting.setScreenOff | setScreenOff | @zos/display |
hmSetting.setBrightScreenCancel | resetPageBrightTime | @zos/display |
hmSetting.getUserData | getProfile | @zos/user |
hmSetting.getDiskInfo | getDiskInfo | @zos/device |
hmSetting.getDeviceInfo | getDeviceInfo | @zos/device |
hmSetting.getLanguage | getLanguage | @zos/settings |
hmSetting.getDateFormat | getDateFormat | @zos/settings |
hmSetting.getMileageUnit | getDistanceUnit | @zos/settings |
hmSetting.getWeightUnit | getWeightUnit | @zos/settings |
hmSetting.getWeightTarget | getWeightTarget | @zos/settings |
hmSetting.getSleepTarget | getSleepTarget | @zos/settings |
hmApp.registerGestureEvent | onGesture | @zos/interaction |
hmApp.unregisterGestureEvent | offGesture | @zos/interaction |
hmApp.registerKeyEvent | onKey | @zos/interaction |
hmApp.unregisterKeyEvent | offKey | @zos/interaction |
hmApp.registerSpinEvent | onDigitalCrown | @zos/interaction |
hmApp.unregisterSpinEvent | offDigitalCrown | @zos/interaction |
hmApp.getPackageInfo | getPackageInfo | @zos/app |
hmSetting.getScreenType | getScene | @zos/app |
hmApp.setLayerY | scrollTo | @zos/page |
hmApp.getLayerY | getScrollTop | @zos/page |
hmUI.getScrollCurrentPage | getSwiperIndex | @zos/page |
举个例子:
v1.0page.js
hmApp.setLayerY(100)
const result = hmSetting.getUserData()
hmApp.gotoHome()
对照上文表格,以及 2.0 API 文档,很快就可以完成替换。
v2.0page.js
import { scrollTo } from '@zos/page'
import { home } from '@zos/router'
import { getProfile } from '@zos/user'
scrollTo({
y: 100
})
const result = getProfile()
home()