@tslsmart/magic-applet

v1.2.2

Published

a year ago

特斯联移动端统一接口,抹平h5和wgt的差异

Downloads

0High
0Medium
0Low

junex

leano_z

gin_black

vue uni-app futureApp h5 wgt app-plus

magic-applet

magic-applet是用于统一特斯联微前端移动端应用在小程序和在 FutureAPP 中的 API 。

magic-applet是基于uni-app，使用typescript编写，编译为ESM规范的 JS 产物的 npm 包，支持在 js 或者 ts 项目中使用。

推荐在 typescript 项目中使用，可以获得更加友好的代码提示。

项目基于compositionAPI编写，请保证你的 vue 版本大于等于2.7！

背景

移动端产品有同时在微信小程序和 FutureApp 上架的需求。

而传统的小程序开发发版较为麻烦，因此采用在小程序（主应用）中通过web-view嵌入h5的子应用，在 FutureApp 集成uni-app SDK，嵌入app-plus子应用包的微前端的方式。

uni-app 虽然统一了大多数的 API，但h5和app-plus中依然有部分 API 无法统一，例如h5无法直接调用扫码 API，需要通知主应用的小程序去扫码，然后将结果返回，如此一来，我们就需要编写大量的条件编译来达到一套代码，多端运行的效果。magic-applet由此而生。

magic-applet中，封装了h5和app-plus有差异的这部分 API 的条件编译，力求达到一个 API，搞定两个应用环境。

使用

安装

pnpm / npm install @tslsmart/magic-applet
# 或者 yarn add @tslsmart/magic-applet

初始化

需要在App.vue中初始化：

// App.vue中
import '@tslsmart/magic-applet'

初始化时会将从主应用（小程序端或者 FutureApp 端）获取到的参数存到localStorage中，具体细节无需关注，相关 API 详见后文。

API

参数类

magic.initParams 初始化

用于持久化保存父应用传递过来的参数，使用import '@tslsmart/magic-applet'导入时已自动执行

也可以手动调用，可以在then中进行其他操作：

// 业务代码中
import magic from '@tslsmart/magic-applet'
magic.initParams().then((res) => {
  console.log(res)
})

magic.getAuthInfo 获取授权信息

一般是在封装axios，将授权信息添加到header中时使用：

// request.js中
import magic from '@tslsmart/magic-applet'

const { authCtxCode, authorization, projectCode } = magic.getAuthInfo()

// 省略其他代码...
if (config.headers) {
  config.headers = {
    ...config.headers,
    authorization,
    projectCode,
    authCtxCode
  }
}
// 省略其他代码...

magic.getParams 获取所有参数

用于获取从父应用传入的所有参数

// 业务代码中
import magic from '@tslsmart/magic-applet'

const params = magic.getParams()

magic.getParamsByKey 获取指定参数

用于获取指定的、从父应用传入的所有参数

// 业务代码中
import magic from '@tslsmart/magic-applet'

const params = magic.getParamsByKey('authorization')

操作类

magic.toScan

在 App 端，会直接调用摄像机进行扫码，但在 h5 端，会跳转到主应用界面，然后调用摄像机进行扫码。

因此，我们将扫码的交互统一为：

调用magic.toScan进行扫码
在新的页面处理扫码结果

这个新的页面也可以是发起扫码的页面，但是会丢失之前进入该页面时的query参数，这种方式建议使用其他方式进行页面传参

magic.toScan的参数是一个ScanParams对象，其中ScanParams.targetUrl为必填参数，是扫码之后需要跳转到的页面路由，例如：

import magic from '@tslsmart/magic-applet'
magic.toScan({
  targetUrl: '/pages/result/index',
  fail(err) {
    console.log(err)
  }
})

ScanParams参数的 ts 类型定义:

export type ScanParams = {
  targetUrl: string // 扫码之后需要跳转到的页面路由，必填项
  fail?: CallBack // 调用失败的回调函数，非必填
}

magic.getScanRes

用于获取扫码的结果，一般是一个字符串，query字符串或者JSON字符串或者其他字符串，视具体项目而定，需要自行处理

import magic from '@tslsmart/magic-applet'

const scanRes = magic.getScanRes()

// 处理json字符串
const resObj = JSON.parse(scanRes)

// 处理query字符串
import qs from 'qs'
const objRes = qs.parse(scanRes)

magic.navigateTo

用于跳转到其他子应用。例如，在会议室相关需求中，预约功能是一个子应用，预约记录是另外一个子应用，预约成功后，可能需要跳转到预约记录中，就会用到这个 API

import magic from '@tslsmart/magic-applet'
magic.navigateTo({
  appid: 'meeting_record_id',
  targetUrl: '/pages/record/index'
})

其参数类型定义如下：

export type NavigateParams = {
  appid: string // 要跳转的目标应用的appid
  targetUrl: string // 要跳转到目标应用的具体页面，默认是'pages/index/index'
}

magic.closeApplet---`v1.1`及以上版本

关闭子应用本身。有时候可能需要通过代码的时候退出子应用，可以使用此API:

import magic from '@tslsmart/magic-applet'

magic.closeApplet()

magic.openDoor---`v1.2`及以上版本

通过蓝牙发起开门请求。有时候可能需要通过代码的时候退出子应用，可以使用此API:

import magic from '@tslsmart/magic-applet'

magic.openDoor({
  info: {
    openType: 'remote', // 开门方式,蓝牙:bluetooth 远程开门：remote
    deviceName: '测试门禁1号', // 设备名
    // 蓝牙开门必传参数：
    mac: '11:11:11:11', // 设备MAC地址
    password: '123456', // 设备密码
    // 远程开门必传参数：
    deviceId: '112233', // 设备id
    productId: string // 产品id
  },
  targetUrl: 'pages/result/index' // 开门成功后的跳转地址，一般是回到钥匙列表页
})

magic.action

其他操作，可能存在尚未被封装的其他的、需要父应用进行的操作，可以使用此 API 请求父应用进行操作：

import magic from '@tslsmart/magic-applet'
magic.action({
  actionType: 'scan' // 需要宿主进行的操作，例如扫码、跳转、或者授权
  appid: 'appid' // 跳转时，必须传入的目标应用的appid
  targetUrl: 'pages/path/index' // 宿主执行操作后，要跳转的url，例如跳转到扫码结果页
}).then(res => {
  console.log('操作成功了')
}).catch(err => {
  console.log('操作失败了')
})

其参数类型定义如下：

export type ActionType = 'scan' | 'navigate' | '/Terminus/Future/Auth/Req' | any

export interface ActionParams {
  actionType: ActionType // 需要宿主进行的操作，例如扫码、跳转、或者授权
  appid?: string // 跳转时，必须传入的目标应用的appid
  targetUrl: string // 宿主执行操作后，要跳转的url，例如跳转到扫码结果页
}

实际上，我们的magic.toScan和magic.navigateTo等都是基于这个 API 进行二次封装的