magic-applet
magic-applet是用于统一特斯联微前端移动端应用在小程序和在 FutureAPP 中的 API 。
magic-applet是基于uni-app，使用typescript编写，编译为ESM规范的 JS 产物的 npm 包，支持在 js 或者 ts 项目中使用。
推荐在 typescript 项目中使用，可以获得更加友好的代码提示。
项目基于compositionAPI编写，请保证你的 vue 版本大于等于2.7！
项目基于compositionAPI编写，请保证你的 vue 版本大于等于2.7！
项目基于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 进行二次封装的
bug/需求提交
当前只封装了以上 API，如果有bug或者其他的需求，可以从GitLab或者禅道中提交，推荐直接在GitLab中提交
GitLab 提交
打开仓库地址 => 点击右上角的➕号，新建议题
填好问题/需求描述后点击提交
禅道 提交
代码贡献
请不要直接在本仓库提交代码，先fork(派生)一个仓库后，提交代码，然后发起PR（合并请求）。
派生仓库
打开仓库地址 => 点击左上角的派生按钮 => 选择命名空间 =》拉取并修改代码
创建合并
提交代码后，打开自己派生的仓库，点击右上角的➕号，新建合并请求
填写相关信息，以及对应的issue(议题)后提交即可
