如何优雅使用「快应用」API

快应用 Aug 17, 2020

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

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

接口声明

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

{
    "features": [
        {
          "name": "system.share"
        },
        {
          "name": "system.shortcut"
        }
      ]
}

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

导入模块

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

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

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

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

// 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。相比较先前每逢使用,必先导入,要方便很多。除了这些需要用到的系统接口,您自己封装的方法、配置的常量,倘若使用频率很高,也可以像这样一并挂载,为您的快捷开发,打造康庄坦途。

接口调用

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

// 同步接口
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 **了🎉;其实,部分内容「快应用」本身,或者生态已经给出了优化方案,只不过没有在明显的文档、教程中给予说明,导致很多开发者朋友不知道这一点;本篇文章的价值就在于,将这些信息分享出来,希望可以帮助更多开发者朋友,高效工作,快乐生活。下面,就写一个完整的示例,来结束本篇分享:

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 编写「快应用」模版),以供参考。

vivo developer

快应用引擎、工具开发者、快应用生态拓展达人(vivo)。

Great! You've successfully subscribed.
Great! Next, complete checkout for full access.
Welcome back! You've successfully signed in.
Success! Your account is fully activated, you now have access to all content.