如何优雅使用「快应用」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.app， qa.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 编写「快应用」模版），以供参考。