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

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