一款 vue 应用 SDK

本文旨在推荐最新开发的一款 SDK，用于提供 vue3 应用开发常用的基础功能。

功能清单

• 路由扩展，支持识别前进后退及携带跳转数据
• 路由动画管理，支持动态切换前进后退动画名及关闭动画
• 路由组件缓存管理，支持前进缓存后退清除

安装 SDK

// plugins/sdk.ts
import { createAppSDK } from 'vue-app-sdk'

// 创建 SDK，之后需通过 app.use 挂载并传递参数
const sdk = createAppSDK()

export default sdk

// main.ts
const app = createApp({ ... })

// 依赖于 `vue-router`，所以必须提前安装路由
app.use(router)
app.use(sdk, {
  // sdk 配置项，具有类型提示
})

路由扩展

旨在扩展原 vue-router 功能，让其能够通过自带的 api 识别前进及后退事件，并且在后退时也支持传递参数给目标页，比较适合用于 h5 应用。

<!-- App.vue -->
<script setup lang="ts">
const router = useRouter()

// 除过 back() 和 go(-n) 均会被认为是前进，也可通过注册插件时传递配置项更改这一行为

// 前进 apis
router.push(to)
router.replace(to)
router.go(+n)
router.forward()

// 后退 apis
router.go(-n)
router.back()

// 额外扩充了携带路由数据的 apis，仅跳转后的目标页会获取数据
router.pushWithData(to, [data])
router.replaceWithData(to, [data])
router.goWithData(n, [data])
router.forwardWithData([data])
router.backWithData([data])

// 使用 useRouteDetails 获取跳转详情，是一个 shallowReactive 对象

// 为了获取类型提示，可以定义详情数据类型
interface DetailsData {
  refreshList?: boolean
}

// 跳转传递的数据需通过 details.data 获取，暂时仅有 data 属性，未来可能扩充其他属性
// 默认的详情数据会进行持久化处理，在页面注销时清除，可通过注册插件时传递配置更改这一行为
const details = useRouteDetails<DetailsData>()
// 持续监听详情数据
watch(() => details.data, (data) => {
  if (data?.refreshList) {
    // 刷新列表
  }
})
</script>

<template>
  <RouterView />
</template>

路由动画管理

由于并非所有项目或开发者都需要动画功能，所以 SDK 引入了简易插件注册器，通过开发插件为 vue-app-sdk 扩展更为广泛和强大的功能，也让使用者不用担心最终的包体积。

注册动画管理器插件。

// plugins/sdk.ts
...
import { createAnimationPlugin } from 'vue-app-sdk/plugins/animation'

...
sdk.use(createAnimationPlugin({
  // 动画配置项，可设置前进后退的动画名及初始状态
}))

改造 App.vue。

<!-- App.vue -->
<script setup lang="ts">
import { useAppSDK } from 'vue-app-sdk'

const { name: transitionName, ...animationControls } = useAppSDK().animation

const router = useRouter()
function replacePage() {
  // 启用状态默认会在切换路由后还原，可通过 allowRevert 禁止还原
  // animationControls.allowRevert(false)

  // h5 的 tabbar 切换时一般不需要切换样式，可以通过 disable() 禁用导航动画
  // !!!禁用时需要设置 Transition.css 为 false，否则会影响切换效果!!!
  animationControls.disable()

  router.replace('/a')
}

function pushPage() {
  // 除过 back() 和 go(-n) 时自动认为是前进，会采用 valueForward 动画
  router.push('/b')
}

function backPage() {
  // 会采用 valueBackward 动画
  router.back()
}
</script>

<template>
  <RouterView v-slot="{ Component: routerComp }">
    <Transition :name="transitionName" :css="!!transitionName">
      <Component :is="routerComp" />
    </Transition>
  </RouterView>
</template>

<style scoped>
.forward-active {
  /* ... */
}

.backward-active {
  /* ... */
}
</style>

路由缓存管理器

通过注册缓存管理器，通过识别前进后退来自动管理页面缓存。

// plugins/sdk.ts
...
import { createKeepAlivePlugin } from 'vue-app-sdk/plugins/keepAlive'

sdk.use(createKeepAlivePlugin({
  // 缓存管理器配置项，可配置缓存行为
}))

再次改造App.vue。

<script setup lang="ts">
import { useAppSDK } from 'vue-app-sdk'

// 由于 KeepAlive 通过组件名进行缓存，所以路由组件必须设置不一样的 name，防止出现未知问题

// 默认会在路由前进后退时自动收集和释放缓存页面，可通过注册插件时传递参数更改这一行为
const { caches: keepAliveCaches, ...cacheControls } = useAppSDK().keepAlive

// 通过组件名管理
cacheControls.addCache('ComponentName')
cacheControls.removeCache('ComponentName')
cacheControls.refreshCache('ComponentName')

// 通过路由管理
cacheControls.addCacheWithRoute(route)
cacheControls.removeCacheWithRoute(route)
cacheControls.refreshCacheWithRoute(route)
</script>

<template>
  <RouterView v-slot="{ Component: routerComp }">
    <Transition :name="transitionName" :css="!!transitionName">
      <KeepAlive :include="keepAliveCaches">
        <Component
          :is="routerComp"
          :key="route.fullPath"
        />
      </KeepAlive>
    </Transition>
  </RouterView>
</template>

开发插件

目前内置插件较少，若不满足项目所需时也可自行抽离常用功能进行插件开发。

// myPlugin.ts
import type { AppSDKPlugin } from 'vue-app-sdk'

// 若不需要接收参数也可直接返回插件函数
export function createMyPlugin(): AppSDKPlugin {
  return (sdk) => {
    // 通过 SDK 实例提供的 hooks 管理器注册路由器导航事件，打印出当前的导航方向
    sdk.hooks.hook('sdk:router:direction', (direction) => {
      console.log(`当前导航是：${direction === 'forward' ? '前进' : '后退'}`)
    })

    // 也可不挂载
    sdk.myPlugin = {
      // ...
    }
  }
}

结语

未来仍然会不断进行优化和内置插件的开发，也期望能有更多道友参与或提出建议来推动该工具的发展，以上就是 vue-app-sdk 的全部内容了，有问题的道友也可评论区留言，谢谢观看🫡！

• vue-app-sdk (github.com)
• vue-app-sdk (npmjs.com)