查阅快应用开发文档,可以知道官方提供了诸多接口;对于如何使用,文档中也给出了简单的说明和代码示例;但照着示例写法,在实际项目中,不够优雅且更不高效;所以,在开发中需要加以变通去写,使得大幅提升开发效率,同时也令整个代码优雅,以便于维护。所以在此篇文章的存在,旨在于讨论:如何优雅使用「快应用」API。

熟悉快应用开发的朋友,应该知道,使用其接口,需要三个步骤:接口声明(大部分),导入模块,接口调用。坦白讲,对于使用前端技术栈的开发者朋友,这是不够友好的设定;无由来给开发者带来了额外的工作量,却没有换来任何实质性价值。下面就从优化这三个步骤,来完成本文的分享主旨:优雅使用「快应用」API。

备注:本文首发于 如何优雅使用「快应用」API - vivo 快应用官方博客

接口声明

快应用开发文档,如分享接口中,在阐述如何使用该接口时,仍旧提及需要在 manifest.json 文件中做接口声明,如下示例:

1
2
3
4
5
6
7
8
9
10
{
"features": [
{
"name": "system.share"
},
{
"name": "system.shortcut"
}
]
}

事实上:作为开发者的您,已经无须如此;因为,快应用打包工具,在打包之时,已经帮着做了优化,帮着注入了接口声明;知晓这一点后,您大可以将 manifest.json 文件中的 features 字段给删除掉。

导入模块

就拿弹窗接口来说,在开发文档中,它介绍如何使用时,提到了须要导入模块,像如下示例这般:

1
2
3
import share from '@system.prompt'
//或
const share = require('@system.prompt')

就如在前文所叙述那般,快应用接口设计不够友好,这便是例证;这样做是麻烦且没有必要;不仅让开发者朋友多敲了代码(增加了工作量),而且也会使得构建出的包增加了体积;它完全可以学习 Web 或 小程序,将这些挂载于全局对象如 qa (quickapp 的缩写),开发者只需用 qa.[API-NAME] 即可调用,岂不美哉?

既然快应用并未对此处理好,我们在开发之时,完全多做一点工作,从而使得节省开发工作量、便捷后续维护、缩小包体积等等。思想很简单,快应用引擎没有挂载,我们按需挂载即可;具体的代码示例如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
// global.js
import app from '@system.app'
import prompt from '@system.prompt'
import webview from '@system.webview'
import router from '@system.router'
const hook2global = global.__proto__ || global
hook2global.qa = {
app,
prompt,
webview,
router
}

如上代码示例,可以将代码封装于单独文件如 global.js,在 app.ux 中导入即可。之后就可以在项目代码中无忧使用了:qa.appqa.router。相比较先前每逢使用,必先导入,要方便很多。除了这些需要用到的系统接口,您自己封装的方法、配置的常量,倘若使用频率很高,也可以像这样一并挂载,为您的快捷开发,打造康庄坦途。

接口调用

快应用接口分为两种:同步(立即返回调用结果)、异步(不会立即返回调用结果)。异步接口,需要在任务完成后执行某些操作,就得使用「回调函数」,如下示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// 同步接口
console.log(JSON.stringify(app.getInfo()))
// 异步接口
prompt.showContextMenu({
itemList: ['item1', 'item2'],
itemColor: '#ff33ff',
success: function(data) {
console.log('handling success')
},
fail: function(data, code) {
console.log(`handling fail, code = ${code}`)
},
cancel: function() {
console.log('handling cancel')
},
complete: function() {
console.log('handling complete')
}
})

这样毕竟麻烦,也不符合当今时代写 JavaScript 的风格;是否能提供有一个类似小程序 API Promise 化(miniprogram-api-promise)的工具,使得所有接口支持 promise?答案是:没必要。快应用自 1010 之后,就支持调用异步接口返回 Promise 实例,开发者可以在返回的 Promise 实例上使用 then, catch 方法绑定回调函数;具体说明可以参见接口概述

需要注意⚠️的是:只有在调用异步接口的实参中,不传递任何回调函数时,才会返回一个 Promise 实例。

有了这个特性的支持,加上如上提及两点,优雅使用「快应用」API 了🎉;其实,部分内容「快应用」本身,或者生态已经给出了优化方案,只不过没有在明显的文档、教程中给予说明,导致很多开发者朋友不知道这一点;本篇文章的价值就在于,将这些信息分享出来,希望可以帮助更多开发者朋友,高效工作,快乐生活。下面,就写一个完整的示例,来结束本篇分享:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
qa.prompt.showContextMenu({
itemList: ['快应用', '快应用+'],
itemColor: '#ff33ff'
}).then(
res => {
console.log(`异步接口返回的数据:${res.data}`)
},
res => {
console.log(`异步接口返回的数据:${res.data}`)
console.log(`异步接口返回的状态码:${res.code}`)
if (res.code === 100) {
// 对应异步接口支持的回调函数中的 cancel
} else if (res.code >= 200) {
// 对应异步接口支持的回调函数中的 fail
}
}
)

当然,您也可以使用 Promise 更常用的方式,如 qa.prompt .showDialog 写法。为了更好的诠释这些用法,有讲这些经验融入于 quickapp-typescript-template(基于 TypeScript 编写「快应用」模版),以供参考。

于 2020 年 08 月,深圳.福田。

原文首发于 vivo 快应用官方博客 — 如何优雅使用「快应用」API

您可能会感兴趣的文章

打赏

静晴轩 ~ 晚晴幽草轩
个人微信公众号晚晴幽草轩;名字取自:“天意怜幽草,人间重晚晴”。
专注互联网开发(Web 大前端、快应用、小程序),以及分享优质网站、AI 应用、效率工具、心得感悟等内容。

文章目录
  1. 1. 接口声明
  2. 2. 导入模块
  3. 3. 接口调用
    1. 3.1. 您可能会感兴趣的文章